@workglow/test-contract 0.6.1

package/dist/web-search/assertions/credentialNaming.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WebSearchProviderConformanceOpts } from "../types";
+/**
+ * A credential is named for a provider, never for the request.
+ *
+ * `credential_keys` maps provider name to credential-store key, and the key
+ * sent is the one named for the provider that RAN — so a key issued for one
+ * vendor cannot leave with a request to another. That is not a tidiness rule:
+ * a search API key is a bearer credential against a metered account, and one
+ * forwarded to the wrong vendor has been disclosed to them.
+ *
+ * The bare `credential_key` port survives for a pinned provider, where the
+ * vendor is unambiguous, and is refused under `"auto"` for the same reason:
+ * routing picks the vendor at run time, so an unnamed key goes wherever it
+ * lands.
+ */
+export declare function credentialNamingBlock(opts: WebSearchProviderConformanceOpts): void;

package/dist/web-search/assertions/dateFiltering.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WebSearchProviderConformanceOpts } from "../types";
+/**
+ * Date filtering is never emulated, and never half-sent.
+ *
+ * Post-filtering by `publishedDate` breaks `maxResults` and drops every result
+ * whose date the provider omitted, so a provider that cannot filter server-side
+ * declares `dateFilter: false` and such a request is refused rather than
+ * approximated. That is the half most people expect.
+ *
+ * The other half is what a provider declaring `true` then owes: something for
+ * EVERY range this task accepts. The real APIs take closed intervals — Brave's
+ * `freshness`, Gemini's `timeRangeFilter` — so a half-open range has to be
+ * filled at the open end. Dropping it instead reports a bound as honored on a
+ * search that ran unfiltered, which is the failure the refusal above exists to
+ * avoid, arrived at by a different road.
+ */
+export declare function dateFilteringBlock(opts: WebSearchProviderConformanceOpts): void;

package/dist/web-search/assertions/domainNormalization.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WebSearchProviderConformanceOpts } from "../types";
+/**
+ * A domain entry means the same thing whichever route carries it.
+ *
+ * There are two routes — a native domain list, and a `site:` clause spliced
+ * into the query — and the same entry has to reduce identically on both. It did
+ * not once: reducing only on the way into an operator left `"https://arxiv.org/"`
+ * restricting one route and reaching a vendor API scheme-first on the other,
+ * where it matches nothing. Under `"auto"` the caller cannot even tell which
+ * route ran, so the search comes back successful, reports the provider, and
+ * silently searched the whole web.
+ *
+ * An unusable entry is refused for the same reason, and for EVERY provider
+ * rather than only the ones translating to `site:`. Dropping it is the same
+ * trade one step worse: the translation emits no clause for an empty list and
+ * the task clears the list afterwards, so one bad entry in a one-entry list
+ * removes the restriction from both paths at once.
+ */
+export declare function domainNormalizationBlock(opts: WebSearchProviderConformanceOpts): void;

package/dist/web-search/assertions/maxResultsCeiling.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WebSearchProviderConformanceOpts } from "../types";
+/**
+ * `maxResults` is a ceiling, and it means the same thing on every route.
+ *
+ * It is the one option `unhonorableOptions` deliberately never reports: asking
+ * for more results than a provider's cap is not a requirement the way a domain
+ * restriction is, so an over-large value is clamped rather than refused. That
+ * asymmetry is what makes the rest of it worth asserting — a provider is free
+ * to return fewer, and never free to return more, and neither half is visible
+ * to a caller who gets a plausible-looking list back.
+ *
+ * Three providers needed a fix for exactly this in one window, each found by
+ * hand on its own route: an API with no result parameter has to apply the bound
+ * itself after the fact, and every one that forgot returned whatever the vendor
+ * felt like.
+ */
+export declare function maxResultsCeilingBlock(opts: WebSearchProviderConformanceOpts): void;

package/dist/web-search/assertions/reportedQuery.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WebSearchProviderConformanceOpts } from "../types";
+/**
+ * The `query` output port is the query that ran, and `provider` is who ran it.
+ *
+ * Both exist because the task rewrites one and chooses the other. A
+ * `query-operator` provider has its domain restriction spliced into the query
+ * as `site:` clauses, so the string that ran is not the string the caller
+ * passed — and an adapter that echoes the input instead is reporting a search
+ * that did not happen. Under `"auto"` the caller did not pick the vendor
+ * either, so `provider` is the only record of which quota was spent and which
+ * engine's ranking produced the list.
+ */
+export declare function reportedQueryBlock(opts: WebSearchProviderConformanceOpts): void;

package/dist/web-search/assertions/signalThreading.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WebSearchProviderConformanceOpts } from "../types";
+/**
+ * The run's signal reaches the call, not just a check in front of it.
+ *
+ * A `throwIfAborted()` before the request answers the easy half — a run already
+ * cancelled does not start one — and leaves the expensive half alone: a
+ * cancelled run whose request is already in flight keeps it in flight, and a
+ * grounded turn nobody is waiting for is still billed for every token it
+ * generates. The signal has to be handed to the transport itself.
+ *
+ * Asserted on what the adapter passed outward rather than on how fast the
+ * promise rejects. A rejection proves the task stopped waiting; only the signal
+ * on the call proves the call stopped running.
+ */
+export declare function signalThreadingBlock(opts: WebSearchProviderConformanceOpts): void;

package/dist/web-search/fixtures.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IWebSearchProvider, WebSearchRequest } from "@workglow/web-search";
+import type { WebSearchConformanceHarness } from "./types";
+/** The query every assertion searches for, so a rewrite of it is visible. */
+export declare const PROBE_QUERY = "transformer architecture";
+/**
+ * A provider registered beside the one under test, so `"auto"` has somewhere
+ * else to land and a credential can be named for a vendor that is not this one.
+ *
+ * It declares everything, which is what makes it a useful foil: routing prefers
+ * a provider a key is named for, so a decoy that could serve the request is the
+ * only way to catch a key reaching the wrong vendor.
+ */
+export declare function decoyProvider(name: string, onSearch?: (r: WebSearchRequest) => void): IWebSearchProvider;
+/** Registers the provider under test alone, the state most assertions want. */
+export declare function registerOnly(harness: WebSearchConformanceHarness): void;
+/**
+ * Whether a domain restriction reaches this provider as a list or as `site:`
+ * operators spliced into the query. The exclude direction defaults to the
+ * include direction, exactly as the task reads it.
+ */
+export declare function domainRoutes(provider: IWebSearchProvider): {
+    readonly include: "native" | "query-operator" | false;
+    readonly exclude: "native" | "query-operator" | false;
+};
+/**
+ * Everything one search sent, as a single string to look for a substring in.
+ *
+ * The decoded rendering is appended rather than substituted, so a value matches
+ * whichever way this provider carried it. One sends `site:example.com` in a
+ * JSON body and the next sends `site%3Aexample.com` in a query string; both are
+ * the same restriction, and a suite that reads only the raw bytes would report
+ * the second as a restriction that never left. Appending keeps the equality
+ * assertions exact — two sends are equal here only if their raw forms were.
+ */
+export declare function sentText(harness: WebSearchConformanceHarness): string;

package/dist/web-search/runWebSearchProviderConformance.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WebSearchProviderConformanceOpts } from "./types";
+/**
+ * Everything an `IWebSearchProvider` owes a caller, over every adapter.
+ *
+ * Seven ship — three that own an HTTP fetch, four that reach a vendor SDK for
+ * model-grounded search — and they had no shared assertions at all. What that
+ * cost is legible in the package's own history: three of its twelve fixes in
+ * one window were "make property P true on every route", each found by hand,
+ * one route at a time, after the route that already had it was shipped. A
+ * property that has to hold on every route is what a parameterized suite is
+ * for.
+ *
+ * So the assertions are derived from `WebSearchCapabilities` rather than
+ * written per provider. The record already declares what each adapter can do;
+ * reading it and asserting the matching behaviour is what makes the suite still
+ * true after a provider changes what it supports — which is the event worth
+ * catching, and the one a hand-written expectation silently outlives.
+ */
+export declare function runWebSearchProviderConformance(opts: WebSearchProviderConformanceOpts): void;

package/dist/web-search/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IWebSearchProvider, WebSearchRequest, WebSearchResponse } from "@workglow/web-search";
+/**
+ * One provider, wired to a transport that answers it instead of a vendor.
+ *
+ * The transport is the adapter's own boundary, not a network stub: an HTTP
+ * provider is intercepted at the `FetchUrlTask` it owns, an SDK-backed one at
+ * the client handed to its constructor. Both report what went out as text,
+ * which is what lets one suite assert "the option reached the wire" across two
+ * transports that share no shape.
+ */
+export interface WebSearchConformanceHarness {
+    readonly provider: IWebSearchProvider;
+    /**
+     * Everything the adapter sent outward, one entry per call, flattened to text
+     * — a URL with its query string and body, or the JSON of the SDK arguments.
+     *
+     * Flattened rather than structured because every assertion over it is
+     * differential: the same search with and without one option has to send
+     * something different. That question has an answer for every provider, where
+     * "which field carries the date bound" has a different one for each.
+     */
+    readonly sent: () => readonly string[];
+    /** The abort signal each outbound call was given, in call order. */
+    readonly signals: () => ReadonlyArray<AbortSignal | undefined>;
+    /** Runs the provider directly against this transport, under `signal`. */
+    readonly search: (request: WebSearchRequest, signal: AbortSignal) => Promise<WebSearchResponse>;
+    /** Removes the interception. Called after every test. */
+    readonly dispose: () => void;
+}
+export interface WebSearchHarnessRequest {
+    /** How many results the canned answer carries. */
+    readonly resultCount: number;
+}
+export interface WebSearchProviderConformanceOpts {
+    readonly name: string;
+    readonly skip?: boolean;
+    readonly timeout?: number;
+    /**
+     * A fresh provider and transport per test. Nothing is shared between tests: a
+     * registry is process-wide, and a provider that cached a client in one test
+     * would answer the next one's assertions about what it sent.
+     */
+    readonly createHarness: (request: WebSearchHarnessRequest) => Promise<WebSearchConformanceHarness>;
+    /**
+     * Whether the run's `AbortSignal` is handed to the outbound call itself.
+     *
+     * True for an adapter reaching a vendor SDK, where nothing else would stop a
+     * grounded turn that is still being billed. False for one whose fetch this
+     * package owns: cancellation reaches it through the `FetchUrlTask` it owns
+     * and that task's own scope, so the adapter passes no signal of its own and
+     * there is nothing at this boundary to observe. A flag rather than a silent
+     * skip, because "this adapter drops the signal" and "this adapter never held
+     * one" are the two answers that must not look alike.
+     */
+    readonly signalReachesTransport: boolean;
+    /**
+     * Whether this provider's date parameter is a CLOSED interval, so a half-open
+     * range has its missing end filled rather than sent half.
+     *
+     * Brave's `freshness` and Gemini's `timeRangeFilter` are closed and fill;
+     * Tavily sets `start_date` and `end_date` independently and correctly sends
+     * only the bound it was given. A flag rather than something the suite infers,
+     * because the two are indistinguishable from outside — and the failure it
+     * guards is a provider that drops the open end and reports the bound as
+     * honored on a search that ran unfiltered at that end. Meaningless, and
+     * ignored, when `dateFilter` is false.
+     */
+    readonly fillsOpenDateBounds: boolean;
+    /**
+     * A domain this provider's canned results sit on, used where a request has to
+     * name a real-looking host. Defaults to `example.com`.
+     */
+    readonly sampleDomain?: string;
+}

package/dist/web-search.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Conformance suite for `IWebSearchProvider` — what a provider declares in its
+ * capability record is what it refuses, what it attempts, and what it sends.
+ */
+export * from "./web-search/assertions/capabilityAgreement";
+export * from "./web-search/assertions/credentialNaming";
+export * from "./web-search/assertions/dateFiltering";
+export * from "./web-search/assertions/domainNormalization";
+export * from "./web-search/assertions/maxResultsCeiling";
+export * from "./web-search/assertions/reportedQuery";
+export * from "./web-search/assertions/signalThreading";
+export * from "./web-search/fixtures";
+export * from "./web-search/runWebSearchProviderConformance";
+export * from "./web-search/types";