@jterrazz/test 8.0.0 → 9.0.0

package/dist/index.d.ts

@@ -1,154 +1,357 @@
-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.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/infra/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/infra/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
-interface OrchestratorOptions {
-  services: ServiceHandle[];
-  mode: 'e2e' | 'integration';
-  root?: string;
-  /** Compose project name — used for per-worker stack isolation. */
-  projectName?: string;
+import { DeepMockProxy } from "vitest-mock-extended";
+//#region src/core/matching/match.d.ts
+/**
+ * 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).
+ */
+/** 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;
 }
 /**
- * Orchestrator for test infrastructure.
- * Integration: starts services via testcontainers.
- * E2E: runs full docker compose up.
+ * 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 class Orchestrator {
-  private services;
-  private mode;
-  private root;
-  private projectName;
-  private running;
-  private composeStack;
-  private composeHandles;
-  private started;
-  constructor(options: OrchestratorOptions);
-  /**
-   * Start declared services via testcontainers (integration mode).
-   * Phase 1: start all containers in parallel (the slow part).
-   * Phase 2: wire connections, healthcheck, and init sequentially (fast).
-   */
-  start(): Promise<void>;
-  /**
-   * Stop testcontainers (integration mode).
-   */
-  stop(): Promise<void>;
-  /**
-   * Start full docker compose stack (e2e mode).
-   * Auto-detects infra services and creates handles for them.
-   */
-  startCompose(): Promise<void>;
+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;
   /**
-   * Stop docker compose stack (e2e mode).
+   * 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`).
    */
-  stopCompose(): Promise<void>;
+  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;
   /**
-   * Get a database service by compose name, or the first one if no name given.
+   * 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).
    */
-  getDatabase(serviceName?: string): DatabasePort | null;
+  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.
+ */
+declare class CaptureScope {
+  private readonly values;
   /**
-   * Get all database services keyed by compose name.
+   * The exact working directory of the current spec, when the framework
+   * knows it (cli mode). Drives the `{{workdir}}` token / `match.workdir()`.
    */
-  getDatabases(): Map<string, DatabasePort>;
+  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
+/**
+ * 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>/`.
+ */
+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
+/**
+ * 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).
+ */
+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/core/ports/server.port.d.ts
+/**
+ * HTTP response returned by a server port, with parsed JSON body.
+ */
+interface ServerResponse {
+  /** HTTP status code. */
+  status: number;
+  /** Parsed JSON response body, or null if parsing failed. */
+  body: unknown;
+  /** Response headers as a flat key-value map. */
+  headers: Record<string, string>;
+}
+/**
+ * Abstract server interface for specification runners.
+ * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
+ */
+interface ServerPort {
+  /** Send an HTTP request and return the parsed response. */
+  request: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<ServerResponse>;
+}
+//#endregion
+//#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;
   /**
-   * Get app URL from compose (e2e mode).
+   * 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.
    */
-  getAppUrl(): null | string;
+  grep(pattern: string): TextAccessor;
+  toString(): string;
+  valueOf(): string;
 }
+/**
+ * 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 function text(value: string): TextAccessor;
 //#endregion
-//#region src/spec/modes/cli/command.port.d.ts
+//#region src/core/ports/cli.port.d.ts
 /**
- * Result of executing a CLI command, including exit code and captured output streams.
+ * Raw output from a command execution, including exit code and captured output streams.
  */
-interface CommandResult {
+interface CliOutput {
   /** Process exit code (0 = success). */
   exitCode: number;
   /** Captured standard output. */
@@ -157,139 +360,223 @@ interface CommandResult {
   stderr: string;
 }
 /**
- * Options for spawning a long-running process.
+ * 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 SpawnOptions {
-  /** Resolve when stdout/stderr contains this string. */
-  waitFor: string;
-  /** Kill the process after this many milliseconds. */
-  timeout: number;
+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 CommandEnv = Record<string, null | string>;
+type CliEnv = Record<string, null | string>;
 /**
- * Abstract CLI interface for specification runners.
+ * Abstract command interface for specification runners.
  * Implement this to plug in your command execution strategy.
  */
-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>;
+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/spec/result/directory.d.ts
-interface DirectorySnapshotOptions {
-  ignore?: string[];
-  update?: boolean;
+//#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;
 }
-declare class DirectoryAccessor {
-  private absPath;
-  private testDir;
-  constructor(absPath: string, testDir: string);
-  toMatchFixture(name: string, options?: DirectorySnapshotOptions): Promise<void>;
-  files(options?: {
-    ignore?: string[];
-  }): Promise<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;
+  /**
+   * Transform raw JSON data into a provider-specific response envelope.
+   * Called when .intercept(trigger, 'adapter/file.json') loads a file.
+   */
+  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/spec/result/filesystem.d.ts
+//#region src/core/contracts/contract.d.ts
 /**
- * Accessor for the whole temporary working directory used by a CLI spec.
- *
- * Generalization of {@link DirectoryAccessor} that snapshots the entire CLI
- * working directory into `<test-file-dir>/expected/filesystem/<name>/`.
+ * 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).
  */
-declare class FilesystemAccessor {
-  /** The absolute path of the temporary working directory. */
-  readonly cwd: string;
-  private readonly testDir;
-  constructor(cwd: string, testDir: string);
-  /** List all files (recursively) under the working directory, sorted. */
-  files(options?: {
-    ignore?: string[];
-  }): Promise<string[]>;
+interface InterceptContract {
+  trigger: InterceptTrigger;
   /**
-   * Assert the working directory matches a convention-based fixture tree:
-   * `<test-file-dir>/expected/filesystem/<name>/`.
+   * The reply — a fixed {@link InterceptResponse}, or a function
+   * `(request) => InterceptResponse` evaluated per consumed request when the
+   * response must derive from the incoming payload.
    */
-  toMatch(name: string, options?: DirectorySnapshotOptions): Promise<void>;
+  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/spec/result/json.d.ts
-interface JsonSnapshotOptions {
-  update?: boolean;
-}
+//#region src/core/ports/isolation.port.d.ts
 /**
- * Accessor for a JSON payload parsed from a text stream (stdout).
+ * Strategy for isolating service state across parallel test workers.
  *
- * Lazily parses the JSON on first use; parse errors are deferred until an
- * assertion is performed so that callers can still read the raw stream text
- * without triggering a throw.
+ * 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.
  *
- * When a `transform` is configured on the spec runner, it is applied to the
- * raw stdout text BEFORE `JSON.parse`. This lets consumers strip ANSI codes,
- * scrub machine-specific paths, etc. before structural comparison.
+ * Implement this interface to support new service types (e.g. MongoDB,
+ * Elasticsearch, S3).
  */
-declare class JsonAccessor {
-  private readonly rawText;
-  private readonly testDir;
-  private readonly transform?;
-  constructor(rawText: string, testDir: string, transform?: (text: string) => string);
-  /** The parsed JSON value. Throws if the text is not valid JSON. */
-  get value(): unknown;
+interface IsolationStrategy {
   /**
-   * Assert the parsed JSON deep-equals the JSON in the given file on disk.
+   * Create an isolated namespace for this worker.
+   * Called once when the worker starts — e.g. clone a template database,
+   * set a Redis key prefix.
    *
-   * Path is resolved relative to the test file directory unless absolute.
-   * If `JTERRAZZ_TEST_UPDATE=1` (or vitest `-u`), the file is (re)written
-   * with the pretty-printed parsed value.
+   * @param workerId - Unique identifier for this vitest worker.
    */
-  toMatchFile(path: string, options?: JsonSnapshotOptions): void;
+  acquire: (workerId: string) => Promise<void>;
   /**
-   * Assert the parsed JSON matches a convention-based fixture:
-   * `<test-file-dir>/expected/json/<name>`.
-   *
-   * The extension is part of the name and must be included by the caller —
-   * e.g. `toMatch('error.json')`, not `toMatch('error')`. Explicit extensions
-   * are clearer at the call site and remove magic from the resolution.
+   * 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.
    */
-  toMatch(name: string, options?: JsonSnapshotOptions): void;
-  private parse;
+  release: () => Promise<void>;
 }
 //#endregion
-//#region src/spec/result/table.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/spec/result/result.d.ts
+//#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;
@@ -298,9 +585,14 @@ interface BaseResultOptions {
 }
 /**
  * Base result - common accessors available after any action type.
- * Extended by HttpResult, CliResult, and used directly by JobResult.
+ * 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 BaseResult {
+  /** @internal Ref-capture scope shared by every assertion on this result. */
+  readonly captures: CaptureScope;
   protected config: SpecificationConfig;
   protected testDir: string;
   protected workDir?: string;
@@ -309,127 +601,164 @@ declare class BaseResult {
   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/spec/result/stream.d.ts
-interface StreamSnapshotOptions {
-  update?: boolean;
+//#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>;
 }
 /**
- * Accessor for a captured text stream (stdout/stderr) with file-based
- * assertion support.
- *
- * 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.
+ * 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.
  */
-declare class StreamAccessor {
-  private readonly streamName;
-  private readonly testDir;
-  private readonly transform?;
-  readonly text: string;
-  constructor(text: string, streamName: string, testDir: string, transform?: (text: string) => string);
+interface DockerSpecConfig {
+  envVar: string;
+  nameLabel: string;
+  testRunLabel: string;
+}
+/** Adapter configuration passed to the specification facets at setup time. */
+interface SpecificationConfig {
+  command?: CliPort;
+  database?: DatabasePort;
   /**
-   * Assert the captured text matches the given file on disk.
-   *
-   * Path is resolved relative to the test file directory unless absolute.
-   * If `JTERRAZZ_TEST_UPDATE=1` (or vitest `-u`), the file is (re)written
-   * with the actual text.
-   *
-   * When a `transform` is configured on the spec runner, it is applied to
-   * the actual text before comparison (and before writing in update mode).
-   * The fixture file is treated as authoritative and is NOT transformed.
+   * 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.
    */
-  toMatchFile(path: string, options?: StreamSnapshotOptions): void;
+  databaseKeys?: string[];
+  databases?: Map<string, DatabasePort>;
+  dockerConfig?: DockerSpecConfig;
   /**
-   * Assert the captured text matches a convention-based fixture:
-   * `<test-file-dir>/expected/<stream>/<name>`.
-   *
-   * The extension is part of the name and must be included by the caller —
-   * e.g. `toMatch('valid.txt')`, not `toMatch('valid')`. Explicit extensions
-   * are clearer at the call site and remove magic from the resolution.
+   * 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.
    */
-  toMatch(name: string, options?: StreamSnapshotOptions): void;
+  dockerTestRunId?: string;
   /**
-   * Assert the captured text contains the given substring. The runner's
-   * `transform` (if any) is applied before the check so callers can rely
-   * on the same normalised view as {@link toMatch}.
-   *
-   * Throws with a tight diff-style error on miss so tests read uniformly
-   * with the other accessor assertions (no reaching through `.text` into
-   * `expect(...).toContain(...)`).
+   * When set, `.intercept()` is unavailable on this runner and throws this
+   * reason immediately (compose mode — MSW is in-process, CONVENTIONS I3).
    */
-  toContain(substring: string): void;
-  toString(): string;
-  valueOf(): string;
+  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;
 }
-//#endregion
-//#region src/spec/modes/cli/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.
+ * 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.
  *
- * 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`.
+ * The `DatabaseKey` parameter is the typed vocabulary of `.seed()`: the keys
+ * of the declared services record that are databases.
  */
-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?;
-  /**
-   * 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.
-   */
-  get id(): null | string;
-  constructor(containerId: null | string, inspectData: unknown, testDir: string, transform?: (text: string) => string);
-  /**
-   * Raw `docker inspect` object for this container. Throws if the container
-   * was not captured (i.e. `.exists === false`).
-   */
-  get inspect(): JsonAccessor;
-  /** Captured logs (stdout+stderr combined for v1). */
-  get stdout(): StreamAccessor;
-  /** Captured logs (stdout+stderr combined for v1). */
-  get stderr(): StreamAccessor;
+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>;
   /**
-   * 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.
+   * 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.
    */
-  file(path: string): FileAccessor;
+  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>;
   /**
-   * Run a shell command inside the container and get back the same
-   * {@link CliResult} used for host-side executions.
+   * 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.
    */
-  exec(cmd: string): Promise<CliResult>;
-  private requireExists;
-  private loadLogs;
-  private containerExec;
+  exec: (args?: string | string[], options?: ExecOptions) => Promise<CliResult>;
 }
 //#endregion
-//#region src/spec/modes/cli/result.d.ts
+//#region src/core/specification/cli/result.d.ts
 /**
- * Result from a CLI action (.exec(), .spawn()).
+ * 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 CLI-only tests
+ * `.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
@@ -438,13 +767,13 @@ declare class ContainerAccessor {
  * a container.
  */
 declare class CliResult extends BaseResult {
-  private readonly commandResult;
+  private readonly commandOutput;
   private containersCache;
   private readonly dockerConfig?;
   private readonly testRunId?;
   private readonly transform?;
   constructor(options: {
-    commandResult: CommandResult;
+    commandOutput: CliOutput;
     config: SpecificationConfig;
     dockerConfig?: DockerSpecConfig;
     testDir: string;
@@ -455,16 +784,17 @@ declare class CliResult extends BaseResult {
   /** The process exit code. */
   get exitCode(): number;
   /** Accessor for the captured standard output with file-based assertions. */
-  get stdout(): StreamAccessor;
+  get stdout(): TextAccessor;
   /** Accessor for the captured standard error with file-based assertions. */
-  get stderr(): StreamAccessor;
+  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;
   /**
-   * Look up a container the CLI spawned during this run by the value of
-   * its name-label (as declared in `SpecOptions.docker.nameLabel`).
+   * 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.
@@ -476,433 +806,349 @@ declare class CliResult extends BaseResult {
   /** All captured container IDs. Triggers the same lazy query as `container()`. */
   get containerIds(): string[];
   [Symbol.asyncDispose](): Promise<void>;
-  /**
-   * Extract text blocks from stdout that contain a pattern.
-   *
-   * @example
-   *   expect(result.grep('error.ts')).toContain('no-unused-vars');
-   */
-  grep(pattern: string): string;
   private ensureDockerAware;
   private loadContainers;
 }
 //#endregion
-//#region src/spec/result/response.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/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?;
   /**
-   * Assert that the response body matches the JSON in `responses/{file}`.
-   *
-   * @example
-   *   result.response.toMatchFile("expected-items.json");
+   * 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.
+   */
+  get id(): null | string;
+  constructor(containerId: null | string, inspectData: unknown, testDir: string, transform?: (text: string) => string);
+  /**
+   * Raw `docker inspect` object for this container. Throws if the container
+   * was not captured (i.e. `.exists === false`).
+   */
+  get inspect(): JsonAccessor;
+  /** Captured logs (stdout+stderr combined for v1). */
+  get stdout(): TextAccessor;
+  /** Captured logs (stdout+stderr combined for v1). */
+  get stderr(): TextAccessor;
+  /**
+   * 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.
+   */
+  file(path: string): FileAccessor;
+  /**
+   * Run a shell command inside the container and get back the same
+   * {@link CliResult} used for host-side executions.
    */
-  toMatchFile(file: string): void;
+  exec(cmd: string): Promise<CliResult>;
+  private requireExists;
+  private loadLogs;
+  private containerExec;
 }
 //#endregion
-//#region src/spec/modes/http/server.port.d.ts
-/**
- * HTTP response returned by a server port, with parsed JSON body.
- */
-interface ServerResponse {
-  /** HTTP status code. */
-  status: number;
-  /** Parsed JSON response body, or null if parsing failed. */
-  body: unknown;
-  /** Response headers as a flat key-value map. */
-  headers: Record<string, string>;
-}
+//#region src/vitest/matchers.d.ts
 /**
- * Abstract server interface for specification runners.
- * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
+ * 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 ServerPort {
-  /** Send an HTTP request and return the parsed response. */
-  request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
+interface MatchFixtureOptions {
+  frozen?: boolean;
 }
 //#endregion
-//#region src/spec/modes/http/result.d.ts
-/** Result from an HTTP action (.get(), .post(), .put(), .delete()). */
-declare class HttpResult extends BaseResult {
-  private responseData;
-  constructor(options: {
-    config: SpecificationConfig;
-    response: ServerResponse;
-    testDir: string;
-  });
-  /** The HTTP response status code. */
-  get status(): number;
-  /** Access the HTTP response body for assertions. */
-  get response(): ResponseAccessor;
-}
-//#endregion
-//#region src/spec/builder.d.ts
-/** A named job that can be triggered via .job(). */
-interface JobHandle$1 {
-  name: string;
-  execute: () => Promise<void>;
-}
-/**
- * Context passed to a {@link SeedHandler} when a non-SQL seed is dispatched.
- */
-interface SeedHandlerContext {
-  /** Absolute path of the temporary working directory for the current spec. */
-  cwd: string;
-  /** Absolute path of the test file directory (where `seeds/` lives). */
-  testDir: string;
-}
-/**
- * Handler invoked for a non-SQL seed entry. The first path segment of the
- * seed file selects the handler; the handler is given the absolute path of
- * the source fragment (file or directory) and the working directory to mutate.
- */
-type SeedHandler = (ctx: SeedHandlerContext, fragmentPath: string) => Promise<void> | void;
-/**
- * Configuration for the docker() spec 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 runner at setup time. */
-interface SpecificationConfig {
-  command?: CommandPort;
-  database?: DatabasePort;
-  databases?: Map<string, DatabasePort>;
-  dockerConfig?: DockerSpecConfig;
-  /**
-   * Unique id shared by every `.run()` 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
-   * public `createSpecificationRunner` auto-populates this when
-   * `dockerConfig` is present — callers should leave it unset.
-   */
-  dockerTestRunId?: string;
-  fixturesRoot?: string;
-  jobs?: JobHandle$1[];
-  /**
-   * Pluggable seed handlers for CLI-mode tests. Keys are leading path
-   * segments (e.g. `"spwn.yaml/"`, `"agent/"`). When `.seed(relPath)` is
-   * called with a path whose first segment matches, the handler is invoked
-   * with the full absolute path of the seed fragment under
-   * `<test-file-dir>/seeds/<relPath>`.
-   */
-  seedHandlers?: Record<string, SeedHandler>;
-  server?: ServerPort;
+//#region src/core/specification/shared/orchestrator.d.ts
+interface OrchestratorOptions {
   /**
-   * Optional normaliser applied to CLI stdout/stderr before every
-   * .toMatch / .toMatchFile comparison. Does not mutate the raw
-   * `.text` accessor.
+   * 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}.
    */
-  transform?: (text: string) => string;
+  services: Record<string, ServiceHandle>;
+  mode: 'e2e' | 'integration';
+  root?: string;
+  /** Compose project name — used for per-worker stack isolation. */
+  projectName?: string;
 }
 /**
- * Fluent builder for declaring a single test specification.
- *
- * 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.
+ * Orchestrator for test infrastructure.
+ * Integration: starts services via testcontainers.
+ * E2E: runs full docker compose up.
  */
-declare class SpecificationBuilder {
-  private commandArgs;
-  private commandEnv;
-  private config;
-  private fixtures;
-  private intercepts;
-  private jobName;
-  private label;
-  private mocks;
+declare class Orchestrator {
+  private services;
+  private mode;
+  private root;
   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();
+  private running;
+  private composeStack;
+  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.
    */
-  env(env: CommandEnv): this;
+  private resolveBindings;
   /**
-   * Set HTTP headers for the request. Multiple calls merge.
-   *
-   * @example
-   *   spec("french").headers({ 'Accept-Language': 'fr' }).get("/articles").run();
+   * Start declared services via testcontainers (integration mode).
+   * Phase 1: start all containers in parallel (the slow part).
+   * Phase 2: wire connections, healthcheck, and init sequentially (fast).
    */
-  headers(headers: Record<string, string>): this;
+  start(): Promise<void>;
   /**
-   * 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')
+   * Stop testcontainers (integration mode).
    */
-  intercept(trigger: InterceptTrigger, response: InterceptResponse | string): this;
+  stop(): Promise<void>;
   /**
-   * Send a GET request to the server adapter.
-   *
-   * @example
-   *   spec("list items").get("/api/items").run();
+   * Start full docker compose stack (e2e mode).
+   * Auto-detects infra services and creates handles for them.
    */
-  get(path: string): this;
+  startCompose(): Promise<void>;
   /**
-   * 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();
+   * Stop docker compose stack (e2e mode).
    */
-  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;
+  stopCompose(): Promise<void>;
   /**
-   * 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();
+   * Get the default database — the first declared handle that is one.
    */
-  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;
+  getDatabase(): DatabasePort | null;
   /**
-   * 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();
+   * Get all database services keyed by their record key (declared services)
+   * or compose service name (stack-detected services).
    */
-  job(name: string): this;
+  getDatabases(): Map<string, DatabasePort>;
+  private allHandles;
   /**
-   * 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);
+   * Get app URL from compose (e2e mode).
    */
-  run(): Promise<BaseResult | CliResult | HttpResult>;
-  private resolveSeedHandler;
-  private resolveEnv;
-  private prepareWorkDir;
-  private runHttpAction;
-  private runJobAction;
-  private runCliAction;
+  getAppUrl(): null | string;
 }
-/** Factory function returned by `cli()`, `integration()`, or `e2e()` that starts a new spec. */
-type SpecificationRunner = (label: string) => SpecificationBuilder;
+//#endregion
+//#region src/core/specification/shared/services.d.ts
 /**
- * Create a {@link SpecificationRunner} bound to the given adapter configuration.
- * The test file directory is auto-detected from the call stack.
+ * 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.
  */
-declare function createSpecificationRunner(config: SpecificationConfig): SpecificationRunner;
+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/spec/targets.d.ts
+//#region src/core/specification/api/start-api.d.ts
 /** Any object with a request method compatible with Hono's app.request(). */
 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>;
-}
-/** 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.
- */
-type AppFactoryResult = HonoApp | {
-  server: HonoApp;
-  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;
-}
-/** CLI command target. Created by {@link command}. */
-interface CommandTarget {
-  readonly kind: 'command';
-  readonly bin: string;
+/** 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;
 }
-/** 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.
- *
- * @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] },
- *   );
- */
-declare function app(factory: (services: AppServices) => HonoApp): 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.
+ * The record returned by {@link startApi | specification.api}. Destructure
+ * with the canonical names (CONVENTIONS A3):
  *
- * @param root - Project root containing `docker/compose.test.yaml`.
- *
- * @example
- *   await spec(stack('../../'));
+ *     const { api, cleanup, docker } = await specification.api(…);
  */
-declare function stack(root: string): StackTarget;
-/**
- * Test a CLI binary. Each spec runs in a fresh temp directory.
- *
- * Pass a `docker: { envVar, nameLabel, testRunLabel }` option on
- * {@link SpecOptions} to make the runner Docker-aware — the runner
- * stamps a unique test-run id into `envVar`, and results expose
- * `.container(name)` accessors that lazily query Docker. Tests that
- * never call `.container(...)` pay zero Docker cost.
- *
- * @param bin - Path to the CLI binary or command name (resolved from node_modules/.bin or PATH).
- *
- * @example
- *   // CLI-only
- *   await spec(command('my-cli'), { root: '../fixtures' });
- *
- *   // CLI binary that also spawns containers — same runner, just
- *   // opt into container accessors via the docker option:
- *   await spec(command('my-cli'), {
- *       root: '../fixtures',
- *       docker: {
- *           envVar: 'MYCLI_TEST_LABEL',
- *           nameLabel: 'com.mycli.world.name',
- *           testRunLabel: 'com.mycli.test.run',
- *       },
- *   });
- */
-declare function command(bin: string): CommandTarget;
+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;
+}
+declare function startApi<Services extends ServiceRecord>(options: ApiSpecificationOptions<Services>): Promise<ApiHandle<DatabaseKeys<Services>>>;
 //#endregion
-//#region src/spec/spec.d.ts
-/** Shared options for all spec targets. */
-interface SpecOptions {
+//#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 for CLI-mode runners. When set, every
-   * `.run()` 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. A test that
-   * never calls `.container(...)` never touches the Docker daemon —
-   * CLI-only and container-asserting tests share one runner.
-   *
-   * Always wrap calls that may spawn containers with `await using`
-   * so leaked containers get force-removed at scope exit (the
-   * runner cleans up by label filter).
+   * 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 for fixture lookup and compose detection (relative paths supported). */
+  /**
+   * 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;
   /**
-   * Pluggable seed handlers for CLI-mode tests. Keys are leading path
-   * segments (e.g. `"spwn.yaml/"`); values receive the seed context and the
-   * absolute path of the source fragment under `<test-file-dir>/seeds/`.
+   * 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.
    */
-  seedHandlers?: Record<string, SeedHandler>;
-  /** Infrastructure services to start via testcontainers. */
-  services?: ServiceHandle[];
+  services?: Services;
   /**
-   * Optional normaliser applied to result.stdout.text and
-   * result.stderr.text before every .toMatch / .toMatchFile
-   * comparison. Useful for stripping ANSI codes, masking
-   * machine-specific paths, scrubbing timestamps, etc.
-   *
-   * The transform does NOT mutate the raw `.text` accessor —
-   * callers can still inspect the pristine output.
+   * 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;
 }
-/** 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. */
+/**
+ * The record returned by {@link startCli | specification.cli}. Destructure
+ * with the canonical names (CONVENTIONS A3):
+ *
+ *     const { cli, cleanup, docker } = await specification.cli(…);
+ */
+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/spec/modes/cli/docker-lookup.d.ts
+//#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. */
@@ -910,71 +1156,346 @@ 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/containers/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/spec/modes/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;
+}
+/**
+ * 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 function postgres(options?: PostgresOptions): PostgresHandle;
+//#endregion
+//#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;
+}
+/**
+ * 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 function redis(options?: RedisOptions): RedisHandle;
+//#endregion
+//#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;
+}
 /**
- * Executes CLI commands via Node.js child_process.
- * Uses `spawnSync` for one-shot commands and `spawn` for long-running processes.
- * Used by the command() specification runner.
+ * Create a SQLite service handle. Uses file-copy isolation for parallel tests.
+ *
+ * @example
+ *   // With Prisma schema
+ *   const db = sqlite({ prismaSchema: './prisma/schema' });
  *
- * `spawnSync` is used (over the simpler `execSync`) so stdout AND stderr are
- * captured regardless of exit code. Many CLIs follow the Unix convention of
- * writing status banners to stderr on success — `execSync` would silently
- * discard them, leaving snapshot tests with no output to assert on.
+ *   // With raw SQL init
+ *   const db = sqlite({ init: './schema.sql' });
+ *
+ *   // Empty database
+ *   const db = sqlite();
  */
-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 sqlite(options?: SqliteOptions): SqliteHandle;
+//#endregion
+//#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;
+/**
+ * Anthropic API intercept helpers.
+ */
+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/modes/http/adapters/fetch.adapter.d.ts
+//#region src/core/contracts/http.d.ts
 /**
- * Server adapter that sends real HTTP requests via the Fetch API.
- * Used by the `e2e()` specification runner to hit a live server.
+ * Request filters for the generic HTTP provider. Every field is a subset
+ * constraint — a request matches when all provided fields match.
  */
-declare class FetchAdapter implements ServerPort {
-  private baseUrl;
-  constructor(url: string);
-  request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
+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>;
 }
+/**
+ * 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 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/modes/http/adapters/hono.adapter.d.ts
+//#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;
 /**
- * Server adapter that dispatches requests in-process through a Hono app instance.
- * Used by the `integration()` specification runner -- no network overhead.
+ * OpenAI API intercept helpers.
  */
-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 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/vitest/mock-of.d.ts
+/** Factory signature that creates a deep mock proxy for any interface. */
+type MockPort = <T>() => DeepMockProxy<T>;
+/**
+ * Create a deep mock proxy for a given type.
+ * Wraps `vitest-mock-extended`'s `mockDeep` for convenient port mocking.
+ */
+declare const mockOf: MockPort;
+//#endregion
+//#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/infra/docker/docker.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, BaseResult, CliResult, type CommandEnv, type CommandPort, type CommandResult, type CommandTarget, ContainerAccessor, type ContainerPort, type DatabasePort, DirectoryAccessor, type DirectorySnapshotOptions, DockerAssertion, type DockerContainerPort, type DockerInspectResult, type DockerSpecConfig, ExecAdapter, FetchAdapter, type FileAccessor, FilesystemAccessor, HonoAdapter, HttpResult, type HttpTarget, type IsolationStrategy, type JobHandle, JsonAccessor, type JsonSnapshotOptions, type MockDatePort, type MockPort, Orchestrator, type PostgresOptions, type RedisOptions, ResponseAccessor, type SeedHandler, type SeedHandlerContext, type ServerPort, type ServerResponse, type ServiceHandle, type SpawnOptions, type SpecOptions, type SpecRunner, type SpecTarget, SpecificationBuilder, type SpecificationConfig, type SpecificationRunner, type SqliteOptions, type StackTarget, StreamAccessor, type StreamSnapshotOptions, TableAssertion, app, command, createSpecificationRunner, dockerContainer, findContainersByLabel, inspectContainer, mockOf, mockOfDate, postgres, redis, removeContainers, spec, sqlite, stack };
-//# 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 };