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

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+[build:web-research] found 35 entry points
+[build:web-research] built successfully

package/AGENTS.md

@@ -0,0 +1,67 @@
+# Web Research Engine
+
+`@open-mercato/web-research` is the adapter-based web search/read engine. It is pure library code:
+no DI, no tenants, no ORM, no vendor. Governance (ACL, rate limits, traces, per-tenant policy) lives
+in `agent_orchestrator`; individual sources live in their own `@open-mercato/web-research-*` packages.
+
+## Always
+
+- Keep this package **zero-dependency** apart from `zod`. Node builtins only. Adapter packages carry
+  their own SDKs; the core must stay installable with no transitive weight.
+- Route every byte of egress through `HttpClient` (`src/net/client.ts`). Never call `fetch`,
+  `node:https`, or an SDK's own transport from an adapter — that bypasses the SSRF guard, DNS pinning,
+  redirect re-validation, byte caps and politeness in one step.
+- Return **outcomes, never throw**, from anything implementing `SearchAdapter`. `unavailable`,
+  `empty`, `blocked`, `timeout` and `error` drive different scheduler behaviour and must stay distinct.
+- Keep `readiness()` synchronous and I/O-free — the scheduler calls it while planning.
+- **Dispose every engine you create.** `createSearchEngine` is called per request by the host, and
+  `dispose()` is the only thing that releases adapter-owned OS resources (the browser tier holds a
+  sidecar process and a Chromium). A caller that skips it leaks one of each per request.
+- Gate any adapter you reach for outside the normal wave on `entry.enabled`. `policy.lastResort` is
+  the single documented exception — browser escalation is not one, or an operator who turned the
+  most expensive tier off still pays for it.
+- Parse HTML with `tokenizeHtml` (`src/extract/tokenizer.ts`). No new regex parsers.
+- Any new public type on the adapter contract is a **contract change**: bump `CONTRACT_VERSION`
+  (`src/contract/version.ts`) and follow `BACKWARD_COMPATIBILITY.md`, because third-party adapter
+  packages compile against it.
+
+## Never
+
+- Never let a confidence threshold or domain cap produce an empty result set — relax and flag
+  `degraded` instead (`src/fusion/fuse.ts`).
+- Never trust an adapter to honour the contract. `runAdapter` converts a throw into an `error`
+  outcome on purpose; do not remove that guard.
+- Never put a vendor name in this package.
+
+## Layout
+
+| Path | Role |
+|---|---|
+| `src/contract/` | Adapter interface, outcomes, steps, policy, errors, `CONTRACT_VERSION` |
+| `src/net/` | SSRF guard + the single hardened, DNS-pinned HTTP client |
+| `src/extract/` | Linear HTML tokenizer, text, title, main-content, page classifier |
+| `src/fusion/` | URL canonicalization, dedup, reciprocal-rank fusion, domain diversity |
+| `src/engine/` | Wave scheduler, deadlines, browser escalation, single-flight, cache seam |
+| `src/testing/` | `describeAdapterContract()` and fakes — published for third-party adapters |
+
+## Design notes worth knowing before changing things
+
+- **DNS pinning** (`createPinnedLookup`) is why the client is built on `node:https` rather than
+  `fetch`: the connection must resolve to exactly the addresses the SSRF guard vetted, or the
+  rebinding window between check and connect stays open.
+- **`assertPublicUrl` fails closed on DNS failure by default**, unlike reference implementations that
+  fail open. We pin, so no addresses means no pinning, and proceeding would silently drop a control.
+- **RRF, not score blending** — an LLM citation list, a SERP and a paid API have no comparable score
+  scale. Rank is the only signal they all agree on.
+- **The soft deadline only binds once results exist.** With nothing in hand the scheduler keeps
+  waiting to the hard deadline; holding back a usable answer for a straggler is the worse failure.
+- **Browser escalation is decided here, in code**, from `classifyPage` — not by prompting the model,
+  which costs a round-trip and answers differently each time.
+
+## Validation
+
+```bash
+yarn workspace @open-mercato/web-research test
+yarn workspace @open-mercato/web-research typecheck
+yarn workspace @open-mercato/web-research build
+```

package/build.mjs

@@ -0,0 +1,10 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildPackage } from '../../scripts/build-package.mjs'
+
+const packageDir = dirname(fileURLToPath(import.meta.url))
+
+await buildPackage(packageDir, {
+  name: 'web-research',
+  entryPoints: 'src/**/*.ts',
+})

package/dist/contract/adapter.js

@@ -0,0 +1,13 @@
+function defineAdapterModule(module) {
+  return module;
+}
+const READY = { ready: true };
+function notReady(reason) {
+  return { ready: false, reason };
+}
+export {
+  READY,
+  defineAdapterModule,
+  notReady
+};
+//# sourceMappingURL=adapter.js.map

package/dist/contract/adapter.js.map

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

package/dist/contract/errors.js

@@ -0,0 +1,28 @@
+class WebResearchError extends Error {
+  constructor(code, message, init = {}) {
+    super(message, init.cause === void 0 ? void 0 : { cause: init.cause });
+    /**
+     * 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.
+     */
+    this.__webResearchError = true;
+    this.name = "WebResearchError";
+    this.code = code;
+    if (init.retryAfterMs !== void 0) this.retryAfterMs = init.retryAfterMs;
+    if (init.status !== void 0) this.status = init.status;
+  }
+}
+function isWebResearchError(value) {
+  return typeof value === "object" && value !== null && value.__webResearchError === true;
+}
+function errorMessage(value) {
+  if (value instanceof Error) return value.message;
+  return String(value);
+}
+export {
+  WebResearchError,
+  errorMessage,
+  isWebResearchError
+};
+//# sourceMappingURL=errors.js.map

package/dist/contract/errors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/contract/errors.ts"],
+  "sourcesContent": ["export type WebResearchErrorCode =\n  | 'ssrf_blocked'\n  | 'timeout'\n  | 'aborted'\n  | 'blocked'\n  | 'bad_response'\n  | 'too_many_redirects'\n  | 'unsupported_content_type'\n  | 'network'\n\nexport type WebResearchErrorInit = {\n  readonly retryAfterMs?: number\n  readonly status?: number\n  readonly cause?: unknown\n}\n\nexport class WebResearchError extends Error {\n  /**\n   * Brand checked by {@link isWebResearchError} instead of `instanceof`. The\n   * package resolves as raw `src` for typecheck and as built `dist` at runtime,\n   * so a value can cross a realm where the two class identities differ.\n   */\n  readonly __webResearchError = true as const\n  readonly code: WebResearchErrorCode\n  readonly retryAfterMs?: number\n  readonly status?: number\n\n  constructor(code: WebResearchErrorCode, message: string, init: WebResearchErrorInit = {}) {\n    super(message, init.cause === undefined ? undefined : { cause: init.cause })\n    this.name = 'WebResearchError'\n    this.code = code\n    if (init.retryAfterMs !== undefined) this.retryAfterMs = init.retryAfterMs\n    if (init.status !== undefined) this.status = init.status\n  }\n}\n\nexport function isWebResearchError(value: unknown): value is WebResearchError {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { __webResearchError?: unknown }).__webResearchError === true\n  )\n}\n\nexport function errorMessage(value: unknown): string {\n  if (value instanceof Error) return value.message\n  return String(value)\n}\n"],
+  "mappings": "AAgBO,MAAM,yBAAyB,MAAM;AAAA,EAW1C,YAAY,MAA4B,SAAiB,OAA6B,CAAC,GAAG;AACxF,UAAM,SAAS,KAAK,UAAU,SAAY,SAAY,EAAE,OAAO,KAAK,MAAM,CAAC;AAN7E;AAAA;AAAA;AAAA;AAAA;AAAA,SAAS,qBAAqB;AAO5B,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,QAAI,KAAK,iBAAiB,OAAW,MAAK,eAAe,KAAK;AAC9D,QAAI,KAAK,WAAW,OAAW,MAAK,SAAS,KAAK;AAAA,EACpD;AACF;AAEO,SAAS,mBAAmB,OAA2C;AAC5E,SACE,OAAO,UAAU,YACjB,UAAU,QACT,MAA2C,uBAAuB;AAEvE;AAEO,SAAS,aAAa,OAAwB;AACnD,MAAI,iBAAiB,MAAO,QAAO,MAAM;AACzC,SAAO,OAAO,KAAK;AACrB;",
+  "names": []
+}

package/dist/contract/http.js

@@ -0,0 +1,7 @@
+const noop = () => {
+};
+const silentLogger = { debug: noop, info: noop, warn: noop, error: noop };
+export {
+  silentLogger
+};
+//# sourceMappingURL=http.js.map

package/dist/contract/http.js.map

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

package/dist/contract/index.js

@@ -0,0 +1,9 @@
+export * from "./adapter.js";
+export * from "./errors.js";
+export * from "./http.js";
+export * from "./outcomes.js";
+export * from "./policy.js";
+export * from "./results.js";
+export * from "./steps.js";
+export * from "./version.js";
+//# sourceMappingURL=index.js.map

package/dist/contract/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/contract/index.ts"],
+  "sourcesContent": ["export * from './adapter'\nexport * from './errors'\nexport * from './http'\nexport * from './outcomes'\nexport * from './policy'\nexport * from './results'\nexport * from './steps'\nexport * from './version'\n"],
+  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
+  "names": []
+}

package/dist/contract/outcomes.js

@@ -0,0 +1,58 @@
+import { isWebResearchError, errorMessage } from "./errors.js";
+function searchOk(results, answer) {
+  const hasAnswer = answer !== void 0 && answer.trim().length > 0;
+  if (results.length === 0 && !hasAnswer) return { status: "empty" };
+  return hasAnswer ? { status: "ok", results, answer } : { status: "ok", results };
+}
+function searchEmpty() {
+  return { status: "empty" };
+}
+function unavailable(reason) {
+  return { status: "unavailable", reason };
+}
+function blocked(reason, retryAfterMs) {
+  return retryAfterMs === void 0 ? { status: "blocked", reason } : { status: "blocked", reason, retryAfterMs };
+}
+function timedOut(reason) {
+  return reason === void 0 ? { status: "timeout" } : { status: "timeout", reason };
+}
+function failed(reason, retriable = false) {
+  return { status: "error", reason, retriable };
+}
+function isFailure(outcome) {
+  return outcome.status !== "ok" && outcome.status !== "empty";
+}
+function toOutcomeFailure(error) {
+  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);
+}
+export {
+  blocked,
+  failed,
+  isFailure,
+  searchEmpty,
+  searchOk,
+  timedOut,
+  toOutcomeFailure,
+  unavailable
+};
+//# sourceMappingURL=outcomes.js.map

package/dist/contract/outcomes.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/contract/outcomes.ts"],
+  "sourcesContent": ["import { isWebResearchError, errorMessage } from './errors'\nimport type { FetchedPage, RawResult } from './results'\n\n/**\n * Failure shapes shared by search and fetch. Keeping `unavailable`, `blocked`\n * and `error` distinct is the point of the whole contract: the scheduler demotes\n * an `unavailable` adapter for the rest of the run, escalates a `blocked` one to\n * the browser tier, and retries only a retriable `error`. Collapsing them into a\n * thrown exception \u2014 as the previous implementation did \u2014 makes all three\n * indistinguishable and forces the caller to guess.\n */\nexport type OutcomeFailure =\n  | { readonly status: 'unavailable'; readonly reason: string }\n  | { readonly status: 'blocked'; readonly reason: string; readonly retryAfterMs?: number }\n  | { readonly status: 'timeout'; readonly reason?: string }\n  | { readonly status: 'error'; readonly reason: string; readonly retriable: boolean }\n\nexport type SearchOutcome =\n  | { readonly status: 'ok'; readonly results: readonly RawResult[]; readonly answer?: string }\n  | { readonly status: 'empty' }\n  | OutcomeFailure\n\nexport type FetchOutcome = { readonly status: 'ok'; readonly page: FetchedPage } | OutcomeFailure\n\nexport type OutcomeStatus = SearchOutcome['status']\n\n/**\n * A prose answer with no citations is still a successful search \u2014 the model\n * knew something, it just did not link anywhere. Only a turn that produced\n * neither links nor prose is `empty`.\n */\nexport function searchOk(results: readonly RawResult[], answer?: string): SearchOutcome {\n  const hasAnswer = answer !== undefined && answer.trim().length > 0\n  if (results.length === 0 && !hasAnswer) return { status: 'empty' }\n  return hasAnswer ? { status: 'ok', results, answer } : { status: 'ok', results }\n}\n\nexport function searchEmpty(): SearchOutcome {\n  return { status: 'empty' }\n}\n\nexport function unavailable(reason: string): OutcomeFailure {\n  return { status: 'unavailable', reason }\n}\n\nexport function blocked(reason: string, retryAfterMs?: number): OutcomeFailure {\n  return retryAfterMs === undefined\n    ? { status: 'blocked', reason }\n    : { status: 'blocked', reason, retryAfterMs }\n}\n\nexport function timedOut(reason?: string): OutcomeFailure {\n  return reason === undefined ? { status: 'timeout' } : { status: 'timeout', reason }\n}\n\nexport function failed(reason: string, retriable = false): OutcomeFailure {\n  return { status: 'error', reason, retriable }\n}\n\nexport function isFailure(outcome: SearchOutcome | FetchOutcome): outcome is OutcomeFailure {\n  return outcome.status !== 'ok' && outcome.status !== 'empty'\n}\n\n/**\n * Maps anything thrown by the shared HTTP client onto the outcome vocabulary, so\n * an adapter body reduces to `try { \u2026 } catch (err) { return toOutcomeFailure(err) }`\n * and never leaks an exception to the scheduler.\n */\nexport function toOutcomeFailure(error: unknown): OutcomeFailure {\n  if (isWebResearchError(error)) {\n    switch (error.code) {\n      case 'timeout':\n        return timedOut(error.message)\n      case 'aborted':\n        return timedOut(error.message)\n      case 'blocked':\n        return blocked(error.message, error.retryAfterMs)\n      case 'ssrf_blocked':\n      case 'unsupported_content_type':\n        return failed(error.message, false)\n      case 'network':\n      case 'bad_response':\n      case 'too_many_redirects':\n        return failed(error.message, true)\n    }\n  }\n  if (error instanceof Error && error.name === 'AbortError') {\n    return timedOut(error.message)\n  }\n  return failed(errorMessage(error), false)\n}\n"],
+  "mappings": "AAAA,SAAS,oBAAoB,oBAAoB;AA+B1C,SAAS,SAAS,SAA+B,QAAgC;AACtF,QAAM,YAAY,WAAW,UAAa,OAAO,KAAK,EAAE,SAAS;AACjE,MAAI,QAAQ,WAAW,KAAK,CAAC,UAAW,QAAO,EAAE,QAAQ,QAAQ;AACjE,SAAO,YAAY,EAAE,QAAQ,MAAM,SAAS,OAAO,IAAI,EAAE,QAAQ,MAAM,QAAQ;AACjF;AAEO,SAAS,cAA6B;AAC3C,SAAO,EAAE,QAAQ,QAAQ;AAC3B;AAEO,SAAS,YAAY,QAAgC;AAC1D,SAAO,EAAE,QAAQ,eAAe,OAAO;AACzC;AAEO,SAAS,QAAQ,QAAgB,cAAuC;AAC7E,SAAO,iBAAiB,SACpB,EAAE,QAAQ,WAAW,OAAO,IAC5B,EAAE,QAAQ,WAAW,QAAQ,aAAa;AAChD;AAEO,SAAS,SAAS,QAAiC;AACxD,SAAO,WAAW,SAAY,EAAE,QAAQ,UAAU,IAAI,EAAE,QAAQ,WAAW,OAAO;AACpF;AAEO,SAAS,OAAO,QAAgB,YAAY,OAAuB;AACxE,SAAO,EAAE,QAAQ,SAAS,QAAQ,UAAU;AAC9C;AAEO,SAAS,UAAU,SAAkE;AAC1F,SAAO,QAAQ,WAAW,QAAQ,QAAQ,WAAW;AACvD;AAOO,SAAS,iBAAiB,OAAgC;AAC/D,MAAI,mBAAmB,KAAK,GAAG;AAC7B,YAAQ,MAAM,MAAM;AAAA,MAClB,KAAK;AACH,eAAO,SAAS,MAAM,OAAO;AAAA,MAC/B,KAAK;AACH,eAAO,SAAS,MAAM,OAAO;AAAA,MAC/B,KAAK;AACH,eAAO,QAAQ,MAAM,SAAS,MAAM,YAAY;AAAA,MAClD,KAAK;AAAA,MACL,KAAK;AACH,eAAO,OAAO,MAAM,SAAS,KAAK;AAAA,MACpC,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AACH,eAAO,OAAO,MAAM,SAAS,IAAI;AAAA,IACrC;AAAA,EACF;AACA,MAAI,iBAAiB,SAAS,MAAM,SAAS,cAAc;AACzD,WAAO,SAAS,MAAM,OAAO;AAAA,EAC/B;AACA,SAAO,OAAO,aAAa,KAAK,GAAG,KAAK;AAC1C;",
+  "names": []
+}

package/dist/contract/policy.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+const MODEL_ADAPTER_TIMEOUT_MS = 45e3;
+const DEFAULT_POLICY = {
+  settleMode: "quorum",
+  concurrency: 2,
+  minResults: 5,
+  minAdapters: 1,
+  minConfidence: 0,
+  // The soft deadline only binds once results exist, so a fast adapter still
+  // settles the run in about a second; this ceiling is what a lone slow adapter
+  // is allowed to use, not what a normal search costs.
+  softDeadlineMs: 6e3,
+  hardDeadlineMs: 6e4,
+  adapterTimeoutMs: 8e3,
+  maxPerDomain: 3,
+  cacheTtlMs: 9e5,
+  lastResort: "model-native",
+  escalateToBrowser: true,
+  content: { enabledByDefault: false, maxPages: 3, maxBytesPerPage: 128 * 1024 },
+  adapters: []
+};
+const adapterPolicyEntrySchema = z.object({
+  id: z.string().min(1),
+  enabled: z.boolean().optional(),
+  order: z.number().int().min(0).optional(),
+  weight: z.number().min(0).max(10).optional(),
+  timeoutMs: z.number().int().min(250).max(12e4).optional(),
+  maxCallsPerHour: z.number().int().min(1).max(1e6).optional()
+});
+const searchPolicySchema = z.object({
+  settleMode: z.enum(["race", "quorum", "exhaustive"]).optional(),
+  concurrency: z.number().int().min(1).max(16).optional(),
+  minResults: z.number().int().min(1).max(50).optional(),
+  minAdapters: z.number().int().min(1).max(16).optional(),
+  minConfidence: z.number().min(0).max(1).optional(),
+  softDeadlineMs: z.number().int().min(250).max(12e4).optional(),
+  hardDeadlineMs: z.number().int().min(500).max(18e4).optional(),
+  adapterTimeoutMs: z.number().int().min(250).max(12e4).optional(),
+  maxPerDomain: z.number().int().min(1).max(50).optional(),
+  cacheTtlMs: z.number().int().min(0).max(864e5).optional(),
+  lastResort: z.string().min(1).nullable().optional(),
+  escalateToBrowser: z.boolean().optional(),
+  content: z.object({
+    enabledByDefault: z.boolean().optional(),
+    maxPages: z.number().int().min(0).max(20).optional(),
+    maxBytesPerPage: z.number().int().min(1024).max(4 * 1024 * 1024).optional()
+  }).optional(),
+  adapters: z.array(adapterPolicyEntrySchema).optional()
+});
+function resolvePolicy(input) {
+  const patch = input ?? {};
+  const hardDeadlineMs = patch.hardDeadlineMs ?? DEFAULT_POLICY.hardDeadlineMs;
+  const softDeadlineMs = Math.min(patch.softDeadlineMs ?? DEFAULT_POLICY.softDeadlineMs, hardDeadlineMs);
+  return {
+    settleMode: patch.settleMode ?? DEFAULT_POLICY.settleMode,
+    concurrency: patch.concurrency ?? DEFAULT_POLICY.concurrency,
+    minResults: patch.minResults ?? DEFAULT_POLICY.minResults,
+    minAdapters: patch.minAdapters ?? DEFAULT_POLICY.minAdapters,
+    minConfidence: patch.minConfidence ?? DEFAULT_POLICY.minConfidence,
+    softDeadlineMs,
+    hardDeadlineMs,
+    adapterTimeoutMs: Math.min(patch.adapterTimeoutMs ?? DEFAULT_POLICY.adapterTimeoutMs, hardDeadlineMs),
+    maxPerDomain: patch.maxPerDomain ?? DEFAULT_POLICY.maxPerDomain,
+    cacheTtlMs: patch.cacheTtlMs ?? DEFAULT_POLICY.cacheTtlMs,
+    lastResort: patch.lastResort === void 0 ? DEFAULT_POLICY.lastResort : patch.lastResort,
+    escalateToBrowser: patch.escalateToBrowser ?? DEFAULT_POLICY.escalateToBrowser,
+    content: {
+      enabledByDefault: patch.content?.enabledByDefault ?? DEFAULT_POLICY.content.enabledByDefault,
+      maxPages: patch.content?.maxPages ?? DEFAULT_POLICY.content.maxPages,
+      maxBytesPerPage: patch.content?.maxBytesPerPage ?? DEFAULT_POLICY.content.maxBytesPerPage
+    },
+    adapters: (patch.adapters ?? []).map((entry, index) => ({
+      id: entry.id,
+      enabled: entry.enabled ?? true,
+      order: entry.order ?? index,
+      weight: entry.weight ?? 1,
+      // Clamped to the hard deadline for the same reason the shared budget is:
+      // a per-adapter timeout past it can never be reached.
+      ...entry.timeoutMs === void 0 ? {} : { timeoutMs: Math.min(entry.timeoutMs, hardDeadlineMs) },
+      ...entry.maxCallsPerHour === void 0 ? {} : { maxCallsPerHour: entry.maxCallsPerHour }
+    }))
+  };
+}
+export {
+  DEFAULT_POLICY,
+  MODEL_ADAPTER_TIMEOUT_MS,
+  adapterPolicyEntrySchema,
+  resolvePolicy,
+  searchPolicySchema
+};
+//# sourceMappingURL=policy.js.map

package/dist/contract/policy.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/contract/policy.ts"],
+  "sourcesContent": ["import { z } from 'zod'\n\nexport type SettleMode = 'race' | 'quorum' | 'exhaustive'\n\nexport type AdapterPolicyEntry = {\n  readonly id: string\n  readonly enabled: boolean\n  readonly order: number\n  /** Relative pull in the fusion step; higher trusts this adapter's ranking more. */\n  readonly weight: number\n  /**\n   * Overrides `adapterTimeoutMs` for this adapter alone. Latency is not uniform\n   * across kinds: a SERP read finishes in about a second, while a model doing its\n   * own multi-step web search takes tens of seconds. One shared budget has to be\n   * either too tight for the model or too slack for everything else.\n   */\n  readonly timeoutMs?: number\n  /**\n   * Ceiling on how often this adapter may be called, per tenant, per hour.\n   *\n   * The engine does not enforce this \u2014 it is per-request and has no memory. The\n   * host counts calls and simply stops enabling the adapter once the ceiling is\n   * reached, which is why the knob lives on the policy rather than in the engine.\n   * Undefined means no ceiling.\n   */\n  readonly maxCallsPerHour?: number\n}\n\nexport type ContentPolicy = {\n  readonly enabledByDefault: boolean\n  readonly maxPages: number\n  readonly maxBytesPerPage: number\n}\n\nexport type SearchPolicy = {\n  readonly settleMode: SettleMode\n  readonly concurrency: number\n  readonly minResults: number\n  readonly minAdapters: number\n  readonly minConfidence: number\n  readonly softDeadlineMs: number\n  readonly hardDeadlineMs: number\n  readonly adapterTimeoutMs: number\n  readonly maxPerDomain: number\n  readonly cacheTtlMs: number\n  /**\n   * Adapter run when every wave is exhausted and the fused set is still short,\n   * even if it is disabled in the normal order. This is what makes \"the engine\n   * always returns something\" true rather than aspirational.\n   */\n  readonly lastResort: string | null\n  readonly escalateToBrowser: boolean\n  readonly content: ContentPolicy\n  readonly adapters: readonly AdapterPolicyEntry[]\n}\n\n/**\n * Budget for `model-native`, the adapter enabled by default. It runs the model's\n * own multi-step web search, which measures at roughly 30s end to end, so the\n * generic adapter budget would time it out on every single run and the shipped\n * configuration could never return anything.\n */\nexport const MODEL_ADAPTER_TIMEOUT_MS = 45_000\n\nexport const DEFAULT_POLICY: SearchPolicy = {\n  settleMode: 'quorum',\n  concurrency: 2,\n  minResults: 5,\n  minAdapters: 1,\n  minConfidence: 0,\n  // The soft deadline only binds once results exist, so a fast adapter still\n  // settles the run in about a second; this ceiling is what a lone slow adapter\n  // is allowed to use, not what a normal search costs.\n  softDeadlineMs: 6_000,\n  hardDeadlineMs: 60_000,\n  adapterTimeoutMs: 8_000,\n  maxPerDomain: 3,\n  cacheTtlMs: 900_000,\n  lastResort: 'model-native',\n  escalateToBrowser: true,\n  content: { enabledByDefault: false, maxPages: 3, maxBytesPerPage: 128 * 1024 },\n  adapters: [],\n}\n\nexport const adapterPolicyEntrySchema = z.object({\n  id: z.string().min(1),\n  enabled: z.boolean().optional(),\n  order: z.number().int().min(0).optional(),\n  weight: z.number().min(0).max(10).optional(),\n  timeoutMs: z.number().int().min(250).max(120_000).optional(),\n  maxCallsPerHour: z.number().int().min(1).max(1_000_000).optional(),\n})\n\nexport const searchPolicySchema = z.object({\n  settleMode: z.enum(['race', 'quorum', 'exhaustive']).optional(),\n  concurrency: z.number().int().min(1).max(16).optional(),\n  minResults: z.number().int().min(1).max(50).optional(),\n  minAdapters: z.number().int().min(1).max(16).optional(),\n  minConfidence: z.number().min(0).max(1).optional(),\n  softDeadlineMs: z.number().int().min(250).max(120_000).optional(),\n  hardDeadlineMs: z.number().int().min(500).max(180_000).optional(),\n  adapterTimeoutMs: z.number().int().min(250).max(120_000).optional(),\n  maxPerDomain: z.number().int().min(1).max(50).optional(),\n  cacheTtlMs: z.number().int().min(0).max(86_400_000).optional(),\n  lastResort: z.string().min(1).nullable().optional(),\n  escalateToBrowser: z.boolean().optional(),\n  content: z\n    .object({\n      enabledByDefault: z.boolean().optional(),\n      maxPages: z.number().int().min(0).max(20).optional(),\n      maxBytesPerPage: z.number().int().min(1024).max(4 * 1024 * 1024).optional(),\n    })\n    .optional(),\n  adapters: z.array(adapterPolicyEntrySchema).optional(),\n})\n\nexport type SearchPolicyInput = z.infer<typeof searchPolicySchema>\n\n/**\n * Merges a partial policy over the defaults. Deadlines are reconciled rather\n * than trusted: a soft deadline past the hard one would make the scheduler wait\n * for a barrier it can never reach.\n */\nexport function resolvePolicy(input: SearchPolicyInput | null | undefined): SearchPolicy {\n  const patch = input ?? {}\n  const hardDeadlineMs = patch.hardDeadlineMs ?? DEFAULT_POLICY.hardDeadlineMs\n  const softDeadlineMs = Math.min(patch.softDeadlineMs ?? DEFAULT_POLICY.softDeadlineMs, hardDeadlineMs)\n  return {\n    settleMode: patch.settleMode ?? DEFAULT_POLICY.settleMode,\n    concurrency: patch.concurrency ?? DEFAULT_POLICY.concurrency,\n    minResults: patch.minResults ?? DEFAULT_POLICY.minResults,\n    minAdapters: patch.minAdapters ?? DEFAULT_POLICY.minAdapters,\n    minConfidence: patch.minConfidence ?? DEFAULT_POLICY.minConfidence,\n    softDeadlineMs,\n    hardDeadlineMs,\n    adapterTimeoutMs: Math.min(patch.adapterTimeoutMs ?? DEFAULT_POLICY.adapterTimeoutMs, hardDeadlineMs),\n    maxPerDomain: patch.maxPerDomain ?? DEFAULT_POLICY.maxPerDomain,\n    cacheTtlMs: patch.cacheTtlMs ?? DEFAULT_POLICY.cacheTtlMs,\n    lastResort: patch.lastResort === undefined ? DEFAULT_POLICY.lastResort : patch.lastResort,\n    escalateToBrowser: patch.escalateToBrowser ?? DEFAULT_POLICY.escalateToBrowser,\n    content: {\n      enabledByDefault: patch.content?.enabledByDefault ?? DEFAULT_POLICY.content.enabledByDefault,\n      maxPages: patch.content?.maxPages ?? DEFAULT_POLICY.content.maxPages,\n      maxBytesPerPage: patch.content?.maxBytesPerPage ?? DEFAULT_POLICY.content.maxBytesPerPage,\n    },\n    adapters: (patch.adapters ?? []).map((entry, index) => ({\n      id: entry.id,\n      enabled: entry.enabled ?? true,\n      order: entry.order ?? index,\n      weight: entry.weight ?? 1,\n      // Clamped to the hard deadline for the same reason the shared budget is:\n      // a per-adapter timeout past it can never be reached.\n      ...(entry.timeoutMs === undefined ? {} : { timeoutMs: Math.min(entry.timeoutMs, hardDeadlineMs) }),\n      ...(entry.maxCallsPerHour === undefined ? {} : { maxCallsPerHour: entry.maxCallsPerHour }),\n    })),\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/contract/results.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+const searchRequestSchema = z.object({
+  query: z.string().trim().min(1).max(500),
+  limit: z.number().int().min(1).max(50).optional(),
+  locale: z.string().min(2).max(16).optional(),
+  freshness: z.enum(["day", "week", "month", "year"]).optional(),
+  site: z.string().min(1).max(253).optional(),
+  includeContent: z.boolean().optional()
+});
+export {
+  searchRequestSchema
+};
+//# sourceMappingURL=results.js.map

package/dist/contract/results.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/contract/results.ts"],
+  "sourcesContent": ["import { z } from 'zod'\n\nexport type Freshness = 'day' | 'week' | 'month' | 'year'\n\n/** Normalized request handed to adapters. The engine resolves defaults first. */\nexport type SearchRequest = {\n  readonly query: string\n  readonly limit: number\n  readonly locale?: string\n  readonly freshness?: Freshness\n  readonly site?: string\n}\n\n/**\n * What an adapter returns per hit. Everything but `url` is optional because\n * sources differ wildly \u2014 an LLM citation list has no snippet, a SERP has no\n * content, a scraping API has both.\n */\nexport type RawResult = {\n  readonly url: string\n  readonly title?: string | null\n  readonly snippet?: string | null\n  readonly content?: string | null\n  readonly publishedAt?: string | null\n  /** Adapter-native relevance, used only to break ties within one adapter. */\n  readonly score?: number | null\n}\n\nexport type ResultProvenance = {\n  readonly adapterId: string\n  readonly rank: number\n}\n\n/** A hit after canonicalization, dedup and cross-adapter fusion. */\nexport type SearchResult = {\n  readonly url: string\n  readonly title: string\n  readonly snippet: string | null\n  readonly content: string | null\n  readonly publishedAt: string | null\n  readonly confidence: number\n  readonly sources: readonly ResultProvenance[]\n}\n\nexport type RenderMode = 'auto' | 'never' | 'always'\n\nexport type FetchRequest = {\n  readonly url: string\n  readonly maxBytes?: number\n  readonly render?: RenderMode\n}\n\n/**\n * Why an HTTP read was judged insufficient. Drives browser escalation, and is\n * reported back so the decision is auditable rather than invisible.\n */\nexport type PageVerdict = 'ok' | 'js-shell' | 'blocked' | 'empty'\n\nexport type FetchedPage = {\n  readonly url: string\n  readonly title: string | null\n  readonly text: string\n  readonly contentType: string | null\n  readonly status: number\n  readonly truncated: boolean\n  readonly renderedWith: 'http' | 'browser'\n  readonly escalatedBecause?: PageVerdict\n}\n\nexport const searchRequestSchema = z.object({\n  query: z.string().trim().min(1).max(500),\n  limit: z.number().int().min(1).max(50).optional(),\n  locale: z.string().min(2).max(16).optional(),\n  freshness: z.enum(['day', 'week', 'month', 'year']).optional(),\n  site: z.string().min(1).max(253).optional(),\n  includeContent: z.boolean().optional(),\n})\n\nexport type SearchRequestInput = z.infer<typeof searchRequestSchema>\n"],
+  "mappings": "AAAA,SAAS,SAAS;AAqEX,MAAM,sBAAsB,EAAE,OAAO;AAAA,EAC1C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG;AAAA,EACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,SAAS;AAAA,EAChD,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,SAAS;AAAA,EAC3C,WAAW,EAAE,KAAK,CAAC,OAAO,QAAQ,SAAS,MAAM,CAAC,EAAE,SAAS;AAAA,EAC7D,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,EAAE,SAAS;AAAA,EAC1C,gBAAgB,EAAE,QAAQ,EAAE,SAAS;AACvC,CAAC;",
+  "names": []
+}

package/dist/contract/steps.js

@@ -0,0 +1 @@
+//# sourceMappingURL=steps.js.map

package/dist/contract/steps.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/contract/version.js

@@ -0,0 +1,11 @@
+const CONTRACT_VERSION = 1;
+const MIN_SUPPORTED_CONTRACT_VERSION = 1;
+function isSupportedContractVersion(version) {
+  return typeof version === "number" && Number.isInteger(version) && version >= MIN_SUPPORTED_CONTRACT_VERSION && version <= CONTRACT_VERSION;
+}
+export {
+  CONTRACT_VERSION,
+  MIN_SUPPORTED_CONTRACT_VERSION,
+  isSupportedContractVersion
+};
+//# sourceMappingURL=version.js.map

package/dist/contract/version.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/contract/version.ts"],
+  "sourcesContent": ["/**\n * Adapter contract version. Adapter packages declare the version they were built\n * against; the loader refuses to instantiate a mismatched major rather than let a\n * stale adapter fail in an unpredictable place at request time.\n */\nexport const CONTRACT_VERSION = 1\n\n/**\n * Oldest adapter contract this engine still accepts.\n *\n * An exact-match check makes every bump a flag day: a purely additive change\n * would disable every third-party adapter at once, with nothing wrong with any\n * of them. A range lets an additive bump raise `CONTRACT_VERSION` while leaving\n * this behind, and a genuinely breaking one raise both together.\n */\nexport const MIN_SUPPORTED_CONTRACT_VERSION = 1\n\nexport function isSupportedContractVersion(version: unknown): version is number {\n  return (\n    typeof version === 'number' &&\n    Number.isInteger(version) &&\n    version >= MIN_SUPPORTED_CONTRACT_VERSION &&\n    version <= CONTRACT_VERSION\n  )\n}\n"],
+  "mappings": "AAKO,MAAM,mBAAmB;AAUzB,MAAM,iCAAiC;AAEvC,SAAS,2BAA2B,SAAqC;AAC9E,SACE,OAAO,YAAY,YACnB,OAAO,UAAU,OAAO,KACxB,WAAW,kCACX,WAAW;AAEf;",
+  "names": []
+}

package/dist/engine/cache.js

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+function buildCacheKey(request, adapterIds) {
+  const payload = JSON.stringify({
+    query: request.query.trim().toLowerCase(),
+    limit: request.limit,
+    locale: request.locale ?? null,
+    freshness: request.freshness ?? null,
+    site: request.site ?? null,
+    adapters: [...adapterIds].sort((left, right) => left < right ? -1 : left > right ? 1 : 0)
+  });
+  return createHash("sha256").update(payload).digest("hex");
+}
+function createSingleFlight() {
+  const inflight = /* @__PURE__ */ new Map();
+  return (key, run) => {
+    const existing = inflight.get(key);
+    if (existing) return existing;
+    const promise = run().finally(() => {
+      inflight.delete(key);
+    });
+    inflight.set(key, promise);
+    return promise;
+  };
+}
+export {
+  buildCacheKey,
+  createSingleFlight
+};
+//# sourceMappingURL=cache.js.map

package/dist/engine/cache.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/engine/cache.ts"],
+  "sourcesContent": ["import { createHash } from 'node:crypto'\nimport type { SearchRequest } from '../contract/results'\n\nexport type CacheEntry<T> = {\n  readonly value: T\n  readonly storedAt: number\n}\n\n/**\n * Storage seam. Deliberately narrow so a host can back it with any store, and\n * deliberately failable \u2014 a cache outage must degrade to a live search, never to\n * an error, so implementations should swallow their own faults.\n */\nexport type ResultCache<T> = {\n  get(key: string): Promise<T | null>\n  set(key: string, value: T, ttlMs: number): Promise<void>\n}\n\nexport function buildCacheKey(request: SearchRequest, adapterIds: readonly string[]): string {\n  const payload = JSON.stringify({\n    query: request.query.trim().toLowerCase(),\n    limit: request.limit,\n    locale: request.locale ?? null,\n    freshness: request.freshness ?? null,\n    site: request.site ?? null,\n    adapters: [...adapterIds].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0)),\n  })\n  return createHash('sha256').update(payload).digest('hex')\n}\n\n/**\n * Collapses concurrent identical calls onto one execution. A fan-out of agents\n * asking the same question hits each adapter once instead of once per agent.\n */\nexport function createSingleFlight<T>(): (key: string, run: () => Promise<T>) => Promise<T> {\n  const inflight = new Map<string, Promise<T>>()\n  return (key, run) => {\n    const existing = inflight.get(key)\n    if (existing) return existing\n    const promise = run().finally(() => {\n      inflight.delete(key)\n    })\n    inflight.set(key, promise)\n    return promise\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,kBAAkB;AAkBpB,SAAS,cAAc,SAAwB,YAAuC;AAC3F,QAAM,UAAU,KAAK,UAAU;AAAA,IAC7B,OAAO,QAAQ,MAAM,KAAK,EAAE,YAAY;AAAA,IACxC,OAAO,QAAQ;AAAA,IACf,QAAQ,QAAQ,UAAU;AAAA,IAC1B,WAAW,QAAQ,aAAa;AAAA,IAChC,MAAM,QAAQ,QAAQ;AAAA,IACtB,UAAU,CAAC,GAAG,UAAU,EAAE,KAAK,CAAC,MAAM,UAAW,OAAO,QAAQ,KAAK,OAAO,QAAQ,IAAI,CAAE;AAAA,EAC5F,CAAC;AACD,SAAO,WAAW,QAAQ,EAAE,OAAO,OAAO,EAAE,OAAO,KAAK;AAC1D;AAMO,SAAS,qBAA4E;AAC1F,QAAM,WAAW,oBAAI,IAAwB;AAC7C,SAAO,CAAC,KAAK,QAAQ;AACnB,UAAM,WAAW,SAAS,IAAI,GAAG;AACjC,QAAI,SAAU,QAAO;AACrB,UAAM,UAAU,IAAI,EAAE,QAAQ,MAAM;AAClC,eAAS,OAAO,GAAG;AAAA,IACrB,CAAC;AACD,aAAS,IAAI,KAAK,OAAO;AACzB,WAAO;AAAA,EACT;AACF;",
+  "names": []
+}

package/dist/engine/deadline.js

@@ -0,0 +1,54 @@
+const DEADLINE_REACHED = /* @__PURE__ */ Symbol("web-research/deadline");
+function deadlineRace(ms) {
+  let cancel = () => {
+  };
+  const promise = new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(DEADLINE_REACHED), Math.max(0, ms));
+    timer.unref?.();
+    cancel = () => {
+      clearTimeout(timer);
+    };
+  });
+  return { promise, cancel };
+}
+function sleep(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(finish, ms);
+    function finish() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", finish);
+      resolve();
+    }
+    signal?.addEventListener("abort", finish, { once: true });
+  });
+}
+function linkSignals(signals) {
+  const controller = new AbortController();
+  const active = signals.filter((candidate) => candidate !== void 0);
+  const abort = () => {
+    controller.abort();
+  };
+  for (const signal of active) {
+    if (signal.aborted) {
+      controller.abort();
+      break;
+    }
+  }
+  if (!controller.signal.aborted) {
+    for (const signal of active) signal.addEventListener("abort", abort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      for (const signal of active) signal.removeEventListener("abort", abort);
+    }
+  };
+}
+export {
+  DEADLINE_REACHED,
+  deadlineRace,
+  linkSignals,
+  sleep
+};
+//# sourceMappingURL=deadline.js.map

package/dist/engine/deadline.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/engine/deadline.ts"],
+  "sourcesContent": ["export const DEADLINE_REACHED = Symbol('web-research/deadline')\n\nexport type DeadlineSignal = typeof DEADLINE_REACHED\n\nexport type Cancellable<T> = {\n  readonly promise: Promise<T>\n  cancel(): void\n}\n\n/** A race participant that resolves once `ms` elapses and can be torn down. */\nexport function deadlineRace(ms: number): Cancellable<DeadlineSignal> {\n  let cancel = (): void => {}\n  const promise = new Promise<DeadlineSignal>((resolve) => {\n    const timer = setTimeout(() => resolve(DEADLINE_REACHED), Math.max(0, ms))\n    timer.unref?.()\n    cancel = () => {\n      clearTimeout(timer)\n    }\n  })\n  return { promise, cancel }\n}\n\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  if (ms <= 0) return Promise.resolve()\n  return new Promise((resolve) => {\n    const timer = setTimeout(finish, ms)\n    function finish(): void {\n      clearTimeout(timer)\n      signal?.removeEventListener('abort', finish)\n      resolve()\n    }\n    signal?.addEventListener('abort', finish, { once: true })\n  })\n}\n\n/**\n * Aborts when any input aborts. Node's `AbortSignal.any` exists on modern\n * runtimes but is wrapped here so teardown is explicit and listeners are always\n * removed \u2014 an engine run creates one of these per adapter per request.\n */\nexport function linkSignals(signals: ReadonlyArray<AbortSignal | undefined>): {\n  readonly signal: AbortSignal\n  dispose(): void\n} {\n  const controller = new AbortController()\n  const active = signals.filter((candidate): candidate is AbortSignal => candidate !== undefined)\n  const abort = (): void => {\n    controller.abort()\n  }\n  for (const signal of active) {\n    if (signal.aborted) {\n      controller.abort()\n      break\n    }\n  }\n  if (!controller.signal.aborted) {\n    for (const signal of active) signal.addEventListener('abort', abort, { once: true })\n  }\n  return {\n    signal: controller.signal,\n    dispose: () => {\n      for (const signal of active) signal.removeEventListener('abort', abort)\n    },\n  }\n}\n"],
+  "mappings": "AAAO,MAAM,mBAAmB,uBAAO,uBAAuB;AAUvD,SAAS,aAAa,IAAyC;AACpE,MAAI,SAAS,MAAY;AAAA,EAAC;AAC1B,QAAM,UAAU,IAAI,QAAwB,CAAC,YAAY;AACvD,UAAM,QAAQ,WAAW,MAAM,QAAQ,gBAAgB,GAAG,KAAK,IAAI,GAAG,EAAE,CAAC;AACzE,UAAM,QAAQ;AACd,aAAS,MAAM;AACb,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,CAAC;AACD,SAAO,EAAE,SAAS,OAAO;AAC3B;AAEO,SAAS,MAAM,IAAY,QAAqC;AACrE,MAAI,MAAM,EAAG,QAAO,QAAQ,QAAQ;AACpC,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,UAAM,QAAQ,WAAW,QAAQ,EAAE;AACnC,aAAS,SAAe;AACtB,mBAAa,KAAK;AAClB,cAAQ,oBAAoB,SAAS,MAAM;AAC3C,cAAQ;AAAA,IACV;AACA,YAAQ,iBAAiB,SAAS,QAAQ,EAAE,MAAM,KAAK,CAAC;AAAA,EAC1D,CAAC;AACH;AAOO,SAAS,YAAY,SAG1B;AACA,QAAM,aAAa,IAAI,gBAAgB;AACvC,QAAM,SAAS,QAAQ,OAAO,CAAC,cAAwC,cAAc,MAAS;AAC9F,QAAM,QAAQ,MAAY;AACxB,eAAW,MAAM;AAAA,EACnB;AACA,aAAW,UAAU,QAAQ;AAC3B,QAAI,OAAO,SAAS;AAClB,iBAAW,MAAM;AACjB;AAAA,IACF;AAAA,EACF;AACA,MAAI,CAAC,WAAW,OAAO,SAAS;AAC9B,eAAW,UAAU,OAAQ,QAAO,iBAAiB,SAAS,OAAO,EAAE,MAAM,KAAK,CAAC;AAAA,EACrF;AACA,SAAO;AAAA,IACL,QAAQ,WAAW;AAAA,IACnB,SAAS,MAAM;AACb,iBAAW,UAAU,OAAQ,QAAO,oBAAoB,SAAS,KAAK;AAAA,IACxE;AAAA,EACF;AACF;",
+  "names": []
+}