@jterrazz/test 15.0.0 → 15.1.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Scalar } from "yaml";
 import { DeepMockProxy } from "vitest-mock-extended";
-//#region src/core/matching/match.d.ts
+//#region src/specification/matching/match.d.ts
 /**
  * Code-side dynamic-value matchers (`match.*`) and the capture scope shared
  * by every assertion of a single spec execution.
@@ -12,30 +12,36 @@ import { DeepMockProxy } from "vitest-mock-extended";
  */
 /** The frozen token vocabulary (CONVENTIONS D4) plus the code-only kinds. */
 type MatcherKind = 'any' | 'base64' | 'date' | 'duration' | 'email' | 'float' | 'hex' | 'includes' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
+/** Every kind usable as a `{{token}}` in fixture files (all but ref/regex/includes). */
+declare const TOKEN_KINDS: readonly ["any", "base64", "date", "duration", "email", "float", "hex", "int", "ip", "iso8601", "number", "path", "port", "semver", "sha", "string", "time", "ulid", "url", "uuid", "workdir"];
+/** A token kind valid inside a fixture `{{...}}` placeholder. */
+type TokenKind = (typeof TOKEN_KINDS)[number];
 /**
  * A dynamic-value matcher. Created via the {@link match} factories — never
  * constructed directly by user code.
  */
 declare class Matcher {
   /** For kind 'includes': the substring the actual value must contain. */
-  readonly includes?: string;
+  readonly includes?: string | undefined;
   readonly kind: MatcherKind;
   /** For kind 'ref': the capture to assert inequality against. */
-  readonly notRef?: string;
+  readonly notRef?: string | undefined;
   /** For kind 'ref': the capture name. */
-  readonly refName?: string;
+  readonly refName?: string | undefined;
   /** For kind 'regex': the pattern the actual value must match. */
-  readonly regex?: RegExp;
+  readonly regex?: RegExp | undefined;
   constructor(kind: MatcherKind, options?: {
-    includes?: string;
-    notRef?: string;
-    refName?: string;
-    regex?: RegExp;
+    includes?: string | undefined;
+    notRef?: string | undefined;
+    refName?: string | undefined;
+    regex?: RegExp | undefined;
   });
   /** Placeholder-style rendering used in failure diffs and serialization. */
   toString(): string;
   toJSON(): string;
 }
+/** A no-argument matcher factory — what every typed entry of `match` is. */
+type TypedMatcher = () => Matcher;
 /**
  * Dynamic-value matchers for structural comparisons — the code-side mirror of
  * the `{{token}}` fixture grammar (CONVENTIONS D4).
@@ -46,72 +52,18 @@ declare class Matcher {
  *       rows: [[match.uuid(), 'Alice']],
  *   });
  */
-declare const match: {
-  /** Matches anything. */
-  any: () => Matcher;
-  /** Matches a base64 string. */
-  base64: () => Matcher;
-  /** Matches a calendar date (`YYYY-MM-DD`). */
-  date: () => Matcher;
-  /** Matches a human duration (`12ms`, `1.5s`, `2m`, `3h`). */
-  duration: () => Matcher;
-  /** Matches an email address. */
-  email: () => Matcher;
-  /**
-   * Matches a float. In JSON contexts any finite number passes (JSON does
-   * not distinguish `42` from `42.0`); in text contexts the decimal part
-   * is required (`4.2`, never `42`).
-   */
-  float: () => Matcher;
-  /** Matches a hexadecimal string. */
-  hex: () => Matcher;
-  /**
-   * Matches a string CONTAINING the given substring. Code-only, like
-   * {@link match.regex} — the `{{token}}` fixture vocabulary does not grow.
-   * The explicit escape hatch now that contract string filters
-   * (`openai.chat({ user })`) mean exact equality.
-   */
+/**
+ * The matcher roster: one no-argument factory per token kind, plus the three
+ * code-only forms the `{{token}}` grammar does not carry.
+ */
+type MatchFactories = Record<TokenKind, TypedMatcher> & {
   includes: (substring: string) => Matcher;
-  /** Matches an integer (or an integer string in text contexts). */
-  int: () => Matcher;
-  /** Matches an IPv4 address. */
-  ip: () => Matcher;
-  /** Matches an ISO-8601 timestamp string. */
-  iso8601: () => Matcher;
-  /** Matches a number (or a numeric string in text contexts). */
-  number: () => Matcher;
-  /** Matches a filesystem path (`/...` or `./...`). */
-  path: () => Matcher;
-  /** Matches a TCP/UDP port number (0-65535). */
-  port: () => Matcher;
-  /**
-   * Capture-and-compare. The first occurrence of `ref(name)` captures the
-   * actual value; every later occurrence must strictly equal the capture.
-   * `{ not: other }` additionally asserts inequality with the capture named
-   * `other`. Scope: the current spec execution (reset per chain).
-   */
   ref: (name: string, options?: {
     not?: string;
   }) => Matcher;
-  /** Matches a string against the given regular expression. */
   regex: (regex: RegExp) => Matcher;
-  /** Matches a semantic version (`1.2.3`, `2.0.0-rc.1`). */
-  semver: () => Matcher;
-  /** Matches a git SHA (7-64 hex chars). */
-  sha: () => Matcher;
-  /** Matches any string. */
-  string: () => Matcher;
-  /** Matches a wall-clock time (`HH:MM` or `HH:MM:SS`). */
-  time: () => Matcher;
-  /** Matches a ULID. */
-  ulid: () => Matcher;
-  /** Matches an http(s) URL. */
-  url: () => Matcher;
-  /** Matches a UUID string. */
-  uuid: () => Matcher;
-  /** Matches the exact working directory of the current spec. */
-  workdir: () => Matcher;
 };
+declare const match: MatchFactories;
 /**
  * Named captures recorded by `match.ref()` / `{{type#ref}}` placeholders.
  * One scope lives on each spec result — every assertion chained off the same
@@ -123,59 +75,14 @@ declare class CaptureScope {
    * The exact working directory of the current spec, when the framework
    * knows it (cli mode). Drives the `{{workdir}}` token / `match.workdir()`.
    */
-  workdir?: string;
+  workdir?: string | undefined;
   constructor(workdir?: string);
   get(name: string): unknown;
   has(name: string): boolean;
   set(name: string, value: unknown): void;
 }
 //#endregion
-//#region src/core/specification/shared/result/directory.d.ts
-/**
- * Read-only accessor for a directory produced by a spec action.
- *
- * Assertions go through `expect()` (async — they walk the disk):
- * `await expect(result.directory('out')).toMatch('scaffold/out')`
- * compares the tree against the fixture directory `_expected/<name>/`.
- */
-declare class DirectoryAccessor {
-  /** @internal Ref-capture scope shared by the current spec execution. */
-  readonly captures: CaptureScope;
-  /** @internal Absolute path of the directory under assertion. */
-  readonly root: string;
-  /** @internal Test-file directory — fixture resolution root for matchers. */
-  readonly testDir: string;
-  constructor(absPath: string, testDir: string, captures?: CaptureScope);
-  /** List all files (recursively) under the directory, sorted. */
-  files(options?: {
-    ignore?: string[];
-  }): Promise<string[]>;
-}
-//#endregion
-//#region src/core/specification/shared/result/filesystem.d.ts
-/**
- * Read-only accessor for the whole temporary working directory used by a
- * command spec.
- *
- * Assertions go through `expect()` (async — they walk the disk):
- * `await expect(result.filesystem).toMatch('scaffolded')` compares the
- * tree against the fixture directory `_expected/<name>/`.
- */
-declare class FilesystemAccessor {
-  /** @internal Ref-capture scope shared by the current spec execution. */
-  readonly captures: CaptureScope;
-  /** The absolute path of the temporary working directory. */
-  readonly cwd: string;
-  /** @internal Test-file directory — fixture resolution root for matchers. */
-  readonly testDir: string;
-  constructor(cwd: string, testDir: string, captures?: CaptureScope);
-  /** List all files (recursively) under the working directory, sorted. */
-  files(options?: {
-    ignore?: string[];
-  }): Promise<string[]>;
-}
-//#endregion
-//#region src/core/specification/shared/result/json.d.ts
+//#region src/specification/facets/_common/result/json.d.ts
 /**
  * Read-only accessor for a JSON payload parsed from a text stream (stdout).
  *
@@ -205,218 +112,14 @@ declare class JsonAccessor {
   get value(): unknown;
 }
 //#endregion
-//#region src/core/ports/server.port.d.ts
-/**
- * HTTP response returned by a server port, with parsed JSON body.
- */
-interface ServerResponse {
-  /** HTTP status code. */
-  status: number;
-  /** Parsed JSON response body, or null if parsing failed. */
-  body: unknown;
-  /** Response headers as a flat key-value map. */
-  headers: Record<string, string>;
-}
-/**
- * Abstract server interface for specification runners.
- * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
- */
-interface ServerPort {
-  /** Send an HTTP request and return the parsed response. */
-  request: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<ServerResponse>;
-}
-//#endregion
-//#region src/core/specification/shared/result/response.d.ts
-/**
- * Read-only accessor for an HTTP response.
- *
- * Assertions go through `expect()`:
- * `expect(result.response).toMatch('created.http')` compares status,
- * a subset of headers, and the JSON body against `_expected/<name>` —
- * with `{{placeholder}}` support in all three.
- */
-declare class ResponseAccessor {
-  /** The parsed JSON response body (null when parsing failed). */
-  readonly body: unknown;
-  /** @internal Ref-capture scope shared by the current spec execution. */
-  readonly captures: CaptureScope;
-  /** Response headers as a flat, lower-cased key-value map. */
-  readonly headers: Record<string, string>;
-  /** The HTTP response status code. */
-  readonly status: number;
-  /** @internal Test-file directory — fixture resolution root for matchers. */
-  readonly testDir: string;
-  constructor(response: ServerResponse, testDir: string, captures?: CaptureScope);
-}
-//#endregion
-//#region src/core/ports/database.port.d.ts
-/**
- * Abstract database interface for specification runners.
- * Implement this to plug in your database stack (e.g. Postgres, SQLite).
- */
-interface DatabasePort {
-  /** Execute raw SQL (for seeding test data). */
-  seed: (sql: string) => Promise<void>;
-  /** Query a table and return rows as arrays of values. */
-  query: (table: string, columns: string[]) => Promise<unknown[][]>;
-  /** Reset database to clean state between tests. */
-  reset: () => Promise<void>;
-}
-//#endregion
-//#region src/core/specification/shared/result/table.d.ts
-/**
- * Read-only accessor for a database table after a specification run.
- *
- * Assertions go through `expect()` (async — they query the database):
- *
- *     await expect(result.table('users', { database: 'db' })).toMatchRows({
- *         columns: ['name'],
- *         rows: [['Alice']],
- *     });
- *     await expect(result.table('users', { database: 'db' })).toBeEmpty();
- */
-declare class TableAccessor {
-  /** @internal Ref-capture scope shared by the current spec execution. */
-  readonly captures: CaptureScope;
-  /** @internal */
-  private readonly db;
-  /** The table name this accessor reads. */
-  readonly name: string;
-  constructor(name: string, db: DatabasePort, captures?: CaptureScope);
-  /** @internal Query the table — used by the toMatchRows / toBeEmpty matchers. */
-  query(columns: string[]): Promise<unknown[][]>;
-}
-//#endregion
-//#region src/core/specification/shared/result/text.d.ts
-/**
- * Read-only accessor for a captured text handle — THE universal one: stdout,
- * stderr, container logs, and file text all surface as a `TextAccessor`.
- *
- * Backed by a primitive string, exposed via {@link text}, but also provides
- * `toString()` / `valueOf()` for string coercion, so common patterns like
- * `String(result.stdout)` and template-literal interpolation still work.
- *
- * ANSI escape sequences are stripped by default before every comparison
- * (CONVENTIONS D6) — `.text` stays raw. The runner `transform` option remains
- * an escape hatch for application noise not covered by the `{{token}}`
- * grammar.
- *
- * Text operations are **closed** over the type: `.grep(pattern)` returns a
- * `TextAccessor` (not a bare string), preserving the `_expected/`-resolution
- * context and the `transform`, so results are chainable
- * (`result.stdout.grep(a).grep(b)`) and snapshot-able
- * (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
- *
- * Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
- * and `expect(result.stdout).toMatch('name.txt')` (resolved against
- * `_expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
- */
-declare class TextAccessor {
-  /** @internal Ref-capture scope shared by the current spec execution. */
-  readonly captures: CaptureScope;
-  /** @internal Stream label used in failure messages ("stdout" / "stderr"). */
-  readonly streamName: string;
-  /** @internal Test-file directory — fixture resolution root for matchers. */
-  readonly testDir: string;
-  /** The raw captured text (never transformed, ANSI preserved). */
-  readonly text: string;
-  /** @internal Normaliser applied before comparisons, never to fixtures. */
-  readonly transform?: (text: string) => string;
-  constructor(value: string, streamName: string, testDir: string, options?: {
-    captures?: CaptureScope;
-    transform?: (text: string) => string;
-  });
-  /** @internal The text as compared by matchers — ANSI stripped, transform applied. */
-  get comparableText(): string;
-  /**
-   * 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;
-}
-/**
- * Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
- * test's directory — the same caller-detection the builders use.
- *
- * The product surface of a test framework is its own error messages, checker
- * output, and reports; those deserve the same goldening as any other output.
- * `text()` makes an ad-hoc string a first-class snapshot subject:
- *
- * ```typescript
- * const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
- * expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to _expected/
- * ```
- *
- * ANSI is stripped before every comparison (the raw form stays on `.text`),
- * the `{{token}}` grammar applies to the fixture, and `.grep()` composition
- * works exactly as on any stream accessor.
- */
-declare function text(value: string): TextAccessor;
-//#endregion
-//#region src/core/ports/cli.port.d.ts
-/**
- * Raw output from a command execution, including exit code and captured output streams.
- */
-interface CliOutput {
-  /** Process exit code (0 = success). */
-  exitCode: number;
-  /** Captured standard output. */
-  stdout: string;
-  /** Captured standard error. */
-  stderr: string;
-}
-/**
- * Options for the long-running form of `.exec()` (CONVENTIONS B2). When
- * either option is present the process is spawned and observed: it resolves
- * as soon as `waitFor` appears in stdout/stderr, and is killed when `timeout`
- * elapses (exit code 124).
- */
-interface ExecOptions {
-  /** Resolve (exit code 0) when stdout/stderr contains this string. */
-  waitFor?: string;
-  /** Kill the process after this many milliseconds. Defaults to 10 000. */
-  timeout?: number;
-}
-/**
- * Extra environment variables to set for the child process.
- * Values are merged on top of process.env. A `null` value unsets the variable.
- */
-type CliEnv = Record<string, null | string>;
-/**
- * Abstract command interface for specification runners.
- * Implement this to plug in your command execution strategy.
- */
-/**
- * What one invocation is handed beyond its arguments — the two per-run inputs a
- * spec document may state. Both are absent by default: the child gets an
- * immediately-closed stdin (never a TTY) and the adapter's own timeout.
- */
-interface CliInput {
-  /** Written to the child's stdin, which is then closed. */
-  stdin?: string;
-  /** Milliseconds after which the run is killed (exit code 124). */
-  timeout?: number;
-}
-interface CliPort {
-  /** Execute a command with the given arguments in the given working directory. */
-  exec: (args: string, cwd: string, env?: CliEnv, input?: CliInput) => Promise<CliOutput>;
-  /** Run a long-running process and wait for a pattern or timeout. */
-  watch: (args: string, cwd: string, options: ExecOptions, env?: CliEnv) => Promise<CliOutput>;
-}
-//#endregion
-//#region src/core/contracts/types.d.ts
+//#region src/specification/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
  * website/mobile) and handed to {@link ContractRequest.match} and to a
  * {@link ContractResponder}.
  */
-interface MatchableRequest {
+type MatchableRequest = {
   /** Parsed JSON body when the payload is JSON, the raw text otherwise, or `null` when absent. */
   body: unknown;
   /** Request headers, keyed by lowercased header name. */
@@ -425,7 +128,7 @@ interface MatchableRequest {
   method: string;
   /** The request URL — fully-qualified, or origin-relative for the stub backend. */
   url: string;
-}
+};
 /**
  * The request half of a contract: which outgoing call it speaks for.
  *
@@ -434,7 +137,7 @@ interface MatchableRequest {
  * website/mobile app's own backend calls take. `{{token}}` segments compare
  * structurally, declared query params are a subset of the observed ones.
  */
-interface ContractRequest {
+type ContractRequest = {
   /** Adapter name — `http` | `openai` | `anthropic`. */
   adapter: string;
   /** HTTP method to match. `*` matches any method. */
@@ -442,23 +145,23 @@ interface ContractRequest {
   /** Absolute URL (string | RegExp) or an any-origin path form (`/articles/{{uuid}}`). */
   url: RegExp | string;
   /** Optional request matcher — the contract only fires if this returns true. */
-  match?: (request: MatchableRequest) => boolean;
+  match?: ((request: MatchableRequest) => boolean) | undefined;
   /** Transform raw data into a provider-specific response envelope. */
   wrap: (data: unknown) => ContractResponse;
-}
+};
 /**
  * The response half of a contract: what to reply when the request matches.
  */
-interface ContractResponse {
+type ContractResponse = {
   /** HTTP status code (default: 200). */
   status?: number;
   /** Response body — an object is JSON, a string is text, `null`/`undefined` is empty. */
   body: unknown;
   /** Response headers. */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | undefined;
   /** Delay in ms before responding (for timeout testing). */
-  delay?: number;
-}
+  delay?: number | undefined;
+};
 /**
  * A dynamic response: computed from the observed request at the moment the
  * contract is served, rather than fixed ahead of time. Handed the same
@@ -472,7 +175,7 @@ type ContractResponder = (request: MatchableRequest) => ContractResponse;
  */
 type ContractResponseValue = ContractResponder | ContractResponse;
 //#endregion
-//#region src/core/contracts/contract.d.ts
+//#region src/specification/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
@@ -480,7 +183,7 @@ type ContractResponseValue = ContractResponder | ContractResponse;
  * payload (prompts, JSON responses) is visible at a glance while the real HTTP
  * call stays mocked underneath.
  */
-interface Contract {
+type Contract = {
   /** Which outgoing call this contract speaks for. */
   request: ContractRequest;
   /**
@@ -501,12 +204,12 @@ interface Contract {
    * silently-unused declaration into a spec failure.
    */
   required?: boolean;
-}
+};
 /**
  * A composite of contracts — the unit tests import. Flat, ordered, immutable;
  * `.with()` derives a variant without touching the original.
  */
-interface Contracts {
+type Contracts = {
   /** The flattened contracts, in selection order. */
   readonly contracts: readonly Contract[];
   /**
@@ -516,7 +219,7 @@ interface Contracts {
    * route it does not replace.
    */
   with: (...overrides: (Contract | Contract[] | Contracts)[]) => Contracts;
-}
+};
 /** Any accepted contract input: one, a list, or a composite. */
 type ContractInput = Contract | Contract[] | Contracts;
 /**
@@ -557,7 +260,7 @@ declare function defineContract(contract: Contract): Contract;
  */
 declare function defineContracts(...items: ContractInput[]): Contracts;
 //#endregion
-//#region src/core/ports/browser.port.d.ts
+//#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,
@@ -575,7 +278,7 @@ type ElementKind = 'button' | 'field' | 'heading' | 'link' | 'testId' | 'text';
  * A descriptor must designate exactly ONE element at action time; see
  * {@link ElementMatch} and CONVENTIONS W3.
  */
-interface ElementRef {
+type ElementRef = {
   /**
    * Match the accessible name as a whole string rather than a substring.
    * Default (`false`) mirrors playwright: `link('Articles')` also matches
@@ -590,47 +293,47 @@ interface ElementRef {
    * `within(scope, target)`. Chains: a scope may itself carry a scope.
    */
   scope?: ElementRef;
-}
+};
 /**
  * One candidate captured when a descriptor matched more than one element —
  * the evidence the ambiguity error enumerates so the author can disambiguate
  * without opening a browser.
  */
-interface ElementMatch {
+type ElementMatch = {
   /** Nearest landmark ancestor (`nav`, `footer`, `main`…), when there is one. */
-  context?: string;
+  context?: string | undefined;
   /** The attribute that disambiguates most — `href` for links, `name` for fields. */
-  detail?: string;
+  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. */
-interface BrowserLinkElement {
+type BrowserLinkElement = {
   href: string;
-  hreflang?: string;
+  hreflang?: string | undefined;
   rel: string;
-  type?: string;
-}
+  type?: string | undefined;
+};
 /** A `<meta>` element captured from the rendered document's head. */
-interface BrowserMetaElement {
+type BrowserMetaElement = {
   content: string;
-  name?: string;
-  property?: string;
-}
+  name?: string | undefined;
+  property?: string | undefined;
+};
 /** A console message emitted while the page loaded or the scenario ran. */
-interface BrowserConsoleMessage {
+type BrowserConsoleMessage = {
   text: string;
   type: string;
-}
+};
 /**
  * The visitor — the interaction vocabulary handed to a visit scenario.
  * Every action auto-waits (playwright actionability); `see()` is the single
  * synchronization primitive: it retries until the element is visible and
  * fails at the timeout. There is no sleep and no conditional helper.
  */
-interface Visitor {
+type Visitor = {
   /** Check a checkbox or radio. */
   check: (element: ElementRef) => Promise<void>;
   /** Click the element. */
@@ -647,16 +350,16 @@ interface Visitor {
   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. */
-interface BrowserOpenOptions {
+type BrowserOpenOptions = {
   /**
    * Extra origins the `external: 'block'` policy lets through — the
    * declared stub backend the page legitimately fetches from.
    */
-  allowedOrigins?: string[];
+  allowedOrigins?: string[] | undefined;
   /**
    * Base URL of the site under test — the origin `goto()` resolves against
    * and the boundary of the `external` policy.
@@ -669,16 +372,16 @@ interface BrowserOpenOptions {
    */
   external: 'allow' | 'block';
   /** Extra HTTP headers sent with every request of the visit (incl. User-Agent overrides). */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | undefined;
   /** The interaction scenario to run after load; the capture reflects the final state. */
-  scenario?: VisitScenario;
-}
+  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 core.
  */
-interface BrowserPage {
+type BrowserPage = {
   /** Console messages emitted while loading and interacting, in order. */
   consoleMessages: BrowserConsoleMessage[];
   /** Serialized DOM after rendering (`document.documentElement.outerHTML`). */
@@ -697,20 +400,85 @@ interface BrowserPage {
   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.
  */
-interface BrowserPort {
+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/core/ports/device.port.d.ts
+//#region src/specification/ports/cli.port.d.ts
+/**
+ * Raw output from a command execution, including exit code and captured output streams.
+ */
+type CliOutput = {
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /** Captured standard output. */
+  stdout: string;
+  /** Captured standard error. */
+  stderr: string;
+};
+/**
+ * Options for the long-running form of `.exec()` (CONVENTIONS B2). When
+ * either option is present the process is spawned and observed: it resolves
+ * as soon as `waitFor` appears in stdout/stderr, and is killed when `timeout`
+ * elapses (exit code 124).
+ */
+type ExecOptions = {
+  /** Resolve (exit code 0) when stdout/stderr contains this string. */
+  waitFor?: string | undefined;
+  /** Kill the process after this many milliseconds. Defaults to 10 000. */
+  timeout?: number | undefined;
+};
+/**
+ * Extra environment variables to set for the child process.
+ * Values are merged on top of process.env. A `null` value unsets the variable.
+ */
+type CliEnv = Record<string, null | string>;
+/**
+ * Abstract command interface for specification runners.
+ * Implement this to plug in your command execution strategy.
+ */
+/**
+ * What one invocation is handed beyond its arguments — the two per-run inputs a
+ * spec document may state. Both are absent by default: the child gets an
+ * immediately-closed stdin (never a TTY) and the adapter's own timeout.
+ */
+type CliInput = {
+  /** Written to the child's stdin, which is then closed. */
+  stdin?: string | undefined;
+  /** Milliseconds after which the run is killed (exit code 124). */
+  timeout?: number | undefined;
+};
+type CliPort = {
+  /** Execute a command with the given arguments in the given working directory. */
+  exec: (args: string, cwd: string, env?: CliEnv, input?: CliInput) => Promise<CliOutput>;
+  /** Run a long-running process and wait for a pattern or timeout. */
+  watch: (args: string, cwd: string, options: ExecOptions, env?: CliEnv) => Promise<CliOutput>;
+};
+//#endregion
+//#region src/specification/ports/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/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.
@@ -738,7 +506,7 @@ type MobileElementRef = ElementRef;
  * the evidence the ambiguity error enumerates so the author can disambiguate
  * without opening the simulator.
  */
-interface MobileElementMatch {
+type MobileElementMatch = {
   /** The accessibility identifier (`testId()` target), when one is set. */
   identifier?: string;
   /** The accessible label, whitespace-collapsed and truncated. */
@@ -747,7 +515,7 @@ interface MobileElementMatch {
   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
@@ -755,14 +523,14 @@ interface MobileElementMatch {
  * synchronization primitive — is satisfied by any visible match. There is
  * no sleep and no conditional helper.
  */
-interface MobileVisitor {
+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>;
 /**
@@ -771,7 +539,7 @@ type MobileScenario = (visitor: MobileVisitor) => Promise<void>;
  * nodes are dropped and their children hoisted, so the projection stays
  * stable and golden-friendly. Type names lose the `XCUIElementType` prefix.
  */
-interface ScreenNode {
+type ScreenNode = {
   children?: ScreenNode[];
   /** The accessibility identifier, only when it differs from the label. */
   identifier?: string;
@@ -779,57 +547,78 @@ interface ScreenNode {
   /** 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.
  */
-interface DeviceScreen {
+type DeviceScreen = {
   texts: string[];
   tree: ScreenNode;
-}
+};
 /** Per-open options forwarded to the device session. */
-interface DeviceOpenOptions {
+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;
+  deepLink?: string | undefined;
   /** The interaction scenario to run after launch; the capture reflects the final state. */
-  scenario?: MobileScenario;
-}
+  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.
  */
-interface DeviceTimeouts {
+type DeviceTimeouts = {
   /**
    * How long every verb polls for a visible match before refusing.
    * Default: `30_000` — enough for a cold app boot on a release bundle.
    */
-  action?: number;
+  action?: number | undefined;
   /**
    * How long the FIRST session waits for WebDriverAgent to build and
    * launch on the simulator. Default: `240_000`.
    */
-  launch?: number;
-}
+  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.
  */
-interface DevicePort {
+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/ports/server.port.d.ts
+/**
+ * HTTP response returned by a server port, with parsed JSON body.
+ */
+type ServerResponse = {
+  /** HTTP status code. */
+  status: number;
+  /** Parsed JSON response body, or null if parsing failed. */
+  body: unknown;
+  /** Response headers as a flat key-value map. */
+  headers: Record<string, string>;
+};
+/**
+ * Abstract server interface for specification runners.
+ * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
+ */
+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/core/ports/isolation.port.d.ts
+//#region src/specification/ports/isolation.port.d.ts
 /**
  * Strategy for isolating service state across parallel test workers.
  *
@@ -840,7 +629,7 @@ interface DevicePort {
  * Implement this interface to support new service types (e.g. MongoDB,
  * Elasticsearch, S3).
  */
-interface IsolationStrategy {
+type IsolationStrategy = {
   /**
    * Create an isolated namespace for this worker.
    * Called once when the worker starts — e.g. clone a template database,
@@ -859,14 +648,14 @@ interface IsolationStrategy {
    * Called once when the worker shuts down — e.g. drop the cloned database.
    */
   release: () => Promise<void>;
-}
+};
 //#endregion
-//#region src/core/ports/service.port.d.ts
+//#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.
  */
-interface ServiceHandle {
+type ServiceHandle = {
   /** Service type identifier. */
   readonly type: string;
   /**
@@ -909,63 +698,200 @@ interface ServiceHandle {
   reset: () => Promise<void>;
   /** Get the isolation strategy for parallel test execution. */
   isolation: () => IsolationStrategy;
+};
+//#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/core/specification/shared/result/result.d.ts
-/** Read-only handle to a single file produced by a spec action. */
-interface FileAccessor {
-  /** The UTF-8 text content. Throws if the file does not exist. */
-  readonly content: string;
-  readonly exists: boolean;
-  /** The file text as a {@link TextAccessor}, keeping only blocks matching `pattern`. */
-  grep: (pattern: string) => TextAccessor;
+//#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;
 }
-interface BaseResultOptions {
-  config: SpecificationConfig;
-  testDir: string;
-  workDir?: string;
+//#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
 /**
- * Base result - common accessors available after any action type.
- * Extended by HttpResult, CliResult, and used directly by job results.
+ * Read-only accessor for a captured text handle — THE universal one: stdout,
+ * stderr, container logs, and file text all surface as a `TextAccessor`.
  *
- * Every result carries a fresh {@link CaptureScope}: `match.ref()` captures
- * and `{{type#ref}}` placeholders are scoped to one spec execution.
+ * 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 BaseResult {
-  /** @internal Ref-capture scope shared by every assertion on this result. */
+declare class TextAccessor {
+  /** @internal Ref-capture scope shared by the current spec execution. */
   readonly captures: CaptureScope;
-  protected config: SpecificationConfig;
-  protected testDir: string;
-  protected workDir?: string;
-  constructor(options: BaseResultOptions);
-  /** Access a directory (relative to the working directory) for snapshot assertions. */
-  directory(path?: string): DirectoryAccessor;
-  /** Access a single file (relative to the working directory) for content assertions. */
-  file(path: string): FileAccessor;
-  /** Access a database table for row-level assertions via expect() matchers. */
-  table(tableName: string, options?: {
-    database?: string;
-  }): TableAccessor;
-  private resolveDatabase;
+  /** @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;
 }
+/**
+ * Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
+ * test's directory — the same caller-detection the builders use.
+ *
+ * The product surface of a test framework is its own error messages, checker
+ * output, and reports; those deserve the same goldening as any other output.
+ * `text()` makes an ad-hoc string a first-class snapshot subject:
+ *
+ * ```typescript
+ * const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
+ * expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to _expected/
+ * ```
+ *
+ * ANSI is stripped before every comparison (the raw form stays on `.text`),
+ * the `{{token}}` grammar applies to the fixture, and `.grep()` composition
+ * works exactly as on any stream accessor.
+ */
+declare function text(value: string): TextAccessor;
 //#endregion
-//#region src/core/specification/api/result.d.ts
-/** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
-declare class HttpResult extends BaseResult {
-  private responseData;
+//#region src/specification/facets/cli/result.d.ts
+/**
+ * Result from a command action (`.exec()`).
+ *
+ * When the runner was configured with a `docker` option, the result also
+ * exposes container accessors and participates in `Symbol.asyncDispose`
+ * cleanup. The Docker shell-outs are **lazy**: a test that never calls
+ * `.container(...)` never queries the Docker daemon, so command-only tests
+ * pay zero Docker cost even when the runner is Docker-aware.
+ *
+ * Dispose always runs one final label-filtered `docker ps` to catch
+ * containers that were spawned during `.exec` but never asserted on —
+ * tests still get leak-free cleanup even if they forget to reach into
+ * a container.
+ */
+declare class CliResult extends BaseResult {
+  private readonly commandOutput;
+  private containersCache;
+  private readonly dockerConfig?;
+  private readonly testRunId?;
+  private readonly transform?;
   constructor(options: {
+    commandOutput: CliOutput;
     config: SpecificationConfig;
-    response: ServerResponse;
+    dockerConfig?: DockerSpecConfig | undefined;
     testDir: string;
+    testRunId?: string | undefined;
+    transform?: ((text: string) => string) | undefined;
+    workDir: string;
   });
-  /** Access the HTTP response (status, headers, body) for assertions. */
-  get response(): ResponseAccessor;
-  /** The HTTP response status code. */
-  get status(): number;
+  /** 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/core/specification/cli/literate.d.ts
+//#region src/specification/facets/cli/literate.d.ts
 /**
  * Running a `<case>.spec.yaml` document: one scenario, one working directory,
  * one set of servers, every run executed and asserted.
@@ -983,7 +909,7 @@ declare class HttpResult extends BaseResult {
  * A server a document may start by name (`serve: mcp`), registered once per app
  * in the `serve` option of `specification.cli()`.
  */
-interface LiterateServeRegistration {
+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. */
@@ -995,9 +921,9 @@ interface LiterateServeRegistration {
   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()`. */
-interface LiterateRunFlags {
+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.
@@ -1006,10 +932,10 @@ interface LiterateRunFlags {
    * instead of being silently corrected into a passing file. The document's
    * mirror of `toMatch(name, { frozen: true })`.
    */
-  frozen?: boolean;
-}
+  frozen?: boolean | undefined;
+};
 //#endregion
-//#region src/core/specification/mobile/result.d.ts
+//#region src/specification/facets/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;
@@ -1030,13 +956,13 @@ declare class ScreenResult extends BaseResult {
   get screen(): JsonAccessor;
 }
 //#endregion
-//#region src/core/specification/website/result.d.ts
+//#region src/specification/facets/website/result.d.ts
 /** A raw HTTP exchange captured by `.fetch()` — redirects are NOT followed. */
-interface FetchExchange {
+type FetchExchange = {
   body: string;
   headers: Record<string, string>;
   status: number;
-}
+};
 /** Result from a raw `.fetch()` action (robots.txt, sitemaps, redirects). */
 declare class FetchResult extends BaseResult {
   private readonly exchange;
@@ -1107,15 +1033,15 @@ declare class PageResult extends BaseResult {
   get url(): string;
 }
 //#endregion
-//#region src/core/specification/shared/stub-backend.d.ts
+//#region src/specification/facets/_common/stub-backend.d.ts
 /** Options for the stub backend server. */
-interface StubBackendOptions {
+type StubBackendOptions = {
   /**
    * Fixed port — pins a stable stub URL across runs (a bundler that inlines
    * the URL at serve time survives warm). Default: a free OS-assigned port.
    */
-  port?: number;
-}
+  port?: number | undefined;
+};
 declare class StubBackend {
   /** Guarded once the current chain declared at least one contract. */
   private guarded;
@@ -1149,107 +1075,107 @@ declare class StubBackend {
   private record;
 }
 //#endregion
-//#region src/core/specification/shared/builder.d.ts
+//#region src/specification/facets/_common/builder.d.ts
 /** A named job that can be triggered via jobs.trigger(). */
-interface JobHandle {
+type JobHandle = {
   name: string;
   execute: () => Promise<void>;
-}
+};
 /**
  * Configuration for the docker-aware cli mode. When set on
  * {@link SpecificationConfig}, the cli runner generates a test-run id, injects
  * it into the child env under `envVar`, then queries Docker for every
  * container carrying `testRunLabel=<id>` after the command exits.
  */
-interface DockerSpecConfig {
+type DockerSpecConfig = {
   envVar: string;
   nameLabel: string;
   testRunLabel: string;
-}
+};
 /** Adapter configuration passed to the specification facets at setup time. */
-interface SpecificationConfig {
+type SpecificationConfig = {
   /**
    * The declared stub backend (website/mobile facets) — armed with the
    * chain's contracts before every terminal action.
    */
-  backend?: StubBackend;
+  backend?: StubBackend | undefined;
   /**
    * Base URL of the running stub backend — allow-listed through the
    * browser's `external: 'block'` policy so client-side fetches reach it.
    */
-  backendUrl?: string;
+  backendUrl?: string | undefined;
   /** Base URL of the website under test (website facet only). */
-  baseUrl?: string;
+  baseUrl?: string | undefined;
   /**
    * Lazy browser accessor (website facet only). The first `.visit()`
    * launches the shared browser instance; `.fetch()`-only spec files never
    * pay the browser cost.
    */
-  browser?: () => Promise<BrowserPort>;
+  browser?: (() => Promise<BrowserPort>) | undefined;
   /**
    * Cross-origin request policy for visits (website facet only): `'block'`
    * aborts requests leaving the site under test — the browser-side analog
    * of strict intercepts.
    */
-  external?: 'allow' | 'block';
+  external?: 'allow' | 'block' | undefined;
   /** Bundle id of the app under test (mobile facet only) — the app `.open()` relaunches. */
-  bundleId?: string;
-  command?: CliPort;
-  database?: DatabasePort;
+  bundleId?: string | undefined;
+  command?: CliPort | undefined;
+  database?: DatabasePort | undefined;
   /**
    * Keys of the declared services record that are databases. Drives the
    * CONVENTIONS A7 rule: with 2+ databases the `database` option is
    * mandatory on `.seed()` / `.table()`; with exactly one it is forbidden.
    */
-  databaseKeys?: string[];
-  databases?: Map<string, DatabasePort>;
+  databaseKeys?: string[] | undefined;
+  databases?: Map<string, DatabasePort> | undefined;
   /**
    * Lazy device accessor (mobile facet only). The first `.open()` creates
    * the shared driver session; the appium/webdriverio integration stays a
    * lazy import so the optional peer is only loaded when a spec opens the
    * app.
    */
-  device?: () => Promise<DevicePort>;
-  dockerConfig?: DockerSpecConfig;
+  device?: (() => Promise<DevicePort>) | undefined;
+  dockerConfig?: DockerSpecConfig | undefined;
   /**
    * Unique id shared by every spec from this runner instance.
    * Stable for the runner's lifetime so multi-step tests (spawn in
    * one run, inspect in another) see the same container scope. The
    * facet factories auto-populate this when `dockerConfig` is present.
    */
-  dockerTestRunId?: string;
+  dockerTestRunId?: string | undefined;
   /**
    * Named environment SETS a spec document may name by bare word
    * (`env: frozen`). Declared once per app in `specification.cli()`.
    */
-  envSets?: Record<string, CliEnv>;
+  envSets?: Record<string, CliEnv> | undefined;
   /**
    * When set, `.intercept()` is unavailable on this runner and throws this
    * reason immediately (compose mode — MSW is in-process, CONVENTIONS I3).
    */
-  interceptDisabledReason?: string;
-  jobs?: JobHandle[];
+  interceptDisabledReason?: string | undefined;
+  jobs?: JobHandle[] | undefined;
   /** The project root — the working directory a document's `serve:` command runs from. */
-  root?: string;
-  server?: ServerPort;
+  root?: string | undefined;
+  server?: ServerPort | undefined;
   /**
    * Named servers a spec document may start (`serve: [mcp]`). Declared once
    * per app in `specification.cli()`.
    */
-  serveRegistry?: Record<string, LiterateServeRegistration>;
+  serveRegistry?: Record<string, LiterateServeRegistration> | undefined;
   /**
    * The declared services record. In cli mode, drives the automatic
    * connection-URL injection into the child env (CONVENTIONS B6):
    * `<KEY>_URL` per service, plus `DATABASE_URL` / `REDIS_URL` when
    * unambiguous.
    */
-  services?: Record<string, ServiceHandle>;
+  services?: Record<string, ServiceHandle> | undefined;
   /**
    * Optional normaliser applied to command stdout/stderr before every
    * comparison. Does not mutate the raw `.text` accessor.
    */
-  transform?: (text: string) => string;
-}
+  transform?: ((text: string) => string) | undefined;
+};
 /**
  * The `.intercept()` overload set, identical on every facet: one contract, a
  * list, a composite — or the inline `(request, response)` pair for a one-off.
@@ -1263,7 +1189,7 @@ type InterceptMethod<T> = ((contracts: ContractInput) => T) & ((request: Contrac
  * The `DatabaseKey` parameter is the typed vocabulary of `.seed()`: the keys
  * of the declared services record that are databases.
  */
-interface ApiSpecification<DatabaseKey extends string = string> {
+type ApiSpecification<DatabaseKey extends string = string> = {
   /** Set HTTP headers for the request. Multiple calls merge. */
   headers: (headers: Record<string, string>) => ApiSpecification<DatabaseKey>;
   /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
@@ -1282,12 +1208,12 @@ interface ApiSpecification<DatabaseKey extends string = string> {
   put: (path: string, body?: unknown) => Promise<HttpResult>;
   /** Send the complete request described by `_requests/<file>` (.http format). */
   request: (file: string) => Promise<HttpResult>;
-}
+};
 /**
  * The `jobs` facet — job chain entry handed out by `specification.jobs()`.
  * Jobs run in-process by definition (CONVENTIONS A5/A8).
  */
-interface JobsSpecification<DatabaseKey extends string = string> {
+type JobsSpecification<DatabaseKey extends string = string> = {
   /** Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair. */
   intercept: InterceptMethod<JobsSpecification<DatabaseKey>>;
   /** Queue a SQL seed file from `_seeds/` to run before the action. */
@@ -1296,13 +1222,13 @@ interface JobsSpecification<DatabaseKey extends string = string> {
   }) => JobsSpecification<DatabaseKey>;
   /** Execute the named job registered via the `jobs` option and resolve with the result. */
   trigger: (name: string) => Promise<BaseResult>;
-}
+};
 /**
  * The `cli` facet — command chain entry handed out by `specification.cli()`.
  * Setup methods chain; `.exec()` is the single terminal action (CONVENTIONS
  * B2) — `{ waitFor?, timeout? }` covers long-running processes.
  */
-interface CliSpecification<DatabaseKey extends string = string> {
+type CliSpecification<DatabaseKey extends string = string> = {
   /** Set environment variables on the child process. `$WORKDIR` expands; `null` unsets. */
   env: (env: CliEnv) => CliSpecification<DatabaseKey>;
   /**
@@ -1333,14 +1259,14 @@ interface CliSpecification<DatabaseKey extends string = string> {
    * directory, where the document lives.
    */
   run: (file: string, options?: LiterateRunFlags) => Promise<CliResult>;
-}
+};
 /**
  * The `website` facet — page chain entry handed out by
  * `specification.website()`. Setup methods chain; action methods are
  * terminal. `.visit()` renders the page in the shared browser; `.fetch()`
  * performs one raw HTTP exchange and never follows redirects.
  */
-interface WebsiteSpecification {
+type WebsiteSpecification = {
   /** Set HTTP headers for the exchange (incl. User-Agent overrides). Multiple calls merge. */
   headers: (headers: Record<string, string>) => WebsiteSpecification;
   /**
@@ -1356,14 +1282,14 @@ interface WebsiteSpecification {
    * the capture reflects the FINAL page state.
    */
   visit: (path: string, scenario?: VisitScenario) => Promise<PageResult>;
-}
+};
 /**
  * The `mobile` facet — screen chain entry handed out by
  * `specification.mobile()`. `.open()` is the single, terminal action: it
  * terminates and relaunches the app (deterministic fresh state), applies the
  * deep link, runs the scenario, and captures the final screen.
  */
-interface MobileSpecification {
+type MobileSpecification = {
   /**
    * Declare the chain's backend contracts — served by the declared stub
    * backend (requires the runner's `backend` option). Multiple calls append.
@@ -1375,65 +1301,91 @@ interface MobileSpecification {
    * first (the When) and the capture reflects the FINAL screen state.
    */
   open: (deepLink?: string, scenario?: MobileScenario) => Promise<ScreenResult>;
+};
+//#endregion
+//#region src/specification/facets/_common/result/directory.d.ts
+/**
+ * Read-only accessor for a directory produced by a spec action.
+ *
+ * Assertions go through `expect()` (async — they walk the disk):
+ * `await expect(result.directory('out')).toMatch('scaffold/out')`
+ * compares the tree against the fixture directory `_expected/<name>/`.
+ */
+declare class DirectoryAccessor {
+  /** @internal Ref-capture scope shared by the current spec execution. */
+  readonly captures: CaptureScope;
+  /** @internal Absolute path of the directory under assertion. */
+  readonly root: string;
+  /** @internal Test-file directory — fixture resolution root for matchers. */
+  readonly testDir: string;
+  constructor(absPath: string, testDir: string, captures?: CaptureScope);
+  /** List all files (recursively) under the directory, sorted. */
+  files(options?: {
+    ignore?: string[];
+  }): Promise<string[]>;
 }
 //#endregion
-//#region src/core/specification/cli/result.d.ts
+//#region src/specification/facets/_common/result/table.d.ts
 /**
- * Result from a command action (`.exec()`).
+ * Read-only accessor for a database table after a specification run.
  *
- * 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.
+ * Assertions go through `expect()` (async — they query the database):
  *
- * 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.
+ *     await expect(result.table('users', { database: 'db' })).toMatchRows({
+ *         columns: ['name'],
+ *         rows: [['Alice']],
+ *     });
+ *     await expect(result.table('users', { database: 'db' })).toBeEmpty();
  */
-declare class CliResult extends BaseResult {
-  private readonly commandOutput;
-  private containersCache;
-  private readonly dockerConfig?;
-  private readonly testRunId?;
-  private readonly transform?;
-  constructor(options: {
-    commandOutput: CliOutput;
-    config: SpecificationConfig;
-    dockerConfig?: DockerSpecConfig;
-    testDir: string;
-    testRunId?: string;
-    transform?: (text: string) => string;
-    workDir: string;
-  });
-  /** The process exit code. */
-  get exitCode(): number;
-  /** Accessor for the captured standard output with file-based assertions. */
-  get stdout(): TextAccessor;
-  /** Accessor for the captured standard error with file-based assertions. */
-  get stderr(): TextAccessor;
-  /** Accessor for parsing stdout as JSON and asserting against JSON fixtures. */
-  get json(): JsonAccessor;
-  /** Accessor for the temporary working directory the command ran in. */
-  get filesystem(): FilesystemAccessor;
-  /**
-   * 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;
+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.
+ *
+ * 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/integrations/docker/container-accessor.d.ts
@@ -1500,12 +1452,12 @@ declare class ContainerAccessor {
  * survivable across update runs instead of being silently overwritten with the
  * actual output.
  */
-interface MatchFixtureOptions {
+type MatchFixtureOptions = {
   frozen?: boolean;
-}
+};
 //#endregion
-//#region src/core/specification/shared/orchestrator.d.ts
-interface OrchestratorOptions {
+//#region src/specification/facets/_common/orchestrator.d.ts
+type OrchestratorOptions = {
   /**
    * Named infrastructure record. Keys become the database vocabulary of the
    * spec (`.seed()` / `.table()` `database` option) and drive the compose
@@ -1526,17 +1478,17 @@ interface OrchestratorOptions {
   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.
  */
 declare class Orchestrator {
-  private services;
-  private mode;
-  private root;
-  private projectName;
+  private readonly services;
+  private readonly mode;
+  private readonly root;
+  private readonly projectName;
   private running;
   private composeStack;
   private composeHandles;
@@ -1585,7 +1537,7 @@ declare class Orchestrator {
   getAppUrl(): null | string;
 }
 //#endregion
-//#region src/core/specification/shared/services.d.ts
+//#region src/specification/facets/_common/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,
@@ -1595,7 +1547,7 @@ type ServiceRecord = Record<string, ServiceHandle>;
 /** Keys of a services record whose handles are databases. */
 type DatabaseKeys<Services extends ServiceRecord> = { [K in keyof Services]: Services[K] extends DatabasePort ? K & string : never; }[keyof Services];
 //#endregion
-//#region src/core/specification/api/start-api.d.ts
+//#region src/specification/facets/api/start-api.d.ts
 /** Any object with a request method compatible with Hono's app.request(). */
 type HonoApp = {
   request: (path: string, init?: RequestInit) => Promise<Response> | Response;
@@ -1603,7 +1555,7 @@ type HonoApp = {
 /** Execution mode — exists ONLY on `specification.api()` (CONVENTIONS A5). */
 type SpecificationMode = 'compose' | 'node';
 /** Options for {@link startApi | specification.api}. */
-interface ApiSpecificationOptions<Services extends ServiceRecord = ServiceRecord> {
+type ApiSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
   /**
    * Execution mode override. Resolution: `options.mode` >
    * `process.env.TEST_MODE` > `'node'`. Never hardcode this in a
@@ -1632,14 +1584,14 @@ interface ApiSpecificationOptions<Services extends ServiceRecord = ServiceRecord
    * its key, else the kebab-case conversion of the key (CONVENTIONS A6).
    */
   services?: Services;
-}
+};
 /**
  * The record returned by {@link startApi | specification.api}. Destructure
  * with the canonical names (CONVENTIONS A3):
  *
  *     const { api, cleanup, docker } = await specification.api(…);
  */
-interface ApiHandle<DatabaseKey extends string = string> {
+type ApiHandle<DatabaseKey extends string = string> = {
   api: ApiSpecification<DatabaseKey>;
   /** Stop all infrastructure started by this specification. */
   cleanup: () => Promise<void>;
@@ -1650,12 +1602,12 @@ interface ApiHandle<DatabaseKey extends string = string> {
   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/core/specification/cli/start-cli.d.ts
+//#region src/specification/facets/cli/start-cli.d.ts
 /** Options for {@link startCli | specification.cli}. */
-interface CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord> {
+type CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord> = {
   /**
    * Opt-in Docker awareness. When set, every spec generates a unique
    * test-run id, injects it into the child process env under `envVar`,
@@ -1699,15 +1651,15 @@ interface CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord
    * D6). Does NOT mutate the raw `.text` accessor. Prefer `{{token}}`
    * placeholders in fixtures.
    */
-  transform?: (text: string) => string;
-}
+  transform?: ((text: string) => string) | undefined;
+};
 /**
  * The record returned by {@link startCli | specification.cli}. Destructure
  * with the canonical names (CONVENTIONS A3):
  *
  *     const { cli, cleanup, docker } = await specification.cli(…);
  */
-interface CliHandle<DatabaseKey extends string = string> {
+type CliHandle<DatabaseKey extends string = string> = {
   /** Stop all infrastructure started by this specification. */
   cleanup: () => Promise<void>;
   cli: CliSpecification<DatabaseKey>;
@@ -1718,12 +1670,12 @@ interface CliHandle<DatabaseKey extends string = string> {
   docker: (containerId: string) => ContainerAccessor;
   /** The orchestrator managing the test infrastructure lifecycle. */
   orchestrator: null | Orchestrator;
-}
+};
 declare function startCli<Services extends ServiceRecord>(bin: string, options?: CliSpecificationOptions<Services>): Promise<CliHandle<DatabaseKeys<Services>>>;
 //#endregion
-//#region src/core/specification/jobs/start-jobs.d.ts
+//#region src/specification/facets/jobs/start-jobs.d.ts
 /** Options for {@link startJobs | specification.jobs}. */
-interface JobsSpecificationOptions<Services extends ServiceRecord = ServiceRecord> {
+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
@@ -1734,23 +1686,23 @@ interface JobsSpecificationOptions<Services extends ServiceRecord = ServiceRecor
   root?: string;
   /** Named infrastructure record started via testcontainers. */
   services?: Services;
-}
+};
 /**
  * The record returned by {@link startJobs | specification.jobs}. Destructure
  * with the canonical names (CONVENTIONS A3):
  *
  *     const { jobs, cleanup } = await specification.jobs(…);
  */
-interface JobsHandle<DatabaseKey extends string = string> {
+type JobsHandle<DatabaseKey extends string = string> = {
   /** Stop all infrastructure started by this specification. */
   cleanup: () => Promise<void>;
   jobs: JobsSpecification<DatabaseKey>;
   /** The orchestrator managing the test infrastructure lifecycle. */
   orchestrator: null | Orchestrator;
-}
+};
 declare function startJobs<Services extends ServiceRecord>(options: JobsSpecificationOptions<Services>): Promise<JobsHandle<DatabaseKeys<Services>>>;
 //#endregion
-//#region src/core/specification/mobile/start-mobile.d.ts
+//#region src/specification/facets/mobile/start-mobile.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
@@ -1758,16 +1710,16 @@ declare function startJobs<Services extends ServiceRecord>(options: JobsSpecific
  * injected: the handle exposes `backendUrl` and the CALLER wires it into its
  * own bundler env.
  */
-interface MobileBackendOptions {
+type MobileBackendOptions = {
   /**
    * Fixed port — pins a stable stub URL across runs. Metro inlines
    * `EXPO_PUBLIC_*` values at bundle-serve time; a stable port lets a warm
    * Metro survive between runs. Default: a free OS-assigned port.
    */
   port?: number;
-}
+};
 /** Options for {@link startMobile | specification.mobile}. */
-interface MobileSpecificationOptions {
+type MobileSpecificationOptions = {
   /** The app under test — terminated and relaunched by every `.open()`. */
   app: {
     /** Bundle id of the installed app (`com.example.app`). */
@@ -1801,31 +1753,31 @@ interface MobileSpecificationOptions {
    * (`{ action: 45_000 }`) instead of sleeping inside its scenarios.
    */
   timeouts?: DeviceTimeouts;
-}
+};
 /**
  * The record returned by {@link startMobile | specification.mobile}.
  * Destructure with the canonical names (CONVENTIONS A3):
  *
  *     const { mobile, cleanup, udid } = await specification.mobile(…);
  */
-interface MobileHandle {
+type MobileHandle = {
   /**
    * Base URL of the declared stub backend — present only with the
    * `backend` option. The caller injects it into its own bundler env
    * (e.g. `EXPO_PUBLIC_API_URL`); the framework never touches the bundler.
    */
-  backendUrl?: string;
+  backendUrl?: string | undefined;
   /** End the driver session, stop the appium server and the stub backend. */
   cleanup: () => Promise<void>;
   mobile: MobileSpecification;
   /** The resolved simulator UDID the specs run against. */
   udid: string;
-}
+};
 declare function startMobile(options: MobileSpecificationOptions): Promise<MobileHandle>;
 //#endregion
-//#region src/core/specification/website/serve.adapter.d.ts
+//#region src/specification/facets/website/serve.adapter.d.ts
 /** Options for a local server started by the framework. */
-interface ServeOptions {
+type ServeOptions = {
   /** Shell command that starts the site. Receives the chosen port as `PORT`. */
   command: string;
   /** Fixed port. Default: an OS-assigned free port, injected as `PORT`. */
@@ -1844,21 +1796,21 @@ interface ServeOptions {
   ready?: RegExp | string;
   /** Readiness budget in milliseconds. Default 30 000. */
   timeout?: number;
-}
+};
 //#endregion
-//#region src/core/specification/website/start-website.d.ts
+//#region src/specification/facets/website/start-website.d.ts
 /**
  * The declared stub backend behind the site under test — started before the
  * server command, torn down with the runner. Its URL is injected into the
  * server child's environment under `env`; the contracts each chain declares
  * via `.intercept(...)` are what it serves.
  */
-interface WebsiteBackendOptions {
+type WebsiteBackendOptions = {
   /** Env var receiving the stub's URL in the server child (e.g. `'API_URL'`). */
   env: string;
   /** Fixed port — pins a stable stub URL across runs. Default: a free OS-assigned port. */
   port?: number;
-}
+};
 /**
  * Options for {@link startWebsite | specification.website}. `server` (start
  * the site locally) and `url` (target a running site) are mutually
@@ -1904,16 +1856,16 @@ type WebsiteSpecificationOptions = {
  *
  *     const { website, cleanup } = await specification.website(…);
  */
-interface WebsiteHandle {
+type WebsiteHandle = {
   /** Stop the server process and the shared browser instance. */
   cleanup: () => Promise<void>;
   /** The base URL the specs run against. */
   url: string;
   website: WebsiteSpecification;
-}
+};
 declare function startWebsite(options: WebsiteSpecificationOptions): Promise<WebsiteHandle>;
 //#endregion
-//#region src/core/specification/shared/specification.d.ts
+//#region src/specification/facets/_common/specification.d.ts
 /**
  * The five specification constructors (CONVENTIONS A2) — created in a
  * `*.specification.ts` file under `specs/`, destructured with canonical
@@ -1938,44 +1890,17 @@ declare function startWebsite(options: WebsiteSpecificationOptions): Promise<Web
  *   export const { cli, cleanup } = await specification.cli('my-cli');
  *   afterAll(cleanup);
  */
-declare const specification: {
-  /**
-   * Test an HTTP app. Mode `'node'` (default) starts the declared services
-   * via testcontainers and runs the app in-process; mode `'compose'` runs
-   * `docker compose up` on `docker/compose.test.yaml` and sends real HTTP
-   * requests to the app service. Resolution: `options.mode` > `TEST_MODE`
-   * env var > `'node'`. Only `.api()` has a mode.
-   */
+/** The five constructors, and only five — the framework's whole entry surface. */
+type Specification = {
   api: typeof startApi;
-  /**
-   * Test a command binary. Each spec runs in a fresh temp directory.
-   *
-   * @param bin - Path to the binary (resolved from node_modules/.bin or PATH).
-   */
   cli: typeof startCli;
-  /**
-   * Test background jobs. Jobs run in-process by definition — no HTTP
-   * server, no mode. `.trigger(name)` is the terminal action.
-   */
   jobs: typeof startJobs;
-  /**
-   * Test a native app on the iOS simulator. `device` names the simulator
-   * (resolved and booted via `simctl`); `app` names the bundle under
-   * test. `.open(deepLink?, scenario?)` relaunches the app fresh, runs
-   * the scenario, and captures the final screen.
-   */
   mobile: typeof startMobile;
-  /**
-   * Test a deployed or locally-served website. `server` starts the site
-   * (a shell command receiving `PORT`); `url` targets a running one.
-   * `.visit(path)` renders the page in a single shared browser instance;
-   * `.fetch(path)` performs one raw HTTP exchange (redirects never
-   * followed).
-   */
   website: typeof startWebsite;
 };
+declare const specification: Specification;
 //#endregion
-//#region src/core/literate/spec-document.d.ts
+//#region src/specification/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.
@@ -1994,22 +1919,22 @@ type SpecEnvToken = {
   name: string;
 };
 /** One `serve:` entry — a registered server plus the extra env it is started with. */
-interface SpecServeEntry {
+type SpecServeEntry = {
   env: Record<string, string>;
   line: number;
   name: string;
-}
+};
 /** One `fixture:` entry — a path with the line it was declared on. */
-interface SpecFixture {
+type SpecFixture = {
   line: number;
   path: string;
-}
+};
 /** An expected stream: its text, and the first line of that text in the file. */
-interface SpecStream {
+type SpecStream = {
   /** 1-based line the scalar's content starts on — where a token defect is reported. */
   line: number;
   text: string;
-}
+};
 /** One `files:` assertion, keyed by a workdir-relative path. */
 type SpecFileAssertion = {
   contains: SpecStream[];
@@ -2027,7 +1952,7 @@ type SpecFileAssertion = {
   path: string;
 };
 /** One run: a command, what it must exit with, and what it must have produced. */
-interface SpecRun {
+type SpecRun = {
   command: string;
   /** 1-based line of the `command:` key — the frame a failure points at. */
   commandLine: number;
@@ -2041,9 +1966,9 @@ interface SpecRun {
   timeout: null | number;
   /** Only ever on the LAST run — a long-running command ends the session. */
   waitFor: null | string;
-}
+};
 /** A parsed `<case>.spec.yaml`. */
-interface SpecDocument {
+type SpecDocument = {
   /** The vitest test title. */
   description: string;
   /** 1-based line of the `description:` key. */
@@ -2053,7 +1978,7 @@ interface SpecDocument {
   kind: SpecKind;
   runs: SpecRun[];
   serve: SpecServeEntry[];
-}
+};
 //#endregion
 //#region src/integrations/docker/docker-lookup.d.ts
 /** Return all container IDs (running or stopped) that carry `key=value`. */
@@ -2063,12 +1988,12 @@ 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/core/ports/container.port.d.ts
+//#region src/specification/ports/container.port.d.ts
 /**
  * Abstract container interface.
  * Represents a running service (database, cache, etc.)
  */
-interface ContainerPort {
+type ContainerPort = {
   /** Start the container and wait until ready. */
   start: () => Promise<void>;
   /** Stop and remove the container. */
@@ -2081,9 +2006,9 @@ interface ContainerPort {
   getConnectionString: () => string;
   /** Get container logs (stdout + stderr). */
   getLogs: () => Promise<string>;
-}
+};
 //#endregion
-//#region src/core/specification/website/elements.d.ts
+//#region src/specification/facets/website/elements.d.ts
 /**
  * The element vocabulary — user-facing descriptors for visit scenarios.
  * Reads like English (`click(link('Articles'))`), translates to
@@ -2099,41 +2024,45 @@ interface ContainerPort {
  *      substring, when two names genuinely overlap.
  */
 /** Options accepted by every named descriptor. */
-interface ElementOptions {
+type ElementOptions = {
   /**
    * Match the accessible name as a whole string. Default is substring —
    * `link('Articles')` also matches "Read Articles".
    */
   exact?: boolean;
-}
+};
+/** A user-facing element factory — what every name in this module is. */
+type ElementFactory = (name: string, options?: ElementOptions) => ElementRef;
 /** A button (or element with the button role), by accessible name. */
-declare const button: (name: string, options?: ElementOptions) => ElementRef;
+declare const button: ElementFactory;
 /** A form field, by label. */
-declare const field: (name: string, options?: ElementOptions) => ElementRef;
+declare const field: ElementFactory;
 /** A heading, by accessible name. */
-declare const heading: (name: string, options?: ElementOptions) => ElementRef;
+declare const heading: ElementFactory;
 /** A link, by accessible name. */
-declare const link: (name: string, options?: ElementOptions) => ElementRef;
+declare const link: ElementFactory;
 /** An element containing the given text. */
-declare const content: (name: string, options?: ElementOptions) => ElementRef;
+declare const content: ElementFactory;
 /** The escape hatch: an element by `data-testid`. Prefer user-facing elements. */
 declare const testId: (id: string) => ElementRef;
+/** A landmark factory — the optionally-named containers `within()` accepts. */
+type LandmarkFactory = (name?: string, options?: ElementOptions) => ElementRef;
 /** The `banner` landmark — the page header. */
-declare const banner: (name?: string, options?: ElementOptions) => ElementRef;
+declare const banner: LandmarkFactory;
 /** The `complementary` landmark — an `<aside>`, a sidebar. */
-declare const complementary: (name?: string, options?: ElementOptions) => ElementRef;
+declare const complementary: LandmarkFactory;
 /** The `contentinfo` landmark — the page footer. */
-declare const contentinfo: (name?: string, options?: ElementOptions) => ElementRef;
+declare const contentinfo: LandmarkFactory;
 /** The `form` landmark — a form carrying an accessible name. */
-declare const form: (name?: string, options?: ElementOptions) => ElementRef;
+declare const form: LandmarkFactory;
 /** The `main` landmark — the primary content of the document. */
-declare const main: (name?: string, options?: ElementOptions) => ElementRef;
+declare const main: LandmarkFactory;
 /** The `navigation` landmark — a `<nav>`. Name it when a page has several. */
-declare const navigation: (name?: string, options?: ElementOptions) => ElementRef;
+declare const navigation: LandmarkFactory;
 /** The `region` landmark — a `<section>` carrying an accessible name. */
-declare const region: (name?: string, options?: ElementOptions) => ElementRef;
+declare const region: LandmarkFactory;
 /** The `search` landmark. */
-declare const search: (name?: string, options?: ElementOptions) => ElementRef;
+declare const search: LandmarkFactory;
 /**
  * Restrict a descriptor to the inside of another — the answer to ambiguity,
  * and the one the framework prefers over a test id.
@@ -2148,7 +2077,7 @@ declare const search: (name?: string, options?: ElementOptions) => ElementRef;
 declare const within: (scope: ElementRef, target: ElementRef) => ElementRef;
 //#endregion
 //#region src/integrations/postgres/postgres.d.ts
-interface PostgresOptions {
+type PostgresOptions = {
   /**
    * Map to a service in docker/compose.test.yaml. Defaults to the handle's
    * key in the declared services record.
@@ -2158,7 +2087,7 @@ interface PostgresOptions {
   image?: string;
   /** Override environment variables. */
   env?: Record<string, string>;
-}
+};
 declare class PostgresHandle implements DatabasePort, ServiceHandle {
   readonly type = "postgres";
   composeName: null | string;
@@ -2195,7 +2124,7 @@ declare class PostgresHandle implements DatabasePort, ServiceHandle {
 declare function postgres(options?: PostgresOptions): PostgresHandle;
 //#endregion
 //#region src/integrations/redis/redis.d.ts
-interface RedisOptions {
+type RedisOptions = {
   /**
    * Map to a service in docker/compose.test.yaml. Defaults to the handle's
    * key in the declared services record.
@@ -2203,7 +2132,7 @@ interface RedisOptions {
   composeService?: string;
   /** Override image. */
   image?: string;
-}
+};
 declare class RedisHandle implements ServiceHandle {
   readonly type = "redis";
   composeName: null | string;
@@ -2232,7 +2161,7 @@ declare class RedisHandle implements ServiceHandle {
 declare function redis(options?: RedisOptions): RedisHandle;
 //#endregion
 //#region src/integrations/sqlite/sqlite.d.ts
-interface SqliteOptions {
+type SqliteOptions = {
   /**
    * Path to a SQL file used to initialize the database schema.
    * Mutually exclusive with `prismaSchema`.
@@ -2245,7 +2174,7 @@ interface SqliteOptions {
    * Mutually exclusive with `init`.
    */
   prismaSchema?: string;
-}
+};
 declare class SqliteHandle implements DatabasePort, ServiceHandle {
   readonly type = "sqlite";
   composeName: null | string;
@@ -2257,8 +2186,8 @@ declare class SqliteHandle implements DatabasePort, ServiceHandle {
   private db;
   private templatePath;
   private workerDbPath;
-  private initSql;
-  private prismaSchema;
+  private readonly initSql;
+  private readonly prismaSchema;
   private readonly options;
   constructor(options?: SqliteOptions);
   buildConnectionString(): string;
@@ -2311,7 +2240,7 @@ declare class SqliteHandle implements DatabasePort, ServiceHandle {
  */
 declare function sqlite(options?: SqliteOptions): SqliteHandle;
 //#endregion
-//#region src/core/contracts/filters.d.ts
+//#region src/specification/contracts/filters.d.ts
 /**
  * A text filter on a provider request builder (`openai.chat({ user })`,
  * `anthropic.messages({ system })`, …).
@@ -2330,13 +2259,12 @@ declare function sqlite(options?: SqliteOptions): SqliteHandle;
 type TextFilter = Matcher | RegExp | string;
 //#endregion
 //#region src/integrations/anthropic/anthropic.d.ts
-interface AnthropicMessagesFilter {
+type AnthropicMessagesFilter = {
   model?: TextFilter;
   system?: TextFilter;
   user?: TextFilter;
   tools?: string[];
-}
-declare function buildReply(data: unknown): ContractResponse;
+};
 /**
  * Anthropic API intercept helpers.
  */
@@ -2355,19 +2283,19 @@ declare const anthropic: {
    */
   messages(filter?: AnthropicMessagesFilter, url?: string): ContractRequest;
   /** Response: wrap data in Anthropic messages format. */
-  reply: typeof buildReply;
+  reply(data: unknown): ContractResponse;
   /** Response: return an Anthropic error. */
   error(status: number, message?: string): ContractResponse;
   /** Response: simulate a timeout. */
   timeout(): ContractResponse;
 };
 //#endregion
-//#region src/core/contracts/http.d.ts
+//#region src/specification/contracts/http.d.ts
 /**
  * Request filters for the generic HTTP provider. Every field is a subset
  * constraint — a request matches when all provided fields match.
  */
-interface HttpContractFilter {
+type HttpContractFilter = {
   /**
    * Body constraint. An object is a deep SUBSET match (toMatchObject-style)
    * whose leaf values may be `match.*` matchers; a string is a containment
@@ -2378,16 +2306,16 @@ interface HttpContractFilter {
   headers?: Record<string, RegExp | string>;
   /** Query-param subset. string = exact value, RegExp = `test()`. */
   query?: Record<string, RegExp | string>;
-}
+};
 /** Init options shared by the response builders. */
-interface HttpResponseInit {
+type HttpResponseInit = {
   /** Delay in ms before responding (for timeout testing). */
   delay?: number;
   /** Response headers, merged over the builder's own. */
   headers?: Record<string, string>;
   /** HTTP status code. */
   status?: number;
-}
+};
 /**
  * Generic HTTP contract helpers for any URL. The url is absolute (string or
  * RegExp), or a PATH FORM starting with `/` — `http.get('/articles/{{uuid}}')`
@@ -2418,20 +2346,19 @@ declare const http: {
 };
 //#endregion
 //#region src/integrations/openai/openai.d.ts
-interface OpenAIChatFilter {
+type OpenAIChatFilter = {
   model?: TextFilter;
   system?: TextFilter;
   user?: TextFilter;
   tools?: string[];
   temperature?: number;
-}
-interface OpenAIResponsesFilter {
+};
+type OpenAIResponsesFilter = {
   model?: TextFilter;
   system?: TextFilter;
   user?: TextFilter;
   tools?: string[];
-}
-declare function buildChatReply(data: unknown): ContractResponse;
+};
 /**
  * OpenAI API intercept helpers.
  */
@@ -2467,7 +2394,7 @@ declare const openai: {
    * @example
    *   openai.reply({ categories: ['TECH'] })
    */
-  reply: typeof buildChatReply;
+  reply(data: unknown): ContractResponse;
   /** Response: return an OpenAI error. */
   error(status: number, message?: string): ContractResponse;
   /** Response: return malformed content. */
@@ -2487,12 +2414,12 @@ declare const mockOf: MockPort;
 //#endregion
 //#region src/vitest/mock-of-date.d.ts
 /** Interface for freezing and resetting the global Date in tests. */
-interface MockDatePort {
+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.