@jterrazz/test 7.1.0 → 9.0.0

package/dist/index.d.ts

@@ -1,45 +1,200 @@
-import { a as PostgresOptions, c as IsolationStrategy, i as redis, l as DatabasePort, n as sqlite, o as postgres, r as RedisOptions, s as ServiceHandle, t as SqliteOptions } from "./sqlite.adapter.js";
-import { n as InterceptResponse, r as InterceptTrigger } from "./types.js";
-import { i as mockOfDate, n as mockOf, r as MockDatePort, t as MockPort } from "./mock-of.js";
-
-//#region src/builder/cli/command.port.d.ts
+import { DeepMockProxy } from "vitest-mock-extended";
+//#region src/core/matching/match.d.ts
 /**
- * Result of executing a CLI command, including exit code and captured output streams.
+ * Code-side dynamic-value matchers (`match.*`) and the capture scope shared
+ * by every assertion of a single spec execution.
+ *
+ * Matchers are used inside `toMatchRows` rows and any structural comparison;
+ * their file-side twins are the `{{placeholder}}` forms in `expected/*.http`
+ * fixtures (body AND headers), `expected/*.json` files, and text snapshots
+ * (`expected/*.txt`). One grammar, one vocabulary (CONVENTIONS D4).
  */
-interface CommandResult {
-  /** Process exit code (0 = success). */
-  exitCode: number;
-  /** Captured standard output. */
-  stdout: string;
-  /** Captured standard error. */
-  stderr: string;
+/** 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';
+/**
+ * A dynamic-value matcher. Created via the {@link match} factories — never
+ * constructed directly by user code.
+ */
+declare class Matcher {
+  readonly kind: MatcherKind;
+  /** For kind 'ref': the capture to assert inequality against. */
+  readonly notRef?: string;
+  /** For kind 'ref': the capture name. */
+  readonly refName?: string;
+  /** For kind 'regex': the pattern the actual value must match. */
+  readonly regex?: RegExp;
+  constructor(kind: MatcherKind, options?: {
+    notRef?: string;
+    refName?: string;
+    regex?: RegExp;
+  });
+  /** Placeholder-style rendering used in failure diffs and serialization. */
+  toString(): string;
+  toJSON(): string;
 }
 /**
- * Options for spawning a long-running process.
+ * Dynamic-value matchers for structural comparisons — the code-side mirror of
+ * the `{{token}}` fixture grammar (CONVENTIONS D4).
+ *
+ * @example
+ *   await expect(result.table('users', { database: 'db' })).toMatchRows({
+ *       columns: ['id', 'name'],
+ *       rows: [[match.uuid(), 'Alice']],
+ *   });
+ */
+declare const match: {
+  /** Matches anything. */
+  any: () => Matcher;
+  /** Matches a base64 string. */
+  base64: () => Matcher;
+  /** Matches a calendar date (`YYYY-MM-DD`). */
+  date: () => Matcher;
+  /** Matches a human duration (`12ms`, `1.5s`, `2m`, `3h`). */
+  duration: () => Matcher;
+  /** Matches an email address. */
+  email: () => Matcher;
+  /**
+   * Matches a float. In JSON contexts any finite number passes (JSON does
+   * not distinguish `42` from `42.0`); in text contexts the decimal part
+   * is required (`4.2`, never `42`).
+   */
+  float: () => Matcher;
+  /** Matches a hexadecimal string. */
+  hex: () => Matcher;
+  /** Matches an integer (or an integer string in text contexts). */
+  int: () => Matcher;
+  /** Matches an IPv4 address. */
+  ip: () => Matcher;
+  /** Matches an ISO-8601 timestamp string. */
+  iso8601: () => Matcher;
+  /** Matches a number (or a numeric string in text contexts). */
+  number: () => Matcher;
+  /** Matches a filesystem path (`/...` or `./...`). */
+  path: () => Matcher;
+  /** Matches a TCP/UDP port number (0-65535). */
+  port: () => Matcher;
+  /**
+   * Capture-and-compare. The first occurrence of `ref(name)` captures the
+   * actual value; every later occurrence must strictly equal the capture.
+   * `{ not: other }` additionally asserts inequality with the capture named
+   * `other`. Scope: the current spec execution (reset per chain).
+   */
+  ref: (name: string, options?: {
+    not?: string;
+  }) => Matcher;
+  /** Matches a string against the given regular expression. */
+  regex: (regex: RegExp) => Matcher;
+  /** Matches a semantic version (`1.2.3`, `2.0.0-rc.1`). */
+  semver: () => Matcher;
+  /** Matches a git SHA (7-64 hex chars). */
+  sha: () => Matcher;
+  /** Matches any string. */
+  string: () => Matcher;
+  /** Matches a wall-clock time (`HH:MM` or `HH:MM:SS`). */
+  time: () => Matcher;
+  /** Matches a ULID. */
+  ulid: () => Matcher;
+  /** Matches an http(s) URL. */
+  url: () => Matcher;
+  /** Matches a UUID string. */
+  uuid: () => Matcher;
+  /** Matches the exact working directory of the current spec. */
+  workdir: () => Matcher;
+};
+/**
+ * Named captures recorded by `match.ref()` / `{{type#ref}}` placeholders.
+ * One scope lives on each spec result — every assertion chained off the same
+ * result shares it, and a new chain starts fresh.
  */
-interface SpawnOptions {
-  /** Resolve when stdout/stderr contains this string. */
-  waitFor: string;
-  /** Kill the process after this many milliseconds. */
-  timeout: number;
+declare class CaptureScope {
+  private readonly values;
+  /**
+   * The exact working directory of the current spec, when the framework
+   * knows it (cli mode). Drives the `{{workdir}}` token / `match.workdir()`.
+   */
+  workdir?: string;
+  constructor(workdir?: string);
+  get(name: string): unknown;
+  has(name: string): boolean;
+  set(name: string, value: unknown): void;
 }
+//#endregion
+//#region src/core/specification/shared/result/directory.d.ts
 /**
- * Extra environment variables to set for the child process.
- * Values are merged on top of process.env. A `null` value unsets the variable.
+ * Read-only accessor for a directory produced by a spec action.
+ *
+ * Assertions go through `expect()` (async — they walk the disk):
+ * `await expect(result.directory('out')).toMatch('scaffold/out')`
+ * compares the tree against the fixture directory `expected/<name>/`.
  */
-type CommandEnv = Record<string, null | string>;
+declare class DirectoryAccessor {
+  /** @internal Ref-capture scope shared by the current spec execution. */
+  readonly captures: CaptureScope;
+  /** @internal Absolute path of the directory under assertion. */
+  readonly root: string;
+  /** @internal Test-file directory — fixture resolution root for matchers. */
+  readonly testDir: string;
+  constructor(absPath: string, testDir: string, captures?: CaptureScope);
+  /** List all files (recursively) under the directory, sorted. */
+  files(options?: {
+    ignore?: string[];
+  }): Promise<string[]>;
+}
+//#endregion
+//#region src/core/specification/shared/result/filesystem.d.ts
 /**
- * Abstract CLI interface for specification runners.
- * Implement this to plug in your command execution strategy.
+ * Read-only accessor for the whole temporary working directory used by a
+ * command spec.
+ *
+ * Assertions go through `expect()` (async — they walk the disk):
+ * `await expect(result.filesystem).toMatch('scaffolded')` compares the
+ * tree against the fixture directory `expected/<name>/`.
+ */
+declare class FilesystemAccessor {
+  /** @internal Ref-capture scope shared by the current spec execution. */
+  readonly captures: CaptureScope;
+  /** The absolute path of the temporary working directory. */
+  readonly cwd: string;
+  /** @internal Test-file directory — fixture resolution root for matchers. */
+  readonly testDir: string;
+  constructor(cwd: string, testDir: string, captures?: CaptureScope);
+  /** List all files (recursively) under the working directory, sorted. */
+  files(options?: {
+    ignore?: string[];
+  }): Promise<string[]>;
+}
+//#endregion
+//#region src/core/specification/shared/result/json.d.ts
+/**
+ * Read-only accessor for a JSON payload parsed from a text stream (stdout).
+ *
+ * Lazily parses the JSON on first use; parse errors are deferred until the
+ * value is read so that callers can still read the raw stream text without
+ * triggering a throw.
+ *
+ * ANSI escape sequences are stripped by default before `JSON.parse`
+ * (CONVENTIONS D6). When a `transform` is configured on the spec runner, it
+ * runs on the stripped text — an escape hatch for application noise not
+ * covered by the `{{token}}` grammar.
+ *
+ * Assertions go through `expect()`: `expect(result.json).toMatch('name.json')`
+ * (deep-equal against `expected/<name>`, with `{{placeholder}}` support).
  */
-interface CommandPort {
-  /** Execute a CLI command with the given arguments in the given working directory. */
-  exec(args: string, cwd: string, env?: CommandEnv): Promise<CommandResult>;
-  /** Spawn a long-running process and wait for a pattern or timeout. */
-  spawn(args: string, cwd: string, options: SpawnOptions, env?: CommandEnv): Promise<CommandResult>;
+declare class JsonAccessor {
+  /** @internal Ref-capture scope shared by the current spec execution. */
+  readonly captures: CaptureScope;
+  /** @internal */
+  private readonly rawText;
+  /** @internal Test-file directory — fixture resolution root for matchers. */
+  readonly testDir: string;
+  /** @internal */
+  private readonly transform?;
+  constructor(rawText: string, testDir: string, transform?: (text: string) => string, captures?: CaptureScope);
+  /** The parsed JSON value. Throws if the text is not valid JSON. */
+  get value(): unknown;
 }
 //#endregion
-//#region src/builder/http/server.port.d.ts
+//#region src/core/ports/server.port.d.ts
 /**
  * HTTP response returned by a server port, with parsed JSON body.
  */
@@ -57,380 +212,682 @@ interface ServerResponse {
  */
 interface ServerPort {
   /** Send an HTTP request and return the parsed response. */
-  request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
+  request: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<ServerResponse>;
 }
 //#endregion
-//#region src/builder/common/directory-accessor.d.ts
-interface DirectorySnapshotOptions {
-  /** Extra path segments to ignore (in addition to default: .git, node_modules, etc.). */
-  ignore?: string[];
+//#region src/core/specification/shared/result/response.d.ts
+/**
+ * Read-only accessor for an HTTP response.
+ *
+ * Assertions go through `expect()`:
+ * `expect(result.response).toMatch('created.http')` compares status,
+ * a subset of headers, and the JSON body against `expected/<name>` —
+ * with `{{placeholder}}` support in all three.
+ */
+declare class ResponseAccessor {
+  /** The parsed JSON response body (null when parsing failed). */
+  readonly body: unknown;
+  /** @internal Ref-capture scope shared by the current spec execution. */
+  readonly captures: CaptureScope;
+  /** Response headers as a flat, lower-cased key-value map. */
+  readonly headers: Record<string, string>;
+  /** The HTTP response status code. */
+  readonly status: number;
+  /** @internal Test-file directory — fixture resolution root for matchers. */
+  readonly testDir: string;
+  constructor(response: ServerResponse, testDir: string, captures?: CaptureScope);
+}
+//#endregion
+//#region src/core/ports/database.port.d.ts
+/**
+ * Abstract database interface for specification runners.
+ * Implement this to plug in your database stack (e.g. Postgres, SQLite).
+ */
+interface DatabasePort {
+  /** Execute raw SQL (for seeding test data). */
+  seed: (sql: string) => Promise<void>;
+  /** Query a table and return rows as arrays of values. */
+  query: (table: string, columns: string[]) => Promise<unknown[][]>;
+  /** Reset database to clean state between tests. */
+  reset: () => Promise<void>;
+}
+//#endregion
+//#region src/core/specification/shared/result/table.d.ts
+/**
+ * Read-only accessor for a database table after a specification run.
+ *
+ * Assertions go through `expect()` (async — they query the database):
+ *
+ *     await expect(result.table('users', { database: 'db' })).toMatchRows({
+ *         columns: ['name'],
+ *         rows: [['Alice']],
+ *     });
+ *     await expect(result.table('users', { database: 'db' })).toBeEmpty();
+ */
+declare class TableAccessor {
+  /** @internal Ref-capture scope shared by the current spec execution. */
+  readonly captures: CaptureScope;
+  /** @internal */
+  private readonly db;
+  /** The table name this accessor reads. */
+  readonly name: string;
+  constructor(name: string, db: DatabasePort, captures?: CaptureScope);
+  /** @internal Query the table — used by the toMatchRows / toBeEmpty matchers. */
+  query(columns: string[]): Promise<unknown[][]>;
+}
+//#endregion
+//#region src/core/specification/shared/result/text.d.ts
+/**
+ * Read-only accessor for a captured text handle — THE universal one: stdout,
+ * stderr, container logs, and file text all surface as a `TextAccessor`.
+ *
+ * Backed by a primitive string, exposed via {@link text}, but also provides
+ * `toString()` / `valueOf()` for string coercion, so common patterns like
+ * `String(result.stdout)` and template-literal interpolation still work.
+ *
+ * ANSI escape sequences are stripped by default before every comparison
+ * (CONVENTIONS D6) — `.text` stays raw. The runner `transform` option remains
+ * an escape hatch for application noise not covered by the `{{token}}`
+ * grammar.
+ *
+ * Text operations are **closed** over the type: `.grep(pattern)` returns a
+ * `TextAccessor` (not a bare string), preserving the `expected/`-resolution
+ * context and the `transform`, so results are chainable
+ * (`result.stdout.grep(a).grep(b)`) and snapshot-able
+ * (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
+ *
+ * Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
+ * and `expect(result.stdout).toMatch('name.txt')` (resolved against
+ * `expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
+ */
+declare class TextAccessor {
+  /** @internal Ref-capture scope shared by the current spec execution. */
+  readonly captures: CaptureScope;
+  /** @internal Stream label used in failure messages ("stdout" / "stderr"). */
+  readonly streamName: string;
+  /** @internal Test-file directory — fixture resolution root for matchers. */
+  readonly testDir: string;
+  /** The raw captured text (never transformed, ANSI preserved). */
+  readonly text: string;
+  /** @internal Normaliser applied before comparisons, never to fixtures. */
+  readonly transform?: (text: string) => string;
+  constructor(value: string, streamName: string, testDir: string, options?: {
+    captures?: CaptureScope;
+    transform?: (text: string) => string;
+  });
+  /** @internal The text as compared by matchers — ANSI stripped, transform applied. */
+  get comparableText(): string;
   /**
-   * Force update mode regardless of vitest flags / env vars.
-   * `true` writes the fixture, `false` always asserts. Defaults to auto-detect.
+   * Keep only the blank-line-separated blocks of the text that contain
+   * `pattern` (how linter/compiler output is structured), returned as a new
+   * `TextAccessor` — the same subject type, so the result is chainable and
+   * snapshot-able. The scalpel for probing large tool outputs; snapshot the
+   * whole surface by default, reach for `.grep()` for targeted checks.
    */
-  update?: boolean;
+  grep(pattern: string): TextAccessor;
+  toString(): string;
+  valueOf(): string;
 }
 /**
- * Handle to a directory produced by a specification run.
- * Supports snapshot-based assertions via {@link toMatchFixture} and file listing via {@link files}.
+ * Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
+ * test's directory — the same caller-detection the builders use.
+ *
+ * The product surface of a test framework is its own error messages, checker
+ * output, and reports; those deserve the same goldening as any other output.
+ * `text()` makes an ad-hoc string a first-class snapshot subject:
+ *
+ * ```typescript
+ * const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
+ * expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to expected/
+ * ```
+ *
+ * ANSI is stripped before every comparison (the raw form stays on `.text`),
+ * the `{{token}}` grammar applies to the fixture, and `.grep()` composition
+ * works exactly as on any stream accessor.
  */
-declare class DirectoryAccessor {
-  private absPath;
-  private testDir;
-  constructor(absPath: string, testDir: string);
+declare function text(value: string): TextAccessor;
+//#endregion
+//#region src/core/ports/cli.port.d.ts
+/**
+ * Raw output from a command execution, including exit code and captured output streams.
+ */
+interface CliOutput {
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /** Captured standard output. */
+  stdout: string;
+  /** Captured standard error. */
+  stderr: string;
+}
+/**
+ * Options for the long-running form of `.exec()` (CONVENTIONS B2). When
+ * either option is present the process is spawned and observed: it resolves
+ * as soon as `waitFor` appears in stdout/stderr, and is killed when `timeout`
+ * elapses (exit code 124).
+ */
+interface ExecOptions {
+  /** Resolve (exit code 0) when stdout/stderr contains this string. */
+  waitFor?: string;
+  /** Kill the process after this many milliseconds. Defaults to 10 000. */
+  timeout?: number;
+}
+/**
+ * Extra environment variables to set for the child process.
+ * Values are merged on top of process.env. A `null` value unsets the variable.
+ */
+type CliEnv = Record<string, null | string>;
+/**
+ * Abstract command interface for specification runners.
+ * Implement this to plug in your command execution strategy.
+ */
+interface CliPort {
+  /** Execute a command with the given arguments in the given working directory. */
+  exec: (args: string, cwd: string, env?: CliEnv) => Promise<CliOutput>;
+  /** Run a long-running process and wait for a pattern or timeout. */
+  watch: (args: string, cwd: string, options: ExecOptions, env?: CliEnv) => Promise<CliOutput>;
+}
+//#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}.
+ */
+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). */
+  url: string;
+}
+/**
+ * An intercept trigger describes which HTTP request to match.
+ */
+interface InterceptTrigger {
+  /** Adapter name - must match the folder prefix in file-based intercepts. */
+  adapter: string;
+  /** HTTP method to match. */
+  method: string;
+  /** URL pattern to match (string for exact prefix, RegExp for pattern). */
+  url: RegExp | string;
+  /** Optional request matcher - the handler only fires if this returns true. */
+  match?: (request: MatchableRequest) => boolean;
   /**
-   * Compare the directory tree against `expected/{name}/` (relative to the test file).
-   * On mismatch, throws with a structured diff. With update mode enabled, the
-   * fixture is overwritten with the current contents instead.
+   * Transform raw JSON data into a provider-specific response envelope.
+   * Called when .intercept(trigger, 'adapter/file.json') loads a file.
    */
-  toMatchFixture(name: string, options?: DirectorySnapshotOptions): Promise<void>;
+  wrap: (data: unknown) => InterceptResponse;
+}
+/**
+ * An intercept response describes what to return when the trigger matches.
+ */
+interface InterceptResponse {
+  /** HTTP status code (default: 200). */
+  status?: number;
+  /** Response body (will be JSON.stringified). */
+  body: unknown;
+  /** Response headers. */
+  headers?: Record<string, string>;
+  /** Delay in ms before responding (for timeout testing). */
+  delay?: number;
+}
+/**
+ * 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.
+ */
+type InterceptResponder = (request: MatchableRequest) => InterceptResponse;
+/**
+ * What an intercept replies with: either a fixed {@link InterceptResponse} or
+ * an {@link InterceptResponder} evaluated per consumed request.
+ */
+type InterceptResponseValue = InterceptResponder | InterceptResponse;
+/**
+ * A fully resolved intercept entry ready to be registered with MSW.
+ */
+interface InterceptEntry {
+  trigger: InterceptTrigger;
+  response: InterceptResponseValue;
+}
+//#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).
+ */
+interface InterceptContract {
+  trigger: InterceptTrigger;
   /**
-   * List all files in the directory (recursive, sorted, ignoring defaults).
-   * Useful for ad-hoc assertions when you don't want a full snapshot.
+   * The reply — a fixed {@link InterceptResponse}, or a function
+   * `(request) => InterceptResponse` evaluated per consumed request when the
+   * response must derive from the incoming payload.
    */
-  files(options?: {
-    ignore?: string[];
-  }): Promise<string[]>;
+  response: InterceptResponseValue;
 }
+/**
+ * Declare an intercept contract. Identity function — its value is the
+ * enforced shape and the naming convention:
+ *
+ * @example
+ *   // specs/api/reports/contracts/classify-article.openai.ts
+ *   import { defineContract, openai } from '@jterrazz/test';
+ *
+ *   export default defineContract({
+ *       trigger: openai.responses({ user: /Report Ingestion/, 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'),
+ *       response: (request) => http.json({ received: request.body }),
+ *   });
+ *
+ *   // specs/api/reports/reports.test.ts
+ *   import classifyArticle from '../../spec/intercept/contracts/classify-article.openai.js';
+ *
+ *   const result = await jobs.intercept(classifyArticle).trigger('report-ingestion');
+ */
+declare function defineContract(contract: InterceptContract): InterceptContract;
 //#endregion
-//#region src/builder/common/response-accessor.d.ts
-/** Accessor for an HTTP response body with file-based assertion support. */
-declare class ResponseAccessor {
-  readonly body: unknown;
-  private testDir;
-  constructor(body: unknown, testDir: string);
+//#region src/core/ports/isolation.port.d.ts
+/**
+ * Strategy for isolating service state across parallel test workers.
+ *
+ * Each service handle provides an isolation strategy. The framework
+ * calls `acquire()` once per vitest worker, `reset()` before each
+ * `spec.run()`, and `release()` when the worker shuts down.
+ *
+ * Implement this interface to support new service types (e.g. MongoDB,
+ * Elasticsearch, S3).
+ */
+interface IsolationStrategy {
   /**
-   * Assert that the response body matches the JSON in `responses/{file}`.
+   * Create an isolated namespace for this worker.
+   * Called once when the worker starts — e.g. clone a template database,
+   * set a Redis key prefix.
    *
-   * @example
-   *   result.response.toMatchFile("expected-items.json");
+   * @param workerId - Unique identifier for this vitest worker.
+   */
+  acquire: (workerId: string) => Promise<void>;
+  /**
+   * Fast reset within the namespace between `spec.run()` calls.
+   * E.g. truncate tables (without dropping the database).
+   */
+  reset: () => Promise<void>;
+  /**
+   * Tear down the isolated namespace.
+   * Called once when the worker shuts down — e.g. drop the cloned database.
    */
-  toMatchFile(file: string): void;
+  release: () => Promise<void>;
 }
 //#endregion
-//#region src/builder/common/table-assertion.d.ts
-/** Assertion helper for verifying database table contents after a specification run. */
-declare class TableAssertion {
-  private tableName;
-  private db;
-  constructor(tableName: string, db: DatabasePort);
+//#region src/core/ports/service.port.d.ts
+/**
+ * A service handle — returned by factory functions like postgres(), redis().
+ * Mutable: connectionString is populated after the orchestrator starts containers.
+ */
+interface ServiceHandle {
+  /** Service type identifier. */
+  readonly type: string;
   /**
-   * Assert that the table contains exactly the expected rows for the given columns.
-   *
-   * @example
-   *   await result.table("users").toMatch({
-   *     columns: ["name", "email"],
-   *     rows: [["Alice", "alice@example.com"]],
-   *   });
+   * Compose service name. Left `null` until the orchestrator binds it at
+   * start time (CONVENTIONS A6): a handle with no explicit `composeService`
+   * links to the compose service named exactly like its record key, else the
+   * kebab-case conversion of the key — so `{ analyticsDb: postgres() }` binds
+   * to the compose service `analytics-db` without any option. Set
+   * `composeService` explicitly only for names the key cannot derive.
    */
-  toMatch(expected: {
-    columns: string[];
-    rows: unknown[][];
-  }): Promise<void>;
-  /** Assert that the table has zero rows. */
-  toBeEmpty(): Promise<void>;
+  composeName: null | string;
+  /** Default container port for this service type. */
+  readonly defaultPort: number;
+  /** Default Docker image for this service type. */
+  readonly defaultImage: string;
+  /** Environment variables to pass to the container. */
+  readonly environment: Record<string, string>;
+  /** Connection string — populated after start. */
+  connectionString: string;
+  /** Whether this service has been started. */
+  started: boolean;
+  /** Build the connection string from host and port. */
+  buildConnectionString: (host: string, port: number) => string;
+  /** Create a DatabasePort adapter (if this is a database). Returns null otherwise. */
+  createDatabaseAdapter: () => DatabasePort | null;
+  /** Verify the service is ready and accepting connections. Throws with context if not. */
+  healthcheck: () => Promise<void>;
+  /** Run initialization scripts (e.g., init.sql). Throws with SQL error context if it fails. */
+  initialize: (composeDir: string) => Promise<void>;
+  /** Reset state between tests (truncate tables, flush cache, etc.) */
+  reset: () => Promise<void>;
+  /** Get the isolation strategy for parallel test execution. */
+  isolation: () => IsolationStrategy;
 }
 //#endregion
-//#region src/builder/common/result.d.ts
-/** Read-only handle to a single file produced by a CLI action. */
+//#region src/core/specification/shared/result/result.d.ts
+/** Read-only handle to a single file produced by a spec action. */
 interface FileAccessor {
   /** The UTF-8 text content. Throws if the file does not exist. */
   readonly content: string;
   readonly exists: boolean;
+  /** The file text as a {@link TextAccessor}, keeping only blocks matching `pattern`. */
+  grep: (pattern: string) => TextAccessor;
+}
+interface BaseResultOptions {
+  config: SpecificationConfig;
+  testDir: string;
+  workDir?: string;
 }
 /**
- * The outcome of a single specification run.
- * Provides accessors for CLI output, HTTP responses, files, directories, and database tables.
+ * Base result - common accessors available after any action type.
+ * Extended by HttpResult, CliResult, and used directly by job results.
+ *
+ * Every result carries a fresh {@link CaptureScope}: `match.ref()` captures
+ * and `{{type#ref}}` placeholders are scoped to one spec execution.
  */
-declare class SpecificationResult {
-  private commandResult?;
-  private config;
-  private requestInfo?;
-  private responseData?;
-  private testDir;
-  private workDir?;
-  constructor(options: {
-    commandResult?: CommandResult;
-    config: SpecificationConfig;
-    requestInfo?: {
-      body?: unknown;
-      method: string;
-      path: string;
-    };
-    response?: ServerResponse;
-    testDir: string;
-    workDir?: string;
-  });
-  /** The process exit code. Only available after a CLI action. */
-  get exitCode(): number;
-  /** The HTTP response status code. Only available after an HTTP action. */
-  get status(): number;
-  /** The captured standard output. Only available after a CLI action. */
-  get stdout(): string;
-  /** The captured standard error. Only available after a CLI action. */
-  get stderr(): string;
-  /**
-   * Extract text blocks from stdout that contain a pattern.
-   * Useful for parsing structured CLI output (linters, compilers).
-   *
-   * @example
-   *   expect(result.grep('error.ts')).toContain('no-unused-vars');
-   */
-  grep(pattern: string): string;
-  /** Access the HTTP response body for assertions. Only available after an HTTP action. */
-  get response(): ResponseAccessor;
+declare class BaseResult {
+  /** @internal Ref-capture scope shared by every assertion on this result. */
+  readonly captures: CaptureScope;
+  protected config: SpecificationConfig;
+  protected testDir: string;
+  protected workDir?: string;
+  constructor(options: BaseResultOptions);
   /** Access a directory (relative to the working directory) for snapshot assertions. */
   directory(path?: string): DirectoryAccessor;
   /** Access a single file (relative to the working directory) for content assertions. */
   file(path: string): FileAccessor;
-  /** Access a database table for row-level assertions. */
+  /** Access a database table for row-level assertions via expect() matchers. */
   table(tableName: string, options?: {
-    service?: string;
-  }): TableAssertion;
+    database?: string;
+  }): TableAccessor;
   private resolveDatabase;
 }
 //#endregion
-//#region src/builder/specification-builder.d.ts
-/** A named job that can be triggered via .job(). */
-interface JobHandle$1 {
+//#region src/core/specification/api/result.d.ts
+/** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
+declare class HttpResult extends BaseResult {
+  private responseData;
+  constructor(options: {
+    config: SpecificationConfig;
+    response: ServerResponse;
+    testDir: string;
+  });
+  /** Access the HTTP response (status, headers, body) for assertions. */
+  get response(): ResponseAccessor;
+  /** The HTTP response status code. */
+  get status(): number;
+}
+//#endregion
+//#region src/core/specification/shared/builder.d.ts
+/** A named job that can be triggered via jobs.trigger(). */
+interface JobHandle {
   name: string;
   execute: () => Promise<void>;
 }
-/** Adapter configuration passed to the specification runner at setup time. */
+/**
+ * Configuration for the docker-aware cli mode. When set on
+ * {@link SpecificationConfig}, the cli runner generates a test-run id, injects
+ * it into the child env under `envVar`, then queries Docker for every
+ * container carrying `testRunLabel=<id>` after the command exits.
+ */
+interface DockerSpecConfig {
+  envVar: string;
+  nameLabel: string;
+  testRunLabel: string;
+}
+/** Adapter configuration passed to the specification facets at setup time. */
 interface SpecificationConfig {
-  command?: CommandPort;
+  command?: CliPort;
   database?: DatabasePort;
+  /**
+   * Keys of the declared services record that are databases. Drives the
+   * CONVENTIONS A7 rule: with 2+ databases the `database` option is
+   * mandatory on `.seed()` / `.table()`; with exactly one it is forbidden.
+   */
+  databaseKeys?: string[];
   databases?: Map<string, DatabasePort>;
-  fixturesRoot?: string;
-  jobs?: JobHandle$1[];
+  dockerConfig?: DockerSpecConfig;
+  /**
+   * Unique id shared by every spec from this runner instance.
+   * Stable for the runner's lifetime so multi-step tests (spawn in
+   * one run, inspect in another) see the same container scope. The
+   * facet factories auto-populate this when `dockerConfig` is present.
+   */
+  dockerTestRunId?: string;
+  /**
+   * When set, `.intercept()` is unavailable on this runner and throws this
+   * reason immediately (compose mode — MSW is in-process, CONVENTIONS I3).
+   */
+  interceptDisabledReason?: string;
+  jobs?: JobHandle[];
   server?: ServerPort;
+  /**
+   * The declared services record. In cli mode, drives the automatic
+   * connection-URL injection into the child env (CONVENTIONS B6):
+   * `<KEY>_URL` per service, plus `DATABASE_URL` / `REDIS_URL` when
+   * unambiguous.
+   */
+  services?: Record<string, ServiceHandle>;
+  /**
+   * Optional normaliser applied to command stdout/stderr before every
+   * comparison. Does not mutate the raw `.text` accessor.
+   */
+  transform?: (text: string) => string;
 }
 /**
- * Fluent builder for declaring a single test specification.
+ * The `api` facet — HTTP chain entry handed out by `specification.api()`.
+ * Setup methods chain; action methods are terminal: they execute the spec
+ * and resolve to the result.
  *
- * Chain setup methods ({@link seed}, {@link fixture}, {@link env}), an action
- * ({@link get}, {@link post}, {@link exec}), then call {@link run} to execute
- * and receive a {@link SpecificationResult} for assertions.
+ * The `DatabaseKey` parameter is the typed vocabulary of `.seed()`: the keys
+ * of the declared services record that are databases.
  */
-declare class SpecificationBuilder {
-  private commandArgs;
-  private commandEnv;
-  private config;
-  private fixtures;
-  private intercepts;
-  private jobName;
-  private label;
-  private mocks;
-  private projectName;
-  private request;
-  private requestHeaders;
-  private seeds;
-  private spawnConfig;
-  private testDir;
-  constructor(config: SpecificationConfig, testDir: string, label: string);
-  /**
-   * Queue a SQL seed file to run before the action.
-   *
-   * @example
-   *   spec("creates user").seed("users.sql").exec("list-users").run();
-   */
-  seed(file: string, options?: {
-    service?: string;
-  }): this;
-  /** Copy a file or directory from `fixtures/` into the working directory before execution. */
-  fixture(file: string): this;
-  /** Copy an entire project fixture from `fixturesRoot` into the working directory. */
-  project(name: string): this;
-  /** Register an MSW mock definition file from `mock/` to intercept HTTP calls. */
-  mock(file: string): this;
-  /**
-   * Set environment variables for the CLI process. Merged on top of process.env.
-   * Use `null` to unset a variable. Multiple calls merge.
-   *
-   * The token `$WORKDIR` (in any value) is replaced with the actual working
-   * directory at run-time — useful for tests that need a fully isolated `HOME`.
-   *
-   * @example
-   *   spec("...").env({ HOME: "$WORKDIR", TZ: "UTC" }).exec("status").run();
-   */
-  env(env: CommandEnv): this;
+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, or a trigger + response pair. */
+  intercept: ((contractOrContracts: InterceptContract | InterceptContract[]) => ApiSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => ApiSpecification<DatabaseKey>);
+  /** Queue a SQL seed file from `seeds/` to run before the action. */
+  seed: (file: string, options?: {
+    database?: DatabaseKey;
+  }) => ApiSpecification<DatabaseKey>;
+  /** Send a DELETE request and resolve with the result. */
+  delete: (path: string) => Promise<HttpResult>;
+  /** Send a GET request and resolve with the result. */
+  get: (path: string) => Promise<HttpResult>;
+  /** Send a POST request (optional inline JSON body) and resolve with the result. */
+  post: (path: string, body?: unknown) => Promise<HttpResult>;
+  /** Send a PUT request (optional inline JSON body) and resolve with the result. */
+  put: (path: string, body?: unknown) => Promise<HttpResult>;
+  /** Send the complete request described by `requests/<file>` (.http format). */
+  request: (file: string) => Promise<HttpResult>;
+}
+/**
+ * The `jobs` facet — job chain entry handed out by `specification.jobs()`.
+ * 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, or a trigger + response pair. */
+  intercept: ((contractOrContracts: InterceptContract | InterceptContract[]) => JobsSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => JobsSpecification<DatabaseKey>);
+  /** Queue a SQL seed file from `seeds/` to run before the action. */
+  seed: (file: string, options?: {
+    database?: DatabaseKey;
+  }) => JobsSpecification<DatabaseKey>;
+  /** Execute the named job registered via the `jobs` option and resolve with the result. */
+  trigger: (name: string) => Promise<BaseResult>;
+}
+/**
+ * The `cli` facet — command chain entry handed out by `specification.cli()`.
+ * Setup methods chain; `.exec()` is the single terminal action (CONVENTIONS
+ * B2) — `{ waitFor?, timeout? }` covers long-running processes.
+ */
+interface CliSpecification<DatabaseKey extends string = string> {
+  /** Set environment variables on the child process. `$WORKDIR` expands; `null` unsets. */
+  env: (env: CliEnv) => CliSpecification<DatabaseKey>;
   /**
-   * Set HTTP headers for the request. Multiple calls merge.
-   *
-   * @example
-   *   spec("french").headers({ 'Accept-Language': 'fr' }).get("/articles").run();
+   * Copy a fixture into the working directory before execution. The path is
+   * feature-local (`<test-dir>/fixtures/<path>`) or, with a `$FIXTURES/`
+   * prefix, from the shared pool at `<specs-root>/fixtures/`. A trailing
+   * slash spreads a directory's contents into the cwd; without one a
+   * directory (or file) is copied under its own name. Chained calls layer.
    */
-  headers(headers: Record<string, string>): this;
+  fixture: (path: string) => CliSpecification<DatabaseKey>;
+  /** Queue a SQL seed file from `seeds/` to run against a database before the action. */
+  seed: (file: string, options?: {
+    database?: DatabaseKey;
+  }) => CliSpecification<DatabaseKey>;
   /**
-   * Intercept an outgoing HTTP request and return a controlled response.
-   * Uses MSW under the hood. Intercepts are queued — multiple calls with the
-   * same trigger fire sequentially (first match consumed first).
-   *
-   * @param trigger - What to match (use openai.agent(), http.get(), etc.)
-   * @param response - What to return: an InterceptResponse object, or a filename
-   *   from `intercepts/` (JSON loaded and auto-wrapped by the trigger).
-   *
-   * @example
-   *   // With inline response
-   *   .intercept(openai.agent({...}), openai.reply({ categories: ['TECH'] }))
-   *
-   *   // With JSON fixture file (loaded from intercepts/ directory)
-   *   .intercept(openai.agent({...}), 'ingest-tech.json')
-   *   .intercept(http.get(url), 'world-news-tech.json')
+   * Execute the command (or sequence of commands) and resolve with the
+   * result. Called with no arguments (`cli.exec()`), the binary runs bare —
+   * no CLI arguments. With `{ waitFor, timeout }`, the process is
+   * long-running: it resolves when the pattern appears and is killed at the
+   * timeout.
    */
-  intercept(trigger: InterceptTrigger, response: InterceptResponse | string): this;
+  exec: (args?: string | string[], options?: ExecOptions) => Promise<CliResult>;
+}
+//#endregion
+//#region src/core/specification/cli/result.d.ts
+/**
+ * Result from a command action (`.exec()`).
+ *
+ * When the runner was configured with a `docker` option, the result also
+ * exposes container accessors and participates in `Symbol.asyncDispose`
+ * cleanup. The Docker shell-outs are **lazy**: a test that never calls
+ * `.container(...)` never queries the Docker daemon, so command-only tests
+ * pay zero Docker cost even when the runner is Docker-aware.
+ *
+ * Dispose always runs one final label-filtered `docker ps` to catch
+ * containers that were spawned during `.exec` but never asserted on —
+ * tests still get leak-free cleanup even if they forget to reach into
+ * a container.
+ */
+declare class CliResult extends BaseResult {
+  private readonly commandOutput;
+  private containersCache;
+  private readonly dockerConfig?;
+  private readonly testRunId?;
+  private readonly transform?;
+  constructor(options: {
+    commandOutput: CliOutput;
+    config: SpecificationConfig;
+    dockerConfig?: DockerSpecConfig;
+    testDir: string;
+    testRunId?: string;
+    transform?: (text: string) => string;
+    workDir: string;
+  });
+  /** The process exit code. */
+  get exitCode(): number;
+  /** Accessor for the captured standard output with file-based assertions. */
+  get stdout(): TextAccessor;
+  /** Accessor for the captured standard error with file-based assertions. */
+  get stderr(): TextAccessor;
+  /** Accessor for parsing stdout as JSON and asserting against JSON fixtures. */
+  get json(): JsonAccessor;
+  /** Accessor for the temporary working directory the command ran in. */
+  get filesystem(): FilesystemAccessor;
   /**
-   * Send a GET request to the server adapter.
+   * Look up a container the command spawned during this run by the value of
+   * its name-label (as declared in the `docker.nameLabel` of the
+   * `specification.cli()` options).
+   * First access triggers a one-shot `docker ps` + `docker inspect`
+   * query and caches the result for the rest of the result's lifetime.
+   * Tests that don't call this never touch Docker.
    *
-   * @example
-   *   spec("list items").get("/api/items").run();
+   * Returns an accessor with `.exists === false` when no container
+   * carries that name — callers can still assert absence without a try.
    */
-  get(path: string): this;
+  container(name: string): ContainerAccessor;
+  /** All captured container IDs. Triggers the same lazy query as `container()`. */
+  get containerIds(): string[];
+  [Symbol.asyncDispose](): Promise<void>;
+  private ensureDockerAware;
+  private loadContainers;
+}
+//#endregion
+//#region src/integrations/docker/container-accessor.d.ts
+/**
+ * Assertion accessor for a single Docker container captured by the docker()
+ * spec mode. Mirrors the shape of {@link CliResult} so tests use the same
+ * vocabulary (`stdout.toContain`, `file(...).content`, etc.) regardless
+ * of where output came from.
+ *
+ * Sync state (`exists`, `running`, `status`) is derived from the `docker
+ * inspect` payload captured at result-construction time. Logs are fetched
+ * lazily on first access to `stdout`/`stderr`.
+ */
+declare class ContainerAccessor {
+  private cachedLogs;
+  private readonly containerId;
+  readonly exists: boolean;
+  private readonly inspectData;
+  readonly running: boolean;
+  readonly status: string;
+  private readonly testDir;
+  private readonly transform?;
   /**
-   * Send a POST request to the server adapter.
-   *
-   * @param bodyFile - Optional JSON file from `requests/` to use as the request body.
-   * @example
-   *   spec("create item").post("/api/items", "new-item.json").run();
+   * Underlying Docker container ID, or `null` if no container was captured
+   * for this name. Useful when a follow-up CLI command needs to reference
+   * the container by id (e.g. `spwn world inspect <id>`). Prefer the other
+   * accessors for common reads — pulling the raw id is the escape hatch.
    */
-  post(path: string, bodyFile?: string): this;
-  /** Send a PUT request to the server adapter. */
-  put(path: string, bodyFile?: string): this;
-  /** Send a DELETE request to the server adapter. */
-  delete(path: string): this;
+  get id(): null | string;
+  constructor(containerId: null | string, inspectData: unknown, testDir: string, transform?: (text: string) => string);
   /**
-   * Execute a CLI command (or a sequence of commands) in an isolated working directory.
-   * When an array is passed, commands run sequentially and stop on the first non-zero exit code.
-   *
-   * @example
-   *   spec("init project").exec("init --name demo").run();
-   *   spec("multi-step").exec(["init", "build"]).run();
+   * Raw `docker inspect` object for this container. Throws if the container
+   * was not captured (i.e. `.exists === false`).
    */
-  exec(args: string | string[]): this;
-  /** Spawn a long-running CLI process with custom spawn options (e.g. timeout, signal). */
-  spawn(args: string, options: SpawnOptions): this;
+  get inspect(): JsonAccessor;
+  /** Captured logs (stdout+stderr combined for v1). */
+  get stdout(): TextAccessor;
+  /** Captured logs (stdout+stderr combined for v1). */
+  get stderr(): TextAccessor;
   /**
-   * Execute a named job registered via the app() factory.
-   *
-   * @param name - The job name to trigger (must match a registered JobHandle.name).
-   *
-   * @example
-   *   spec('pipeline').intercept(openai.chat(), openai.response({...})).job('report-refresh').run();
+   * Read a file from inside the container via `docker exec cat`. The
+   * returned object satisfies the same {@link FileAccessor} shape used by
+   * the host filesystem accessor, so tests do not need to learn a new API.
    */
-  job(name: string): this;
+  file(path: string): FileAccessor;
   /**
-   * Execute the specification: run seeds, copy fixtures, then perform the
-   * configured action (HTTP or CLI).
-   *
-   * @returns The result object used for assertions.
-   * @example
-   *   const result = await spec("test").exec("status").run();
-   *   expect(result.exitCode).toBe(0);
-   */
-  run(): Promise<SpecificationResult>;
-  private resolveEnv;
-  private prepareWorkDir;
-  private runHttpAction;
-  private runJobAction;
-  private runCliAction;
-}
-/** Factory function returned by `cli()`, `integration()`, or `e2e()` that starts a new spec. */
-type SpecificationRunner = (label: string) => SpecificationBuilder;
-/**
- * Create a {@link SpecificationRunner} bound to the given adapter configuration.
- * The test file directory is auto-detected from the call stack.
- */
-declare function createSpecificationRunner(config: SpecificationConfig): SpecificationRunner;
-//#endregion
-//#region src/docker/docker-port.d.ts
-/** Abstract interface for interacting with a Docker container (exec, inspect, file I/O). */
-interface DockerContainerPort {
-  /** Execute a command inside the container, return stdout */
-  exec(cmd: string[]): Promise<string>;
-  /** Read a file from inside the container */
-  file(path: string): Promise<{
-    exists: boolean;
-    content: string;
-  }>;
-  /** Check if container is running */
-  isRunning(): Promise<boolean>;
-  /** Get container logs */
-  logs(tail?: number): Promise<string>;
-  /** Get full docker inspect JSON */
-  inspect(): Promise<DockerInspectResult>;
-  /** Check if a file/directory exists */
-  exists(path: string): Promise<boolean>;
-}
-/** Normalized subset of `docker inspect` output for assertion use. */
-interface DockerInspectResult {
-  id: string;
-  name: string;
-  state: {
-    running: boolean;
-    exitCode: number;
-    status: string;
-  };
-  config: {
-    image: string;
-    env: string[];
-  };
-  hostConfig: {
-    memory: number;
-    cpuQuota: number;
-    networkMode: string;
-    mounts: Array<{
-      source: string;
-      destination: string;
-      type: string;
-    }>;
-  };
-  networkSettings: {
-    networks: Record<string, {
-      gateway: string;
-      ipAddress: string;
-    }>;
-  };
-}
-//#endregion
-//#region src/docker/docker-assertion.d.ts
-/**
- * Fluent assertion builder for Docker containers.
- * Chain async assertions like `toBeRunning()`, `toHaveFile()`, `toHaveMount()`.
- */
-declare class DockerAssertion {
-  private container;
-  constructor(container: DockerContainerPort);
-  /** Assert the container is running */
-  toBeRunning(): Promise<this>;
-  /** Assert the container is NOT running / doesn't exist */
-  toNotExist(): Promise<this>;
-  /** Assert a file exists inside the container */
-  toHaveFile(path: string, opts?: {
-    containing?: string;
-  }): Promise<this>;
-  /** Assert a file does NOT exist */
-  toNotHaveFile(path: string): Promise<this>;
-  /** Assert a directory exists */
-  toHaveDirectory(path: string): Promise<this>;
-  /** Assert a mount exists */
-  toHaveMount(destination: string): Promise<this>;
-  /** Assert network mode */
-  toHaveNetwork(mode: string): Promise<this>;
-  /** Assert memory limit */
-  toHaveMemoryLimit(bytes: number): Promise<this>;
-  /** Assert CPU quota */
-  toHaveCpuQuota(quota: number): Promise<this>;
-  /** Execute a command and return output for custom assertions */
-  exec(cmd: string[]): Promise<string>;
-  /** Read a file for custom assertions */
-  readFile(path: string): Promise<string>;
-  /** Get logs for custom assertions */
-  getLogs(tail?: number): Promise<string>;
-}
-//#endregion
-//#region src/infra/orchestrator.d.ts
+   * Run a shell command inside the container and get back the same
+   * {@link CliResult} used for host-side executions.
+   */
+  exec(cmd: string): Promise<CliResult>;
+  private requireExists;
+  private loadLogs;
+  private containerExec;
+}
+//#endregion
+//#region src/vitest/matchers.d.ts
+/**
+ * Per-call options for the fixture-file `toMatch` subjects. `frozen` opts a
+ * single fixture OUT of update-mode rewriting: a frozen fixture is NEVER
+ * written under `TEST_UPDATE=1` (or vitest `-u`) — in update mode a frozen
+ * mismatch still throws its diff, and a frozen missing fixture still throws its
+ * "does not exist" error. This is what makes a DELIBERATELY-WRONG fixture (the
+ * subject of a negative test that asserts the mismatch/error rendering)
+ * survivable across update runs instead of being silently overwritten with the
+ * actual output.
+ */
+interface MatchFixtureOptions {
+  frozen?: boolean;
+}
+//#endregion
+//#region src/core/specification/shared/orchestrator.d.ts
 interface OrchestratorOptions {
-  services: ServiceHandle[];
+  /**
+   * Named infrastructure record. Keys become the database vocabulary of the
+   * spec (`.seed()` / `.table()` `database` option) and drive the compose
+   * binding: a handle with no explicit `composeService` links to the compose
+   * service named exactly like its key, else the kebab-case conversion of the
+   * key (`analyticsDb` → `analytics-db`) — see {@link resolveComposeBinding}.
+   */
+  services: Record<string, ServiceHandle>;
   mode: 'e2e' | 'integration';
   root?: string;
   /** Compose project name — used for per-worker stack isolation. */
@@ -451,6 +908,14 @@ declare class Orchestrator {
   private composeHandles;
   private started;
   constructor(options: OrchestratorOptions);
+  /**
+   * Bind each declared handle to a compose service (CONVENTIONS A6): a record
+   * key resolves to the service named exactly like it, else the kebab-case
+   * conversion of the key; an explicit `composeService` wins. Throws on an
+   * ambiguous binding (both names present). Runs once compose config is known
+   * so the two-step resolution can consult the real service list.
+   */
+  private resolveBindings;
   /**
    * Start declared services via testcontainers (integration mode).
    * Phase 1: start all containers in parallel (the slow part).
@@ -471,264 +936,566 @@ declare class Orchestrator {
    */
   stopCompose(): Promise<void>;
   /**
-   * Get a database service by compose name, or the first one if no name given.
+   * Get the default database — the first declared handle that is one.
    */
-  getDatabase(serviceName?: string): DatabasePort | null;
+  getDatabase(): DatabasePort | null;
   /**
-   * Get all database services keyed by compose name.
+   * Get all database services keyed by their record key (declared services)
+   * or compose service name (stack-detected services).
    */
   getDatabases(): Map<string, DatabasePort>;
+  private allHandles;
   /**
    * Get app URL from compose (e2e mode).
    */
   getAppUrl(): null | string;
 }
 //#endregion
-//#region src/spec/targets.d.ts
+//#region src/core/specification/shared/services.d.ts
+/**
+ * Infrastructure services declared as a named record. Keys become the typed
+ * vocabulary of the whole spec: the server factory receives the same record,
+ * and `.seed()` / `.table()` target databases by key.
+ */
+type ServiceRecord = Record<string, ServiceHandle>;
+/** Keys of a services record whose handles are databases. */
+type DatabaseKeys<Services extends ServiceRecord> = { [K in keyof Services]: Services[K] extends DatabasePort ? K & string : never; }[keyof Services];
+//#endregion
+//#region src/core/specification/api/start-api.d.ts
 /** Any object with a request method compatible with Hono's app.request(). */
-type HonoApp$1 = {
+type HonoApp = {
   request: (path: string, init?: RequestInit) => Promise<Response> | Response;
 };
-/** A named job that can be triggered via .job(). */
-interface JobHandle {
-  name: string;
-  execute: () => Promise<void>;
+/** Execution mode — exists ONLY on `specification.api()` (CONVENTIONS A5). */
+type SpecificationMode = 'compose' | 'node';
+/** Options for {@link startApi | specification.api}. */
+interface ApiSpecificationOptions<Services extends ServiceRecord = ServiceRecord> {
+  /**
+   * Execution mode override. Resolution: `options.mode` >
+   * `process.env.TEST_MODE` > `'node'`. Never hardcode this in a
+   * specification file when `server` is defined — set it per vitest
+   * project via `env: { TEST_MODE: 'compose' }` (CONVENTIONS A5).
+   */
+  mode?: SpecificationMode;
+  /**
+   * Project root override for compose detection and init scripts. When
+   * absent, the root is auto-discovered by walking up from the calling
+   * specification file to the first directory containing
+   * `docker/compose.test.yaml`, else the first containing `package.json`
+   * (CONVENTIONS A9).
+   */
+  root?: string;
+  /**
+   * The app factory — receives the started services record (fully typed)
+   * and returns the Hono app. Required in node mode, ignored in compose
+   * mode (the app runs as a compose service there).
+   */
+  server?: (services: Services) => HonoApp;
+  /**
+   * Named infrastructure record. Keys become the `database` vocabulary of
+   * `.seed()` / `.table()` and drive the compose binding: a handle with no
+   * `composeService` option links to the compose service named exactly like
+   * its key, else the kebab-case conversion of the key (CONVENTIONS A6).
+   */
+  services?: Services;
 }
-/** Services map passed to the app factory after infrastructure starts. */
-type AppServices = Record<string, ServiceHandle>;
 /**
- * Return value from the app() factory. Either a bare server (backward compat)
- * or an object with server + jobs for job-based testing.
+ * The record returned by {@link startApi | specification.api}. Destructure
+ * with the canonical names (CONVENTIONS A3):
+ *
+ *     const { api, cleanup, docker } = await specification.api(…);
  */
-type AppFactoryResult = HonoApp$1 | {
-  server: HonoApp$1;
-  jobs: JobHandle[];
-};
-/** In-process Hono app target. Created by {@link app}. */
-interface AppTarget {
-  readonly kind: 'app';
-  readonly factory: (services: AppServices) => AppFactoryResult;
-}
-/** Docker compose stack target. Created by {@link stack}. */
-interface StackTarget {
-  readonly kind: 'stack';
-  readonly root: string;
+interface ApiHandle<DatabaseKey extends string = string> {
+  api: ApiSpecification<DatabaseKey>;
+  /** Stop all infrastructure started by this specification. */
+  cleanup: () => Promise<void>;
+  /**
+   * Read a running container by id — returns a {@link ContainerAccessor}
+   * usable with `await expect(...).toBeRunning()` and read accessors.
+   */
+  docker: (containerId: string) => ContainerAccessor;
+  /** The orchestrator managing the test infrastructure lifecycle. */
+  orchestrator: Orchestrator;
 }
-/** CLI command target. Created by {@link command}. */
-interface CommandTarget {
-  readonly kind: 'command';
-  readonly bin: string;
+declare function startApi<Services extends ServiceRecord>(options: ApiSpecificationOptions<Services>): Promise<ApiHandle<DatabaseKeys<Services>>>;
+//#endregion
+//#region src/core/specification/cli/start-cli.d.ts
+/** Options for {@link startCli | specification.cli}. */
+interface CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord> {
+  /**
+   * Opt-in Docker awareness. When set, every spec generates a unique
+   * test-run id, injects it into the child process env under `envVar`,
+   * and exposes `.container(name)` accessors on the result that lazily
+   * query Docker. Always declare results with `await using` so leaked
+   * containers get force-removed at scope exit (CONVENTIONS B5).
+   */
+  docker?: DockerSpecConfig;
+  /**
+   * Project-root override (CONVENTIONS A9) — the single meaning of `root`:
+   * it anchors compose detection and local-bin resolution for the tested
+   * binary. It is NOT a fixtures root; `.fixture()` resolves feature-local
+   * or `$FIXTURES/` paths on its own.
+   */
+  root?: string;
+  /**
+   * Named infrastructure record started via testcontainers. Connection
+   * URLs are injected automatically into the child env: `<KEY>_URL` per
+   * service, plus `DATABASE_URL` / `REDIS_URL` when unambiguous
+   * (CONVENTIONS B6). `.env()` overrides.
+   */
+  services?: Services;
+  /**
+   * Escape hatch: normaliser applied to result.stdout / result.stderr
+   * before every comparison, AFTER the default ANSI strip (CONVENTIONS
+   * D6). Does NOT mutate the raw `.text` accessor. Prefer `{{token}}`
+   * placeholders in fixtures.
+   */
+  transform?: (text: string) => string;
 }
-/** Any target that produces an HTTP interface (app or stack). */
-type HttpTarget = AppTarget | StackTarget;
-/** Any valid spec target. */
-type SpecTarget = AppTarget | CommandTarget | StackTarget;
 /**
- * Test against an in-process Hono app. The factory receives started services
- * so you can wire connection strings into your app/DI container.
+ * The record returned by {@link startCli | specification.cli}. Destructure
+ * with the canonical names (CONVENTIONS A3):
  *
- * @param factory - Function that receives services and returns a Hono app instance.
- *
- * @example
- *   const db = postgres({ compose: 'db' });
- *   await spec(
- *       app((services) => createApp({ databaseUrl: services.db.connectionString })),
- *       { services: [db] },
- *   );
+ *     const { cli, cleanup, docker } = await specification.cli(…);
  */
-declare function app(factory: (services: AppServices) => HonoApp$1): AppTarget;
-/**
- * Test against a full docker compose stack. The stack is started with
- * `docker compose up` and real HTTP requests are sent to the app service.
- *
- * @param root - Project root containing `docker/compose.test.yaml`.
- *
- * @example
- *   await spec(stack('../../'));
- */
-declare function stack(root: string): StackTarget;
-/**
- * Test a CLI binary. Each spec runs in a fresh temp directory.
- *
- * @param bin - Path to the CLI binary or command name (resolved from node_modules/.bin or PATH).
- *
- * @example
- *   await spec(command('my-cli'), { root: '../fixtures' });
- */
-declare function command(bin: string): CommandTarget;
-//#endregion
-//#region src/spec/spec.d.ts
-/** Shared options for all spec targets. */
-interface SpecOptions {
-  /** Project root for fixture lookup and compose detection (relative paths supported). */
-  root?: string;
-  /** Infrastructure services to start via testcontainers. */
-  services?: ServiceHandle[];
-}
-/** A specification runner with teardown support and orchestrator access. */
-interface SpecRunner {
-  /** The function to create individual specs: `runner('label').get('/path').run()`. */
-  (label: string): SpecificationBuilder;
-  /** Stop all infrastructure started by this runner. */
+interface CliHandle<DatabaseKey extends string = string> {
+  /** Stop all infrastructure started by this specification. */
   cleanup: () => Promise<void>;
+  cli: CliSpecification<DatabaseKey>;
   /**
-   * Get a Docker assertion builder for a running container.
-   *
-   * @example
-   *   await runner.docker('my-container').toBeRunning();
+   * Read a running container by id — returns a {@link ContainerAccessor}
+   * usable with `await expect(...).toBeRunning()` and read accessors.
    */
-  docker: (containerId: string) => DockerAssertion;
+  docker: (containerId: string) => ContainerAccessor;
   /** The orchestrator managing the test infrastructure lifecycle. */
-  orchestrator: Orchestrator;
+  orchestrator: null | Orchestrator;
+}
+declare function startCli<Services extends ServiceRecord>(bin: string, options?: CliSpecificationOptions<Services>): Promise<CliHandle<DatabaseKeys<Services>>>;
+//#endregion
+//#region src/core/specification/jobs/start-jobs.d.ts
+/** Options for {@link startJobs | specification.jobs}. */
+interface JobsSpecificationOptions<Services extends ServiceRecord = ServiceRecord> {
+  /**
+   * Named jobs triggerable via `jobs.trigger(name)` — a factory receiving
+   * the started services record, or a static array. Jobs run in-process by
+   * definition (CONVENTIONS A5/A8) — there is no mode.
+   */
+  jobs: ((services: Services) => JobHandle[]) | JobHandle[];
+  /** Project root override — see the `root` option of `specification.api()`. */
+  root?: string;
+  /** Named infrastructure record started via testcontainers. */
+  services?: Services;
 }
 /**
- * Create a specification runner for the given target.
+ * The record returned by {@link startJobs | specification.jobs}. Destructure
+ * with the canonical names (CONVENTIONS A3):
  *
- * @param target - What to test against: {@link app}, {@link stack}, or {@link command}.
- * @param options - Shared options: root directory, infrastructure services.
+ *     const { jobs, cleanup } = await specification.jobs(…);
+ */
+interface JobsHandle<DatabaseKey extends string = string> {
+  /** Stop all infrastructure started by this specification. */
+  cleanup: () => Promise<void>;
+  jobs: JobsSpecification<DatabaseKey>;
+  /** The orchestrator managing the test infrastructure lifecycle. */
+  orchestrator: null | Orchestrator;
+}
+declare function startJobs<Services extends ServiceRecord>(options: JobsSpecificationOptions<Services>): Promise<JobsHandle<DatabaseKeys<Services>>>;
+//#endregion
+//#region src/core/specification/shared/specification.d.ts
+/**
+ * The three specification constructors (CONVENTIONS A2) — created in a
+ * `*.specification.ts` file under `specs/`, destructured with canonical
+ * names, and cleaned up via `afterAll(cleanup)` (A1/A3/A4).
  *
  * @example
- *   // HTTP — in-process app with testcontainers
- *   const s = await spec(app(() => createApp(db)), { services: [db] });
+ *   // specs/api/api.specification.ts
+ *   export const { api, cleanup } = await specification.api({
+ *       services: { db: postgres() },
+ *       server: ({ db }) => createApp({ databaseUrl: db.connectionString }),
+ *   });
+ *   afterAll(cleanup);
  *
- *   // HTTP — full docker compose stack
- *   const s = await spec(stack('../../'));
+ *   // specs/jobs/jobs.specification.ts
+ *   export const { jobs, cleanup } = await specification.jobs({
+ *       services: { db: postgres() },
+ *       jobs: ({ db }) => [nightlyReport(db)],
+ *   });
+ *   afterAll(cleanup);
  *
- *   // CLI — command binary
- *   const s = await spec(command('my-cli'), { root: '../fixtures' });
+ *   // specs/setup/cli.specification.ts
+ *   export const { cli, cleanup } = await specification.cli('my-cli');
+ *   afterAll(cleanup);
  */
-declare function spec(target: SpecTarget, options?: SpecOptions): Promise<SpecRunner>;
+declare const specification: {
+  /**
+   * Test an HTTP app. Mode `'node'` (default) starts the declared services
+   * via testcontainers and runs the app in-process; mode `'compose'` runs
+   * `docker compose up` on `docker/compose.test.yaml` and sends real HTTP
+   * requests to the app service. Resolution: `options.mode` > `TEST_MODE`
+   * env var > `'node'`. Only `.api()` has a mode.
+   */
+  api: typeof startApi;
+  /**
+   * Test a command binary. Each spec runs in a fresh temp directory.
+   *
+   * @param bin - Path to the binary (resolved from node_modules/.bin or PATH).
+   */
+  cli: typeof startCli;
+  /**
+   * Test background jobs. Jobs run in-process by definition — no HTTP
+   * server, no mode. `.trigger(name)` is the terminal action.
+   */
+  jobs: typeof startJobs;
+};
+//#endregion
+//#region src/integrations/docker/docker-lookup.d.ts
+/** Return all container IDs (running or stopped) that carry `key=value`. */
+declare function findContainersByLabel(key: string, value: string): string[];
+/** Return the raw `docker inspect` payload (object, not array) for a container. */
+declare function inspectContainer(id: string): unknown;
+/** Force-remove the given container IDs in a single call. Errors are swallowed. */
+declare function removeContainers(ids: string[]): void;
 //#endregion
-//#region src/infra/ports/container.port.d.ts
+//#region src/core/ports/container.port.d.ts
 /**
  * Abstract container interface.
  * Represents a running service (database, cache, etc.)
  */
 interface ContainerPort {
   /** Start the container and wait until ready. */
-  start(): Promise<void>;
+  start: () => Promise<void>;
   /** Stop and remove the container. */
-  stop(): Promise<void>;
+  stop: () => Promise<void>;
   /** Get the mapped host port for a container port. */
-  getMappedPort(containerPort: number): number;
+  getMappedPort: (containerPort: number) => number;
   /** Get the host to connect to. */
-  getHost(): string;
+  getHost: () => string;
   /** Get a full connection string for this service. */
-  getConnectionString(): string;
+  getConnectionString: () => string;
   /** Get container logs (stdout + stderr). */
-  getLogs(): Promise<string>;
+  getLogs: () => Promise<string>;
 }
 //#endregion
-//#region src/builder/cli/adapters/exec.adapter.d.ts
+//#region src/integrations/postgres/postgres.d.ts
+interface PostgresOptions {
+  /**
+   * Map to a service in docker/compose.test.yaml. Defaults to the handle's
+   * key in the declared services record.
+   */
+  composeService?: string;
+  /** Override image. */
+  image?: string;
+  /** Override environment variables. */
+  env?: Record<string, string>;
+}
+declare class PostgresHandle implements DatabasePort, ServiceHandle {
+  readonly type = "postgres";
+  composeName: null | string;
+  readonly defaultPort = 5432;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  private client;
+  private originalConnectionString;
+  private schema;
+  constructor(options?: PostgresOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort;
+  healthcheck(): Promise<void>;
+  initialize(composeDir: string): Promise<void>;
+  private getClient;
+  seed(sql: string): Promise<void>;
+  reset(): Promise<void>;
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  isolation(): IsolationStrategy;
+}
 /**
- * Executes CLI commands via Node.js child_process.
- * Uses `execSync` for one-shot commands and `spawn` for long-running processes.
- * Used by the `cli()` specification runner.
+ * Create a PostgreSQL service handle.
+ *
+ * @example
+ * // Key derives the compose service (exact name or kebab-case):
+ * //   { db: postgres() }          → compose service "db"
+ * //   { analyticsDb: postgres() } → compose service "analytics-db"
+ * // Escape hatch for names the key cannot derive:
+ * const events = postgres({ composeService: "legacy_event_store" });
+ * // After start: events.connectionString is populated
  */
-declare class ExecAdapter implements CommandPort {
-  private command;
-  constructor(command: string);
-  exec(args: string, cwd: string, extraEnv?: CommandEnv): Promise<CommandResult>;
-  spawn(args: string, cwd: string, options: SpawnOptions, extraEnv?: CommandEnv): Promise<CommandResult>;
-}
+declare function postgres(options?: PostgresOptions): PostgresHandle;
 //#endregion
-//#region src/builder/http/adapters/fetch.adapter.d.ts
+//#region src/integrations/redis/redis.d.ts
+interface RedisOptions {
+  /**
+   * Map to a service in docker/compose.test.yaml. Defaults to the handle's
+   * key in the declared services record.
+   */
+  composeService?: string;
+  /** Override image. */
+  image?: string;
+}
+declare class RedisHandle implements ServiceHandle {
+  readonly type = "redis";
+  composeName: null | string;
+  readonly defaultPort = 6379;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  private dbIndex;
+  constructor(options?: RedisOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort | null;
+  healthcheck(): Promise<void>;
+  initialize(): Promise<void>;
+  reset(): Promise<void>;
+  isolation(): IsolationStrategy;
+}
 /**
- * Server adapter that sends real HTTP requests via the Fetch API.
- * Used by the `e2e()` specification runner to hit a live server.
+ * Create a Redis service handle.
+ *
+ * @example
+ * // The record key derives the compose service: { cache: redis() } → "cache".
+ * const cache = redis();
+ * // After start: cache.connectionString is populated
  */
-declare class FetchAdapter implements ServerPort {
-  private baseUrl;
-  constructor(url: string);
-  request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
-}
+declare function redis(options?: RedisOptions): RedisHandle;
 //#endregion
-//#region src/builder/http/adapters/hono.adapter.d.ts
+//#region src/integrations/sqlite/sqlite.d.ts
+interface SqliteOptions {
+  /**
+   * Path to a SQL file used to initialize the database schema.
+   * Mutually exclusive with `prismaSchema`.
+   */
+  init?: string;
+  /**
+   * Path to a Prisma schema directory or file.
+   * The adapter runs `prisma db push` to create the template.
+   * Mutually exclusive with `init`.
+   */
+  prismaSchema?: string;
+}
+declare class SqliteHandle implements DatabasePort, ServiceHandle {
+  readonly type = "sqlite";
+  composeName: null | string;
+  readonly defaultPort = 0;
+  readonly defaultImage = "";
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  started: boolean;
+  private db;
+  private templatePath;
+  private workerDbPath;
+  private initSql;
+  private prismaSchema;
+  constructor(options?: SqliteOptions);
+  buildConnectionString(): string;
+  createDatabaseAdapter(): DatabasePort;
+  healthcheck(): Promise<void>;
+  initialize(): Promise<void>;
+  private getDb;
+  private closeDb;
+  seed(sql: string): Promise<void>;
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  reset(): Promise<void>;
+  isolation(): IsolationStrategy;
+}
 /**
- * Server adapter that dispatches requests in-process through a Hono app instance.
- * Used by the `integration()` specification runner -- no network overhead.
+ * Create a SQLite service handle. Uses file-copy isolation for parallel tests.
+ *
+ * @example
+ *   // With Prisma schema
+ *   const db = sqlite({ prismaSchema: './prisma/schema' });
+ *
+ *   // With raw SQL init
+ *   const db = sqlite({ init: './schema.sql' });
+ *
+ *   // Empty database
+ *   const db = sqlite();
  */
-declare class HonoAdapter implements ServerPort {
-  private app;
-  constructor(app: {
-    request: (path: string, init?: RequestInit) => Promise<Response> | Response;
-  });
-  request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
-}
+declare function sqlite(options?: SqliteOptions): SqliteHandle;
 //#endregion
-//#region src/spec/legacy-integration.d.ts
-type HonoApp = {
-  fetch: (...args: any[]) => any;
-  request: (path: string, init?: RequestInit) => Promise<Response> | Response;
-};
-interface IntegrationOptions {
-  /** Factory that returns a Hono app — called after services start. */
-  app: () => HonoApp;
-  /** Project root for compose detection (relative paths supported). */
-  root?: string;
-  /** Declared services — started via testcontainers. */
-  services: ServiceHandle[];
-}
-/** A specification runner that also exposes teardown and the underlying orchestrator. */
-interface SpecificationRunnerWithCleanup extends SpecificationRunner {
-  /** Stop all infrastructure containers started by this runner. */
-  cleanup: () => Promise<void>;
-  /** The orchestrator managing the test infrastructure lifecycle. */
-  orchestrator: Orchestrator;
+//#region src/integrations/anthropic/anthropic.d.ts
+interface AnthropicMessagesFilter {
+  model?: RegExp | string;
+  system?: RegExp | string;
+  user?: RegExp | string;
+  tools?: string[];
 }
+declare function buildReply(data: unknown): InterceptResponse;
 /**
- * Create an integration specification runner.
- * Starts infra containers via testcontainers, app runs in-process.
+ * Anthropic API intercept helpers.
  */
-declare function integration(options: IntegrationOptions): Promise<SpecificationRunnerWithCleanup>;
+declare const anthropic: {
+  /**
+   * Trigger: match Messages API requests, 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.
+   *
+   * @example
+   *   anthropic.messages()
+   *   anthropic.messages({ system: /classify/ })
+   *   anthropic.messages({ user: /classify/ }, GATEWAY)
+   */
+  messages(filter?: AnthropicMessagesFilter, url?: string): InterceptTrigger;
+  /** Response: wrap data in Anthropic messages format. */
+  reply: typeof buildReply;
+  /** Response: return an Anthropic error. */
+  error(status: number, message?: string): InterceptResponse;
+  /** Response: simulate a timeout. */
+  timeout(): InterceptResponse;
+};
 //#endregion
-//#region src/spec/legacy-cli.d.ts
-interface CliOptions {
-  /** CLI command to run (resolved from node_modules/.bin or PATH). */
-  command: string;
-  /** Project root — base dir for .project() fixture lookup (relative paths supported). */
-  root?: string;
-  /** Optional infrastructure services (started via testcontainers). */
-  services?: ServiceHandle[];
+//#region src/core/contracts/http.d.ts
+/**
+ * Request filters for the generic HTTP provider. Every field is a subset
+ * constraint — a request matches when all provided fields match.
+ */
+interface HttpInterceptFilter {
+  /**
+   * Body constraint. An object is a deep SUBSET match (toMatchObject-style)
+   * whose leaf values may be `match.*` matchers; a string is a containment
+   * test and a RegExp a `test()` over the raw text body.
+   */
+  body?: object | RegExp | string;
+  /** Header subset. Names are case-insensitive; string = exact value, RegExp = `test()`. */
+  headers?: Record<string, RegExp | string>;
+  /** Query-param subset. string = exact value, RegExp = `test()`. */
+  query?: Record<string, RegExp | string>;
 }
 /**
- * Create a CLI specification runner.
- * Runs CLI commands against fixture projects. Optionally starts infrastructure.
+ * 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).
+ *
+ * @example
+ *   .intercept(http.get('https://api.example.com/data'), 'http/response.json')
+ *   .intercept(http.post(URL, { body: { user: 'alice' } }), http.json({ ok: true }))
  */
-declare function cli(options: CliOptions): Promise<SpecificationRunnerWithCleanup>;
+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;
+};
 //#endregion
-//#region src/spec/legacy-e2e.d.ts
-interface E2eOptions {
-  /** Project root — must contain docker/compose.test.yaml. */
-  root?: string;
+//#region src/integrations/openai/openai.d.ts
+interface OpenAIChatFilter {
+  model?: RegExp | string;
+  system?: RegExp | string;
+  user?: RegExp | string;
+  tools?: string[];
+  temperature?: number;
+}
+interface OpenAIResponsesFilter {
+  model?: RegExp | string;
+  system?: RegExp | string;
+  user?: RegExp | string;
+  tools?: string[];
 }
+declare function buildChatReply(data: unknown): InterceptResponse;
 /**
- * Create an E2E specification runner.
- * Starts full docker compose stack. App URL and database auto-detected.
+ * OpenAI API intercept helpers.
  */
-declare function e2e(options?: E2eOptions): Promise<SpecificationRunnerWithCleanup>;
+declare const openai: {
+  /**
+   * Trigger: match Chat Completions API requests.
+   *
+   * @example
+   *   openai.chat()                         // any chat call
+   *   openai.chat({ model: 'gpt-4o' })      // specific model
+   *   openai.chat({ system: /classify/ })    // system prompt match
+   */
+  chat(filter?: OpenAIChatFilter): InterceptTrigger;
+  /**
+   * Trigger: match Responses API requests (AI SDK v5+) with auto-wrapping.
+   * When used with a JSON file, the data is automatically wrapped in the
+   * Responses API envelope.
+   *
+   * @param filter - Optional body filters.
+   * @param url - Custom gateway URL (default: api.openai.com).
+   *
+   * @example
+   *   openai.responses({ user: /Report Ingestion/ }, GATEWAY)
+   */
+  responses(filter?: OpenAIResponsesFilter, url?: string): InterceptTrigger;
+  /**
+   * Response: wrap data in Chat Completions format.
+   *
+   * @example
+   *   openai.reply({ categories: ['TECH'] })
+   */
+  reply: typeof buildChatReply;
+  /** Response: return an OpenAI error. */
+  error(status: number, message?: string): InterceptResponse;
+  /** Response: return malformed content. */
+  malformed(content: string): InterceptResponse;
+  /** Response: simulate a timeout. */
+  timeout(): InterceptResponse;
+};
 //#endregion
-//#region src/builder/common/grep.d.ts
+//#region src/vitest/mock-of.d.ts
+/** Factory signature that creates a deep mock proxy for any interface. */
+type MockPort = <T>() => DeepMockProxy<T>;
 /**
- * Extract text blocks from output that contain a pattern.
- * Splits by blank lines (how linter/compiler output is structured),
- * returns only blocks matching the pattern.
- *
- * @example
- * expect(grep(result.stdout, "unused-var.ts")).toContain("no-unused-vars")
- * expect(grep(result.stdout, "valid/sorted.ts")).not.toContain("sort-imports")
+ * Create a deep mock proxy for a given type.
+ * Wraps `vitest-mock-extended`'s `mockDeep` for convenient port mocking.
  */
-declare function grep(output: string, pattern: string): string;
+declare const mockOf: MockPort;
 //#endregion
-//#region src/builder/common/reporter.d.ts
-/** Strip ANSI escape codes from a string. */
-declare function stripAnsi(str: string): string;
-/** Strip ANSI codes and replace volatile tokens (ports, durations) with placeholders. */
-declare function normalizeOutput(str: string): string;
+//#region src/vitest/mock-of-date.d.ts
+/** Interface for freezing and resetting the global Date in tests. */
+interface MockDatePort {
+  /** Restore the real Date object. */
+  reset: () => void;
+  /** Freeze `Date.now()` and `new Date()` to the given value. */
+  set: (date: Date | number | string) => void;
+}
+/**
+ * Freeze or reset the global Date for deterministic time-dependent tests.
+ * Wraps the `mockdate` package.
+ */
+declare const mockOfDate: MockDatePort;
 //#endregion
-//#region src/docker/docker-adapter.d.ts
-/** Create a {@link DockerContainerPort} bound to an existing container by ID. */
-declare function dockerContainer(containerId: string): DockerContainerPort;
+//#region src/index.d.ts
+declare module 'vitest' {
+  interface Matchers<T = any> {
+    /** Assert the table has zero rows. Async — queries the database. */
+    toBeEmpty: T extends TableAccessor ? () => Promise<void> : never;
+    /** Assert the container is running. Async — docker-backed subject. */
+    toBeRunning: T extends ContainerAccessor ? () => Promise<void> : never;
+    /**
+     * Assert the table contains exactly the given rows for the given
+     * columns. Cells accept `match.*` dynamic-value matchers. Async —
+     * queries the database.
+     */
+    toMatchRows: T extends TableAccessor ? (expected: {
+      columns: string[];
+      rows: readonly (readonly unknown[])[];
+    }) => Promise<void> : never;
+  }
+  interface Assertion<T = any> {
+    /**
+     * On `@jterrazz/test` accessors: assert the subject matches a fixture
+     * file under `expected/<name>` (flat — a slash creates a subfolder;
+     * `.http` format for `result.response`). Async for filesystem/directory
+     * subjects (tree compare on disk). Other subjects keep vitest-native
+     * `toMatch` semantics (string substring / regexp).
+     *
+     * Pass `{ frozen: true }` to opt a single fixture OUT of update-mode
+     * rewriting: a frozen fixture is never overwritten under `TEST_UPDATE=1`
+     * (or vitest `-u`), and a frozen mismatch/missing fixture still throws.
+     * Use it for a deliberately-wrong fixture whose diff/error rendering is
+     * the behaviour under test.
+     */
+    toMatch: T extends DirectoryAccessor | FilesystemAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => Promise<void> : T extends JsonAccessor | ResponseAccessor | TextAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => void : (expected: RegExp | string, options?: MatchFixtureOptions) => void;
+  }
+}
 //#endregion
-export { type AppFactoryResult, type AppServices, type AppTarget, type CliOptions, type CommandEnv, type CommandPort, type CommandResult, type CommandTarget, type ContainerPort, type DatabasePort, DirectoryAccessor, type DirectorySnapshotOptions, DockerAssertion, type DockerContainerPort, type DockerInspectResult, type E2eOptions, ExecAdapter, FetchAdapter, type FileAccessor, HonoAdapter, type HttpTarget, type IntegrationOptions, type IsolationStrategy, type JobHandle, type MockDatePort, type MockPort, Orchestrator, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServerPort, type ServerResponse, type ServiceHandle, type SpawnOptions, type SpecOptions, type SpecRunner, type SpecTarget, SpecificationBuilder, type SpecificationConfig, SpecificationResult, type SpecificationRunner, type SpecificationRunnerWithCleanup, type SqliteOptions, type StackTarget, TableAssertion, app, cli, command, createSpecificationRunner, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, spec, sqlite, stack, stripAnsi };
-//# sourceMappingURL=index.d.ts.map
+export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type DatabaseKeys, type DatabasePort, DirectoryAccessor, type DockerSpecConfig, type ExecOptions, 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 MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MockDatePort, type MockPort, Orchestrator, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, anthropic, defineContract, findContainersByLabel, http, inspectContainer, match, mockOf, mockOfDate, openai, postgres, redis, removeContainers, specification, sqlite, text };