@jterrazz/test 10.1.0 → 12.0.0

package/dist/index.d.ts

@@ -10,12 +10,14 @@ import { DeepMockProxy } from "vitest-mock-extended";
  * (`expected/*.txt`). One grammar, one vocabulary (CONVENTIONS D4).
  */
 /** The frozen token vocabulary (CONVENTIONS D4) plus the code-only kinds. */
-type MatcherKind = 'any' | 'base64' | 'date' | 'duration' | 'email' | 'float' | 'hex' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
+type MatcherKind = 'any' | 'base64' | 'date' | 'duration' | 'email' | 'float' | 'hex' | 'includes' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
 /**
  * A dynamic-value matcher. Created via the {@link match} factories — never
  * constructed directly by user code.
  */
 declare class Matcher {
+  /** For kind 'includes': the substring the actual value must contain. */
+  readonly includes?: string;
   readonly kind: MatcherKind;
   /** For kind 'ref': the capture to assert inequality against. */
   readonly notRef?: string;
@@ -24,6 +26,7 @@ declare class Matcher {
   /** For kind 'regex': the pattern the actual value must match. */
   readonly regex?: RegExp;
   constructor(kind: MatcherKind, options?: {
+    includes?: string;
     notRef?: string;
     refName?: string;
     regex?: RegExp;
@@ -61,6 +64,13 @@ declare const match: {
   float: () => Matcher;
   /** Matches a hexadecimal string. */
   hex: () => Matcher;
+  /**
+   * Matches a string CONTAINING the given substring. Code-only, like
+   * {@link match.regex} — the `{{token}}` fixture vocabulary does not grow.
+   * The explicit escape hatch now that contract string filters
+   * (`openai.chat({ user })`) mean exact equality.
+   */
+  includes: (substring: string) => Matcher;
   /** Matches an integer (or an integer string in text contexts). */
   int: () => Matcher;
   /** Matches an IPv4 address. */
@@ -389,43 +399,48 @@ interface CliPort {
 //#endregion
 //#region src/core/contracts/types.d.ts
 /**
- * The observed outgoing request, reduced to what trigger matchers inspect.
- * Built once per request by the MSW integration and handed to
- * {@link InterceptTrigger.match}.
+ * The observed outgoing request, reduced to what contract matchers inspect.
+ * Built once per request by the engine (MSW on api/jobs, the stub backend on
+ * website/mobile) and handed to {@link ContractRequest.match} and to a
+ * {@link ContractResponder}.
  */
 interface MatchableRequest {
   /** Parsed JSON body when the payload is JSON, the raw text otherwise, or `null` when absent. */
   body: unknown;
   /** Request headers, keyed by lowercased header name. */
   headers: Record<string, string>;
-  /** The fully-qualified request URL (including any query string). */
+  /** Uppercased HTTP method of the observed request. */
+  method: string;
+  /** The request URL — fully-qualified, or origin-relative for the stub backend. */
   url: string;
 }
 /**
- * An intercept trigger describes which HTTP request to match.
+ * The request half of a contract: which outgoing call it speaks for.
+ *
+ * `url` is either an absolute URL (string or RegExp), or a PATH FORM starting
+ * with `/` (`/articles/{{uuid}}`) which matches any origin — the shape a
+ * website/mobile app's own backend calls take. `{{token}}` segments compare
+ * structurally, declared query params are a subset of the observed ones.
  */
-interface InterceptTrigger {
-  /** Adapter name - must match the folder prefix in file-based intercepts. */
+interface ContractRequest {
+  /** Adapter name — `http` | `openai` | `anthropic`. */
   adapter: string;
-  /** HTTP method to match. */
+  /** HTTP method to match. `*` matches any method. */
   method: string;
-  /** URL pattern to match (string for exact prefix, RegExp for pattern). */
+  /** Absolute URL (string | RegExp) or an any-origin path form (`/articles/{{uuid}}`). */
   url: RegExp | string;
-  /** Optional request matcher - the handler only fires if this returns true. */
+  /** Optional request matcher — the contract only fires if this returns true. */
   match?: (request: MatchableRequest) => boolean;
-  /**
-   * Transform raw JSON data into a provider-specific response envelope.
-   * Called when .intercept(trigger, 'adapter/file.json') loads a file.
-   */
-  wrap: (data: unknown) => InterceptResponse;
+  /** Transform raw data into a provider-specific response envelope. */
+  wrap: (data: unknown) => ContractResponse;
 }
 /**
- * An intercept response describes what to return when the trigger matches.
+ * The response half of a contract: what to reply when the request matches.
  */
-interface InterceptResponse {
+interface ContractResponse {
   /** HTTP status code (default: 200). */
   status?: number;
-  /** Response body (will be JSON.stringified). */
+  /** Response body — an object is JSON, a string is text, `null`/`undefined` is empty. */
   body: unknown;
   /** Response headers. */
   headers?: Record<string, string>;
@@ -434,67 +449,101 @@ interface InterceptResponse {
 }
 /**
  * A dynamic response: computed from the observed request at the moment the
- * intercept is consumed, rather than fixed ahead of time. Handed the same
- * {@link MatchableRequest} the trigger matched on, so the reply can echo or
- * derive from the request body/headers/url.
+ * contract is served, rather than fixed ahead of time. Handed the same
+ * {@link MatchableRequest} the request half matched on, so the reply can echo
+ * or derive from the body/headers/url.
  */
-type InterceptResponder = (request: MatchableRequest) => InterceptResponse;
+type ContractResponder = (request: MatchableRequest) => ContractResponse;
 /**
- * What an intercept replies with: either a fixed {@link InterceptResponse} or
- * an {@link InterceptResponder} evaluated per consumed request.
+ * What a contract replies with: either a fixed {@link ContractResponse} or a
+ * {@link ContractResponder} evaluated per served request.
  */
-type InterceptResponseValue = InterceptResponder | InterceptResponse;
-/**
- * A fully resolved intercept entry ready to be registered with MSW.
- */
-interface InterceptEntry {
-  trigger: InterceptTrigger;
-  response: InterceptResponseValue;
-}
+type ContractResponseValue = ContractResponder | ContractResponse;
 //#endregion
 //#region src/core/contracts/contract.d.ts
 /**
- * A declared external interaction: what to match and what to reply, together
- * in one named artifact. Contracts live in flat TypeScript files under
- * `contracts/` next to the tests that use them — `<name>.<provider>.ts` with
- * `provider ∈ { openai, anthropic, http }` (CONVENTIONS C4) — so the business
- * payload (prompts, JSON responses) is visible at a glance while the real
- * HTTP call stays mocked underneath (MSW).
+ * A declared external interaction: what to match (`request`) and what to reply
+ * (`response`), together in one named artifact. Contracts live in TypeScript
+ * files under `contracts/` next to the tests that use them, so the business
+ * payload (prompts, JSON responses) is visible at a glance while the real HTTP
+ * call stays mocked underneath.
  */
-interface InterceptContract {
-  trigger: InterceptTrigger;
+interface Contract {
+  /** Which outgoing call this contract speaks for. */
+  request: ContractRequest;
   /**
-   * The reply — a fixed {@link InterceptResponse}, or a function
-   * `(request) => InterceptResponse` evaluated per consumed request when the
+   * The reply — a fixed {@link ContractResponse}, or a function
+   * `(request) => ContractResponse` evaluated per served request when the
    * response must derive from the incoming payload.
    */
-  response: InterceptResponseValue;
+  response: ContractResponseValue;
+  /**
+   * How many times this contract may serve. Omitted = unlimited (a
+   * re-render or a retry replays it). `n` = exhausted after n serves, so an
+   * ordered sequence is a finite contract followed by an unlimited tail.
+   */
+  times?: number;
+  /**
+   * When true, the chain FAILS unless the contract was actually requested:
+   * at least once, or exactly `times` times when `times` is set. Turns a
+   * silently-unused declaration into a spec failure.
+   */
+  required?: boolean;
 }
 /**
- * Declare an intercept contract. Identity function — its value is the
- * enforced shape and the naming convention:
+ * A composite of contracts — the unit tests import. Flat, ordered, immutable;
+ * `.with()` derives a variant without touching the original.
+ */
+interface Contracts {
+  /** The flattened contracts, in selection order. */
+  readonly contracts: readonly Contract[];
+  /**
+   * Derive a new composite: every base contract sharing a route with an
+   * override is REPLACED, and the overrides are PREPENDED — so a
+   * more-specific override wins first-match selection over a generic base
+   * route it does not replace.
+   */
+  with: (...overrides: (Contract | Contract[] | Contracts)[]) => Contracts;
+}
+/** Any accepted contract input: one, a list, or a composite. */
+type ContractInput = Contract | Contract[] | Contracts;
+/**
+ * Declare one contract. Identity function — its value is the enforced shape
+ * and the naming convention:
  *
  * @example
- *   // specs/api/reports/contracts/classify-article.openai.ts
+ *   // specs/api/reports/contracts/openai/classify-article.ts
  *   import { defineContract, openai } from '@jterrazz/test';
  *
  *   export default defineContract({
- *       trigger: openai.responses({ user: /Report Ingestion/, tools: ['classify'] }),
+ *       request: openai.responses({ user: PROMPT, tools: ['classify'] }),
  *       response: openai.reply({ categories: ['TECH'] }),
  *   });
  *
  *   // Dynamic — the response is computed from the observed request:
  *   export default defineContract({
- *       trigger: http.post('https://api.example.com/echo'),
+ *       request: http.post('https://api.example.com/echo'),
  *       response: (request) => http.json({ received: request.body }),
  *   });
+ */
+declare function defineContract(contract: Contract): Contract;
+/**
+ * Compose contracts into the artifact a test imports — it's contracts all the
+ * way down: a composite may extend contracts, lists, and other composites,
+ * recursively, order preserved.
  *
- *   // specs/api/reports/reports.test.ts
- *   import classifyArticle from '../../spec/intercept/contracts/classify-article.openai.js';
+ * `.with(...)` derives a scenario: contracts whose route the overrides claim
+ * are removed from the base, and the overrides are prepended. Under
+ * first-match selection a more specific override (`/articles/gone-1`) also
+ * wins over a generic base route (`/articles/{{uuid}}`) it does not replace.
  *
- *   const result = await jobs.intercept(classifyArticle).trigger('report-ingestion');
+ * @example
+ *   // contracts/newsroom.contracts.ts
+ *   export default defineContracts(events, articleById);
+ *   export const withArticleGone = (id: string) =>
+ *       newsroom.with(articleGone(id));
  */
-declare function defineContract(contract: InterceptContract): InterceptContract;
+declare function defineContracts(...items: ContractInput[]): Contracts;
 //#endregion
 //#region src/core/ports/browser.port.d.ts
 /**
@@ -975,30 +1024,6 @@ declare class PageResult extends BaseResult {
   get url(): string;
 }
 //#endregion
-//#region src/core/http-files/intercept-file.d.ts
-/** The declared request half of an exchange — the matching trigger. */
-interface ExchangeRequest {
-  /** Declared header subset — names case-insensitive, values may carry `{{token}}`s. */
-  headers: Record<string, string>;
-  method: string;
-  /** Path as written, query string included (`/articles?event_id=…`). */
-  path: string;
-}
-/** The declared response half of an exchange — the stubbed reply. */
-interface ExchangeResponse {
-  /** Parsed JSON body — or the raw text when the body is not valid JSON. */
-  body: unknown;
-  /** True when a body section is present. */
-  hasBody: boolean;
-  headers: Record<string, string>;
-  status: number;
-}
-/** One declared request/response pair of an `intercepts/*.http` file. */
-interface InterceptExchange {
-  request: ExchangeRequest;
-  response: ExchangeResponse;
-}
-//#endregion
 //#region src/core/specification/shared/stub-backend.d.ts
 /** Options for the stub backend server. */
 interface StubBackendOptions {
@@ -1009,11 +1034,10 @@ interface StubBackendOptions {
   port?: number;
 }
 declare class StubBackend {
-  private consumed;
-  private entries;
-  /** Guarded once the current chain declared at least one intercept. */
+  /** Guarded once the current chain declared at least one contract. */
   private guarded;
   private readonly options;
+  private queue;
   private server;
   private readonly unmatchedRequests;
   private url;
@@ -1023,28 +1047,23 @@ declare class StubBackend {
   /** Stop the server (idempotent). */
   stop(): Promise<void>;
   /**
-   * Arm the stub for one chain: the declared exchanges replace the previous
-   * chain's wholesale, consumption restarts, and the unmatched log clears —
+   * Arm the stub for one chain: the declared contracts replace the previous
+   * chain's wholesale, the queue restarts, and the unmatched log clears —
    * the reset-between-chains databases already follow.
    */
-  beginChain(exchanges: InterceptExchange[]): void;
+  beginChain(contracts: readonly Contract[]): void;
   /**
-   * The strict failure for the chain, or null — non-null when the chain
-   * declared at least one intercept AND an unmatched request was recorded.
-   * Enumerates every unmatched request (method, path, count) plus the
-   * declared routes, so the missing exchange writes itself.
+   * The strict failure for the chain, or null. Non-null when the chain
+   * declared at least one contract AND either an unmatched request was
+   * recorded, or a `required` contract was never satisfied. Enumerates every
+   * unmatched request (method, path, count) plus the declared routes, so the
+   * missing contract writes itself.
    */
   violation(): Error | null;
   private corsHeaders;
   private describeRoutes;
   private handle;
   private record;
-  /**
-   * FIFO with a sticky tail: the first unconsumed matching exchange is
-   * consumed; when every matching exchange is spent, the LAST one keeps
-   * replying.
-   */
-  private take;
 }
 //#endregion
 //#region src/core/specification/shared/builder.d.ts
@@ -1068,7 +1087,7 @@ interface DockerSpecConfig {
 interface SpecificationConfig {
   /**
    * The declared stub backend (website/mobile facets) — armed with the
-   * chain's `.http` intercept exchanges before every terminal action.
+   * chain's contracts before every terminal action.
    */
   backend?: StubBackend;
   /**
@@ -1136,6 +1155,11 @@ interface SpecificationConfig {
    */
   transform?: (text: string) => string;
 }
+/**
+ * The `.intercept()` overload set, identical on every facet: one contract, a
+ * list, a composite — or the inline `(request, response)` pair for a one-off.
+ */
+type InterceptMethod<T> = ((contracts: ContractInput) => T) & ((request: ContractRequest, response: ContractResponder | ContractResponse) => T);
 /**
  * The `api` facet — HTTP chain entry handed out by `specification.api()`.
  * Setup methods chain; action methods are terminal: they execute the spec
@@ -1147,8 +1171,8 @@ interface SpecificationConfig {
 interface ApiSpecification<DatabaseKey extends string = string> {
   /** Set HTTP headers for the request. Multiple calls merge. */
   headers: (headers: Record<string, string>) => ApiSpecification<DatabaseKey>;
-  /** Intercept an outgoing HTTP call — a contract, an array of contracts, an `intercepts/*.http` file, or a trigger + response pair. */
-  intercept: ((contractOrContracts: InterceptContract | InterceptContract[] | string) => ApiSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => ApiSpecification<DatabaseKey>);
+  /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
+  intercept: InterceptMethod<ApiSpecification<DatabaseKey>>;
   /** Queue a SQL seed file from `seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
@@ -1169,8 +1193,8 @@ interface ApiSpecification<DatabaseKey extends string = string> {
  * Jobs run in-process by definition (CONVENTIONS A5/A8).
  */
 interface JobsSpecification<DatabaseKey extends string = string> {
-  /** Intercept an outgoing HTTP call — a contract, an array of contracts, an `intercepts/*.http` file, or a trigger + response pair. */
-  intercept: ((contractOrContracts: InterceptContract | InterceptContract[] | string) => JobsSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => JobsSpecification<DatabaseKey>);
+  /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
+  intercept: InterceptMethod<JobsSpecification<DatabaseKey>>;
   /** Queue a SQL seed file from `seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
@@ -1217,11 +1241,10 @@ interface WebsiteSpecification {
   /** Set HTTP headers for the exchange (incl. User-Agent overrides). Multiple calls merge. */
   headers: (headers: Record<string, string>) => WebsiteSpecification;
   /**
-   * Declare the chain's backend exchanges from an `intercepts/<name>.http`
-   * file — served by the declared stub backend (requires the runner's
-   * `backend` option). Multiple calls layer in order.
+   * Declare the chain's backend contracts — served by the declared stub
+   * backend (requires the runner's `backend` option). Multiple calls append.
    */
-  intercept: (file: string) => WebsiteSpecification;
+  intercept: InterceptMethod<WebsiteSpecification>;
   /** Perform one raw HTTP GET — redirects surface as 3xx results, never followed. */
   fetch: (path: string) => Promise<FetchResult>;
   /**
@@ -1239,11 +1262,10 @@ interface WebsiteSpecification {
  */
 interface MobileSpecification {
   /**
-   * Declare the chain's backend exchanges from an `intercepts/<name>.http`
-   * file — served by the declared stub backend (requires the runner's
-   * `backend` option). Multiple calls layer in order.
+   * Declare the chain's backend contracts — served by the declared stub
+   * backend (requires the runner's `backend` option). Multiple calls append.
    */
-  intercept: (file: string) => MobileSpecification;
+  intercept: InterceptMethod<MobileSpecification>;
   /**
    * Relaunch the app and resolve with the captured screen. With a deep
    * link, the app opens on it; with a scenario, the visitor interacts
@@ -1390,7 +1412,15 @@ interface OrchestratorOptions {
    */
   services: Record<string, ServiceHandle>;
   mode: 'e2e' | 'integration';
-  root?: string;
+  /**
+   * The project root, already resolved. REQUIRED: the constructors derive it
+   * by walking up from the calling specification file (CONVENTIONS A9), and
+   * the orchestrator is handed the answer. Defaulting to `process.cwd()` here
+   * meant one silent second opinion about what the project is — the runner
+   * resolving from the caller, this from wherever the runner happened to be
+   * launched, which in a workspace is rarely the same directory.
+   */
+  root: string;
   /** Compose project name — used for per-worker stack isolation. */
   projectName?: string;
 }
@@ -1626,8 +1656,8 @@ interface MobileSpecificationOptions {
     bundleId: string;
   };
   /**
-   * Declared stub backend: started with the runner, serving the exchanges
-   * each chain declares via `.intercept('<name>.http')`. The handle gains
+   * Declared stub backend: started with the runner, serving the contracts
+   * each chain declares via `.intercept(...)`. The handle gains
    * `backendUrl` — inject it into your bundler env yourself.
    */
   backend?: MobileBackendOptions;
@@ -1685,8 +1715,8 @@ interface ServeOptions {
 /**
  * The declared stub backend behind the site under test — started before the
  * server command, torn down with the runner. Its URL is injected into the
- * server child's environment under `env`; the chain's
- * `.intercept('<name>.http')` exchanges are what it serves.
+ * server child's environment under `env`; the contracts each chain declares
+ * via `.intercept(...)` are what it serves.
  */
 interface WebsiteBackendOptions {
   /** Env var receiving the stub's URL in the server child (e.g. `'API_URL'`). */
@@ -1718,7 +1748,7 @@ type WebsiteSpecificationOptions = {
   /**
    * Declared stub backend: started BEFORE the server command, its
    * URL injected into the child env under `backend.env`. Serves the
-   * exchanges each chain declares via `.intercept('<name>.http')`.
+   * contracts each chain declares via `.intercept(...)`.
    */
   backend?: WebsiteBackendOptions;
   /**
@@ -1994,8 +2024,9 @@ interface SqliteOptions {
    */
   init?: string;
   /**
-   * Path to a Prisma schema directory or file.
-   * The adapter runs `prisma db push` to create the template.
+   * Path to a Prisma schema directory or file, resolved against the current
+   * working directory. The adapter runs `prisma db push --schema <path>` to
+   * create the template, so the schema needs no Prisma config at the cwd.
    * Mutually exclusive with `init`.
    */
   prismaSchema?: string;
@@ -2013,6 +2044,7 @@ declare class SqliteHandle implements DatabasePort, ServiceHandle {
   private workerDbPath;
   private initSql;
   private prismaSchema;
+  private readonly options;
   constructor(options?: SqliteOptions);
   buildConnectionString(): string;
   createDatabaseAdapter(): DatabasePort;
@@ -2040,20 +2072,38 @@ declare class SqliteHandle implements DatabasePort, ServiceHandle {
  */
 declare function sqlite(options?: SqliteOptions): SqliteHandle;
 //#endregion
+//#region src/core/contracts/filters.d.ts
+/**
+ * A text filter on a provider request builder (`openai.chat({ user })`,
+ * `anthropic.messages({ system })`, …).
+ *
+ * A **string is EXACT**. That is deliberate: a substring filter silently
+ * cross-matches — two prompts sharing a preamble both satisfy the first
+ * contract, and the spec goes green on the wrong reply. Looser matching is
+ * explicit, and says which looseness it means:
+ *
+ * - a `RegExp` — pattern matching;
+ * - `match.includes('…')` — containment, the code-only matcher (it never joins
+ *   the `{{token}}` file vocabulary, CONVENTIONS D4);
+ * - any other `match.*` matcher, evaluated by the same structural engine the
+ *   assertions use.
+ */
+type TextFilter = Matcher | RegExp | string;
+//#endregion
 //#region src/integrations/anthropic/anthropic.d.ts
 interface AnthropicMessagesFilter {
-  model?: RegExp | string;
-  system?: RegExp | string;
-  user?: RegExp | string;
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
   tools?: string[];
 }
-declare function buildReply(data: unknown): InterceptResponse;
+declare function buildReply(data: unknown): ContractResponse;
 /**
  * Anthropic API intercept helpers.
  */
 declare const anthropic: {
   /**
-   * Trigger: match Messages API requests, optionally routed through a
+   * Request: match Messages API calls, optionally routed through a
    * custom gateway URL. When used with a JSON fixture file, the data is
    * returned as-is (no wrapping) because Anthropic fixtures are typically
    * already in the Messages API response shape.
@@ -2061,15 +2111,16 @@ declare const anthropic: {
    * @example
    *   anthropic.messages()
    *   anthropic.messages({ system: /classify/ })
+   *   anthropic.messages({ user: buildPrompt() })   // string = EXACT equality
    *   anthropic.messages({ user: /classify/ }, GATEWAY)
    */
-  messages(filter?: AnthropicMessagesFilter, url?: string): InterceptTrigger;
+  messages(filter?: AnthropicMessagesFilter, url?: string): ContractRequest;
   /** Response: wrap data in Anthropic messages format. */
   reply: typeof buildReply;
   /** Response: return an Anthropic error. */
-  error(status: number, message?: string): InterceptResponse;
+  error(status: number, message?: string): ContractResponse;
   /** Response: simulate a timeout. */
-  timeout(): InterceptResponse;
+  timeout(): ContractResponse;
 };
 //#endregion
 //#region src/core/contracts/http.d.ts
@@ -2077,7 +2128,7 @@ declare const anthropic: {
  * Request filters for the generic HTTP provider. Every field is a subset
  * constraint — a request matches when all provided fields match.
  */
-interface HttpInterceptFilter {
+interface HttpContractFilter {
   /**
    * Body constraint. An object is a deep SUBSET match (toMatchObject-style)
    * whose leaf values may be `match.*` matchers; a string is a containment
@@ -2089,58 +2140,78 @@ interface HttpInterceptFilter {
   /** Query-param subset. string = exact value, RegExp = `test()`. */
   query?: Record<string, RegExp | string>;
 }
+/** Init options shared by the response builders. */
+interface HttpResponseInit {
+  /** Delay in ms before responding (for timeout testing). */
+  delay?: number;
+  /** Response headers, merged over the builder's own. */
+  headers?: Record<string, string>;
+  /** HTTP status code. */
+  status?: number;
+}
 /**
- * Generic HTTP intercept helpers for any URL. An optional {@link
- * HttpInterceptFilter} narrows matching by request body, headers, or query —
- * a request that hits the URL/method but fails the filter counts as unmatched
- * (strict intercepts, CONVENTIONS D7).
+ * Generic HTTP contract helpers for any URL. The url is absolute (string or
+ * RegExp), or a PATH FORM starting with `/` — `http.get('/articles/{{uuid}}')`
+ * matches that path on ANY origin, which is what an app calling its own
+ * backend needs. An optional {@link HttpContractFilter} narrows matching by
+ * body, headers, or query — a request that hits the URL/method but fails the
+ * filter counts as unmatched (strict contracts, CONVENTIONS D7).
  *
  * @example
- *   .intercept(http.get('https://api.example.com/data'), 'http/response.json')
- *   .intercept(http.post(URL, { body: { user: 'alice' } }), http.json({ ok: true }))
+ *   defineContract({ request: http.get('/articles/{{uuid}}'), response: http.json(article) })
+ *   defineContract({ request: http.post(URL, { body: { user: 'alice' } }), response: http.empty() })
  */
 declare const http: {
-  get(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  post(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  put(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  delete(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  any(url: RegExp | string, filter?: HttpInterceptFilter): InterceptTrigger;
-  /** Response: simple JSON success. */
-  json(data: unknown, status?: number): InterceptResponse;
-  /** Response: error with message. */
-  error(status: number, message?: string): InterceptResponse;
+  any(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  delete(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  get(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  patch(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  post(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  put(url: RegExp | string, filter?: HttpContractFilter): ContractRequest;
+  /** Response: a body-less reply (204 by default). */
+  empty(status?: number): ContractResponse;
+  /** Response: an error status. Without a body, `{ error: 'HTTP <status>' }`. */
+  error(status: number, body?: unknown): ContractResponse;
+  /** Response: a JSON body (200 by default). */
+  json(body: unknown, init?: HttpResponseInit): ContractResponse;
+  /** Response: a text body, served as `text/plain` (200 by default). */
+  text(body: string, init?: HttpResponseInit): ContractResponse;
 };
 //#endregion
 //#region src/integrations/openai/openai.d.ts
 interface OpenAIChatFilter {
-  model?: RegExp | string;
-  system?: RegExp | string;
-  user?: RegExp | string;
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
   tools?: string[];
   temperature?: number;
 }
 interface OpenAIResponsesFilter {
-  model?: RegExp | string;
-  system?: RegExp | string;
-  user?: RegExp | string;
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
   tools?: string[];
 }
-declare function buildChatReply(data: unknown): InterceptResponse;
+declare function buildChatReply(data: unknown): ContractResponse;
 /**
  * OpenAI API intercept helpers.
  */
 declare const openai: {
   /**
-   * Trigger: match Chat Completions API requests.
+   * Request: match Chat Completions API calls. STRING filters mean EXACT
+   * equality (pass the app's own prompt builder); loosen deliberately with a
+   * RegExp or `match.includes(...)`.
    *
    * @example
-   *   openai.chat()                         // any chat call
-   *   openai.chat({ model: 'gpt-4o' })      // specific model
-   *   openai.chat({ system: /classify/ })    // system prompt match
+   *   openai.chat()                            // any chat call
+   *   openai.chat({ model: 'gpt-4o' })         // exact model
+   *   openai.chat({ system: buildPrompt() })   // exact system prompt
+   *   openai.chat({ system: /classify/ })      // pattern
    */
-  chat(filter?: OpenAIChatFilter): InterceptTrigger;
+  chat(filter?: OpenAIChatFilter): ContractRequest;
   /**
-   * Trigger: match Responses API requests (AI SDK v5+) with auto-wrapping.
+   * Request: match Responses API calls (AI SDK v5+) with auto-wrapping.
+   * String filters mean EXACT equality (see {@link openai.chat}).
    * When used with a JSON file, the data is automatically wrapped in the
    * Responses API envelope.
    *
@@ -2150,7 +2221,7 @@ declare const openai: {
    * @example
    *   openai.responses({ user: /Report Ingestion/ }, GATEWAY)
    */
-  responses(filter?: OpenAIResponsesFilter, url?: string): InterceptTrigger;
+  responses(filter?: OpenAIResponsesFilter, url?: string): ContractRequest;
   /**
    * Response: wrap data in Chat Completions format.
    *
@@ -2159,11 +2230,11 @@ declare const openai: {
    */
   reply: typeof buildChatReply;
   /** Response: return an OpenAI error. */
-  error(status: number, message?: string): InterceptResponse;
+  error(status: number, message?: string): ContractResponse;
   /** Response: return malformed content. */
-  malformed(content: string): InterceptResponse;
+  malformed(content: string): ContractResponse;
   /** Response: simulate a timeout. */
-  timeout(): InterceptResponse;
+  timeout(): ContractResponse;
 };
 //#endregion
 //#region src/vitest/mock-of.d.ts
@@ -2229,4 +2300,4 @@ declare module 'vitest' {
   }
 }
 //#endregion
-export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, HttpResult, type InterceptContract, type InterceptEntry, type InterceptResponder, type InterceptResponse, type InterceptResponseValue, type InterceptTrigger, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type VisitScenario, type Visitor, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, content, contentinfo, defineContract, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };
+export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type Contract, type ContractInput, type ContractRequest, type ContractResponder, type ContractResponse, type ContractResponseValue, type Contracts, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, type HttpContractFilter, type HttpResponseInit, HttpResult, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type TextFilter, type VisitScenario, type Visitor, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, content, contentinfo, defineContract, defineContracts, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };