@jterrazz/test 15.3.0 → 16.1.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Scalar } from "yaml";
 import { DeepMockProxy, MockProxy } from "vitest-mock-extended";
 import { ReactNode as ComponentUi } from "react";
 import "vitest/browser";
-//#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
@@ -104,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
@@ -189,12 +189,25 @@ declare function defineContract(contract: Contract): Contract;
  */
 declare function defineContracts(...items: ContractInput[]): Contracts;
 //#endregion
-//#region src/integrations/msw/scope.d.ts
+//#region src/model/contracts/intercept.d.ts
 /**
  * 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 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 module-scope network double. Resolves once the engine is listening —
  * which is why it is a promise, and why the canonical form awaits it:
@@ -207,9 +220,9 @@ type InterceptScope = AsyncDisposable;
  * first handler is in place, so the shape refuses the racy spelling: a promise
  * is not an `AsyncDisposable`, and the compiler says so.
  */
-type Intercept = ((contracts: ContractInput) => Promise<InterceptScope>) & ((request: ContractRequest, response: ContractResponder | ContractResponse) => Promise<InterceptScope>);
+type Intercept = ((contracts: ContractInput, options?: InterceptOptions) => Promise<InterceptScope>) & ((request: ContractRequest, response: ContractResponder | ContractResponse, options?: InterceptOptions) => Promise<InterceptScope>);
 //#endregion
-//#region src/specification/matching/match.d.ts
+//#region src/model/matching/match.d.ts
 /**
  * Code-side dynamic-value matchers (`match.*`) and the capture scope shared
  * by every assertion of a single spec execution.
@@ -291,7 +304,52 @@ declare class CaptureScope {
   set(name: string, value: unknown): void;
 }
 //#endregion
-//#region src/specification/facets/_common/result/json.d.ts
+//#region src/model/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/model/result/filesystem.d.ts
+/**
+ * Read-only accessor for the whole temporary working directory used by a
+ * command spec.
+ *
+ * Assertions go through `expect()` (async — they walk the disk):
+ * `await expect(result.filesystem).toMatch('scaffolded')` compares the
+ * tree against the fixture directory `_expected/<name>/`.
+ */
+declare class FilesystemAccessor {
+  /** @internal Ref-capture scope shared by the current spec execution. */
+  readonly captures: CaptureScope;
+  /** The absolute path of the temporary working directory. */
+  readonly cwd: string;
+  /** @internal Test-file directory — fixture resolution root for matchers. */
+  readonly testDir: string;
+  constructor(cwd: string, testDir: string, captures?: CaptureScope);
+  /** List all files (recursively) under the working directory, sorted. */
+  files(options?: {
+    ignore?: string[];
+  }): Promise<string[]>;
+}
+//#endregion
+//#region src/model/result/json.d.ts
 /**
  * Read-only accessor for a JSON payload parsed from a text stream (stdout).
  *
@@ -327,214 +385,220 @@ declare class JsonAccessor<Value = unknown> {
   get value(): Value;
 }
 //#endregion
-//#region src/specification/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';
+//#region src/model/result/match-options.d.ts
 /**
- * The interactive/textual element kinds — what a visitor actually acts on.
+ * The per-call option both `toMatch` implementations honour.
  *
- * `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()`.
+ * 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 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.
+ * 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 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;
+type MatchFixtureOptions = {
+  frozen?: boolean;
 };
+//#endregion
+//#region src/model/ports/server.port.d.ts
 /**
- * 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.
+ * HTTP response returned by a server port, with parsed JSON body.
  */
-type ElementMatch = {
-  /**
-   * 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.
-   */
-  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;
+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>;
 };
 /**
- * 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.
+ * Abstract server interface for specification runners.
+ * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
  */
-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;
-  /**
-   * 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;
+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/model/result/response.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 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.
  */
-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 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). */
+  seed: (sql: string) => Promise<void>;
+  /** Query a table and return rows as arrays of values. */
+  query: (table: string, columns: string[]) => Promise<unknown[][]>;
+  /** Reset database to clean state between tests. */
+  reset: () => Promise<void>;
 };
+//#endregion
+//#region src/model/result/table.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 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 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 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
+/**
+ * Read-only accessor for a captured text handle — THE universal one: stdout,
+ * stderr, container logs, and file text all surface as a `TextAccessor`.
+ *
+ * Backed by a primitive string, exposed via {@link text}, but also provides
+ * `toString()` / `valueOf()` for string coercion, so common patterns like
+ * `String(result.stdout)` and template-literal interpolation still work.
+ *
+ * ANSI escape sequences are stripped by default before every comparison
+ * (CONVENTIONS D6) — `.text` stays raw. The runner `transform` option remains
+ * an escape hatch for application noise not covered by the `{{token}}`
+ * grammar.
+ *
+ * Text operations are **closed** over the type: `.grep(pattern)` returns a
+ * `TextAccessor` (not a bare string), preserving the `_expected/`-resolution
+ * context and the `transform`, so results are chainable
+ * (`result.stdout.grep(a).grep(b)`) and snapshot-able
+ * (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
+ *
+ * Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
+ * and `expect(result.stdout).toMatch('name.txt')` (resolved against
+ * `_expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
+ */
+declare class TextAccessor {
+  /** @internal Ref-capture scope shared by the current spec execution. */
+  readonly captures: CaptureScope;
+  /** @internal Stream label used in failure messages ("stdout" / "stderr"). */
+  readonly streamName: string;
+  /** @internal Test-file directory — fixture resolution root for matchers. */
+  readonly testDir: string;
+  /** The raw captured text (never transformed, ANSI preserved). */
+  readonly text: string;
+  /** @internal Normaliser applied before comparisons, never to fixtures. */
+  readonly transform?: ((text: string) => string) | 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;
 };
+/**
+ * Base result - common accessors available after any action type.
+ * Extended by HttpResult, CliResult, and used directly by job results.
+ *
+ * Every result carries a fresh {@link CaptureScope}: `match.ref()` captures
+ * and `{{type#ref}}` placeholders are scoped to one spec execution.
+ */
+declare class 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/specification/ports/cli.port.d.ts
+//#region src/model/ports/cli.port.d.ts
 /**
  * Raw output from a command execution, including exit code and captured output streams.
  */
@@ -585,516 +649,457 @@ type CliPort = {
   watch: (args: string, cwd: string, options: ExecOptions, env?: CliEnv) => Promise<CliOutput>;
 };
 //#endregion
-//#region src/specification/ports/database.port.d.ts
+//#region src/facets/cli/literate.d.ts
 /**
- * Abstract database interface for specification runners.
- * Implement this to plug in your database stack (e.g. Postgres, SQLite).
+ * 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 DatabasePort = {
-  /** Execute raw SQL (for seeding test data). */
-  seed: (sql: string) => Promise<void>;
-  /** Query a table and return rows as arrays of values. */
-  query: (table: string, columns: string[]) => Promise<unknown[][]>;
-  /** Reset database to clean state between tests. */
-  reset: () => Promise<void>;
-};
-//#endregion
-//#region src/specification/ports/device.port.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.
+ * A server a document may start by name (`serve: mcp`), registered once per app
+ * in the `serve` option of `specification.cli()`.
  */
-type MobileElementKind = 'button' | 'field' | 'testId' | 'text';
+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/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;
+};
 /**
- * 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.
+ * 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.
  *
- * 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.
+ * Three answers, because a type has three ways of relating to `string`:
+ *
+ * - EXACTLY a string — a `TextAccessor`, and nothing to narrow;
+ * - it MAY be a string (`string | undefined`, `string | number`, `any`) — the
+ *   UNION, which the test narrows. The type used to read the static type only
+ *   while the accessor was built from the RUNTIME value, so a subject typed
+ *   `string | undefined` was handed back as a `JsonAccessor`: `.value.value`
+ *   compiled, the runtime had built a `TextAccessor`, and the read silently
+ *   answered `undefined`;
+ * - never a string — a `JsonAccessor<Returned>`.
+ *
+ * `Returned` there is what the value CLAIMS, not what survived the crossing:
+ * the accessor is built from `JSON.stringify`, so a `Map`, a `Date` or a class
+ * instance arrives as the plain JSON it serialises to (`{}`, an ISO string, an
+ * object of its own fields). A subject whose answer is one of those is
+ * projected to plain data inside the call, where the test can see it happen.
  */
-type MobileElementRef = ElementRef;
+type CallValue<Returned> = [Returned] extends [string] ? TextAccessor : [Extract<Returned, string>] extends [never] ? JsonAccessor<Returned> : JsonAccessor<Exclude<Returned, string>> | TextAccessor;
 /**
- * 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.
+ * The result of an in-process call — the integration facet's whole surface.
+ *
+ * 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.
+ *
+ * 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 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>;
-/**
- * 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;
-};
-/**
- * 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 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 = {
+declare class CallResult<Returned = unknown> extends BaseResult {
+  private readonly outcome;
+  constructor(options: CallResultOptions);
   /**
-   * How long every verb polls for a visible match before refusing.
-   * Default: `30_000` — enough for a cold app boot on a release bundle.
+   * What the call THREW, as text — the message of an `Error`, the value
+   * itself when something else was thrown, and empty when it returned.
+   *
+   * 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).
    */
-  action?: number | undefined;
+  get error(): TextAccessor;
   /**
-   * How long the FIRST session waits for WebDriverAgent to build and
-   * launch on the simulator. Default: `240_000`.
+   * 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, chosen on the value in hand and
+   * typed by {@link CallValue}, which answers for the three ways a type can
+   * relate to `string`.
+   *
+   * A call that threw has no value to choose an accessor on, so `value` is
+   * the JSON reading of `null` whatever the declared type promises: what a
+   * refusal produced is {@link CallResult.error}, and that is where a spec
+   * reads it.
    */
-  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>;
-};
+  get value(): CallValue<Returned>;
+}
 //#endregion
-//#region src/specification/ports/server.port.d.ts
+//#region src/model/ports/browser.port.d.ts
 /**
- * HTTP response returned by a server port, with parsed JSON body.
+ * 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 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>;
-};
+type LandmarkKind = 'banner' | 'complementary' | 'contentinfo' | 'form' | 'main' | 'navigation' | 'region' | 'search';
 /**
- * Abstract server interface for specification runners.
- * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
+ * 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 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/isolation.port.d.ts
+type ElementKind = 'button' | 'dialog' | 'field' | 'heading' | 'link' | 'listitem' | 'option' | 'row' | 'status' | 'table' | 'testId' | 'text';
 /**
- * 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.
+ * 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.
  *
- * Implement this interface to support new service types (e.g. MongoDB,
- * Elasticsearch, S3).
+ * A descriptor must designate exactly ONE element at action time; see
+ * {@link ElementMatch} and CONVENTIONS W3.
  */
-type IsolationStrategy = {
+type ElementRef = {
   /**
-   * Create an isolated namespace for this worker.
-   * Called once when the worker starts — e.g. clone a template database,
-   * set a Redis key prefix.
+   * Match the accessible name as a whole string rather than a substring.
    *
-   * @param workerId - Unique identifier for this vitest worker.
+   * 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.
    */
-  acquire: (workerId: string) => Promise<void>;
+  exact?: boolean;
   /**
-   * Fast reset within the namespace between `spec.run()` calls.
-   * E.g. truncate tables (without dropping the database).
+   * 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.
    */
-  reset: () => Promise<void>;
+  focused?: boolean;
   /**
-   * Tear down the isolated namespace.
-   * Called once when the worker shuts down — e.g. drop the cloned database.
+   * 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.
    */
-  release: () => Promise<void>;
-};
-//#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.
- */
-type ServiceHandle = {
-  /** Service type identifier. */
-  readonly type: string;
+  disabled?: boolean;
+  kind: ElementKind | LandmarkKind;
+  /** Landmarks may be anonymous (`main()`, `banner()`); everything else is named. */
+  name?: string;
   /**
-   * 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.
+   * 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.
    */
-  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>;
+  selected?: boolean;
   /**
-   * 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.
+   * 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.
    */
-  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;
+  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/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.
- */
-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
 /**
- * Read-only accessor for the whole temporary working directory used by a
- * command spec.
- *
- * Assertions go through `expect()` (async — they walk the disk):
- * `await expect(result.filesystem).toMatch('scaffolded')` compares the
- * tree against the fixture directory `_expected/<name>/`.
- */
-declare class FilesystemAccessor {
-  /** @internal Ref-capture scope shared by the current spec execution. */
-  readonly captures: CaptureScope;
-  /** The absolute path of the temporary working directory. */
-  readonly cwd: string;
-  /** @internal Test-file directory — fixture resolution root for matchers. */
-  readonly testDir: string;
-  constructor(cwd: string, testDir: string, captures?: CaptureScope);
-  /** List all files (recursively) under the working directory, sorted. */
-  files(options?: {
-    ignore?: string[];
-  }): Promise<string[]>;
-}
-//#endregion
-//#region src/specification/facets/_common/result/text.d.ts
-/**
- * Read-only accessor for a captured text handle — THE universal one: stdout,
- * stderr, container logs, and file text all surface as a `TextAccessor`.
- *
- * Backed by a primitive string, exposed via {@link text}, but also provides
- * `toString()` / `valueOf()` for string coercion, so common patterns like
- * `String(result.stdout)` and template-literal interpolation still work.
- *
- * ANSI escape sequences are stripped by default before every comparison
- * (CONVENTIONS D6) — `.text` stays raw. The runner `transform` option remains
- * an escape hatch for application noise not covered by the `{{token}}`
- * grammar.
- *
- * Text operations are **closed** over the type: `.grep(pattern)` returns a
- * `TextAccessor` (not a bare string), preserving the `_expected/`-resolution
- * context and the `transform`, so results are chainable
- * (`result.stdout.grep(a).grep(b)`) and snapshot-able
- * (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
- *
- * Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
- * and `expect(result.stdout).toMatch('name.txt')` (resolved against
- * `_expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
+ * 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.
  */
-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;
+type ElementMatch = {
   /**
-   * 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.
+   * 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.
    */
-  grep(pattern: string): TextAccessor;
-  toString(): string;
-  valueOf(): string;
-}
-//#endregion
-//#region src/specification/facets/cli/result.d.ts
+  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;
+};
 /**
- * Result from a command action (`.exec()`).
- *
- * When the runner was configured with a `docker` option, the result also
- * exposes container accessors and participates in `Symbol.asyncDispose`
- * cleanup. The Docker shell-outs are **lazy**: a test that never calls
- * `.container(...)` never queries the Docker daemon, so command-only tests
- * pay zero Docker cost even when the runner is Docker-aware.
- *
- * Dispose always runs one final label-filtered `docker ps` to catch
- * containers that were spawned during `.exec` but never asserted on —
- * tests still get leak-free cleanup even if they forget to reach into
- * a container.
+ * 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.
  */
-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;
+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>;
   /**
-   * 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.
+   * 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.
    */
-  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;
-}
+  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;
+};
+/**
+ * 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.
+ */
+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;
+};
+/**
+ * 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.
+ */
+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/cli/literate.d.ts
+//#region src/model/ports/device.port.d.ts
 /**
- * Running a `<case>.spec.yaml` document: one scenario, one working directory,
- * one set of servers, every run executed and asserted.
+ * 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.
+ */
+type MobileElementKind = 'button' | 'field' | 'testId' | 'text';
+/**
+ * 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.
  *
- * 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.
+ * 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.
  */
+type MobileElementRef = ElementRef;
 /**
- * A server a document may start by name (`serve: mcp`), registered once per app
- * in the `serve` option of `specification.cli()`.
+ * 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 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;
+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;
 };
-//#endregion
-//#region src/specification/facets/integration/result.d.ts
-/** What `.call()` produced: the value it returned, or the error it threw. */
-type CallOutcome = {
-  error: unknown;
-  threw: boolean;
-  value: unknown;
+/**
+ * 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>;
 };
-type CallResultOptions = BaseResultOptions & {
-  outcome: CallOutcome;
+/** 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.
+ */
+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;
 };
 /**
- * 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.
+ * 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 CallValue<Returned> = Returned extends string ? TextAccessor : JsonAccessor<Returned>;
+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;
+};
 /**
- * The result of an in-process call — the integration facet's whole surface.
- *
- * 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 — which is
- * the shape that used to make a refusal spec three times the size of the
- * happy one, and the shape that quietly passes when nothing throws at all.
- *
- * 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.
+ * 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.
  */
-declare class CallResult<Returned = unknown> extends BaseResult {
-  private readonly outcome;
-  constructor(options: CallResultOptions);
+type DeviceTimeouts = {
   /**
-   * What the call THREW, as text — the message of an `Error`, the value
-   * itself when something else was thrown, and empty when it returned.
-   *
-   * 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).
+   * How long every verb polls for a visible match before refusing.
+   * Default: `30_000` — enough for a cold app boot on a release bundle.
    */
-  get error(): TextAccessor;
+  action?: number | undefined;
   /**
-   * 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}.
+   * How long the FIRST session waits for WebDriverAgent to build and
+   * launch on the simulator. Default: `240_000`.
    */
-  get value(): CallValue<Returned>;
-}
+  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;
@@ -1115,7 +1120,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;
@@ -1174,32 +1179,113 @@ declare class PageResult extends BaseResult {
   /** The rendered DOM serialization as a text accessor. */
   get html(): TextAccessor;
   /**
-   * Every `application/ld+json` block of the page, parsed, as one JSON
-   * array — `expect(result.jsonLd).toMatch('article.jsonld.json')`.
+   * Every `application/ld+json` block of the page, parsed, as one JSON
+   * array — `expect(result.jsonLd).toMatch('article.jsonld.json')`.
+   */
+  get jsonLd(): JsonAccessor;
+  /** `<link>` elements of the head, in DOM order. */
+  get links(): BrowserLinkElement[];
+  /** The content of a named meta — `meta('description')`, `meta('og:image')`. */
+  meta(name: string): string | undefined;
+  /** HTTP status of the main document response. */
+  get status(): number;
+  /** Rendered body text as a text accessor. */
+  get content(): TextAccessor;
+  /**
+   * The ARIA snapshot of the rendered `<body>` — the page's outline, as the
+   * accessibility tree draws it, and the one golden a rendered surface pins.
+   * Deterministic where a screenshot is not, and the SAME dialect a component
+   * spec asserts, so a page and the components inside it read alike.
+   */
+  get tree(): TextAccessor;
+  /** The document title as a text accessor. */
+  get title(): TextAccessor;
+  /** Final URL after redirects. */
+  get url(): string;
+}
+//#endregion
+//#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.
    */
-  get jsonLd(): JsonAccessor;
-  /** `<link>` elements of the head, in DOM order. */
-  get links(): BrowserLinkElement[];
-  /** The content of a named meta — `meta('description')`, `meta('og:image')`. */
-  meta(name: string): string | undefined;
-  /** HTTP status of the main document response. */
-  get status(): number;
-  /** Rendered body text as a text accessor. */
-  get content(): TextAccessor;
+  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>;
   /**
-   * The ARIA snapshot of the rendered `<body>` — the page's outline, as the
-   * accessibility tree draws it, and the one golden a rendered surface pins.
-   * Deterministic where a screenshot is not, and the SAME dialect a component
-   * spec asserts, so a page and the components inside it read alike.
+   * 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.
    */
-  get tree(): TextAccessor;
-  /** The document title as a text accessor. */
-  get title(): TextAccessor;
-  /** Final URL after redirects. */
-  get url(): string;
-}
+  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/specification/facets/_common/stub-backend.d.ts
+//#region src/model/chain/stub-backend.d.ts
 /** Options for the stub backend server. */
 type StubBackendOptions = {
   /**
@@ -1241,7 +1327,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;
@@ -1321,17 +1407,6 @@ type SpecificationConfig = {
    * (`env: frozen`). Declared once per app in `specification.cli()`.
    */
   envSets?: Record<string, CliEnv> | undefined;
-  /**
-   * When set, `.clock()` is unavailable on this runner and throws this
-   * reason immediately (compose mode — the calendar it would pin is this
-   * process's, and the app runs in a container).
-   */
-  clockDisabledReason?: string | 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;
@@ -1391,8 +1466,18 @@ 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>;
@@ -1403,7 +1488,7 @@ 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
@@ -1515,92 +1600,66 @@ type MobileSpecification = {
   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
+//#region src/facets/cli/cli.result.d.ts
 /**
- * Read-only accessor for a database table after a specification run.
- *
- * Assertions go through `expect()` (async — they query the database):
+ * Result from a command action (`.exec()`).
  *
- *     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;
-};
-/**
- * Base result - common accessors available after any action type.
- * Extended by HttpResult, CliResult, and used directly by job results.
+ * 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.
  *
- * Every result carries a fresh {@link CaptureScope}: `match.ref()` captures
- * and `{{type#ref}}` placeholders are scoped to one spec execution.
+ * 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
@@ -1653,31 +1712,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.
@@ -1701,7 +1736,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. */
@@ -1725,7 +1760,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.
  *
@@ -1740,7 +1775,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.
@@ -1770,7 +1805,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.
  *
@@ -1824,26 +1859,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;
 };
@@ -1958,7 +1996,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 })`, …).
@@ -1976,7 +2014,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;
@@ -2008,7 +2046,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.
@@ -2111,7 +2149,7 @@ declare const http: {
   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;
@@ -2169,7 +2207,7 @@ declare const openai: {
   timeout(): ContractResponse;
 };
 //#endregion
-//#region src/vitest/mock-of.d.ts
+//#region src/model/doubles/mock-of.d.ts
 /** How much of the port the double answers for. */
 type MockOfOptions = {
   /**
@@ -2183,7 +2221,7 @@ type MockOfOptions = {
 };
 /**
  * A typed double for an injected port — the fourth rung of the doubles ladder
- * (docs/12-conventions.md), and the only one a module test may build itself.
+ * (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
@@ -2200,21 +2238,7 @@ declare function mockOf<T extends object>(options?: MockOfOptions): DeepMockProx
 /** The factory's own shape — kept as a name so a consumer can annotate with it. */
 type MockPort = typeof mockOf;
 //#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;
-};
-/**
- * Freeze or reset the global Date for deterministic time-dependent tests.
- * Wraps the `mockdate` package.
- */
-declare const mockOfDate: MockDatePort;
-//#endregion
-//#region src/vitest/clock.d.ts
+//#region src/model/clock/clock.d.ts
 /**
  * The one time primitive.
  *
@@ -2269,7 +2293,7 @@ declare const clock: {
   run(iso?: string): PinnedClock;
 };
 //#endregion
-//#region src/specification/assertions/required.d.ts
+//#region src/model/assertions/required.d.ts
 /**
  * The value, or a failure that says what was missing and why it mattered.
  *
@@ -2286,7 +2310,7 @@ declare const clock: {
  */
 declare function required<T>(value: null | T | undefined, why: string): T;
 //#endregion
-//#region src/specification/assertions/wait-until.d.ts
+//#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. */
@@ -2325,7 +2349,7 @@ declare function waitUntil(predicate: () => boolean | Promise<boolean>, options?
 //#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).
@@ -2349,9 +2373,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 —
@@ -2364,17 +2388,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
@@ -2384,68 +2430,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,
@@ -2455,41 +2473,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;
 };
@@ -2508,12 +2514,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> = {
   /**
@@ -2549,9 +2553,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;
   /**
@@ -2589,7 +2593,7 @@ 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/integration/start-integration.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()`. */
@@ -2619,19 +2623,20 @@ type IntegrationHandle<Services extends ServiceRecord = ServiceRecord, DatabaseK
  *
  * 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 — and it used to be neither: a `specs/` folder
- * with plain vitest, a hand-built sqlite template, a `beforeAll` that started
- * a container, and a `toMatchSnapshot` where the package has a golden engine.
+ * 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/specification/facets/jobs/start-jobs.d.ts
+//#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()`. */
@@ -2654,7 +2659,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
@@ -2735,11 +2740,11 @@ type MobileHandle = {
 };
 declare function startMobile<Services extends ServiceRecord>(options: MobileSpecificationOptions<Services>): Promise<MobileHandle>;
 //#endregion
-//#region src/specification/facets/website/serve.adapter.d.ts
+//#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 11) and accepted wherever a facet starts something outside this
+ * (chapter 17) and accepted wherever a facet starts something outside this
  * process: `website({ server })`, `services: { api: process(…) }`, and the
  * literate `serve:` registry.
  */
@@ -2779,26 +2784,16 @@ type ProcessOptions = {
   /** Readiness budget in milliseconds. Default 30 000. */
   timeout?: number;
 };
-/**
- * What `ProcessOptions` was called in 15.2, when the only process the
- * framework owned was a website's server.
- *
- * @deprecated Renamed to {@link ProcessOptions} in 15.3 — the shape is the
- * one external process every facet starts, not a website's alone. The alias
- * is removed in 16.0.
- */
-type ServeOptions = ProcessOptions;
 //#endregion
-//#region src/specification/facets/_common/process.d.ts
+//#region src/model/chain/process.d.ts
 /**
  * An external process, declared like any other service.
  *
- * Before this there were three shapes for the same thing: `website({ server })`
- * took a `ServeOptions`, a literate document took a `serve:` entry, and a
- * project that needed a second process — an API behind the site, Metro behind
- * the simulator — started one by hand in a `beforeAll` and killed it in an
- * `afterAll` it sometimes forgot. `process()` is the one shape, and the
- * framework owns the lifetime.
+ * 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
@@ -2810,7 +2805,7 @@ declare class ProcessHandle implements ServiceHandle {
   readonly defaultPort = 0;
   readonly environment: Record<string, string>;
   readonly type = "process";
-  composeName: null | string;
+  serviceName: null | string;
   connectionString: string;
   started: boolean;
   private adapter;
@@ -2866,7 +2861,7 @@ declare class ProcessHandle implements ServiceHandle {
  */
 declare function processService(options: ProcessOptions): ProcessHandle;
 //#endregion
-//#region src/specification/facets/website/start-website.d.ts
+//#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;
 /**
@@ -2909,6 +2904,14 @@ type WebsiteSpecificationOptions<Services extends ServiceRecord = ServiceRecord>
    * API it was started beside.
    */
   services?: Services;
+  /**
+   * Escape hatch: normaliser applied to every compared reading of a result
+   * — the head projection and the json-ld among them — before the
+   * comparison (CONVENTIONS D6). Does NOT mutate the raw `.text` accessor.
+   * Prefer `{{token}}` placeholders in fixtures; this is for what a token
+   * cannot name, a meta a FRAMEWORK owns and the page never asked for.
+   */
+  transform?: ((text: string) => string) | undefined;
 } & ({
   /**
    * Declared stub backend: started BEFORE the server command, its
@@ -2944,7 +2947,7 @@ type 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 six specification constructors (CONVENTIONS A2) — created in a
  * `*.specification.ts` file under `specs/`, destructured with canonical
@@ -2980,11 +2983,11 @@ type Specification = {
 };
 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.
@@ -3064,15 +3067,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.
@@ -3098,7 +3093,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.)
@@ -3118,13 +3113,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. */
@@ -3132,7 +3122,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>;
@@ -3145,7 +3135,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>;
@@ -3156,28 +3146,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>;
@@ -3196,13 +3181,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.
@@ -3219,7 +3204,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>;
@@ -3249,7 +3234,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.
    *
@@ -3285,8 +3270,8 @@ declare function sqlite(options?: SqliteOptions): SqliteHandle;
 //#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 10).
+ * chain to hang contracts on reaches for (chapter 16).
  */
 declare const intercept: Intercept;
 //#endregion
-export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, CallResult, 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 HttpStreamInit, type IntegrationHandle, type IntegrationSpecification, type IntegrationSpecificationOptions, type Intercept, type InterceptScope, 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 MockOfOptions, type MockPort, Orchestrator, PageResult, type PinnedClock, type PostgresOptions, ProcessHandle, type ProcessOptions, type RedisOptions, type RenderResult, type RenderSubject, type RenderedText, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, 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 SpecificationMode, type SqliteOptions, type SseEvent, type StreamBody, TableAccessor, 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, findContainersByLabel, focused, form, heading, http, inspectContainer, intercept, link, listitem, main, match, mockOf, mockOfDate, navigation, openai, option, postgres, processService as process, redis, region, removeContainers, required, row, search, selected, specification, sqlite, status, table, testId, text, valued, waitUntil, within };
+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 };