@jterrazz/test 15.2.0 → 16.0.0

package/dist/index.d.ts

@@ -1,120 +1,8 @@
 import { Scalar } from "yaml";
-import { DeepMockProxy } from "vitest-mock-extended";
+import { DeepMockProxy, MockProxy } from "vitest-mock-extended";
 import { ReactNode as ComponentUi } from "react";
 import "vitest/browser";
-//#region src/specification/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' | 'includes' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
-/** Every kind usable as a `{{token}}` in fixture files (all but ref/regex/includes). */
-declare const TOKEN_KINDS: readonly ["any", "base64", "date", "duration", "email", "float", "hex", "int", "ip", "iso8601", "number", "path", "port", "semver", "sha", "string", "time", "ulid", "url", "uuid", "workdir"];
-/** A token kind valid inside a fixture `{{...}}` placeholder. */
-type TokenKind = (typeof TOKEN_KINDS)[number];
-/**
- * A dynamic-value matcher. Created via the {@link match} factories — never
- * constructed directly by user code.
- */
-declare class Matcher {
-  /** For kind 'includes': the substring the actual value must contain. */
-  readonly includes?: string | undefined;
-  readonly kind: MatcherKind;
-  /** For kind 'ref': the capture to assert inequality against. */
-  readonly notRef?: string | undefined;
-  /** For kind 'ref': the capture name. */
-  readonly refName?: string | undefined;
-  /** For kind 'regex': the pattern the actual value must match. */
-  readonly regex?: RegExp | undefined;
-  constructor(kind: MatcherKind, options?: {
-    includes?: string | undefined;
-    notRef?: string | undefined;
-    refName?: string | undefined;
-    regex?: RegExp | undefined;
-  });
-  /** Placeholder-style rendering used in failure diffs and serialization. */
-  toString(): string;
-  toJSON(): string;
-}
-/** A no-argument matcher factory — what every typed entry of `match` is. */
-type TypedMatcher = () => Matcher;
-/**
- * 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']],
- *   });
- */
-/**
- * The matcher roster: one no-argument factory per token kind, plus the three
- * code-only forms the `{{token}}` grammar does not carry.
- */
-type MatchFactories = Record<TokenKind, TypedMatcher> & {
-  includes: (substring: string) => Matcher;
-  ref: (name: string, options?: {
-    not?: string;
-  }) => Matcher;
-  regex: (regex: RegExp) => Matcher;
-};
-declare const match: MatchFactories;
-/**
- * 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;
-  /**
-   * The exact working directory of the current spec, when the framework
-   * knows it (cli mode). Drives the `{{workdir}}` token / `match.workdir()`.
-   */
-  workdir?: string | undefined;
-  constructor(workdir?: string);
-  get(name: string): unknown;
-  has(name: string): boolean;
-  set(name: string, value: unknown): void;
-}
-//#endregion
-//#region src/specification/facets/_common/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/specification/contracts/types.d.ts
+//#region src/model/contracts/types.d.ts
 /**
  * The observed outgoing request, reduced to what contract matchers inspect.
  * Built once per request by the engine (MSW on api/jobs, the stub backend on
@@ -157,7 +45,11 @@ type ContractRequest = {
 type ContractResponse = {
   /** HTTP status code (default: 200). */
   status?: number;
-  /** Response body — an object is JSON, a string is text, `null`/`undefined` is empty. */
+  /**
+   * Response body — an object is JSON, a string is text, `null`/`undefined`
+   * is empty, and a {@link StreamBody} (built by `http.stream()` /
+   * `http.sse()`) arrives in pieces.
+   */
   body: unknown;
   /** Response headers. */
   headers?: Record<string, string> | undefined;
@@ -174,6 +66,31 @@ type ContractResponse = {
    */
   transport?: 'network-error' | undefined;
 };
+/**
+ * The marker that tells a STREAMED body from a value that happens to be an
+ * object. A body reaches three different engines (msw's server, msw's worker,
+ * the `node:http` stub) and each of them serialises "an object" as JSON, so a
+ * stream declared as a plain value arrives as `{}`. The tag is what each
+ * engine recognises before it reaches for `JSON.stringify`.
+ */
+declare const STREAM_BODY = "@jterrazz/test:stream";
+/**
+ * A body that arrives in pieces — what `http.stream()` and `http.sse()` build.
+ *
+ * The chunks are written in order, `delayBetweenChunks` milliseconds apart,
+ * and the connection closes after the last one. It is the chunks and their
+ * ORDER that a streaming subject is specified against: a client that renders
+ * tokens as they land, or one that reconnects on a half-read body.
+ */
+type StreamBody = {
+  /** The pieces, written in order. */
+  chunks: readonly string[];
+  /** The `content-type` the stream is served under. */
+  contentType: string;
+  /** Milliseconds between two chunks. Default 0 — everything at once. */
+  delayBetweenChunks: number;
+  kind: typeof STREAM_BODY;
+};
 /**
  * A dynamic response: computed from the observed request at the moment the
  * contract is served, rather than fixed ahead of time. Handed the same
@@ -187,7 +104,7 @@ type ContractResponder = (request: MatchableRequest) => ContractResponse;
  */
 type ContractResponseValue = ContractResponder | ContractResponse;
 //#endregion
-//#region src/specification/contracts/contract.d.ts
+//#region src/model/contracts/contract.d.ts
 /**
  * A declared external interaction: what to match (`request`) and what to reply
  * (`response`), together in one named artifact. Contracts live in TypeScript
@@ -272,263 +189,274 @@ declare function defineContract(contract: Contract): Contract;
  */
 declare function defineContracts(...items: ContractInput[]): Contracts;
 //#endregion
-//#region src/specification/ports/browser.port.d.ts
+//#region src/model/contracts/intercept.d.ts
 /**
- * The landmark roles — the standard set of page regions, and the only
- * containers a scope can name. Closed on purpose: ARIA defines exactly these,
- * so `within()` never becomes a second selector language.
+ * One block's worth of declared network. Disposed at the end of the scope that
+ * declared it: the handlers are dropped, and an unmatched request is thrown.
  */
-type LandmarkKind = 'banner' | 'complementary' | 'contentinfo' | 'form' | 'main' | 'navigation' | 'region' | 'search';
+type InterceptScope = AsyncDisposable;
+/** What a scope may state about the network it declares. */
+type InterceptOptions = {
+  /**
+   * The base a RELATIVE request resolves against, for the life of the scope.
+   *
+   * A module that calls `fetch('/api/posts')` is browser code: under node the
+   * URL cannot be parsed at all, so the request fails before any contract can
+   * answer it and the test's only way out was to replace `fetch` itself. With
+   * an origin stated, the relative call resolves here and the declared
+   * contracts — path form or absolute — match it as they would any other.
+   */
+  origin?: string;
+};
 /**
- * The interactive/textual element kinds — what a visitor actually acts on.
+ * The module-scope network double. Resolves once the engine is listening —
+ * which is why it is a promise, and why the canonical form awaits it:
  *
- * `dialog`, `status`, `table`, `row`, `listitem` and `option` are ARIA roles
- * like the landmarks, but they are not CONTAINERS of a page: they are things a
- * visitor reads and acts on, and they are the roles the estate's UI specs were
- * already reaching for through `getByRole` or, worse, through `.first()`.
+ * ```typescript
+ * await using _ = await intercept(http.get(url), http.json({ ok: true }));
+ * ```
+ *
+ * Without that `await` the subject could reach the real network before the
+ * first handler is in place, so the shape refuses the racy spelling: a promise
+ * is not an `AsyncDisposable`, and the compiler says so.
  */
-type ElementKind = 'button' | 'dialog' | 'field' | 'heading' | 'link' | 'listitem' | 'option' | 'row' | 'status' | 'table' | 'testId' | 'text';
+type Intercept = ((contracts: ContractInput, options?: InterceptOptions) => Promise<InterceptScope>) & ((request: ContractRequest, response: ContractResponder | ContractResponse, options?: InterceptOptions) => Promise<InterceptScope>);
+//#endregion
+//#region src/model/matching/match.d.ts
 /**
- * A user-facing element descriptor — pure data, built by the element
- * vocabulary (`button()`, `link()`, `field()`, …) and translated into
- * concrete locators by the browser integration. CSS/XPath selectors are
- * deliberately not expressible: user-facing elements are the only surface.
+ * Code-side dynamic-value matchers (`match.*`) and the capture scope shared
+ * by every assertion of a single spec execution.
  *
- * A descriptor must designate exactly ONE element at action time; see
- * {@link ElementMatch} and CONVENTIONS W3.
+ * 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).
  */
-type ElementRef = {
-  /**
-   * Match the accessible name as a whole string rather than a substring.
-   * Default (`false`) mirrors playwright: `link('Articles')` also matches
-   * "Read Articles".
-   */
-  exact?: boolean;
-  /**
-   * Assert about the element's FOCUS rather than its presence — built by
-   * `focused(element)`. The accessibility tree carries no focus state, so
-   * where the keyboard is cannot be goldened; it is asserted by a verb.
-   */
-  focused?: boolean;
-  /**
-   * Narrows to "and it is (not) accepting input" — built by `disabled(x)` /
-   * `enabled(x)`. Like `focused`, a STATE the vocabulary can already name the
-   * element of; unlike it, one the ARIA tree carries too (`[disabled]`), so
-   * this modifier is what names the ONE control a test is about, and it
-   * reaches the direction a behavioural substitute cannot — clicking a
-   * disabled control is a timeout, never an answer.
-   */
-  disabled?: boolean;
-  kind: ElementKind | LandmarkKind;
-  /** Landmarks may be anonymous (`main()`, `banner()`); everything else is named. */
-  name?: string;
-  /**
-   * Narrows to "and it is (not) the chosen one" — built by `selected(x)`.
-   * An option of a COLLAPSED select is in the tree and in the document, and
-   * it has no box on the screen, so this facet of it is read from the node
-   * (`:checked`) rather than from what a visitor could point at.
-   */
-  selected?: boolean;
-  /**
-   * The value the field must hold — built by `valued(field('Title'), '…')`.
-   * A field's value is a PROPERTY of the node: a controlled input's `value`
-   * attribute never moves, so nothing but the live value answers for it.
-   */
-  value?: string;
-  /**
-   * Restrict the search to the elements of another descriptor — built by
-   * `within(scope, target)`. Chains: a scope may itself carry a scope.
-   */
-  scope?: ElementRef;
+/** The frozen token vocabulary (CONVENTIONS D4) plus the code-only kinds. */
+type MatcherKind = 'any' | 'base64' | 'date' | 'duration' | 'email' | 'float' | 'hex' | 'includes' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
+/** Every kind usable as a `{{token}}` in fixture files (all but ref/regex/includes). */
+declare const TOKEN_KINDS: readonly ["any", "base64", "date", "duration", "email", "float", "hex", "int", "ip", "iso8601", "number", "path", "port", "semver", "sha", "string", "time", "ulid", "url", "uuid", "workdir"];
+/** A token kind valid inside a fixture `{{...}}` placeholder. */
+type TokenKind = (typeof TOKEN_KINDS)[number];
+/**
+ * A dynamic-value matcher. Created via the {@link match} factories — never
+ * constructed directly by user code.
+ */
+declare class Matcher {
+  /** For kind 'includes': the substring the actual value must contain. */
+  readonly includes?: string | undefined;
+  readonly kind: MatcherKind;
+  /** For kind 'ref': the capture to assert inequality against. */
+  readonly notRef?: string | undefined;
+  /** For kind 'ref': the capture name. */
+  readonly refName?: string | undefined;
+  /** For kind 'regex': the pattern the actual value must match. */
+  readonly regex?: RegExp | undefined;
+  constructor(kind: MatcherKind, options?: {
+    includes?: string | undefined;
+    notRef?: string | undefined;
+    refName?: string | undefined;
+    regex?: RegExp | undefined;
+  });
+  /** Placeholder-style rendering used in failure diffs and serialization. */
+  toString(): string;
+  toJSON(): string;
+}
+/** A no-argument matcher factory — what every typed entry of `match` is. */
+type TypedMatcher = () => Matcher;
+/**
+ * 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']],
+ *   });
+ */
+/**
+ * The matcher roster: one no-argument factory per token kind, plus the three
+ * code-only forms the `{{token}}` grammar does not carry.
+ */
+type MatchFactories = Record<TokenKind, TypedMatcher> & {
+  includes: (substring: string) => Matcher;
+  ref: (name: string, options?: {
+    not?: string;
+  }) => Matcher;
+  regex: (regex: RegExp) => Matcher;
 };
+declare const match: MatchFactories;
 /**
- * One candidate captured when a descriptor matched more than one element —
- * the evidence the ambiguity error enumerates so the author can disambiguate
- * without opening a browser.
+ * 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.
  */
-type ElementMatch = {
+declare class CaptureScope {
+  private readonly values;
   /**
-   * The accessible name, when it differs from the text — an `aria-label` is
-   * what a role descriptor MATCHED on, and printing the text alone sends the
-   * author to disambiguate a name they cannot see.
+   * The exact working directory of the current spec, when the framework
+   * knows it (cli mode). Drives the `{{workdir}}` token / `match.workdir()`.
    */
-  accessibleName?: string | undefined;
-  /** Nearest landmark ancestor (`nav`, `footer`, `main`…), when there is one. */
-  context?: string | undefined;
-  /** The attribute that disambiguates most — `href` for links, `name` for fields. */
-  detail?: string | undefined;
-  /** Tag name, lower-cased. */
-  tag: string;
-  /** Text content, whitespace-collapsed and truncated. */
-  text: string;
-};
-/** A `<link>` element captured from the rendered document's head. */
-type BrowserLinkElement = {
-  href: string;
-  hreflang?: string | undefined;
-  rel: string;
-  type?: string | undefined;
-};
-/** A `<meta>` element captured from the rendered document's head. */
-type BrowserMetaElement = {
-  content: string;
-  name?: string | undefined;
-  property?: string | undefined;
-};
-/** A console message emitted while the page loaded or the scenario ran. */
-type BrowserConsoleMessage = {
-  text: string;
-  type: string;
-};
+  workdir?: string | undefined;
+  constructor(workdir?: string);
+  get(name: string): unknown;
+  has(name: string): boolean;
+  set(name: string, value: unknown): void;
+}
+//#endregion
+//#region src/model/result/directory.d.ts
 /**
- * The visitor — the interaction vocabulary handed to a visit scenario.
- * Every action auto-waits (playwright actionability); `see()` is the single
- * synchronization primitive: it retries until the element is visible and
- * fails at the timeout. There is no sleep and no conditional helper.
+ * Read-only accessor for a directory produced by a spec action.
+ *
+ * Assertions go through `expect()` (async — they walk the disk):
+ * `await expect(result.directory('out')).toMatch('scaffold/out')`
+ * compares the tree against the fixture directory `_expected/<name>/`.
  */
-type Visitor = {
-  /** Check a checkbox or radio. */
-  check: (element: ElementRef) => Promise<void>;
-  /** Click the element. */
-  click: (element: ElementRef) => Promise<void>;
-  /** Fill a form field with a value. */
-  fill: (element: ElementRef, value: string) => Promise<void>;
-  /**
-   * Wait until the element is GONE — hidden, or never in the document. The
-   * absence primitive: `see()` cannot answer "the dialog closed", because an
-   * element that never appears and one that disappeared read the same to it.
-   */
-  gone: (element: ElementRef) => Promise<void>;
-  /** Navigate to a path of the site under test. */
-  goto: (path: string) => Promise<void>;
-  /** Hover the element. */
-  hover: (element: ElementRef) => Promise<void>;
-  /** Press a key (e.g. `Enter`). */
-  press: (key: string) => Promise<void>;
-  /** Wait until the element is visible — the only synchronization primitive. */
-  see: (element: ElementRef) => Promise<void>;
-  /** Select an option in a select field. */
-  select: (element: ElementRef, option: string) => Promise<void>;
-};
-/** The behavior of a visit — the When of the spec; assertions stay in the Then. */
-type VisitScenario = (visitor: Visitor) => Promise<void>;
-/** Per-visit options forwarded to the browser context. */
-type BrowserOpenOptions = {
-  /**
-   * Extra origins the `external: 'block'` policy lets through — the
-   * declared stub backend the page legitimately fetches from.
-   */
-  allowedOrigins?: string[] | undefined;
-  /**
-   * Base URL of the site under test — the origin `goto()` resolves against
-   * and the boundary of the `external` policy.
-   */
-  baseUrl: string;
-  /**
-   * Cross-origin request policy. `'block'` aborts every request leaving
-   * the site under test (analytics, CDNs) — the browser-side analog of
-   * strict intercepts. `'allow'` lets them through (deployed-site mode).
-   */
-  external: 'allow' | 'block';
-  /** Extra HTTP headers sent with every request of the visit (incl. User-Agent overrides). */
-  headers?: Record<string, string> | undefined;
-  /** The interaction scenario to run after load; the capture reflects the final state. */
-  scenario?: undefined | VisitScenario;
-};
+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/model/result/filesystem.d.ts
 /**
- * The rendered page captured by a browser visit — the FINAL state when a
- * scenario ran. Extraction happens in-page (the browser IS the HTML
- * parser); interpretation of the raw elements belongs to core.
+ * 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>/`.
  */
-type BrowserPage = {
-  /** Console messages emitted while loading and interacting, in order. */
-  consoleMessages: BrowserConsoleMessage[];
-  /** Serialized DOM after rendering (`document.documentElement.outerHTML`). */
-  html: string;
-  /** Raw text content of every `application/ld+json` script, in DOM order. */
-  jsonLdBlocks: string[];
-  /** `<link>` elements of the head, in DOM order. */
-  links: BrowserLinkElement[];
-  /** `<meta>` elements of the head, in DOM order. */
-  metas: BrowserMetaElement[];
-  /** HTTP status of the main document response (0 when unavailable). */
-  status: number;
-  /** Rendered `document.body.innerText`. */
-  text: string;
-  /** The ARIA snapshot of the rendered `<body>` — the outline a golden pins. */
-  tree: string;
-  /** `document.title` after rendering. */
-  title: string;
-  /** Final URL after redirects and scenario navigation. */
-  url: string;
-};
+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/model/result/json.d.ts
 /**
- * Abstract browser interface for the website specification runner.
- * One implementation lives in `integrations/playwright/` — a single shared
- * browser instance per runner; each `open()` gets a fresh, isolated context.
+ * 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).
  */
-type BrowserPort = {
-  /** Close the shared browser instance (idempotent). */
-  close: () => Promise<void>;
-  /** Load `url` in a fresh context, run the scenario, capture the final page. */
-  open: (url: string, options: BrowserOpenOptions) => Promise<BrowserPage>;
-};
+declare class JsonAccessor<Value = unknown> {
+  /** @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.
+   *
+   * `Value` is `unknown` unless the subject that produced this accessor
+   * knows better — `.call<T>()` does, and hands its T straight through so a
+   * one-field reading needs no cast in the test.
+   */
+  get value(): Value;
+}
 //#endregion
-//#region src/specification/ports/cli.port.d.ts
+//#region src/model/result/match-options.d.ts
 /**
- * Raw output from a command execution, including exit code and captured output streams.
+ * The per-call option both `toMatch` implementations honour.
+ *
+ * A golden is read from disk under node and through a server command from
+ * inside a page, and BOTH builds must answer `{ frozen: true }` the same way —
+ * so the option is declared here, where the node matchers and the page's
+ * matchers can each reach it, rather than in the runner's own folder, which a
+ * seam may not import (rule I1).
  */
-type CliOutput = {
-  /** Process exit code (0 = success). */
-  exitCode: number;
-  /** Captured standard output. */
-  stdout: string;
-  /** Captured standard error. */
-  stderr: string;
-};
 /**
- * Options for the long-running form of `.exec()` (CONVENTIONS B2). When
- * either option is present the process is spawned and observed: it resolves
- * as soon as `waitFor` appears in stdout/stderr, and is killed when `timeout`
- * elapses (exit code 124).
+ * 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.
  */
-type ExecOptions = {
-  /** Resolve (exit code 0) when stdout/stderr contains this string. */
-  waitFor?: string | undefined;
-  /** Kill the process after this many milliseconds. Defaults to 10 000. */
-  timeout?: number | undefined;
+type MatchFixtureOptions = {
+  frozen?: boolean;
 };
+//#endregion
+//#region src/model/ports/server.port.d.ts
 /**
- * Extra environment variables to set for the child process.
- * Values are merged on top of process.env. A `null` value unsets the variable.
- */
-type CliEnv = Record<string, null | string>;
-/**
- * Abstract command interface for specification runners.
- * Implement this to plug in your command execution strategy.
+ * HTTP response returned by a server port, with parsed JSON body.
  */
+type 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>;
+};
 /**
- * What one invocation is handed beyond its arguments — the two per-run inputs a
- * spec document may state. Both are absent by default: the child gets an
- * immediately-closed stdin (never a TTY) and the adapter's own timeout.
+ * Abstract server interface for specification runners.
+ * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
  */
-type CliInput = {
-  /** Written to the child's stdin, which is then closed. */
-  stdin?: string | undefined;
-  /** Milliseconds after which the run is killed (exit code 124). */
-  timeout?: number | undefined;
-};
-type CliPort = {
-  /** Execute a command with the given arguments in the given working directory. */
-  exec: (args: string, cwd: string, env?: CliEnv, input?: CliInput) => 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>;
+type 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/specification/ports/database.port.d.ts
+//#region src/model/result/response.d.ts
 /**
- * Abstract database interface for specification runners.
- * Implement this to plug in your database stack (e.g. Postgres, SQLite).
+ * 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/model/ports/database.port.d.ts
+/**
+ * Abstract database interface for specification runners.
+ * Implement this to plug in your database stack (e.g. Postgres, SQLite).
  */
 type DatabasePort = {
   /** Execute raw SQL (for seeding test data). */
@@ -539,446 +467,618 @@ type DatabasePort = {
   reset: () => Promise<void>;
 };
 //#endregion
-//#region src/specification/ports/device.port.d.ts
+//#region src/model/result/table.d.ts
 /**
- * The element kinds a mobile screen can designate — the structural subset of
- * {@link ElementRef} kinds that map onto the XCUITest accessibility tree.
- * There is ONE element vocabulary across facets: `button('Bookmark')` works
- * in a visit scenario and a mobile scenario alike. Landmarks have no iOS
- * analog — passing one to a mobile verb refuses at runtime.
+ * 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();
  */
-type MobileElementKind = 'button' | 'field' | 'testId' | 'text';
+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/model/result/text.d.ts
 /**
- * A user-facing element descriptor for mobile scenarios — pure data, built by
- * the shared element vocabulary (`button()`, `field()`, `content()`,
- * `testId()`, `within()`) and translated into iOS predicate strings by the
- * device integration. Structurally the same ref type as the browser's, so the
- * vocabulary stays single; kinds outside {@link MobileElementKind} (the ARIA
- * landmarks) are refused at runtime with a message naming the boundary.
+ * Read-only accessor for a captured text handle — THE universal one: stdout,
+ * stderr, container logs, and file text all surface as a `TextAccessor`.
  *
- * A descriptor must designate exactly ONE element when a verb ACTS on it
- * (`tap`, `fill`) — see {@link MobileElementMatch} and CONVENTIONS W3.
- * `see()` acts on nothing, so any visible match satisfies it: XCUITest trees
- * legitimately duplicate a label across container and child.
+ * 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).
  */
-type MobileElementRef = ElementRef;
+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) | undefined;
+  constructor(value: string, streamName: string, testDir: string, options?: {
+    captures?: CaptureScope | undefined;
+    transform?: ((text: string) => string) | undefined;
+  });
+  /** @internal The text as compared by matchers — ANSI stripped, transform applied. */
+  get comparableText(): string;
+  /**
+   * 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.
+   */
+  grep(pattern: string): TextAccessor;
+  toString(): string;
+  valueOf(): string;
+}
+//#endregion
+//#region src/model/result/result.d.ts
+/** Read-only handle to a single file produced by a spec action. */
+type 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;
+};
+type BaseResultOptions = {
+  config: SpecificationConfig;
+  testDir: string;
+  workDir?: string | undefined;
+};
 /**
- * One candidate captured when a descriptor matched more than one element —
- * the evidence the ambiguity error enumerates so the author can disambiguate
- * without opening the simulator.
+ * Base result - common accessors available after any action type.
+ * Extended by HttpResult, CliResult, and used directly by job results.
+ *
+ * Every result carries a fresh {@link CaptureScope}: `match.ref()` captures
+ * and `{{type#ref}}` placeholders are scoped to one spec execution.
  */
-type MobileElementMatch = {
-  /** The accessibility identifier (`testId()` target), when one is set. */
-  identifier?: string;
-  /** The accessible label, whitespace-collapsed and truncated. */
-  label?: string;
-  /** Element type without the `XCUIElementType` prefix — `Button`, `StaticText`. */
-  type: string;
-  /** The element value (text-field content, adjustable value), when present. */
-  value?: string;
-};
+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 | undefined;
+  constructor(options: BaseResultOptions);
+  /** Access a directory (relative to the working directory) for snapshot assertions. */
+  directory(path?: string): DirectoryAccessor;
+  /** Access a single file (relative to the working directory) for content assertions. */
+  file(path: string): FileAccessor;
+  /** Access a database table for row-level assertions via expect() matchers. */
+  table(tableName: string, options?: {
+    database?: string;
+  }): TableAccessor;
+  private resolveDatabase;
+}
+//#endregion
+//#region src/facets/api/api.result.d.ts
+/** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
+declare class HttpResult extends BaseResult {
+  private readonly 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/model/ports/cli.port.d.ts
 /**
- * The visitor — the interaction vocabulary handed to a mobile scenario.
- * Every verb auto-waits by polling until a visible match exists; acting
- * verbs then enforce exactly-one (W3), while `see()` — the single
- * synchronization primitive — is satisfied by any visible match. There is
- * no sleep and no conditional helper.
+ * Raw output from a command execution, including exit code and captured output streams.
  */
-type MobileVisitor = {
-  /** Fill a text field with a value. */
-  fill: (element: MobileElementRef, value: string) => Promise<void>;
-  /** Wait until the element is visible — the only synchronization primitive. */
-  see: (element: MobileElementRef) => Promise<void>;
-  /** Tap the element. */
-  tap: (element: MobileElementRef) => Promise<void>;
+type CliOutput = {
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /** Captured standard output. */
+  stdout: string;
+  /** Captured standard error. */
+  stderr: string;
 };
-/** The behavior of an open — the When of the spec; assertions stay in the Then. */
-type MobileScenario = (visitor: MobileVisitor) => Promise<void>;
 /**
- * One node of the projected accessibility tree — the XCUITest page source
- * with its noise collapsed: unlabeled, identifier-less, valueless wrapper
- * nodes are dropped and their children hoisted, so the projection stays
- * stable and golden-friendly. Type names lose the `XCUIElementType` prefix.
+ * 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).
  */
-type ScreenNode = {
-  children?: ScreenNode[];
-  /** The accessibility identifier, only when it differs from the label. */
-  identifier?: string;
-  label?: string;
-  /** Element type without the `XCUIElementType` prefix — `Button`, `StaticText`. */
-  type: string;
-  value?: string;
+type ExecOptions = {
+  /** Resolve (exit code 0) when stdout/stderr contains this string. */
+  waitFor?: string | undefined;
+  /** Kill the process after this many milliseconds. Defaults to 10 000. */
+  timeout?: number | undefined;
 };
 /**
- * The screen captured by a device open — the FINAL state when a scenario
- * ran. The tree is the projected page source; `texts` are the visible
- * labels/values in document order, consecutive duplicates collapsed.
+ * Extra environment variables to set for the child process.
+ * Values are merged on top of process.env. A `null` value unsets the variable.
  */
-type DeviceScreen = {
-  texts: string[];
-  tree: ScreenNode;
-};
-/** Per-open options forwarded to the device session. */
-type DeviceOpenOptions = {
-  /** The app under test — terminated and relaunched for a fresh, deterministic state. */
-  bundleId: string;
-  /** Deep link applied after the relaunch (`news://events`); absent opens the app plainly. */
-  deepLink?: string | undefined;
-  /** The interaction scenario to run after launch; the capture reflects the final state. */
-  scenario?: MobileScenario | undefined;
-};
+type CliEnv = Record<string, null | string>;
 /**
- * How long a device session waits, in milliseconds. Every field is optional
- * and falls back to the framework's own default, so a runner states only the
- * wait it needs to move — the defaults suit a release build, and a project
- * that drives a DEV build pays for its bundler's cold boot.
+ * Abstract command interface for specification runners.
+ * Implement this to plug in your command execution strategy.
  */
-type DeviceTimeouts = {
-  /**
-   * How long every verb polls for a visible match before refusing.
-   * Default: `30_000` — enough for a cold app boot on a release bundle.
-   */
-  action?: number | undefined;
-  /**
-   * How long the FIRST session waits for WebDriverAgent to build and
-   * launch on the simulator. Default: `240_000`.
-   */
-  launch?: number | undefined;
-};
 /**
- * Abstract device interface for the mobile specification runner.
- * One implementation lives in `integrations/appium/` — a single driver
- * session per runner, created on the first `open()` and reused; each open
- * terminates and relaunches the app for a deterministic fresh state.
+ * What one invocation is handed beyond its arguments — the two per-run inputs a
+ * spec document may state. Both are absent by default: the child gets an
+ * immediately-closed stdin (never a TTY) and the adapter's own timeout.
  */
-type DevicePort = {
-  /** End the driver session (idempotent). */
-  close: () => Promise<void>;
-  /** Relaunch the app, apply the deep link, run the scenario, capture the final screen. */
-  open: (options: DeviceOpenOptions) => Promise<DeviceScreen>;
+type CliInput = {
+  /** Written to the child's stdin, which is then closed. */
+  stdin?: string | undefined;
+  /** Milliseconds after which the run is killed (exit code 124). */
+  timeout?: number | undefined;
+};
+type CliPort = {
+  /** Execute a command with the given arguments in the given working directory. */
+  exec: (args: string, cwd: string, env?: CliEnv, input?: CliInput) => 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/specification/ports/server.port.d.ts
+//#region src/facets/cli/literate.d.ts
 /**
- * HTTP response returned by a server port, with parsed JSON body.
+ * Running a `<case>.spec.yaml` document: one scenario, one working directory,
+ * one set of servers, every run executed and asserted.
+ *
+ * The engine composes pieces that already exist rather than adding a second of
+ * anything — {@link copyPlan} for `fixture:`, the runner's own command adapter
+ * for each run, {@link ServeAdapter} for `serve:`, the `{{token}}` engine for
+ * every comparison, and {@link mergeTextPreservingPlaceholders} for the
+ * rewrite. What is new here is only the ORCHESTRATION the chain cannot express:
+ * several commands sharing one working directory, each judged the moment it
+ * ends — so what a run states about that directory is what IT left there, and
+ * the first run to disagree is the one the failure names.
  */
-type 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.
+ * A server a document may start by name (`serve: mcp`), registered once per app
+ * in the `serve` option of `specification.cli()`.
  */
-type ServerPort = {
-  /** Send an HTTP request and return the parsed response. */
-  request: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<ServerResponse>;
+type LiterateServeRegistration = {
+  /** Shell command that starts the server, run from the project root. */
+  command: string;
+  /** The variable the resolved URL is bound to in every run's child env. */
+  env: string;
+  /**
+   * Matched against the server's output; the FIRST capture group is the port
+   * it chose — named (`(?<port>\d+)`) or not, it is group 1 either way.
+   */
+  ready: RegExp;
+  /** Builds the URL bound to {@link env} from the announced port. */
+  url: (port: number) => string;
+};
+/** Per-call options for {@link runSpecDocument} / `cli.run()`. */
+type LiterateRunFlags = {
+  /**
+   * Opt this document OUT of the update-mode rewrite. A frozen document is
+   * NEVER written under `TEST_UPDATE=1`: its mismatch still throws its diff.
+   * That is what makes a DELIBERATELY-WRONG `.spec.yaml` — one whose failure
+   * rendering is the subject of a negative test — survive an update run
+   * instead of being silently corrected into a passing file. The document's
+   * mirror of `toMatch(name, { frozen: true })`.
+   */
+  frozen?: boolean | undefined;
 };
 //#endregion
-//#region src/specification/ports/isolation.port.d.ts
+//#region src/facets/integration/integration.result.d.ts
+/** What `.call()` produced: the value it returned, or the error it threw. */
+type CallOutcome = {
+  error: unknown;
+  threw: boolean;
+  value: unknown;
+};
+type CallResultOptions = BaseResultOptions & {
+  outcome: CallOutcome;
+};
 /**
- * Strategy for isolating service state across parallel test workers.
+ * What `result.value` is, decided by what the call returned: a string reads as
+ * a stream, anything else as JSON. `.call<T>()` already knows T, so the test
+ * reads one field (`result.value.value.ok`) without narrowing a union first.
+ */
+type CallValue<Returned> = Returned extends string ? TextAccessor : JsonAccessor<Returned>;
+/**
+ * The result of an in-process call — the integration facet's whole surface.
  *
- * 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.
+ * Two readings, never both: `value` is what the call RETURNED, `error` is
+ * what it THREW. A module that refuses is specified the same way a module
+ * that answers is, and neither needs a `try`/`catch` in the test — a shape
+ * that costs a refusal spec three times the size of the happy one, and that
+ * quietly passes when nothing throws at all.
  *
- * Implement this interface to support new service types (e.g. MongoDB,
- * Elasticsearch, S3).
+ * Both are the package's ordinary accessors, so the golden mechanism reaches
+ * them, and `Returned` is what `.call<T>()` returned — `result.value.value` is
+ * that type, not `unknown`, so a one-field reading needs no golden file: `toMatch('<name>.json'|'<name>.txt')`, the `{{token}}` grammar,
+ * `{ frozen }` and `TEST_UPDATE=1` all work here exactly as on an HTTP
+ * response or a command's stdout.
  */
-type IsolationStrategy = {
+declare class CallResult<Returned = unknown> extends BaseResult {
+  private readonly outcome;
+  constructor(options: CallResultOptions);
   /**
-   * Create an isolated namespace for this worker.
-   * Called once when the worker starts — e.g. clone a template database,
-   * set a Redis key prefix.
+   * What the call THREW, as text — the message of an `Error`, the value
+   * itself when something else was thrown, and empty when it returned.
    *
-   * @param workerId - Unique identifier for this vitest worker.
+   * Empty rather than absent on purpose: `await expect(result.error).toBeEmpty()`
+   * is how a spec says "and it did not refuse" — awaited, because the
+   * matcher answers a promise on every subject it takes, and a dropped one
+   * passes the test while the failure surfaces as an unhandled rejection
+   * (D2 refuses the bare form).
    */
-  acquire: (workerId: string) => Promise<void>;
+  get error(): TextAccessor;
   /**
-   * Fast reset within the namespace between `spec.run()` calls.
-   * E.g. truncate tables (without dropping the database).
+   * What the call RETURNED. A string reads as a stream (`<name>.txt`),
+   * anything else as JSON (`<name>.json`) — the same two subjects every
+   * other facet's results are built from.
+   *
+   * A call that threw returns the empty value: what it produced is
+   * {@link CallResult.error}.
    */
-  reset: () => Promise<void>;
+  get value(): CallValue<Returned>;
+}
+//#endregion
+//#region src/model/ports/browser.port.d.ts
+/**
+ * The landmark roles — the standard set of page regions, and the only
+ * containers a scope can name. Closed on purpose: ARIA defines exactly these,
+ * so `within()` never becomes a second selector language.
+ */
+type LandmarkKind = 'banner' | 'complementary' | 'contentinfo' | 'form' | 'main' | 'navigation' | 'region' | 'search';
+/**
+ * The interactive/textual element kinds — what a visitor actually acts on.
+ *
+ * `dialog`, `status`, `table`, `row`, `listitem` and `option` are ARIA roles
+ * like the landmarks, but they are not CONTAINERS of a page: they are things a
+ * visitor reads and acts on, and they are the roles the estate's UI specs were
+ * already reaching for through `getByRole` or, worse, through `.first()`.
+ */
+type ElementKind = 'button' | 'dialog' | 'field' | 'heading' | 'link' | 'listitem' | 'option' | 'row' | 'status' | 'table' | 'testId' | 'text';
+/**
+ * A user-facing element descriptor — pure data, built by the element
+ * vocabulary (`button()`, `link()`, `field()`, …) and translated into
+ * concrete locators by the browser integration. CSS/XPath selectors are
+ * deliberately not expressible: user-facing elements are the only surface.
+ *
+ * A descriptor must designate exactly ONE element at action time; see
+ * {@link ElementMatch} and CONVENTIONS W3.
+ */
+type ElementRef = {
   /**
-   * Tear down the isolated namespace.
-   * Called once when the worker shuts down — e.g. drop the cloned database.
+   * Match the accessible name as a whole string rather than a substring.
+   *
+   * ABSENT means "the author said nothing", which the adapters read as the
+   * default — exact — while keeping the information that no choice was made,
+   * so a name that matches only as a substring can be reported once with the
+   * transitional warning.
    */
-  release: () => Promise<void>;
+  exact?: boolean;
+  /**
+   * Assert about the element's FOCUS rather than its presence — built by
+   * `focused(element)`. The accessibility tree carries no focus state, so
+   * where the keyboard is cannot be goldened; it is asserted by a verb.
+   */
+  focused?: boolean;
+  /**
+   * Narrows to "and it is (not) accepting input" — built by `disabled(x)` /
+   * `enabled(x)`. Like `focused`, a STATE the vocabulary can already name the
+   * element of; unlike it, one the ARIA tree carries too (`[disabled]`), so
+   * this modifier is what names the ONE control a test is about, and it
+   * reaches the direction a behavioural substitute cannot — clicking a
+   * disabled control is a timeout, never an answer.
+   */
+  disabled?: boolean;
+  kind: ElementKind | LandmarkKind;
+  /** Landmarks may be anonymous (`main()`, `banner()`); everything else is named. */
+  name?: string;
+  /**
+   * Narrows to "and it is (not) the chosen one" — built by `selected(x)`.
+   * An option of a COLLAPSED select is in the tree and in the document, and
+   * it has no box on the screen, so this facet of it is read from the node
+   * (`:checked`) rather than from what a visitor could point at.
+   */
+  selected?: boolean;
+  /**
+   * The value the field must hold — built by `valued(field('Title'), '…')`.
+   * A field's value is a PROPERTY of the node: a controlled input's `value`
+   * attribute never moves, so nothing but the live value answers for it.
+   */
+  value?: string;
+  /**
+   * Restrict the search to the elements of another descriptor — built by
+   * `within(scope, target)`. Chains: a scope may itself carry a scope.
+   */
+  scope?: ElementRef;
 };
-//#endregion
-//#region src/specification/ports/service.port.d.ts
 /**
- * A service handle — returned by factory functions like postgres(), redis().
- * Mutable: connectionString is populated after the orchestrator starts containers.
+ * One candidate captured when a descriptor matched more than one element —
+ * the evidence the ambiguity error enumerates so the author can disambiguate
+ * without opening a browser.
  */
-type ServiceHandle = {
-  /** Service type identifier. */
-  readonly type: string;
+type ElementMatch = {
   /**
-   * 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.
+   * The accessible name, when it differs from the text — an `aria-label` is
+   * what a role descriptor MATCHED on, and printing the text alone sends the
+   * author to disambiguate a name they cannot see.
    */
-  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>;
+  accessibleName?: string | undefined;
+  /** Nearest landmark ancestor (`nav`, `footer`, `main`…), when there is one. */
+  context?: string | undefined;
+  /** The attribute that disambiguates most — `href` for links, `name` for fields. */
+  detail?: string | undefined;
+  /** Tag name, lower-cased. */
+  tag: string;
+  /** Text content, whitespace-collapsed and truncated. */
+  text: string;
+};
+/** A `<link>` element captured from the rendered document's head. */
+type BrowserLinkElement = {
+  href: string;
+  hreflang?: string | undefined;
+  rel: string;
+  type?: string | undefined;
+};
+/** A `<meta>` element captured from the rendered document's head. */
+type BrowserMetaElement = {
+  content: string;
+  name?: string | undefined;
+  property?: string | undefined;
+};
+/** A console message emitted while the page loaded or the scenario ran. */
+type BrowserConsoleMessage = {
+  text: string;
+  type: string;
+};
+/**
+ * The visitor — the interaction vocabulary handed to a visit scenario.
+ * Every action auto-waits (playwright actionability); `see()` is the single
+ * synchronization primitive: it retries until the element is visible and
+ * fails at the timeout. There is no sleep and no conditional helper.
+ */
+type Visitor = {
+  /** Check a checkbox or radio. */
+  check: (element: ElementRef) => Promise<void>;
+  /** Click the element. */
+  click: (element: ElementRef) => Promise<void>;
+  /** Fill a form field with a value. */
+  fill: (element: ElementRef, value: string) => Promise<void>;
   /**
-   * Run initialization scripts (e.g., init.sql). Throws with SQL error
-   * context if it fails.
-   *
-   * `composeDir` is where the compose file lives — where a service reads its
-   * `init.sql` from. `root` is the project root the specification resolved
-   * (A9), handed down so a service that CACHES something writes it under the
-   * project's own `.artifacts/`, never in a machine-global directory two
-   * checkouts would share.
+   * Wait until the element is GONE — hidden, or never in the document. The
+   * absence primitive: `see()` cannot answer "the dialog closed", because an
+   * element that never appears and one that disappeared read the same to it.
    */
-  initialize: (composeDir: string, root: 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;
+  gone: (element: ElementRef) => Promise<void>;
+  /** Navigate to a path of the site under test. */
+  goto: (path: string) => Promise<void>;
+  /** Hover the element. */
+  hover: (element: ElementRef) => Promise<void>;
+  /** Press a key (e.g. `Enter`). */
+  press: (key: string) => Promise<void>;
+  /** Wait until the element is visible — the only synchronization primitive. */
+  see: (element: ElementRef) => Promise<void>;
+  /** Select an option in a select field. */
+  select: (element: ElementRef, option: string) => Promise<void>;
+};
+/** The behavior of a visit — the When of the spec; assertions stay in the Then. */
+type VisitScenario = (visitor: Visitor) => Promise<void>;
+/** Per-visit options forwarded to the browser context. */
+type BrowserOpenOptions = {
+  /**
+   * Extra origins the `external: 'block'` policy lets through — the
+   * declared stub backend the page legitimately fetches from.
+   */
+  allowedOrigins?: string[] | undefined;
+  /**
+   * Base URL of the site under test — the origin `goto()` resolves against
+   * and the boundary of the `external` policy.
+   */
+  baseUrl: string;
+  /**
+   * Pin the page's own `Date` at this instant before the first byte is
+   * parsed — the calendar the site's scripts read. `.clock()` on the chain.
+   */
+  clock?: string | undefined;
+  /**
+   * Cross-origin request policy. `'block'` aborts every request leaving
+   * the site under test (analytics, CDNs) — the browser-side analog of
+   * strict intercepts. `'allow'` lets them through (deployed-site mode).
+   */
+  external: 'allow' | 'block';
+  /** Extra HTTP headers sent with every request of the visit (incl. User-Agent overrides). */
+  headers?: Record<string, string> | undefined;
+  /** The interaction scenario to run after load; the capture reflects the final state. */
+  scenario?: undefined | VisitScenario;
 };
-//#endregion
-//#region src/specification/facets/_common/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.
+ * The rendered page captured by a browser visit — the FINAL state when a
+ * scenario ran. Extraction happens in-page (the browser IS the HTML
+ * parser); interpretation of the raw elements belongs to the model.
  */
-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/specification/facets/api/result.d.ts
-/** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
-declare class HttpResult extends BaseResult {
-  private readonly 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/specification/facets/_common/result/filesystem.d.ts
+type BrowserPage = {
+  /** Console messages emitted while loading and interacting, in order. */
+  consoleMessages: BrowserConsoleMessage[];
+  /** Serialized DOM after rendering (`document.documentElement.outerHTML`). */
+  html: string;
+  /** Raw text content of every `application/ld+json` script, in DOM order. */
+  jsonLdBlocks: string[];
+  /** `<link>` elements of the head, in DOM order. */
+  links: BrowserLinkElement[];
+  /** `<meta>` elements of the head, in DOM order. */
+  metas: BrowserMetaElement[];
+  /** HTTP status of the main document response (0 when unavailable). */
+  status: number;
+  /** Rendered `document.body.innerText`. */
+  text: string;
+  /** The ARIA snapshot of the rendered `<body>` — the outline a golden pins. */
+  tree: string;
+  /** `document.title` after rendering. */
+  title: string;
+  /** Final URL after redirects and scenario navigation. */
+  url: string;
+};
 /**
- * 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>/`.
+ * Abstract browser interface for the website specification runner.
+ * One implementation lives in `integrations/playwright/` — a single shared
+ * browser instance per runner; each `open()` gets a fresh, isolated context.
  */
-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[]>;
-}
+type BrowserPort = {
+  /** Close the shared browser instance (idempotent). */
+  close: () => Promise<void>;
+  /** Load `url` in a fresh context, run the scenario, capture the final page. */
+  open: (url: string, options: BrowserOpenOptions) => Promise<BrowserPage>;
+};
 //#endregion
-//#region src/specification/facets/_common/result/text.d.ts
+//#region src/model/ports/device.port.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).
+ * The element kinds a mobile screen can designate — the structural subset of
+ * {@link ElementRef} kinds that map onto the XCUITest accessibility tree.
+ * There is ONE element vocabulary across facets: `button('Bookmark')` works
+ * in a visit scenario and a mobile scenario alike. Landmarks have no iOS
+ * analog — passing one to a mobile verb refuses at runtime.
  */
-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) | undefined;
-  constructor(value: string, streamName: string, testDir: string, options?: {
-    captures?: CaptureScope | undefined;
-    transform?: ((text: string) => string) | undefined;
-  });
-  /** @internal The text as compared by matchers — ANSI stripped, transform applied. */
-  get comparableText(): string;
-  /**
-   * 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.
-   */
-  grep(pattern: string): TextAccessor;
-  toString(): string;
-  valueOf(): string;
-}
-//#endregion
-//#region src/specification/facets/cli/result.d.ts
+type MobileElementKind = 'button' | 'field' | 'testId' | 'text';
 /**
- * Result from a command action (`.exec()`).
- *
- * When the runner was configured with a `docker` option, the result also
- * exposes container accessors and participates in `Symbol.asyncDispose`
- * cleanup. The Docker shell-outs are **lazy**: a test that never calls
- * `.container(...)` never queries the Docker daemon, so command-only tests
- * pay zero Docker cost even when the runner is Docker-aware.
+ * A user-facing element descriptor for mobile scenarios — pure data, built by
+ * the shared element vocabulary (`button()`, `field()`, `content()`,
+ * `testId()`, `within()`) and translated into iOS predicate strings by the
+ * device integration. Structurally the same ref type as the browser's, so the
+ * vocabulary stays single; kinds outside {@link MobileElementKind} (the ARIA
+ * landmarks) are refused at runtime with a message naming the boundary.
  *
- * Dispose always runs one final label-filtered `docker ps` to catch
- * containers that were spawned during `.exec` but never asserted on —
- * tests still get leak-free cleanup even if they forget to reach into
- * a container.
+ * A descriptor must designate exactly ONE element when a verb ACTS on it
+ * (`tap`, `fill`) — see {@link MobileElementMatch} and CONVENTIONS W3.
+ * `see()` acts on nothing, so any visible match satisfies it: XCUITest trees
+ * legitimately duplicate a label across container and child.
  */
-declare class CliResult extends BaseResult {
-  private readonly commandOutput;
-  private containersCache;
-  private readonly dockerConfig?;
-  private readonly testRunId?;
-  private readonly transform?;
-  constructor(options: {
-    commandOutput: CliOutput;
-    config: SpecificationConfig;
-    dockerConfig?: DockerSpecConfig | undefined;
-    testDir: string;
-    testRunId?: string | undefined;
-    transform?: ((text: string) => string) | undefined;
-    workDir: string;
-  });
-  /** The process exit code. */
-  get exitCode(): number;
-  /** Accessor for the captured standard output with file-based assertions. */
-  get stdout(): TextAccessor;
-  /** Accessor for the captured standard error with file-based assertions. */
-  get stderr(): TextAccessor;
-  /** Accessor for parsing stdout as JSON and asserting against JSON fixtures. */
-  get json(): JsonAccessor;
-  /** Accessor for the temporary working directory the command ran in. */
-  get filesystem(): FilesystemAccessor;
-  /**
-   * 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.
-   *
-   * Returns an accessor with `.exists === false` when no container
-   * carries that name — callers can still assert absence without a try.
-   */
-  container(name: string): ContainerAccessor;
-  /** All captured container IDs. Triggers the same lazy query as `container()`. */
-  get containerIds(): string[];
-  [Symbol.asyncDispose](): Promise<void>;
-  private ensureDockerAware;
-  private loadContainers;
-}
-//#endregion
-//#region src/specification/facets/cli/literate.d.ts
+type MobileElementRef = ElementRef;
+/**
+ * One candidate captured when a descriptor matched more than one element —
+ * the evidence the ambiguity error enumerates so the author can disambiguate
+ * without opening the simulator.
+ */
+type MobileElementMatch = {
+  /** The accessibility identifier (`testId()` target), when one is set. */
+  identifier?: string;
+  /** The accessible label, whitespace-collapsed and truncated. */
+  label?: string;
+  /** Element type without the `XCUIElementType` prefix — `Button`, `StaticText`. */
+  type: string;
+  /** The element value (text-field content, adjustable value), when present. */
+  value?: string;
+};
+/**
+ * The visitor — the interaction vocabulary handed to a mobile scenario.
+ * Every verb auto-waits by polling until a visible match exists; acting
+ * verbs then enforce exactly-one (W3), while `see()` — the single
+ * synchronization primitive — is satisfied by any visible match. There is
+ * no sleep and no conditional helper.
+ */
+type MobileVisitor = {
+  /** Fill a text field with a value. */
+  fill: (element: MobileElementRef, value: string) => Promise<void>;
+  /** Wait until the element is visible — the only synchronization primitive. */
+  see: (element: MobileElementRef) => Promise<void>;
+  /** Tap the element. */
+  tap: (element: MobileElementRef) => Promise<void>;
+};
+/** The behavior of an open — the When of the spec; assertions stay in the Then. */
+type MobileScenario = (visitor: MobileVisitor) => Promise<void>;
 /**
- * Running a `<case>.spec.yaml` document: one scenario, one working directory,
- * one set of servers, every run executed and asserted.
- *
- * The engine composes pieces that already exist rather than adding a second of
- * anything — {@link copyPlan} for `fixture:`, the runner's own command adapter
- * for each run, {@link ServeAdapter} for `serve:`, the `{{token}}` engine for
- * every comparison, and {@link mergeTextPreservingPlaceholders} for the
- * rewrite. What is new here is only the ORCHESTRATION the chain cannot express:
- * several commands sharing one working directory, each judged the moment it
- * ends — so what a run states about that directory is what IT left there, and
- * the first run to disagree is the one the failure names.
+ * One node of the projected accessibility tree — the XCUITest page source
+ * with its noise collapsed: unlabeled, identifier-less, valueless wrapper
+ * nodes are dropped and their children hoisted, so the projection stays
+ * stable and golden-friendly. Type names lose the `XCUIElementType` prefix.
  */
+type ScreenNode = {
+  children?: ScreenNode[];
+  /** The accessibility identifier, only when it differs from the label. */
+  identifier?: string;
+  label?: string;
+  /** Element type without the `XCUIElementType` prefix — `Button`, `StaticText`. */
+  type: string;
+  value?: string;
+};
 /**
- * A server a document may start by name (`serve: mcp`), registered once per app
- * in the `serve` option of `specification.cli()`.
+ * The screen captured by a device open — the FINAL state when a scenario
+ * ran. The tree is the projected page source; `texts` are the visible
+ * labels/values in document order, consecutive duplicates collapsed.
  */
-type LiterateServeRegistration = {
-  /** Shell command that starts the server, run from the project root. */
-  command: string;
-  /** The variable the resolved URL is bound to in every run's child env. */
-  env: string;
+type DeviceScreen = {
+  texts: string[];
+  tree: ScreenNode;
+};
+/** Per-open options forwarded to the device session. */
+type DeviceOpenOptions = {
+  /** The app under test — terminated and relaunched for a fresh, deterministic state. */
+  bundleId: string;
+  /** Deep link applied after the relaunch (`news://events`); absent opens the app plainly. */
+  deepLink?: string | undefined;
+  /** The interaction scenario to run after launch; the capture reflects the final state. */
+  scenario?: MobileScenario | undefined;
+};
+/**
+ * How long a device session waits, in milliseconds. Every field is optional
+ * and falls back to the framework's own default, so a runner states only the
+ * wait it needs to move — the defaults suit a release build, and a project
+ * that drives a DEV build pays for its bundler's cold boot.
+ */
+type DeviceTimeouts = {
   /**
-   * Matched against the server's output; the FIRST capture group is the port
-   * it chose — named (`(?<port>\d+)`) or not, it is group 1 either way.
+   * How long every verb polls for a visible match before refusing.
+   * Default: `30_000` — enough for a cold app boot on a release bundle.
    */
-  ready: RegExp;
-  /** Builds the URL bound to {@link env} from the announced port. */
-  url: (port: number) => string;
-};
-/** Per-call options for {@link runSpecDocument} / `cli.run()`. */
-type LiterateRunFlags = {
+  action?: number | undefined;
   /**
-   * Opt this document OUT of the update-mode rewrite. A frozen document is
-   * NEVER written under `TEST_UPDATE=1`: its mismatch still throws its diff.
-   * That is what makes a DELIBERATELY-WRONG `.spec.yaml` — one whose failure
-   * rendering is the subject of a negative test — survive an update run
-   * instead of being silently corrected into a passing file. The document's
-   * mirror of `toMatch(name, { frozen: true })`.
+   * How long the FIRST session waits for WebDriverAgent to build and
+   * launch on the simulator. Default: `240_000`.
    */
-  frozen?: boolean | undefined;
+  launch?: number | undefined;
+};
+/**
+ * Abstract device interface for the mobile specification runner.
+ * One implementation lives in `integrations/appium/` — a single driver
+ * session per runner, created on the first `open()` and reused; each open
+ * terminates and relaunches the app for a deterministic fresh state.
+ */
+type DevicePort = {
+  /** End the driver session (idempotent). */
+  close: () => Promise<void>;
+  /** Relaunch the app, apply the deep link, run the scenario, capture the final screen. */
+  open: (options: DeviceOpenOptions) => Promise<DeviceScreen>;
 };
 //#endregion
-//#region src/specification/facets/mobile/result.d.ts
+//#region src/facets/mobile/mobile.result.d.ts
 /** Result from a `.open()` action — the screen as the device saw it, final state. */
 declare class ScreenResult extends BaseResult {
   private readonly capturedScreen;
@@ -999,7 +1099,7 @@ declare class ScreenResult extends BaseResult {
   get screen(): JsonAccessor;
 }
 //#endregion
-//#region src/specification/facets/website/result.d.ts
+//#region src/facets/website/website.result.d.ts
 /** A raw HTTP exchange captured by `.fetch()` — redirects are NOT followed. */
 type FetchExchange = {
   body: string;
@@ -1083,7 +1183,88 @@ declare class PageResult extends BaseResult {
   get url(): string;
 }
 //#endregion
-//#region src/specification/facets/_common/stub-backend.d.ts
+//#region src/model/ports/isolation.port.d.ts
+/**
+ * Strategy for isolating service state across parallel test workers.
+ *
+ * Each service handle provides an isolation strategy. The framework
+ * calls `acquire()` once per vitest worker, `reset()` before each
+ * `spec.run()`, and `release()` when the worker shuts down.
+ *
+ * Implement this interface to support new service types (e.g. MongoDB,
+ * Elasticsearch, S3).
+ */
+type IsolationStrategy = {
+  /**
+   * Create an isolated namespace for this worker.
+   * Called once when the worker starts — e.g. clone a template database,
+   * set a Redis key prefix.
+   *
+   * @param workerId - Unique identifier for this vitest worker.
+   */
+  acquire: (workerId: string) => Promise<void>;
+  /**
+   * Fast reset within the namespace between `spec.run()` calls.
+   * E.g. truncate tables (without dropping the database).
+   */
+  reset: () => Promise<void>;
+  /**
+   * Tear down the isolated namespace.
+   * Called once when the worker shuts down — e.g. drop the cloned database.
+   */
+  release: () => Promise<void>;
+};
+//#endregion
+//#region src/model/ports/service.port.d.ts
+/**
+ * A service handle — returned by factory functions like postgres(), redis().
+ * Mutable: connectionString is populated after the orchestrator starts containers.
+ */
+type ServiceHandle = {
+  /** Service type identifier. */
+  readonly type: string;
+  /**
+   * The name this handle is known by. Left `null` until the orchestrator
+   * assigns it at start time: it is the kebab-case form of the RECORD KEY,
+   * so `{ analyticsDb: postgres() }` reports as `analytics-db` and reads its
+   * init script from `docker/analytics-db/`. The key is the only name a
+   * specification writes; a handle carries no second one of its own.
+   */
+  serviceName: 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.
+   *
+   * `dockerDir` is `<root>/docker` — where a service reads its `init.sql`
+   * from, under its own name. `root` is the project root the specification resolved
+   * (A9), handed down so a service that CACHES something writes it under the
+   * project's own `.artifacts/`, never in a machine-global directory two
+   * checkouts would share.
+   */
+  initialize: (dockerDir: string, root: 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/model/chain/stub-backend.d.ts
 /** Options for the stub backend server. */
 type StubBackendOptions = {
   /**
@@ -1125,7 +1306,7 @@ declare class StubBackend {
   private record;
 }
 //#endregion
-//#region src/specification/facets/_common/builder.d.ts
+//#region src/model/chain/builder.d.ts
 /** A named job that can be triggered via jobs.trigger(). */
 type JobHandle = {
   name: string;
@@ -1194,16 +1375,17 @@ type SpecificationConfig = {
    * facet factories auto-populate this when `dockerConfig` is present.
    */
   dockerTestRunId?: string | undefined;
+  /**
+   * Environment applied to every run of the declared binary
+   * (`specification.cli({ defaults })`) — under a chain's own `.env()` and
+   * under a document's `env:`, both of which win.
+   */
+  defaultEnv?: CliEnv | undefined;
   /**
    * Named environment SETS a spec document may name by bare word
    * (`env: frozen`). Declared once per app in `specification.cli()`.
    */
   envSets?: Record<string, CliEnv> | undefined;
-  /**
-   * When set, `.intercept()` is unavailable on this runner and throws this
-   * reason immediately (compose mode — MSW is in-process, CONVENTIONS I3).
-   */
-  interceptDisabledReason?: string | undefined;
   jobs?: JobHandle[] | undefined;
   /** The project root — the working directory a document's `serve:` command runs from. */
   root?: string | undefined;
@@ -1240,6 +1422,8 @@ type InterceptMethod<T> = ((contracts: ContractInput) => T) & ((request: Contrac
  * of the declared services record that are databases.
  */
 type ApiSpecification<DatabaseKey extends string = string> = {
+  /** Pin the app's `Date` at `iso` for this chain — the calendar the app reads. */
+  clock: (iso: string) => ApiSpecification<DatabaseKey>;
   /** Set HTTP headers for the request. Multiple calls merge. */
   headers: (headers: Record<string, string>) => ApiSpecification<DatabaseKey>;
   /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
@@ -1261,9 +1445,21 @@ type ApiSpecification<DatabaseKey extends string = string> = {
 };
 /**
  * The `jobs` facet — job chain entry handed out by `specification.jobs()`.
- * Jobs run in-process by definition (CONVENTIONS A5/A8).
+ * Jobs run in-process by definition (CONVENTIONS A8).
+ */
+/**
+ * What a triggered job HANDS BACK.
+ *
+ * A job writes to a database, a cache, a queue — never to a working directory
+ * the spec then walks, because a job has none: it runs in this process, where
+ * the only filesystem is the repository's. So the two accessors that read one
+ * (`file()`, `directory()`) are not on this result. A pipeline that really
+ * produces files is a binary, and `specification.cli()` is its facet.
  */
+type JobsResult = Omit<BaseResult, 'directory' | 'file'>;
 type JobsSpecification<DatabaseKey extends string = string> = {
+  /** Pin the job's `Date` at `iso` for this chain — the calendar the job reads. */
+  clock: (iso: string) => JobsSpecification<DatabaseKey>;
   /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
   intercept: InterceptMethod<JobsSpecification<DatabaseKey>>;
   /** Queue a SQL seed file from `_seeds/` to run before the action. */
@@ -1271,7 +1467,32 @@ type JobsSpecification<DatabaseKey extends string = string> = {
     database?: DatabaseKey;
   }) => JobsSpecification<DatabaseKey>;
   /** Execute the named job registered via the `jobs` option and resolve with the result. */
-  trigger: (name: string) => Promise<BaseResult>;
+  trigger: (name: string) => Promise<JobsResult>;
+};
+/**
+ * The `integration` facet — the in-process chain handed out by
+ * `specification.integration()`.
+ *
+ * The subject is a MODULE, not an entry: no HTTP, no binary, no page. What
+ * makes it a spec rather than a module test is what it stands on — real
+ * services, declared contracts, a golden — so it takes the same setups as
+ * every other facet and ends on the one action a module has: being called.
+ */
+type IntegrationSpecification<Services extends Record<string, unknown> = Record<string, unknown>, DatabaseKey extends string = string> = {
+  /** Pin the module's `Date` at `iso` for this chain. */
+  clock: (iso: string) => IntegrationSpecification<Services, DatabaseKey>;
+  /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
+  intercept: InterceptMethod<IntegrationSpecification<Services, DatabaseKey>>;
+  /** Queue a SQL seed file from `_seeds/` to run before the call. */
+  seed: (file: string, options?: {
+    database?: DatabaseKey;
+  }) => IntegrationSpecification<Services, DatabaseKey>;
+  /**
+   * Call the module and resolve with what it produced. The started services
+   * record is handed in, so the subject is constructed with the real
+   * connection strings rather than with a double.
+   */
+  call: <T>(subject: (services: Services) => Promise<T> | T) => Promise<CallResult<T>>;
 };
 /**
  * The `cli` facet — command chain entry handed out by `specification.cli()`.
@@ -1317,6 +1538,11 @@ type CliSpecification<DatabaseKey extends string = string> = {
  * performs one raw HTTP exchange and never follows redirects.
  */
 type WebsiteSpecification = {
+  /**
+   * Pin the PAGE's `Date` at `iso` for this chain — what the site's own
+   * scripts read. A `.fetch()` opens no page and refuses the setup.
+   */
+  clock: (iso: string) => WebsiteSpecification;
   /** Set HTTP headers for the exchange (incl. User-Agent overrides). Multiple calls merge. */
   headers: (headers: Record<string, string>) => WebsiteSpecification;
   /**
@@ -1341,104 +1567,78 @@ type WebsiteSpecification = {
  */
 type MobileSpecification = {
   /**
-   * Declare the chain's backend contracts — served by the declared stub
-   * backend (requires the runner's `backend` option). Multiple calls append.
-   */
-  intercept: InterceptMethod<MobileSpecification>;
-  /**
-   * Relaunch the app and resolve with the captured screen. With a deep
-   * link, the app opens on it; with a scenario, the visitor interacts
-   * first (the When) and the capture reflects the FINAL screen state.
-   */
-  open: (deepLink?: string, scenario?: MobileScenario) => Promise<ScreenResult>;
-};
-//#endregion
-//#region src/specification/facets/_common/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/specification/facets/_common/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/specification/facets/_common/result/result.d.ts
-/** Read-only handle to a single file produced by a spec action. */
-type 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;
-};
-type BaseResultOptions = {
-  config: SpecificationConfig;
-  testDir: string;
-  workDir?: string | undefined;
+   * Declare the chain's backend contracts — served by the declared stub
+   * backend (requires the runner's `backend` option). Multiple calls append.
+   */
+  intercept: InterceptMethod<MobileSpecification>;
+  /**
+   * Relaunch the app and resolve with the captured screen. With a deep
+   * link, the app opens on it; with a scenario, the visitor interacts
+   * first (the When) and the capture reflects the FINAL screen state.
+   */
+  open: (deepLink?: string, scenario?: MobileScenario) => Promise<ScreenResult>;
 };
+//#endregion
+//#region src/facets/cli/cli.result.d.ts
 /**
- * Base result - common accessors available after any action type.
- * Extended by HttpResult, CliResult, and used directly by job results.
+ * Result from a command action (`.exec()`).
  *
- * Every result carries a fresh {@link CaptureScope}: `match.ref()` captures
- * and `{{type#ref}}` placeholders are scoped to one spec execution.
+ * When the runner was configured with a `docker` option, the result also
+ * exposes container accessors and participates in `Symbol.asyncDispose`
+ * cleanup. The Docker shell-outs are **lazy**: a test that never calls
+ * `.container(...)` never queries the Docker daemon, so command-only tests
+ * pay zero Docker cost even when the runner is Docker-aware.
+ *
+ * Dispose always runs one final label-filtered `docker ps` to catch
+ * containers that were spawned during `.exec` but never asserted on —
+ * tests still get leak-free cleanup even if they forget to reach into
+ * a container.
  */
-declare class BaseResult {
-  /** @internal Ref-capture scope shared by every assertion on this result. */
-  readonly captures: CaptureScope;
-  protected config: SpecificationConfig;
-  protected testDir: string;
-  protected workDir?: string | undefined;
-  constructor(options: BaseResultOptions);
-  /** Access a directory (relative to the working directory) for snapshot assertions. */
-  directory(path?: string): DirectoryAccessor;
-  /** Access a single file (relative to the working directory) for content assertions. */
-  file(path: string): FileAccessor;
-  /** Access a database table for row-level assertions via expect() matchers. */
-  table(tableName: string, options?: {
-    database?: string;
-  }): TableAccessor;
-  private resolveDatabase;
+declare class CliResult extends BaseResult {
+  private readonly commandOutput;
+  private containersCache;
+  private readonly dockerConfig?;
+  private readonly testRunId?;
+  private readonly transform?;
+  constructor(options: {
+    commandOutput: CliOutput;
+    config: SpecificationConfig;
+    dockerConfig?: DockerSpecConfig | undefined;
+    testDir: string;
+    testRunId?: string | undefined;
+    transform?: ((text: string) => string) | undefined;
+    workDir: string;
+  });
+  /** The process exit code. */
+  get exitCode(): number;
+  /** Accessor for the captured standard output with file-based assertions. */
+  get stdout(): TextAccessor;
+  /** Accessor for the captured standard error with file-based assertions. */
+  get stderr(): TextAccessor;
+  /** Accessor for parsing stdout as JSON and asserting against JSON fixtures. */
+  get json(): JsonAccessor;
+  /** Accessor for the temporary working directory the command ran in. */
+  get filesystem(): FilesystemAccessor;
+  /**
+   * 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.
+   *
+   * Returns an accessor with `.exists === false` when no container
+   * carries that name — callers can still assert absence without a try.
+   */
+  container(name: string): ContainerAccessor;
+  /** All captured container IDs. Triggers the same lazy query as `container()`. */
+  get containerIds(): string[];
+  [Symbol.asyncDispose](): Promise<void>;
+  private ensureDockerAware;
+  private loadContainers;
 }
 //#endregion
-//#region src/integrations/docker/container-accessor.d.ts
+//#region src/seams/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
@@ -1491,31 +1691,7 @@ declare class ContainerAccessor {
   private containerExec;
 }
 //#endregion
-//#region src/specification/facets/_common/result/match-options.d.ts
-/**
- * The per-call option both `toMatch` implementations honour.
- *
- * A golden is read from disk under node and through a server command from
- * inside a page, and BOTH builds must answer `{ frozen: true }` the same way —
- * so the option is declared here, where the node matchers and the page's
- * matchers can each reach it, rather than in the runner's own folder, which a
- * seam may not import (rule I1).
- */
-/**
- * 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.
- */
-type MatchFixtureOptions = {
-  frozen?: boolean;
-};
-//#endregion
-//#region src/integrations/vitest-browser/ui.d.ts
+//#region src/seams/vitest-browser/ui.d.ts
 /**
  * A vanilla DOM subject: a function handed the container it must fill. Its
  * optional return is the teardown, the way a DOM library states one.
@@ -1539,7 +1715,7 @@ declare module 'vitest/browser' {
   }
 }
 //#endregion
-//#region src/integrations/vitest-browser/vitest-browser.adapter.d.ts
+//#region src/seams/vitest-browser/vitest-browser.adapter.d.ts
 /** What a mounted subject offers the chain, React or vanilla DOM alike. */
 type MountedSurface = {
   /** The element the subject was mounted into. */
@@ -1563,7 +1739,7 @@ declare function componentVerbs(surface: MountedSurface): {
   unmount: () => Promise<void>;
 };
 //#endregion
-//#region src/specification/facets/component/rendered-text.d.ts
+//#region src/facets/component/rendered-text.d.ts
 /**
  * A stream captured INSIDE the page.
  *
@@ -1578,7 +1754,7 @@ declare class RenderedText extends TextAccessor {
   readonly capturedInPage: true;
 }
 //#endregion
-//#region src/specification/facets/component/component.result.d.ts
+//#region src/facets/component/component.result.d.ts
 /**
  * What a render resolves to — the component as the page saw it, after the
  * scenario ran.
@@ -1608,7 +1784,7 @@ declare class RenderResult {
   });
 }
 //#endregion
-//#region src/specification/facets/component/component.types.d.ts
+//#region src/facets/component/component.types.d.ts
 /**
  * The component facet's shape, stated where BOTH runtimes can read it.
  *
@@ -1662,26 +1838,29 @@ type ComponentChain = {
   wrap: (wrapper: (ui: ComponentUi) => ComponentUi) => ComponentChain;
 };
 //#endregion
-//#region src/specification/facets/website/elements.d.ts
+//#region src/model/elements/elements.d.ts
 /**
  * The element vocabulary — user-facing descriptors for visit scenarios.
  * Reads like English (`click(link('Articles'))`), translates to
  * accessibility-first locators in the browser integration. CSS/XPath is
  * deliberately not expressible; `testId()` is the single escape hatch.
  *
- * A descriptor must designate exactly ONE element (CONVENTIONS W3). Two knobs
- * narrow it, in this order of preference:
- *
- *   1. `within(scope, target)` — search inside a landmark, the way a person
- *      would say "the Articles link *in the nav*";
- *   2. `{ exact: true }` — match the accessible name whole rather than as a
- *      substring, when two names genuinely overlap.
+ * A descriptor must designate exactly ONE element (CONVENTIONS W3). A name
+ * matches the accessible name WHOLE, and `within(scope, target)` is how an
+ * overlap is narrowed — the way a person would say "the Articles link *in the
+ * nav*".
  */
 /** Options accepted by every named descriptor. */
 type ElementOptions = {
   /**
-   * Match the accessible name as a whole string. Default is substring —
-   * `link('Articles')` also matches "Read Articles".
+   * Match the accessible name as a whole string. `true` by default since
+   * 16.0.
+   *
+   * A substring match is what a person does NOT mean: `link('Articles')`
+   * designated "Read Articles" as readily as "Articles", so a test could pass
+   * for years against the element beside the one it named. `{ exact: false }`
+   * is the opt-out, for a name that genuinely carries a variable part the
+   * test does not control.
    */
   exact?: boolean;
 };
@@ -1796,7 +1975,7 @@ declare const selected: (element: ElementRef) => ElementRef;
  */
 declare const valued: (element: ElementRef, value: string) => ElementRef;
 //#endregion
-//#region src/specification/contracts/filters.d.ts
+//#region src/model/contracts/filters.d.ts
 /**
  * A text filter on a provider request builder (`openai.chat({ user })`,
  * `anthropic.messages({ system })`, …).
@@ -1814,7 +1993,7 @@ declare const valued: (element: ElementRef, value: string) => ElementRef;
  */
 type TextFilter = Matcher | RegExp | string;
 //#endregion
-//#region src/integrations/anthropic/anthropic.d.ts
+//#region src/seams/anthropic/anthropic.d.ts
 type AnthropicMessagesFilter = {
   model?: TextFilter;
   system?: TextFilter;
@@ -1846,7 +2025,7 @@ declare const anthropic: {
   timeout(): ContractResponse;
 };
 //#endregion
-//#region src/specification/contracts/http.d.ts
+//#region src/model/contracts/http.d.ts
 /**
  * Request filters for the generic HTTP provider. Every field is a subset
  * constraint — a request matches when all provided fields match.
@@ -1863,6 +2042,28 @@ type HttpContractFilter = {
   /** Query-param subset. string = exact value, RegExp = `test()`. */
   query?: Record<string, RegExp | string>;
 };
+/** Init options for a streamed reply. */
+type HttpStreamInit = {
+  /** The `content-type` the stream is served under. Default `application/octet-stream`. */
+  contentType?: string;
+  /** Milliseconds between two chunks. Default 0 — every chunk at once. */
+  delay?: number;
+  /** Response headers, merged over the builder's own. */
+  headers?: Record<string, string>;
+  /** HTTP status code. Default 200. */
+  status?: number;
+};
+/** One server-sent event, as `http.sse()` frames it. */
+type SseEvent = {
+  /** The `data:` payload. An object is serialised as JSON; a string is sent as-is. */
+  data: unknown;
+  /** The `event:` name. Omitted for an unnamed (default `message`) event. */
+  event?: string;
+  /** The `id:` the client echoes as `Last-Event-ID` when it reconnects. */
+  id?: string;
+  /** The `retry:` hint, in milliseconds. */
+  retry?: number;
+};
 /** Init options shared by the response builders. */
 type HttpResponseInit = {
   /** Delay in ms before responding (for timeout testing). */
@@ -1902,11 +2103,32 @@ declare const http: {
    * server that is not running fails it. `fetch` rejects; no status is served.
    */
   unreachable(): ContractResponse;
+  /**
+   * Response: a body that arrives in PIECES, written in order.
+   *
+   * A subject that reads a response as it lands — a token-by-token render, a
+   * progress bar, a reconnect on a half-read body — is specified by the
+   * chunks and their order, which a single serialised body cannot state.
+   * Honoured by all three engines: msw's server, msw's worker, and the
+   * `node:http` stub the website and mobile facets serve from.
+   *
+   * @example
+   *   http.stream(['Hel', 'lo, ', 'world'], { contentType: 'text/plain', delay: 10 })
+   */
+  stream(chunks: readonly string[], init?: HttpStreamInit): ContractResponse;
+  /**
+   * Response: a server-sent event stream — one chunk per event, framed the
+   * way an `EventSource` reads them, served as `text/event-stream`.
+   *
+   * @example
+   *   http.sse([{ data: { token: 'Hel' } }, { data: { token: 'lo' } }, { event: 'done', data: '' }])
+   */
+  sse(events: readonly SseEvent[], init?: Omit<HttpStreamInit, "contentType">): ContractResponse;
   /** Response: a text body, served as `text/plain` (200 by default). */
   text(body: string, init?: HttpResponseInit): ContractResponse;
 };
 //#endregion
-//#region src/integrations/openai/openai.d.ts
+//#region src/seams/openai/openai.d.ts
 type OpenAIChatFilter = {
   model?: TextFilter;
   system?: TextFilter;
@@ -1964,32 +2186,149 @@ declare const openai: {
   timeout(): ContractResponse;
 };
 //#endregion
-//#region src/vitest/mock-of.d.ts
-/** Factory signature that creates a deep mock proxy for any interface. */
-type MockPort = <T>() => DeepMockProxy<T>;
+//#region src/model/doubles/mock-of.d.ts
+/** How much of the port the double answers for. */
+type MockOfOptions = {
+  /**
+   * Deep (the default): reading a member that was never stubbed hands back
+   * another double, however far down the port nests. `false` gives the flat
+   * proxy — every member of `T` and nothing beneath them, which is what a
+   * port with a nested namespace wants when the test only ever touches the
+   * first level.
+   */
+  deep?: boolean;
+};
+/**
+ * A typed double for an injected port — the fourth rung of the doubles ladder
+ * (docs/18-conventions.md), and the only one a module test may build itself.
+ *
+ * The type argument is the port: `T` is constrained to `object` and has no
+ * default, so a double is always asked for something. A call with no argument
+ * answers for `object`, which satisfies no port and fails where it is used.
+ *
+ * @example
+ *   const gateway = mockOf<PaymentGateway>();                // deep
+ *   const clock = mockOf<ClockPort>({ deep: false });        // flat
+ */
+declare function mockOf<T extends object>(options: {
+  deep: false;
+}): MockProxy<T>;
+declare function mockOf<T extends object>(options?: MockOfOptions): DeepMockProxy<T>;
+/** The factory's own shape — kept as a name so a consumer can annotate with it. */
+type MockPort = typeof mockOf;
+//#endregion
+//#region src/model/clock/clock.d.ts
+/**
+ * The one time primitive.
+ *
+ * Time is the determinism the framework owns (CONVENTIONS D16): a test that
+ * samples `Date.now()` and asserts on what comes back is a test that fails on
+ * the next leap second, and a test that reaches for `vi.useFakeTimers()` owns a
+ * teardown it will one day forget. `clock` is both answers in one name — the
+ * instant is stated, and the scope restores itself.
+ *
+ * ```typescript
+ * using _ = clock.at('2026-03-04T09:30:00Z');   // Date is pinned until the scope ends
+ * ```
+ *
+ * `at()` takes the CALENDAR and leaves the scheduler alone: a UI framework's
+ * own loop, a `setTimeout` inside the subject and every promise still resolve
+ * on their own. `run()` takes the scheduler too, for a subject whose behaviour
+ * IS the passage of time — a debounce, a retry backoff, a poll.
+ */
+/** A pinned clock — released when the `using` scope that declared it ends. */
+type PinnedClock = Disposable;
+declare const clock: {
+  /**
+   * Move the pinned clock forward by `ms` — and, under {@link clock.run},
+   * fire every callback that came due, awaiting what each of them started.
+   *
+   * Only a pinned clock moves: called with no clock taken, it says so rather
+   * than silently doing nothing to the real one.
+   */
+  advance(ms: number): Promise<void>;
+  /**
+   * Pin `Date` at `iso` for the current scope. `Date` ONLY: the scheduler
+   * stays real, so a subject that awaits, renders or polls keeps running.
+   *
+   * @example
+   *   using _ = clock.at('2026-03-04T09:30:00Z');
+   *   expect(stampedAt()).toBe('2026-03-04T09:30:00.000Z');
+   */
+  at(iso: string): PinnedClock;
+  /**
+   * Take the scheduler as well as the calendar: `setTimeout`, `setInterval`
+   * and their friends queue instead of firing, and {@link clock.advance} is
+   * what makes them due. For a subject whose behaviour IS elapsed time — a
+   * debounce, a retry backoff, a poll — where waiting for real would be the
+   * arbitrary sleep J2 forbids.
+   *
+   * @example
+   *   using _ = clock.run('2026-03-04T09:30:00Z');
+   *   const pending = retrying(failsTwice);
+   *   await clock.advance(5_000);
+   *   await expect(pending).resolves.toBe('ok');
+   */
+  run(iso?: string): PinnedClock;
+};
+//#endregion
+//#region src/model/assertions/required.d.ts
 /**
- * Create a deep mock proxy for a given type.
- * Wraps `vitest-mock-extended`'s `mockDeep` for convenient port mocking.
+ * The value, or a failure that says what was missing and why it mattered.
+ *
+ * A test reaching into a captured structure — a row, a header, the third
+ * element of a list — meets `T | undefined` and has to do something about it.
+ * The two things it usually does are both wrong: `!` erases the question, and
+ * an `if (!x) throw new Error('missing')` re-states the same three lines in
+ * every repository (the estate had two hand-written copies of exactly this).
+ * `required` is that gesture with the reason attached, so the failure reads as
+ * a sentence rather than as a `TypeError` two frames further down.
+ *
+ * @example
+ *   const id = required(result.response.body.id, 'the creation reply carries the new id');
  */
-declare const mockOf: MockPort;
+declare function required<T>(value: null | T | undefined, why: string): T;
 //#endregion
-//#region src/vitest/mock-of-date.d.ts
-/** Interface for freezing and resetting the global Date in tests. */
-type MockDatePort = {
-  /** Restore the real Date object. */
-  reset: () => void;
-  /** Freeze `Date.now()` and `new Date()` to the given value. */
-  set: (date: Date | number | string) => void;
+//#region src/model/assertions/wait-until.d.ts
+/** How long to wait, and how often to look. */
+type WaitUntilOptions = {
+  /** Milliseconds between two readings. Default 50. */
+  interval?: number;
+  /** How long the condition has to become true. Default 5 000 ms. */
+  timeout?: number;
+  /** What the condition is, named in the failure. Default: the predicate's source. */
+  why?: string;
 };
 /**
- * Freeze or reset the global Date for deterministic time-dependent tests.
- * Wraps the `mockdate` package.
+ * Wait until a condition holds — the sanctioned answer to "the thing I am
+ * specifying is not ready yet".
+ *
+ * A spec that sleeps for a guessed duration is a spec that is slow on a fast
+ * machine and flaky on a slow one, which is why J2 refuses `setTimeout` under
+ * `specs/`. Every facet that drives something already waits on a CONDITION —
+ * a served page, a banner on stdout, an element the visitor can see — and this
+ * is that primitive where no facet owns the waiting: a background write to
+ * land, a queue to drain, a file to appear.
+ *
+ * The failure names the condition and how long it was given, so a timeout is a
+ * sentence rather than "expected true, got false".
+ *
+ * The budget is measured on `performance.now()`, not on `Date` — `clock.at()`
+ * freezes the calendar, and a deadline read off a frozen calendar never
+ * arrives: the poll would run until vitest killed the test with a sentence
+ * about the file rather than about the condition.
+ *
+ * Not for a subject under `clock.run()`: there the scheduler is the test's, and
+ * `clock.advance(ms)` is what makes time pass.
+ *
+ * @example
+ *   await waitUntil(() => outbox.length === 1, { why: 'the job wrote its one message' });
  */
-declare const mockOfDate: MockDatePort;
+declare function waitUntil(predicate: () => boolean | Promise<boolean>, options?: WaitUntilOptions): Promise<void>;
 //#endregion
 //#region src/surface.d.ts
 declare module 'vitest' {
-  interface Assertion<T = any> {
+  interface Assertion<R extends Promise<void> | void = void, T = unknown> {
     /**
      * Assert the subject is empty — zero rows for a table (async), an
      * empty stream for a text accessor (console, errors, stdout).
@@ -2013,9 +2352,9 @@ declare module 'vitest' {
      * 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 {
+    toMatch: T extends DirectoryAccessor | FilesystemAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => Promise<void> & R : T extends {
       readonly capturedInPage: true;
-    } ? (name: RegExp | string, options?: MatchFixtureOptions) => Promise<void> : T extends JsonAccessor | ResponseAccessor | TextAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => void : (expected: RegExp | string, options?: MatchFixtureOptions) => void;
+    } ? (name: RegExp | string, options?: MatchFixtureOptions) => Promise<void> & R : T extends JsonAccessor | ResponseAccessor | TextAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => R : (expected: RegExp | string, options?: MatchFixtureOptions) => R;
     /**
      * Assert the table contains exactly the given rows for the given
      * columns. Cells accept `match.*` dynamic-value matchers. Async —
@@ -2028,17 +2367,39 @@ declare module 'vitest' {
   }
 }
 //#endregion
-//#region src/specification/facets/_common/orchestrator.d.ts
+//#region src/model/chain/reporter.d.ts
+/**
+ * What the subject IS, for the line the startup report closes on.
+ *
+ * Four shapes, because there are four: an app built and served inside this
+ * process (api), a child process the runner started and polls (a site's dev
+ * server), a deployment already running somewhere (`url`), and a subject that
+ * is not an app at all — a binary, a pipeline, a module, a screen — which gets
+ * no line rather than a wrong one.
+ */
+type AppInfo = {
+  /** The command, for a child process. */
+  command?: string | undefined;
+  type: 'http' | 'in-process' | 'none' | 'process';
+  url?: string | undefined;
+};
+//#endregion
+//#region src/model/chain/orchestrator.d.ts
 type OrchestratorOptions = {
   /**
-   * 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}.
+   * What the subject IS — the line the startup report closes on. Defaults to
+   * the api shape, which is the only facet that serves an app in this
+   * process; a facet whose subject is a binary, a pipeline or a screen says
+   * `{ type: 'none' }` and gets no line rather than a wrong one.
+   */
+  subject?: AppInfo | undefined;
+  /**
+   * Named infrastructure record. Keys are the database vocabulary of the spec
+   * (`.seed()` / `.table()` `database` option) and the name each handle is
+   * reported and initialised under: the kebab-case form of the key is the
+   * directory its init script lives in (`analyticsDb` → `docker/analytics-db/`).
    */
   services: Record<string, ServiceHandle>;
-  mode: 'e2e' | 'integration';
   /**
    * The project root, already resolved. REQUIRED: the constructors derive it
    * by walking up from the calling specification file (CONVENTIONS A9), and
@@ -2048,68 +2409,40 @@ type OrchestratorOptions = {
    * launched, which in a workspace is rarely the same directory.
    */
   root: string;
-  /** Compose project name — used for per-worker stack isolation. */
-  projectName?: string;
 };
 /**
- * Orchestrator for test infrastructure.
- * Integration: starts services via testcontainers.
- * E2E: runs full docker compose up.
+ * The infrastructure a specification declares, started and stopped as a unit.
+ *
+ * Every declared handle becomes a real thing: a container through
+ * testcontainers, or an embedded service (SQLite) that needs no container. The
+ * record KEY is the only name in play — it is the spec's database vocabulary,
+ * the name the startup report prints, and, kebab-cased, the directory the
+ * service reads its init script from.
+ *
+ * It is internal wiring: the constructors drive it, and no consumer names it.
  */
 declare class Orchestrator {
   private readonly services;
-  private readonly mode;
   private readonly root;
-  private readonly projectName;
+  private readonly subject;
   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.
-   */
-  private resolveBindings;
-  /**
-   * Start declared services via testcontainers (integration mode).
+   * Start every declared service.
    * 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 every container this stack started. */
   stop(): Promise<void>;
-  /**
-   * Start full docker compose stack (e2e mode).
-   * Auto-detects infra services and creates handles for them.
-   */
-  startCompose(): Promise<void>;
-  /**
-   * Stop docker compose stack (e2e mode).
-   */
-  stopCompose(): Promise<void>;
-  /**
-   * Get the default database — the first declared handle that is one.
-   */
+  /** The default database — the first declared handle that is one. */
   getDatabase(): DatabasePort | null;
-  /**
-   * Get all database services keyed by their record key (declared services)
-   * or compose service name (stack-detected services).
-   */
+  /** Every database service, keyed by its record key. */
   getDatabases(): Map<string, DatabasePort>;
-  private allHandles;
-  /**
-   * Get app URL from compose (e2e mode).
-   */
-  getAppUrl(): null | string;
 }
 //#endregion
-//#region src/specification/facets/_common/services.d.ts
+//#region src/model/chain/services.d.ts
 /**
  * Infrastructure services declared as a named record. Keys become the typed
  * vocabulary of the whole spec: the server factory receives the same record,
@@ -2119,41 +2452,29 @@ 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/specification/facets/api/start-api.d.ts
+//#region src/facets/api/api.specification.d.ts
 /** Any object with a request method compatible with Hono's app.request(). */
 type HonoApp = {
   request: (path: string, init?: RequestInit) => Promise<Response> | Response;
 };
-/** Execution mode — exists ONLY on `specification.api()` (CONVENTIONS A5). */
-type SpecificationMode = 'compose' | 'node';
 /** Options for {@link startApi | specification.api}. */
 type 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).
+   * Project root override for init scripts and artefact paths. When absent,
+   * the root is auto-discovered by walking up from the calling specification
+   * file to the first directory 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).
+   * and returns the Hono app.
    */
-  server?: (services: Services) => HonoApp;
+  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).
+   * `.seed()` / `.table()`, and, kebab-cased, the folder each service reads
+   * its init script from (`{ analyticsDb: postgres() }` →
+   * `docker/analytics-db/init.sql`).
    */
   services?: Services;
 };
@@ -2172,12 +2493,10 @@ type ApiHandle<DatabaseKey extends string = string> = {
    * 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/specification/facets/cli/start-cli.d.ts
+//#region src/facets/cli/cli.specification.d.ts
 /** Options for {@link startCli | specification.cli}. */
 type CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
   /**
@@ -2188,6 +2507,14 @@ type CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
    * containers get force-removed at scope exit (CONVENTIONS B5).
    */
   docker?: DockerSpecConfig;
+  /**
+   * Environment applied to EVERY run of this binary — the variables the
+   * product needs to be deterministic at all (`TZ`, `NO_COLOR`, `LANG`,
+   * a config home under the spec's own workdir). Stated once per app
+   * instead of repeated on every chain and in every document; a chained
+   * `.env()` and a document's `env:` both win over it.
+   */
+  defaults?: CliEnv;
   /**
    * Named environment SETS for `<case>.spec.yaml` documents. An `env:` entry
    * `frozen` applies the whole `frozen` record; `$WORKDIR` expands and `null`
@@ -2205,9 +2532,9 @@ type CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
   serve?: Record<string, LiterateServeRegistration>;
   /**
    * 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.
+   * it anchors the local-bin resolution of the tested binary, in place of
+   * the walk to the nearest `package.json`. It is NOT a fixtures root;
+   * `.fixture()` resolves feature-local or `$FIXTURES/` paths on its own.
    */
   root?: string;
   /**
@@ -2245,13 +2572,50 @@ type CliHandle<DatabaseKey extends string = string> = {
 };
 declare function startCli<Services extends ServiceRecord>(bin: string, options?: CliSpecificationOptions<Services>): Promise<CliHandle<DatabaseKeys<Services>>>;
 //#endregion
-//#region src/specification/facets/jobs/start-jobs.d.ts
+//#region src/facets/integration/integration.specification.d.ts
+/** Options for {@link startIntegration | specification.integration}. */
+type IntegrationSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
+  /** Project-root override — see the `root` option of `specification.api()`. */
+  root?: string;
+  /**
+   * Named infrastructure the module is specified AGAINST — a real database,
+   * a real cache, a `process()` it talks to. Omit it for the other half of
+   * the facet: a pure module whose oracle is a golden.
+   */
+  services?: Services;
+};
+/**
+ * The record returned by {@link startIntegration | specification.integration}.
+ * Destructure with the canonical names (CONVENTIONS A3):
+ *
+ *     const { integration, cleanup } = await specification.integration(…);
+ */
+type IntegrationHandle<Services extends ServiceRecord = ServiceRecord, DatabaseKey extends string = string> = {
+  /** Stop all infrastructure started by this specification. */
+  cleanup: () => Promise<void>;
+  integration: IntegrationSpecification<Services, DatabaseKey>;
+};
+/**
+ * Specify a module the way the assembled product is specified: against real
+ * services and declared contracts, with the golden mechanism on what it
+ * produces.
+ *
+ * The fork is the SUBJECT. A module alone is a module test, beside its code,
+ * with no runner at all. A module that needs a real database, or whose oracle
+ * is a golden file, is this one — which is what spares it the shape it would
+ * otherwise take: plain vitest under a `specs/` folder, a hand-built sqlite
+ * template, a `beforeAll` starting a container, and a `toMatchSnapshot` beside
+ * a framework that owns a golden engine.
+ */
+declare function startIntegration<Services extends ServiceRecord>(options?: IntegrationSpecificationOptions<Services>): Promise<IntegrationHandle<Services, DatabaseKeys<Services>>>;
+//#endregion
+//#region src/facets/jobs/jobs.specification.d.ts
 /** Options for {@link startJobs | specification.jobs}. */
 type 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.
+   * definition (CONVENTIONS A8).
    */
   jobs: ((services: Services) => JobHandle[]) | JobHandle[];
   /** Project root override — see the `root` option of `specification.api()`. */
@@ -2274,7 +2638,7 @@ type JobsHandle<DatabaseKey extends string = string> = {
 };
 declare function startJobs<Services extends ServiceRecord>(options: JobsSpecificationOptions<Services>): Promise<JobsHandle<DatabaseKeys<Services>>>;
 //#endregion
-//#region src/specification/facets/mobile/start-mobile.d.ts
+//#region src/facets/mobile/mobile.specification.d.ts
 /**
  * The declared stub backend behind the app under test. The framework owns
  * the simulator and appium but NOT the JS bundler (Metro belongs to the
@@ -2291,7 +2655,7 @@ type MobileBackendOptions = {
   port?: number;
 };
 /** Options for {@link startMobile | specification.mobile}. */
-type MobileSpecificationOptions = {
+type MobileSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
   /** The app under test — terminated and relaunched by every `.open()`. */
   app: {
     /** Bundle id of the installed app (`com.example.app`). */
@@ -2324,6 +2688,14 @@ type MobileSpecificationOptions = {
    * driving a DEV build states the wait its bundler's cold boot needs
    * (`{ action: 45_000 }`) instead of sleeping inside its scenarios.
    */
+  /**
+   * Named services started with the runner and stopped with it — a
+   * `process()` for the bundler the app loads from, a database a dev build
+   * reads. Metro stops being a `beforeAll` the repository maintains: it is
+   * `process({ command: 'expo start', ready: /Metro waiting on .*:(\\d+)/ })`
+   * like every other external process the framework owns.
+   */
+  services?: Services;
   timeouts?: DeviceTimeouts;
 };
 /**
@@ -2345,13 +2717,35 @@ type MobileHandle = {
   /** The resolved simulator UDID the specs run against. */
   udid: string;
 };
-declare function startMobile(options: MobileSpecificationOptions): Promise<MobileHandle>;
+declare function startMobile<Services extends ServiceRecord>(options: MobileSpecificationOptions<Services>): Promise<MobileHandle>;
 //#endregion
-//#region src/specification/facets/website/serve.adapter.d.ts
-/** Options for a local server started by the framework. */
-type ServeOptions = {
-  /** Shell command that starts the site. Receives the chosen port as `PORT`. */
+//#region src/seams/process/serve.adapter.d.ts
+/**
+ * The ONE shape an external process takes — the site under test, a backend a
+ * page talks to, a bundler a simulator loads from. Built by `process()`
+ * (chapter 17) and accepted wherever a facet starts something outside this
+ * process: `website({ server })`, `services: { api: process(…) }`, and the
+ * literate `serve:` registry.
+ */
+type ProcessOptions = {
+  /**
+   * A one-shot command run ONCE per specification, before the process is
+   * spawned, which must exit 0 — a build, a migration, a fixture load. Its
+   * failure is the specification's, and it says so.
+   */
+  before?: string;
+  /** Shell command that starts the process. Receives the chosen port as `PORT`. */
   command: string;
+  /** Working directory, relative to the project root. Default: the root itself. */
+  cwd?: string;
+  /**
+   * Environment for the child, on top of the runner's own. A function
+   * receives the services already started beside this one, so a process can
+   * be handed a sibling's connection string.
+   */
+  env?: ((services: Record<string, {
+    connectionString: string;
+  }>) => Record<string, string>) | Record<string, string>;
   /** Fixed port. Default: an OS-assigned free port, injected as `PORT`. */
   port?: number;
   /**
@@ -2370,7 +2764,85 @@ type ServeOptions = {
   timeout?: number;
 };
 //#endregion
-//#region src/specification/facets/website/start-website.d.ts
+//#region src/model/chain/process.d.ts
+/**
+ * An external process, declared like any other service.
+ *
+ * One shape for every one of them: a site's dev server, an API behind the
+ * site, the bundler a simulator loads from. Without it each is declared
+ * somewhere else — a facet option, a document's `serve:` entry, a `beforeAll`
+ * spawning a child and an `afterAll` that sometimes forgets to kill it — and
+ * the lifetime belongs to whoever remembered. Here it is the framework's.
+ *
+ * It sits in a `services` record beside `postgres()`, `redis()` and
+ * `sqlite()`, so it starts after them and can be handed their connection
+ * strings through `env`, and it is stopped with the specification.
+ */
+declare class ProcessHandle implements ServiceHandle {
+  /** Embedded: nothing to pull, nothing to run in a container. */
+  readonly defaultImage = "";
+  readonly defaultPort = 0;
+  readonly environment: Record<string, string>;
+  readonly type = "process";
+  serviceName: null | string;
+  connectionString: string;
+  started: boolean;
+  private adapter;
+  private readonly options;
+  constructor(options: ProcessOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort | null;
+  healthcheck(): Promise<void>;
+  /**
+   * A process is not a container, so the orchestrator never starts it: the
+   * facet does, once its siblings are up and their connection strings are
+   * readable ({@link startProcessServices}).
+   */
+  initialize(): Promise<void>;
+  /**
+   * Isolation is the RUN's, not the worker's — and a run here is one
+   * EVALUATION of the specification module. Under vitest's default
+   * isolation that is once per test file, so two files that import the same
+   * specification get a child each, with the id the facet minted for it.
+   * Nothing is acquired or reset between tests: the id is what tells two
+   * runs apart, never a label a spec samples.
+   */
+  isolation(): IsolationStrategy;
+  reset(): Promise<void>;
+  /**
+   * Spawn it and wait until it answers. `services` is every handle declared
+   * beside this one, already started — what an `env` function reads.
+   *
+   * @internal
+   */
+  spawnWith(root: string, services: Record<string, {
+    connectionString: string;
+  }>, runId: string): Promise<void>;
+  /** Terminate the process group. Idempotent. */
+  shutdown(): Promise<void>;
+  /** What it was declared as — what a facet reads to start it in a slot of its own. */
+  get spec(): ProcessOptions;
+  /** The base URL it came up on — known only once it is started. */
+  get url(): string;
+}
+/**
+ * Declare an external process the framework owns for the life of the
+ * specification.
+ *
+ * @example
+ *   const { website, cleanup } = await specification.website({
+ *       services: { api: process({ command: 'bin/server web', ready: '/health' }) },
+ *       server: ({ api }) => process({
+ *           command: 'next dev',
+ *           env: { NEXT_PUBLIC_API_URL: api.connectionString },
+ *       }),
+ *   });
+ */
+declare function processService(options: ProcessOptions): ProcessHandle;
+//#endregion
+//#region src/facets/website/website.specification.d.ts
+/** What `server` may be handed as, and what it resolves to. */
+type ServerSpec<Services extends ServiceRecord> = ((services: Services) => ProcessHandle | ProcessOptions) | ProcessHandle | ProcessOptions;
 /**
  * The declared stub backend behind the site under test — started before the
  * server command, torn down with the runner. Its URL is injected into the
@@ -2391,7 +2863,7 @@ type WebsiteBackendOptions = {
  * mode for the same reason: a deployed site cannot be pointed at a local
  * stub.
  */
-type WebsiteSpecificationOptions = {
+type WebsiteSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
   /**
    * Cross-origin request policy for visits. Default: `'block'` with a
    * local `server` (deterministic — analytics and CDNs never leave the
@@ -2403,6 +2875,14 @@ type WebsiteSpecificationOptions = {
    * `server` command. Auto-discovered from the calling file when absent.
    */
   root?: string;
+  /**
+   * Named services started with the runner, before the site is: a database
+   * the site reads, a `process()` backend it calls. They are started in
+   * declaration order and stopped with the specification, and `server` may
+   * be a function of them — which is how a site is handed the URL of the
+   * API it was started beside.
+   */
+  services?: Services;
 } & ({
   /**
    * Declared stub backend: started BEFORE the server command, its
@@ -2411,10 +2891,11 @@ type WebsiteSpecificationOptions = {
    */
   backend?: WebsiteBackendOptions;
   /**
-   * Start the site locally: a shell command receiving a free port
-   * as `PORT`, polled on `ready` (default `/`) until it answers.
+   * Start the site locally: a `process()` — a shell command receiving
+   * a free port as `PORT`, polled on `ready` (default `/`) until it
+   * answers — or a function of the started services returning one.
    */
-  server: ServeOptions;
+  server: ServerSpec<Services>;
   url?: never;
 } | {
   backend?: never;
@@ -2435,11 +2916,11 @@ type WebsiteHandle = {
   url: string;
   website: WebsiteSpecification;
 };
-declare function startWebsite(options: WebsiteSpecificationOptions): Promise<WebsiteHandle>;
+declare function startWebsite<Services extends ServiceRecord>(options: WebsiteSpecificationOptions<Services>): Promise<WebsiteHandle>;
 //#endregion
-//#region src/specification/facets/_common/specification.d.ts
+//#region src/facets/specification.d.ts
 /**
- * The five specification constructors (CONVENTIONS A2) — created in a
+ * The six 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).
  *
@@ -2462,21 +2943,22 @@ declare function startWebsite(options: WebsiteSpecificationOptions): Promise<Web
  *   export const { cli, cleanup } = await specification.cli('my-cli');
  *   afterAll(cleanup);
  */
-/** The five constructors, and only five — the framework's whole entry surface. */
+/** The six constructors, and only six — the framework's whole entry surface. */
 type Specification = {
   api: typeof startApi;
   cli: typeof startCli;
+  integration: typeof startIntegration;
   jobs: typeof startJobs;
   mobile: typeof startMobile;
   website: typeof startWebsite;
 };
 declare const specification: Specification;
 //#endregion
-//#region src/specification/facets/component/component.node.d.ts
+//#region src/facets/component/component.specification.d.ts
 /** Present, typed, and refusing — every setup and the terminal action alike. */
 declare const component: ComponentChain;
 //#endregion
-//#region src/specification/literate/spec-document.d.ts
+//#region src/model/literate/spec-document.d.ts
 /**
  * The facets a document may describe. `cli` is the only one implemented; the
  * key exists so a second facet can arrive without a second grammar.
@@ -2556,15 +3038,7 @@ type SpecDocument = {
   serve: SpecServeEntry[];
 };
 //#endregion
-//#region src/integrations/docker/docker-lookup.d.ts
-/** Return all container IDs (running or stopped) that carry `key=value`. */
-declare function findContainersByLabel(key: string, value: string): string[];
-/** Return the raw `docker inspect` payload (object, not array) for a container. */
-declare function inspectContainer(id: string): unknown;
-/** Force-remove the given container IDs in a single call. Errors are swallowed. */
-declare function removeContainers(ids: string[]): void;
-//#endregion
-//#region src/specification/facets/_common/result/text-subject.d.ts
+//#region src/model/result/text-subject.d.ts
 /**
  * Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
  * test's directory — the same caller-detection the builders use.
@@ -2590,7 +3064,7 @@ declare function removeContainers(ids: string[]): void;
  */
 declare function text(value: string): TextAccessor;
 //#endregion
-//#region src/specification/ports/container.port.d.ts
+//#region src/model/ports/container.port.d.ts
 /**
  * Abstract container interface.
  * Represents a running service (database, cache, etc.)
@@ -2610,13 +3084,8 @@ type ContainerPort = {
   getLogs: () => Promise<string>;
 };
 //#endregion
-//#region src/integrations/postgres/postgres.d.ts
+//#region src/seams/postgres/postgres.d.ts
 type 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. */
@@ -2624,7 +3093,7 @@ type PostgresOptions = {
 };
 declare class PostgresHandle implements DatabasePort, ServiceHandle {
   readonly type = "postgres";
-  composeName: null | string;
+  serviceName: null | string;
   readonly defaultPort = 5432;
   readonly defaultImage: string;
   readonly environment: Record<string, string>;
@@ -2637,7 +3106,7 @@ declare class PostgresHandle implements DatabasePort, ServiceHandle {
   buildConnectionString(host: string, port: number): string;
   createDatabaseAdapter(): DatabasePort;
   healthcheck(): Promise<void>;
-  initialize(composeDir: string): Promise<void>;
+  initialize(dockerDir: string): Promise<void>;
   private getClient;
   seed(sql: string): Promise<void>;
   reset(): Promise<void>;
@@ -2648,28 +3117,23 @@ declare class PostgresHandle implements DatabasePort, ServiceHandle {
  * 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" });
+ * // The record key is the name: it is the spec's `database` vocabulary, and
+ * // Kebab-cased it is the folder the init script is read from.
+ * //   { db: postgres() }          → docker/db/init.sql, then docker/postgres/init.sql
+ * //   { analyticsDb: postgres() } → docker/analytics-db/init.sql
+ * const events = postgres();
  * // After start: events.connectionString is populated
  */
 declare function postgres(options?: PostgresOptions): PostgresHandle;
 //#endregion
-//#region src/integrations/redis/redis.d.ts
+//#region src/seams/redis/redis.d.ts
 type 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;
+  serviceName: null | string;
   readonly defaultPort = 6379;
   readonly defaultImage: string;
   readonly environment: Record<string, string>;
@@ -2688,13 +3152,13 @@ declare class RedisHandle implements ServiceHandle {
  * Create a Redis service handle.
  *
  * @example
- * // The record key derives the compose service: { cache: redis() } → "cache".
+ * // The record key is the name it reports under: { 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
+//#region src/seams/sqlite/sqlite.d.ts
 type SqliteOptions = {
   /**
    * Path to a SQL file used to initialize the database schema.
@@ -2711,7 +3175,7 @@ type SqliteOptions = {
 };
 declare class SqliteHandle implements DatabasePort, ServiceHandle {
   readonly type = "sqlite";
-  composeName: null | string;
+  serviceName: null | string;
   readonly defaultPort = 0;
   readonly defaultImage = "";
   readonly environment: Record<string, string>;
@@ -2741,7 +3205,7 @@ declare class SqliteHandle implements DatabasePort, ServiceHandle {
    * rather than proceeding into a second concurrent `prisma db push` on the
    * same file (which is what `database is locked` was).
    */
-  initialize(_composeDir?: string, root?: string): Promise<void>;
+  initialize(_dockerDir?: string, root?: string): Promise<void>;
   /**
    * Build the template on a private path, then rename it into place.
    *
@@ -2774,4 +3238,11 @@ declare class SqliteHandle implements DatabasePort, ServiceHandle {
  */
 declare function sqlite(options?: SqliteOptions): SqliteHandle;
 //#endregion
-export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliInput, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, type ComponentChain, type ComponentScenario, type ComponentUi, type ComponentVisitor, ContainerAccessor, type ContainerPort, type Contract, type ContractInput, type ContractRequest, type ContractResponder, type ContractResponse, type ContractResponseValue, type Contracts, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, type DeviceTimeouts, DirectoryAccessor, type DockerSpecConfig, type DomMount, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, type HttpContractFilter, type HttpResponseInit, HttpResult, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type LiterateRunFlags, type LiterateServeRegistration, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, type RenderResult, type RenderSubject, type RenderedText, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecDocument, type SpecEnvToken, type SpecFileAssertion, type SpecFixture, type SpecKind, type SpecRun, type SpecServeEntry, type SpecStream, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type TextFilter, type VisitScenario, type Visitor, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, findContainersByLabel, focused, form, heading, http, inspectContainer, link, listitem, main, match, mockOf, mockOfDate, navigation, openai, option, postgres, redis, region, removeContainers, row, search, selected, specification, sqlite, status, table, testId, text, valued, within };
+//#region src/index.d.ts
+/**
+ * The module-scope network double, on msw's node server — what a test with no
+ * chain to hang contracts on reaches for (chapter 16).
+ */
+declare const intercept: Intercept;
+//#endregion
+export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, type BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CallResult, type CaptureScope, type CliEnv, type CliHandle, type CliInput, type CliOutput, type CliPort, type CliResult, type CliSpecification, type CliSpecificationOptions, type ComponentChain, type ComponentScenario, type ComponentUi, type ComponentVisitor, type ContainerAccessor, type ContainerPort, type Contract, type ContractInput, type ContractRequest, type ContractResponder, type ContractResponse, type ContractResponseValue, type Contracts, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, type DeviceTimeouts, type DirectoryAccessor, type DockerSpecConfig, type DomMount, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, type FetchResult, type FileAccessor, type FilesystemAccessor, type HonoApp, type HttpContractFilter, type HttpResponseInit, type HttpResult, type HttpStreamInit, type IntegrationHandle, type IntegrationSpecification, type IntegrationSpecificationOptions, type Intercept, type InterceptOptions, type InterceptScope, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsResult, type JobsSpecification, type JobsSpecificationOptions, type JsonAccessor, type LandmarkKind, type LiterateRunFlags, type LiterateServeRegistration, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockOfOptions, type MockPort, type PageResult, type PinnedClock, type PostgresOptions, ProcessHandle, type ProcessOptions, type RedisOptions, type RenderResult, type RenderSubject, type RenderedText, type ResponseAccessor, type ScreenNode, type ScreenResult, type ServerPort, type ServerResponse, type ServerSpec, type ServiceHandle, type ServiceRecord, type SpecDocument, type SpecEnvToken, type SpecFileAssertion, type SpecFixture, type SpecKind, type SpecRun, type SpecServeEntry, type SpecStream, type SpecificationConfig, type SqliteOptions, type SseEvent, type StreamBody, type TableAccessor, type TextAccessor, type TextFilter, type VisitScenario, type Visitor, type WaitUntilOptions, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, clock, complementary, component, content, contentinfo, defineContract, defineContracts, dialog, disabled, enabled, field, focused, form, heading, http, intercept, link, listitem, main, match, mockOf, navigation, openai, option, postgres, processService as process, redis, region, required, row, search, selected, specification, sqlite, status, table, testId, text, valued, waitUntil, within };