@open-mercato/web-research 0.7.1-develop.7194.1.ab4fc81f82

package/dist/testing/contract.js

@@ -0,0 +1,118 @@
+import { silentLogger } from "../contract/http.js";
+import { CONTRACT_VERSION } from "../contract/version.js";
+function createStubHttpClient(handler) {
+  const calls = [];
+  return {
+    calls,
+    async request(url, init) {
+      calls.push(url);
+      const stub = await handler(url, init);
+      return {
+        url: stub.url ?? url,
+        status: stub.status ?? 200,
+        headers: stub.headers ?? /* @__PURE__ */ new Map(),
+        contentType: stub.contentType ?? "text/html",
+        body: stub.body,
+        truncated: stub.truncated ?? false
+      };
+    }
+  };
+}
+function createTestContext(overrides = {}) {
+  return {
+    signal: new AbortController().signal,
+    http: createStubHttpClient(() => ({ body: "" })),
+    report: () => {
+    },
+    deadlineAt: Date.now() + 1e4,
+    logger: silentLogger,
+    ...overrides
+  };
+}
+const SAMPLE_REQUEST = { query: "open mercato", limit: 5 };
+const VALID_STATUSES = ["ok", "empty", "unavailable", "blocked", "timeout", "error"];
+function describeAdapterContract(module, testCase, api) {
+  const { describe, it, expect } = api;
+  describe(`${module.id} adapter contract`, () => {
+    it("declares the contract version it was built against", () => {
+      expect(module.contractVersion).toBe(CONTRACT_VERSION);
+    });
+    it("exposes a stable id and kind", () => {
+      expect(typeof module.id).toBe("string");
+      expect(module.id.length > 0).toBe(true);
+      expect(["serp", "api", "model", "browser"].includes(module.kind)).toBe(true);
+    });
+    it("validates its own options", () => {
+      const parsed = module.optionsSchema.safeParse(testCase.configuredOptions);
+      expect(parsed.success).toBe(true);
+    });
+    it("reports readiness without performing I/O", () => {
+      const adapter = module.createAdapter(testCase.configuredOptions);
+      const readiness = adapter.readiness();
+      expect(typeof readiness.ready).toBe("boolean");
+    });
+    const unconfigured = testCase.unconfiguredOptions;
+    if (unconfigured !== void 0) {
+      it("is unavailable rather than broken when unconfigured", async () => {
+        const adapter = module.createAdapter(unconfigured);
+        const readiness = adapter.readiness();
+        expect(readiness.ready).toBe(false);
+        if (!readiness.ready) expect(readiness.reason.length > 0).toBe(true);
+        const outcome = await adapter.search(SAMPLE_REQUEST, createTestContext());
+        expect(outcome.status).toBe("unavailable");
+      });
+    }
+    it("returns an outcome rather than throwing when egress fails", async () => {
+      const adapter = module.createAdapter(testCase.configuredOptions);
+      const context = createTestContext({
+        http: createStubHttpClient(() => {
+          throw new Error("network exploded");
+        })
+      });
+      const outcome = await adapter.search(SAMPLE_REQUEST, context);
+      expect(VALID_STATUSES.includes(outcome.status)).toBe(true);
+    });
+    it("honours an already-aborted signal without hanging", async () => {
+      const adapter = module.createAdapter(testCase.configuredOptions);
+      const controller = new AbortController();
+      controller.abort();
+      const outcome = await adapter.search(SAMPLE_REQUEST, createTestContext({ signal: controller.signal }));
+      expect(typeof outcome.status).toBe("string");
+    });
+    it("never returns a result without a url", async () => {
+      const adapter = module.createAdapter(testCase.configuredOptions);
+      const context = testCase.context ? testCase.context() : createTestContext();
+      const outcome = await adapter.search(SAMPLE_REQUEST, context);
+      if (outcome.status !== "ok") return;
+      for (const result of outcome.results) {
+        expect(typeof result.url).toBe("string");
+        expect(result.url.length > 0).toBe(true);
+      }
+    });
+    it("tears down cleanly even when it was never used", async () => {
+      const adapter = module.createAdapter(testCase.configuredOptions);
+      if (!adapter.dispose) return;
+      await adapter.dispose();
+      await adapter.dispose();
+      expect(true).toBe(true);
+    });
+    it("answers a health check without throwing", async () => {
+      const adapter = module.createAdapter(testCase.configuredOptions);
+      if (!adapter.healthCheck) return;
+      const context = createTestContext({
+        http: createStubHttpClient(() => {
+          throw new Error("network exploded");
+        })
+      });
+      const health = await adapter.healthCheck(context);
+      expect(typeof health.ok).toBe("boolean");
+    });
+  });
+}
+export {
+  SAMPLE_REQUEST,
+  createStubHttpClient,
+  createTestContext,
+  describeAdapterContract
+};
+//# sourceMappingURL=contract.js.map

package/dist/testing/contract.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/testing/contract.ts"],
+  "sourcesContent": ["import type { AdapterContext, AdapterModule, SearchAdapter } from '../contract/adapter'\nimport { silentLogger, type HttpClient, type HttpResponse } from '../contract/http'\nimport { CONTRACT_VERSION } from '../contract/version'\nimport type { SearchRequest } from '../contract/results'\n\nexport type StubResponse = Partial<HttpResponse> & { readonly body: string }\n\n/**\n * Minimal HTTP double. Adapters are contractually forbidden from reaching for\n * `fetch`, so a test that passes with this client has also proved the adapter\n * routes every byte through the hardened transport.\n */\nexport function createStubHttpClient(\n  handler: (url: string, init: Parameters<HttpClient['request']>[1]) => StubResponse | Promise<StubResponse>,\n): HttpClient & { readonly calls: readonly string[] } {\n  const calls: string[] = []\n  return {\n    calls,\n    async request(url, init) {\n      calls.push(url)\n      const stub = await handler(url, init)\n      return {\n        url: stub.url ?? url,\n        status: stub.status ?? 200,\n        headers: stub.headers ?? new Map<string, string>(),\n        contentType: stub.contentType ?? 'text/html',\n        body: stub.body,\n        truncated: stub.truncated ?? false,\n      }\n    },\n  }\n}\n\nexport function createTestContext(overrides: Partial<AdapterContext> = {}): AdapterContext {\n  return {\n    signal: new AbortController().signal,\n    http: createStubHttpClient(() => ({ body: '' })),\n    report: () => {},\n    deadlineAt: Date.now() + 10_000,\n    logger: silentLogger,\n    ...overrides,\n  }\n}\n\nexport const SAMPLE_REQUEST: SearchRequest = { query: 'open mercato', limit: 5 }\n\nconst VALID_STATUSES = ['ok', 'empty', 'unavailable', 'blocked', 'timeout', 'error']\n\nexport type AdapterContractCase<TOptions> = {\n  /** Options that leave the adapter deliberately unconfigured. */\n  readonly unconfiguredOptions?: TOptions\n  /** Options sufficient for the adapter to consider itself ready. */\n  readonly configuredOptions: TOptions\n  /** Context used for the \"returns results\" probe; stub the HTTP client here. */\n  readonly context?: () => AdapterContext\n}\n\ntype TestApi = {\n  describe: (name: string, body: () => void) => void\n  it: (name: string, body: () => void | Promise<void>) => void\n  expect: (value: unknown) => {\n    toBe(expected: unknown): void\n    toBeDefined(): void\n    toContain(expected: string): void\n  }\n}\n\n/**\n * Behavioural suite every adapter must pass, ours and third parties'. It pins the\n * parts of the contract the scheduler actually depends on \u2014 most importantly that\n * an adapter reports rather than throws, because a throwing adapter would\n * otherwise take down an entire search.\n */\nexport function describeAdapterContract<TOptions>(\n  module: AdapterModule<TOptions>,\n  testCase: AdapterContractCase<TOptions>,\n  api: TestApi,\n): void {\n  const { describe, it, expect } = api\n\n  describe(`${module.id} adapter contract`, () => {\n    it('declares the contract version it was built against', () => {\n      expect(module.contractVersion).toBe(CONTRACT_VERSION)\n    })\n\n    it('exposes a stable id and kind', () => {\n      expect(typeof module.id).toBe('string')\n      expect(module.id.length > 0).toBe(true)\n      expect(['serp', 'api', 'model', 'browser'].includes(module.kind)).toBe(true)\n    })\n\n    it('validates its own options', () => {\n      const parsed = module.optionsSchema.safeParse(testCase.configuredOptions)\n      expect(parsed.success).toBe(true)\n    })\n\n    it('reports readiness without performing I/O', () => {\n      const adapter = module.createAdapter(testCase.configuredOptions)\n      const readiness = adapter.readiness()\n      expect(typeof readiness.ready).toBe('boolean')\n    })\n\n    const unconfigured = testCase.unconfiguredOptions\n    if (unconfigured !== undefined) {\n      it('is unavailable rather than broken when unconfigured', async () => {\n        const adapter = module.createAdapter(unconfigured)\n        const readiness = adapter.readiness()\n        expect(readiness.ready).toBe(false)\n        if (!readiness.ready) expect(readiness.reason.length > 0).toBe(true)\n\n        const outcome = await adapter.search(SAMPLE_REQUEST, createTestContext())\n        expect(outcome.status).toBe('unavailable')\n      })\n    }\n\n    // The contract is \"never throws\", not \"always fails when HTTP does\" \u2014 a model\n    // or browser adapter may not touch the HTTP client at all.\n    it('returns an outcome rather than throwing when egress fails', async () => {\n      const adapter = module.createAdapter(testCase.configuredOptions)\n      const context = createTestContext({\n        http: createStubHttpClient(() => {\n          throw new Error('network exploded')\n        }),\n      })\n      const outcome = await adapter.search(SAMPLE_REQUEST, context)\n      expect(VALID_STATUSES.includes(outcome.status)).toBe(true)\n    })\n\n    it('honours an already-aborted signal without hanging', async () => {\n      const adapter = module.createAdapter(testCase.configuredOptions)\n      const controller = new AbortController()\n      controller.abort()\n      const outcome = await adapter.search(SAMPLE_REQUEST, createTestContext({ signal: controller.signal }))\n      expect(typeof outcome.status).toBe('string')\n    })\n\n    it('never returns a result without a url', async () => {\n      const adapter: SearchAdapter = module.createAdapter(testCase.configuredOptions)\n      const context = testCase.context ? testCase.context() : createTestContext()\n      const outcome = await adapter.search(SAMPLE_REQUEST, context)\n      if (outcome.status !== 'ok') return\n      for (const result of outcome.results) {\n        expect(typeof result.url).toBe('string')\n        expect(result.url.length > 0).toBe(true)\n      }\n    })\n\n    // The host builds an engine per request and disposes it after, so a `dispose`\n    // that throws on an adapter which was never used, or on a second call, breaks\n    // teardown for every other adapter in the same engine. This is the surface\n    // that leaked a browser sidecar and a Chromium per tool call.\n    it('tears down cleanly even when it was never used', async () => {\n      const adapter = module.createAdapter(testCase.configuredOptions)\n      if (!adapter.dispose) return\n      await adapter.dispose()\n      await adapter.dispose()\n      expect(true).toBe(true)\n    })\n\n    it('answers a health check without throwing', async () => {\n      const adapter = module.createAdapter(testCase.configuredOptions)\n      if (!adapter.healthCheck) return\n      const context = createTestContext({\n        http: createStubHttpClient(() => {\n          throw new Error('network exploded')\n        }),\n      })\n      const health = await adapter.healthCheck(context)\n      expect(typeof health.ok).toBe('boolean')\n    })\n  })\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/testing/fakeAdapter.js

@@ -0,0 +1,44 @@
+import { READY, notReady } from "../contract/adapter.js";
+const BASE_CAPABILITIES = {
+  search: true,
+  fetch: false,
+  snippets: true,
+  content: false,
+  freshness: false,
+  siteFilter: false,
+  cost: "free"
+};
+function createFakeAdapter(options) {
+  const capabilities = { ...BASE_CAPABILITIES, ...options.capabilities };
+  const outcome = options.outcome ?? (options.results && options.results.length > 0 ? { status: "ok", results: options.results } : { status: "empty" });
+  return {
+    id: options.id,
+    kind: options.kind ?? "api",
+    capabilities,
+    readiness: () => options.ready === false ? notReady("fake adapter configured as not ready") : typeof options.ready === "string" ? notReady(options.ready) : READY,
+    async search(_request, context) {
+      if (options.throws) throw new Error(`${options.id} exploded`);
+      const latency = options.latencyMs ?? 0;
+      if (latency > 0) {
+        await new Promise((resolve) => {
+          const timer = setTimeout(resolve, latency);
+          timer.unref?.();
+          context.signal.addEventListener(
+            "abort",
+            () => {
+              clearTimeout(timer);
+              resolve();
+            },
+            { once: true }
+          );
+        });
+      }
+      if (context.signal.aborted) return { status: "timeout", reason: "aborted" };
+      return outcome;
+    }
+  };
+}
+export {
+  createFakeAdapter
+};
+//# sourceMappingURL=fakeAdapter.js.map

package/dist/testing/fakeAdapter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/testing/fakeAdapter.ts"],
+  "sourcesContent": ["import type { AdapterCapabilities, AdapterKind, SearchAdapter } from '../contract/adapter'\nimport { READY, notReady } from '../contract/adapter'\nimport type { SearchOutcome } from '../contract/outcomes'\nimport type { RawResult } from '../contract/results'\n\nexport type FakeAdapterOptions = {\n  readonly id: string\n  readonly kind?: AdapterKind\n  readonly ready?: boolean | string\n  /** Milliseconds of simulated work before the outcome resolves. */\n  readonly latencyMs?: number\n  readonly outcome?: SearchOutcome\n  readonly results?: readonly RawResult[]\n  readonly capabilities?: Partial<AdapterCapabilities>\n  /** Set to make the adapter violate the contract, for isolation tests. */\n  readonly throws?: boolean\n}\n\nconst BASE_CAPABILITIES: AdapterCapabilities = {\n  search: true,\n  fetch: false,\n  snippets: true,\n  content: false,\n  freshness: false,\n  siteFilter: false,\n  cost: 'free',\n}\n\n/** Deterministic adapter double for scheduler and fusion tests. */\nexport function createFakeAdapter(options: FakeAdapterOptions): SearchAdapter {\n  const capabilities: AdapterCapabilities = { ...BASE_CAPABILITIES, ...options.capabilities }\n  const outcome: SearchOutcome =\n    options.outcome ??\n    (options.results && options.results.length > 0\n      ? { status: 'ok', results: options.results }\n      : { status: 'empty' })\n\n  return {\n    id: options.id,\n    kind: options.kind ?? 'api',\n    capabilities,\n    readiness: () =>\n      options.ready === false\n        ? notReady('fake adapter configured as not ready')\n        : typeof options.ready === 'string'\n          ? notReady(options.ready)\n          : READY,\n    async search(_request, context) {\n      if (options.throws) throw new Error(`${options.id} exploded`)\n      const latency = options.latencyMs ?? 0\n      if (latency > 0) {\n        await new Promise<void>((resolve) => {\n          const timer = setTimeout(resolve, latency)\n          timer.unref?.()\n          context.signal.addEventListener(\n            'abort',\n            () => {\n              clearTimeout(timer)\n              resolve()\n            },\n            { once: true },\n          )\n        })\n      }\n      if (context.signal.aborted) return { status: 'timeout', reason: 'aborted' }\n      return outcome\n    },\n  }\n}\n"],
+  "mappings": "AACA,SAAS,OAAO,gBAAgB;AAiBhC,MAAM,oBAAyC;AAAA,EAC7C,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,UAAU;AAAA,EACV,SAAS;AAAA,EACT,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,MAAM;AACR;AAGO,SAAS,kBAAkB,SAA4C;AAC5E,QAAM,eAAoC,EAAE,GAAG,mBAAmB,GAAG,QAAQ,aAAa;AAC1F,QAAM,UACJ,QAAQ,YACP,QAAQ,WAAW,QAAQ,QAAQ,SAAS,IACzC,EAAE,QAAQ,MAAM,SAAS,QAAQ,QAAQ,IACzC,EAAE,QAAQ,QAAQ;AAExB,SAAO;AAAA,IACL,IAAI,QAAQ;AAAA,IACZ,MAAM,QAAQ,QAAQ;AAAA,IACtB;AAAA,IACA,WAAW,MACT,QAAQ,UAAU,QACd,SAAS,sCAAsC,IAC/C,OAAO,QAAQ,UAAU,WACvB,SAAS,QAAQ,KAAK,IACtB;AAAA,IACR,MAAM,OAAO,UAAU,SAAS;AAC9B,UAAI,QAAQ,OAAQ,OAAM,IAAI,MAAM,GAAG,QAAQ,EAAE,WAAW;AAC5D,YAAM,UAAU,QAAQ,aAAa;AACrC,UAAI,UAAU,GAAG;AACf,cAAM,IAAI,QAAc,CAAC,YAAY;AACnC,gBAAM,QAAQ,WAAW,SAAS,OAAO;AACzC,gBAAM,QAAQ;AACd,kBAAQ,OAAO;AAAA,YACb;AAAA,YACA,MAAM;AACJ,2BAAa,KAAK;AAClB,sBAAQ;AAAA,YACV;AAAA,YACA,EAAE,MAAM,KAAK;AAAA,UACf;AAAA,QACF,CAAC;AAAA,MACH;AACA,UAAI,QAAQ,OAAO,QAAS,QAAO,EAAE,QAAQ,WAAW,QAAQ,UAAU;AAC1E,aAAO;AAAA,IACT;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/testing/index.js

@@ -0,0 +1,15 @@
+import {
+  SAMPLE_REQUEST,
+  createStubHttpClient,
+  createTestContext,
+  describeAdapterContract
+} from "./contract.js";
+import { createFakeAdapter } from "./fakeAdapter.js";
+export {
+  SAMPLE_REQUEST,
+  createFakeAdapter,
+  createStubHttpClient,
+  createTestContext,
+  describeAdapterContract
+};
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/testing/index.ts"],
+  "sourcesContent": ["export {\n  SAMPLE_REQUEST,\n  createStubHttpClient,\n  createTestContext,\n  describeAdapterContract,\n  type AdapterContractCase,\n  type StubResponse,\n} from './contract'\nexport { createFakeAdapter, type FakeAdapterOptions } from './fakeAdapter'\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP,SAAS,yBAAkD;",
+  "names": []
+}

package/jest.config.cjs

@@ -0,0 +1,24 @@
+/** @type {import('jest').Config} */
+const base = require('../../jest.config.base.cjs')
+
+module.exports = {
+  ...base,
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  watchman: false,
+  rootDir: '.',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          rootDir: '.',
+          ignoreDeprecations: '6.0',
+        },
+      },
+    ],
+  },
+  testMatch: ['<rootDir>/src/**/__tests__/**/*.test.(ts|tsx)'],
+  passWithNoTests: true,
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@open-mercato/web-research",
+  "version": "0.7.1-develop.7194.1.ab4fc81f82",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts",
+        "./src/*/*.tsx"
+      ],
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*": {
+      "types": [
+        "./src/*/*/*.ts",
+        "./src/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.0.1",
+    "esbuild": "^0.28.1",
+    "glob": "^13.0.6",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/web-research"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/contract/adapter.ts

@@ -0,0 +1,100 @@
+import type { z } from 'zod'
+import type { HttpClient, Logger } from './http'
+import type { FetchOutcome, SearchOutcome } from './outcomes'
+import type { FetchRequest, SearchRequest } from './results'
+import type { StepReporter } from './steps'
+
+export type AdapterKind = 'serp' | 'api' | 'model' | 'browser'
+
+export type AdapterCost = 'free' | 'metered' | 'llm-tokens'
+
+/**
+ * What calling `healthCheck()` costs — which is NOT what searching costs.
+ *
+ * Exa's probe reads a local key and Model-native's resolves configuration, both
+ * free, though both are priced adapters to search with. Firecrawl's and Tavily's
+ * probes issue a real query and bill for it. The browser tier's spawns an OS
+ * process: no money, but not something to run on every page view either.
+ *
+ * A status surface may run `free` probes unattended; `heavy` and `billable` need
+ * a human to ask for them.
+ */
+export type ProbeCost = 'free' | 'heavy' | 'billable'
+
+export type AdapterCapabilities = {
+  readonly search: boolean
+  readonly fetch: boolean
+  /** Returns real snippets rather than bare URLs. */
+  readonly snippets: boolean
+  /** Returns full page text inline, sparing a follow-up fetch. */
+  readonly content: boolean
+  readonly freshness: boolean
+  readonly siteFilter: boolean
+  readonly cost: AdapterCost
+}
+
+export type AdapterReadiness =
+  | { readonly ready: true }
+  | { readonly ready: false; readonly reason: string }
+
+export type AdapterHealth = {
+  readonly ok: boolean
+  readonly detail?: string
+  readonly latencyMs?: number
+}
+
+export type AdapterContext = {
+  readonly signal: AbortSignal
+  readonly http: HttpClient
+  /** Narrates progress; the engine supplies the sequence, timestamp and adapter id. */
+  readonly report: StepReporter
+  /** Epoch ms after which the engine stops caring about this adapter's answer. */
+  readonly deadlineAt: number
+  readonly logger: Logger
+}
+
+export interface SearchAdapter {
+  readonly id: string
+  readonly kind: AdapterKind
+  readonly capabilities: AdapterCapabilities
+  /**
+   * Synchronous and I/O-free by contract, so planning a wave never blocks and an
+   * unconfigured adapter costs nothing to skip.
+   */
+  readiness(): AdapterReadiness
+  /**
+   * What `healthCheck()` costs to call. Omitting it is safe but pessimistic: the
+   * engine then derives `billable` from `capabilities.cost === 'metered'` and
+   * `free` otherwise, so an adapter that never declares it is simply left out of
+   * unattended probing. Declare it whenever the probe costs money.
+   */
+  readonly probeCost?: ProbeCost
+  search(request: SearchRequest, context: AdapterContext): Promise<SearchOutcome>
+  fetch?(request: FetchRequest, context: AdapterContext): Promise<FetchOutcome>
+  healthCheck?(context: AdapterContext): Promise<AdapterHealth>
+  dispose?(): Promise<void>
+}
+
+/**
+ * What an adapter package default-exports. A descriptor rather than an instance,
+ * because the engine builds one instance per tenant from that tenant's options.
+ */
+export type AdapterModule<TOptions = unknown> = {
+  readonly id: string
+  readonly kind: AdapterKind
+  readonly contractVersion: number
+  readonly optionsSchema: z.ZodType<TOptions>
+  createAdapter(options: TOptions): SearchAdapter
+}
+
+export function defineAdapterModule<TOptions>(
+  module: AdapterModule<TOptions>,
+): AdapterModule<TOptions> {
+  return module
+}
+
+export const READY: AdapterReadiness = { ready: true }
+
+export function notReady(reason: string): AdapterReadiness {
+  return { ready: false, reason }
+}

package/src/contract/errors.ts

@@ -0,0 +1,48 @@
+export type WebResearchErrorCode =
+  | 'ssrf_blocked'
+  | 'timeout'
+  | 'aborted'
+  | 'blocked'
+  | 'bad_response'
+  | 'too_many_redirects'
+  | 'unsupported_content_type'
+  | 'network'
+
+export type WebResearchErrorInit = {
+  readonly retryAfterMs?: number
+  readonly status?: number
+  readonly cause?: unknown
+}
+
+export class WebResearchError extends Error {
+  /**
+   * Brand checked by {@link isWebResearchError} instead of `instanceof`. The
+   * package resolves as raw `src` for typecheck and as built `dist` at runtime,
+   * so a value can cross a realm where the two class identities differ.
+   */
+  readonly __webResearchError = true as const
+  readonly code: WebResearchErrorCode
+  readonly retryAfterMs?: number
+  readonly status?: number
+
+  constructor(code: WebResearchErrorCode, message: string, init: WebResearchErrorInit = {}) {
+    super(message, init.cause === undefined ? undefined : { cause: init.cause })
+    this.name = 'WebResearchError'
+    this.code = code
+    if (init.retryAfterMs !== undefined) this.retryAfterMs = init.retryAfterMs
+    if (init.status !== undefined) this.status = init.status
+  }
+}
+
+export function isWebResearchError(value: unknown): value is WebResearchError {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { __webResearchError?: unknown }).__webResearchError === true
+  )
+}
+
+export function errorMessage(value: unknown): string {
+  if (value instanceof Error) return value.message
+  return String(value)
+}

package/src/contract/http.ts

@@ -0,0 +1,46 @@
+export type HttpMethod = 'GET' | 'POST'
+
+export type HttpRequestInit = {
+  readonly method?: HttpMethod
+  readonly headers?: Readonly<Record<string, string>>
+  readonly body?: string
+  readonly maxBytes?: number
+  readonly timeoutMs?: number
+  readonly signal?: AbortSignal
+  /**
+   * Content-type prefixes the caller can handle. A response outside the list is
+   * rejected with `unsupported_content_type` instead of being decoded as text —
+   * without this a PDF or image comes back as mojibake the model then tries to read.
+   */
+  readonly accept?: readonly string[]
+}
+
+export type HttpResponse = {
+  /** Final URL after redirects, each of which was re-vetted. */
+  readonly url: string
+  readonly status: number
+  readonly headers: ReadonlyMap<string, string>
+  readonly contentType: string | null
+  readonly body: string
+  readonly truncated: boolean
+}
+
+/**
+ * The single egress path. Adapters receive one of these and must never reach for
+ * `fetch` themselves — the SSRF guard, DNS pinning, redirect re-validation, byte
+ * caps and politeness live here, and a bypass silently loses all of them.
+ */
+export interface HttpClient {
+  request(url: string, init?: HttpRequestInit): Promise<HttpResponse>
+}
+
+export type Logger = {
+  debug(message: string, meta?: Record<string, unknown>): void
+  info(message: string, meta?: Record<string, unknown>): void
+  warn(message: string, meta?: Record<string, unknown>): void
+  error(message: string, meta?: Record<string, unknown>): void
+}
+
+const noop = (): void => {}
+
+export const silentLogger: Logger = { debug: noop, info: noop, warn: noop, error: noop }

package/src/contract/index.ts

@@ -0,0 +1,8 @@
+export * from './adapter'
+export * from './errors'
+export * from './http'
+export * from './outcomes'
+export * from './policy'
+export * from './results'
+export * from './steps'
+export * from './version'

package/src/contract/outcomes.ts

@@ -0,0 +1,91 @@
+import { isWebResearchError, errorMessage } from './errors'
+import type { FetchedPage, RawResult } from './results'
+
+/**
+ * Failure shapes shared by search and fetch. Keeping `unavailable`, `blocked`
+ * and `error` distinct is the point of the whole contract: the scheduler demotes
+ * an `unavailable` adapter for the rest of the run, escalates a `blocked` one to
+ * the browser tier, and retries only a retriable `error`. Collapsing them into a
+ * thrown exception — as the previous implementation did — makes all three
+ * indistinguishable and forces the caller to guess.
+ */
+export type OutcomeFailure =
+  | { readonly status: 'unavailable'; readonly reason: string }
+  | { readonly status: 'blocked'; readonly reason: string; readonly retryAfterMs?: number }
+  | { readonly status: 'timeout'; readonly reason?: string }
+  | { readonly status: 'error'; readonly reason: string; readonly retriable: boolean }
+
+export type SearchOutcome =
+  | { readonly status: 'ok'; readonly results: readonly RawResult[]; readonly answer?: string }
+  | { readonly status: 'empty' }
+  | OutcomeFailure
+
+export type FetchOutcome = { readonly status: 'ok'; readonly page: FetchedPage } | OutcomeFailure
+
+export type OutcomeStatus = SearchOutcome['status']
+
+/**
+ * A prose answer with no citations is still a successful search — the model
+ * knew something, it just did not link anywhere. Only a turn that produced
+ * neither links nor prose is `empty`.
+ */
+export function searchOk(results: readonly RawResult[], answer?: string): SearchOutcome {
+  const hasAnswer = answer !== undefined && answer.trim().length > 0
+  if (results.length === 0 && !hasAnswer) return { status: 'empty' }
+  return hasAnswer ? { status: 'ok', results, answer } : { status: 'ok', results }
+}
+
+export function searchEmpty(): SearchOutcome {
+  return { status: 'empty' }
+}
+
+export function unavailable(reason: string): OutcomeFailure {
+  return { status: 'unavailable', reason }
+}
+
+export function blocked(reason: string, retryAfterMs?: number): OutcomeFailure {
+  return retryAfterMs === undefined
+    ? { status: 'blocked', reason }
+    : { status: 'blocked', reason, retryAfterMs }
+}
+
+export function timedOut(reason?: string): OutcomeFailure {
+  return reason === undefined ? { status: 'timeout' } : { status: 'timeout', reason }
+}
+
+export function failed(reason: string, retriable = false): OutcomeFailure {
+  return { status: 'error', reason, retriable }
+}
+
+export function isFailure(outcome: SearchOutcome | FetchOutcome): outcome is OutcomeFailure {
+  return outcome.status !== 'ok' && outcome.status !== 'empty'
+}
+
+/**
+ * Maps anything thrown by the shared HTTP client onto the outcome vocabulary, so
+ * an adapter body reduces to `try { … } catch (err) { return toOutcomeFailure(err) }`
+ * and never leaks an exception to the scheduler.
+ */
+export function toOutcomeFailure(error: unknown): OutcomeFailure {
+  if (isWebResearchError(error)) {
+    switch (error.code) {
+      case 'timeout':
+        return timedOut(error.message)
+      case 'aborted':
+        return timedOut(error.message)
+      case 'blocked':
+        return blocked(error.message, error.retryAfterMs)
+      case 'ssrf_blocked':
+      case 'unsupported_content_type':
+        return failed(error.message, false)
+      case 'network':
+      case 'bad_response':
+      case 'too_many_redirects':
+        return failed(error.message, true)
+    }
+  }
+  if (error instanceof Error && error.name === 'AbortError') {
+    return timedOut(error.message)
+  }
+  return failed(errorMessage(error), false)
+}