@specific.dev/spectest 0.26.0 → 0.28.0

package/src/index.ts

@@ -1,2350 +0,0 @@
-// Spectest SDK. The user's single `spectest/index.ts` calls
-// `defineEnvironment({ name, services })` once, defines test cases via
-// the returned `env.test(...)`, and default-exports `env.project([...])`.
-// The daemon loads this file on boot and the control plane talks to it
-// over HTTP.
-
-import { strict as nodeAssert } from "node:assert";
-
-import { recordAssertion, safeSerialize } from "./recorder.js";
-import { adoptNullishTag, readRaw, readTag } from "./inspect.js";
-
-// Provenance-wrapper types: what tracked ops (ctx.fetch, db queries,
-// browser.evaluate) resolve to, and the `.unwrap()` escape hatch.
-export type {
-  Carrier,
-  Wrapped,
-  WrappedObject,
-  WrappedArray,
-  WrappedResponse,
-  Provenanced,
-  SpectestFetch,
-  Unwrap,
-} from "./inspect.js";
-import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
-
-// `field` — a provenance-preserving, null-safe selector: a `null`/`undefined`
-// leaf read off a wrapped op result is raw and untagged, so an `expect(...)` on
-// it renders detached from its source op; `field` tags from the container so the
-// assertion still nests. (A decoded value loses provenance the same way — that
-// case is the `.transform(label, fn)` method every wrapped value carries, which
-// runs the still-tagged value through `fn` and re-wraps the result.)
-// To recover a raw value, call `.unwrap()` on it — spectest op results are
-// always wrapped (in every context), so the method is always there; there is no
-// `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
-export { field } from "./inspect.js";
-
-// Instrumented client primitives — drop-in replacements for Bun's native
-// clients that record each operation on the test event log and return their
-// results inspect-wrapped, so `expect(...)` on a result links back to the op
-// in the timeline (same provenance mechanism as the wrapped `fetch`). Reach
-// for these over the raw `Bun.*` clients in service `helpers` and tests so
-// assertions stay tracked. See `sql.ts` / `redis.ts` / `s3.ts`.
-export { SQL, type SqlClient, type SqlOptions } from "./sql.js";
-export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js";
-export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
-
-export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./browser.js";
-
-import type { Browser, BrowserOptions } from "./browser.js";
-
-// Playwright-native locators — the select-then-act surface shared by
-// `ctx.browser()` and `ctx.mobile()`. `Locator` mirrors playwright-core's
-// Locator (getBy*/filter/first/nth/click/fill/textContent/…, STRICT mode).
-export type {
-  Locator,
-  GetByRoleOptions,
-  GetByTextOptions,
-  FilterOptions,
-  ClickOptions,
-  BoundingBox,
-} from "./locator.js";
-import type { Locator } from "./locator.js";
-import { isLocator, getLocatorProbe, DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
-
-// Mobile (Expo / React Native Web) surface: a phone-emulated session driven
-// with the same locators + touch gestures, replayed inside a phone bezel.
-// Opened with `ctx.mobile(ctx.svc.app)` where the app is registered via the
-// `expo()` component.
-export type { Mobile, MobileApp } from "./mobile.js";
-import type { Mobile, MobileApp } from "./mobile.js";
-
-export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
-
-import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
-
-// Low-level ingress primitives + the framework lowering that the friendly
-// `tls` / `hostnames` fields and `defineFake(...)` are built on. See
-// `ingress.ts`.
-export {
-  certificate,
-  dnsName,
-  proxy,
-  provides,
-  lowerIngress,
-  isWildcard,
-  SELF_SERVICE_TOKEN,
-} from "./ingress.js";
-export type {
-  CertificateDecl,
-  DnsDecl,
-  ProxyDecl,
-  IngressDecl,
-  DnsTarget,
-  LoweredIngress,
-} from "./ingress.js";
-import type { DnsTarget } from "./ingress.js";
-
-// ──────────────────────────────────────────────────────────────────────────
-// Environment configuration
-// ──────────────────────────────────────────────────────────────────────────
-
-export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
-  /** Human-friendly name for the environment, e.g. "my-app". */
-  name: string;
-  /**
-   * Services that make up the environment, keyed by service name. The key
-   * is the container name, the DNS hostname on `spectest-net`, and the
-   * string used in `dependsOn` references.
-   */
-  services: S;
-  /** Sandbox timeout in seconds (default 1h). */
-  timeoutSecs?: number;
-}
-
-/**
- * The shape that ends up in the JSON config the control plane and Rust
- * mirror care about. `ServiceDefinition` is the same thing with an extra
- * non-serialisable `client` factory tacked on; `JSON.stringify` drops
- * functions, so the wire format is `ServiceConfig`.
- */
-export interface ServiceConfig {
-  /** Image definition: registry pull or inline build. */
-  image: ServiceImage;
-  /**
-   * Shell command to run (sh -c). Defaults to the image's CMD. NB: this
-   * **replaces the image's entrypoint** with `/bin/sh -c` — an
-   * init-wrapped image (postgres's `docker-entrypoint.sh`) skips its
-   * initialization. Use {@link args} to keep the entrypoint.
-   */
-  command?: string;
-  /**
-   * Arguments appended after the image name (`docker run <image>
-   * <args…>`) — a CMD override that **keeps the image's entrypoint**.
-   * E.g. `args: ["postgres", "-c", "wal_level=logical"]` still runs
-   * postgres's `docker-entrypoint.sh` initialization. Mutually
-   * exclusive with {@link command}.
-   */
-  args?: readonly string[];
-  env?: Record<string, string>;
-  /**
-   * Ports the container listens on. Advisory only — surfaced in
-   * `spectest list` output. Peer services reach each other by `<service>:<port>`
-   * without any port declaration.
-   */
-  ports?: readonly number[];
-  /**
-   * Extra DNS names this service answers to inside the environment.
-   * Each entry must be a fully-qualified, multi-label hostname (e.g.
-   * `api.stripe.com`). Both peer containers (via Docker's embedded DNS)
-   * and code on the VM host (via spectest-resolver) resolve these names
-   * to the service's IP on `spectest-net`. Useful for mocking external
-   * APIs — point an SDK at `http://api.stripe.com` and a service of
-   * yours answers directly (no proxy). For HTTPS, use {@link tls}
-   * instead — those names terminate TLS in the daemon and reverse-proxy
-   * to the service's HTTP port.
-   *
-   * The `.internal` TLD is reserved: every service automatically
-   * answers to `<name>.internal` in addition to its bare `<name>`, and
-   * user-supplied hostnames may not end in `.internal`.
-   */
-  hostnames?: readonly string[];
-  /**
-   * Expose this service over HTTPS via a TLS-terminating reverse proxy
-   * hosted in the spectest-daemon. Each entry maps a fully-qualified
-   * hostname to the HTTP port the service listens on inside its
-   * container; the daemon binds the hostname on `:443` (SNI-multiplexed,
-   * with a leaf cert signed by the in-VM root CA) and on `:80`, and
-   * proxies the request to `http://<service>:<port>`. WebSocket
-   * upgrades are forwarded.
-   *
-   * The in-VM root CA is already trusted by Chromium (`ctx.browser()`)
-   * and by service-container runtimes (Node, Python, Go, etc.) via
-   * the env-var bundle, so `https://<hostname>/` Just Works from
-   * tests and from peer services. Hostname rules match {@link hostnames}:
-   * multi-label, lowercase, no `.internal` suffix, no collision with
-   * services, other service TLS hostnames, or fakes.
-   */
-  tls?: readonly ServiceTls[];
-  /** Bind-mounted volumes for state that survives snapshot/fork. */
-  volumes?: readonly VolumeMount[];
-  /**
-   * Files seeded into the container's filesystem **before it starts**.
-   * Each entry's `content` is written to a VM-host staging path and
-   * bind-mounted (read-only) at `path` inside the container. Unlike a
-   * `setup` hook — which runs after the container is up — `files` is the
-   * way to inject configuration a process reads at boot, e.g. k3s's
-   * `/etc/rancher/k3s/registries.yaml`, which must exist before
-   * `k3s server` starts.
-   */
-  files?: readonly FileMount[];
-  /** Other services (keys in the services map) that must be ready first. */
-  dependsOn?: readonly string[];
-  readyCheck?: ReadyCheck;
-  /** Container workdir override. */
-  workdir?: string;
-  /**
-   * Run the container with `--privileged`. Required by workloads that
-   * embed their own container runtime (e.g. k3s) and need full access
-   * to the host kernel surface. Off by default.
-   */
-  privileged?: boolean;
-  /**
-   * Tmpfs mounts (one `--tmpfs <path>` per entry). Required by some
-   * workloads — k3s wants `/run` and `/var/run` writable and
-   * non-persistent. Snapshots/forks preserve tmpfs contents along with
-   * the rest of process memory.
-   */
-  tmpfs?: readonly string[];
-  /**
-   * Cgroup namespace mode — `"host"` or `"private"`. Omit for docker's
-   * default. k3s needs `"host"` so its embedded containerd can manage
-   * cgroups for the pods it schedules.
-   */
-  cgroupns?: string;
-}
-
-/**
- * The slice of the in-VM world a component's `setup` / `helpers` hooks can
- * reach — beyond what the service definition itself declares. Handed to
- * both hooks (see {@link ServiceSetupContext} / {@link ServiceHelpersContext})
- * so components stop hand-rolling `child_process` docker execs and stop
- * hard-coding control-plane paths like `/workspace`.
- */
-export interface ComponentContext {
-  /**
-   * Absolute path of the extracted project root inside the VM — the
-   * directory the user's repo lands in, with `spectest/` directly under
-   * it. Use this (never a hard-coded path) to locate project files a
-   * component consumes, e.g. `supabase/migrations/**`.
-   */
-  projectRoot: string;
-  /** Read a project file as UTF-8. Relative paths resolve against
-   *  {@link projectRoot}; absolute paths are read as-is. */
-  readProjectFile(path: string): Promise<string>;
-  /**
-   * Run a command inside a service container (a raw `docker exec` — not
-   * recorded on any test timeline, result is plain, not
-   * provenance-wrapped). Pass an **array** for exact argv with no shell
-   * (`["psql", "-f", "-"]`), or a **string** to run via `sh -lc`.
-   * `opts.stdin` is piped to the process — the natural way to feed a SQL
-   * file to `psql -f -` or a manifest to `kubectl apply -f -`.
-   *
-   * Never throws on non-zero exit — inspect `exitCode` yourself.
-   */
-  exec(
-    service: string,
-    command: string | string[],
-    opts?: ComponentExecOpts,
-  ): Promise<ExecResult>;
-}
-
-/** Options for {@link ComponentContext.exec}. */
-export interface ComponentExecOpts {
-  /** Piped to the command's stdin, then closed. */
-  stdin?: string;
-  /** Working directory inside the container (`docker exec -w`). */
-  cwd?: string;
-  /** Kill the exec after this long. Default 120_000. */
-  timeoutMs?: number;
-}
-
-/** What a service's `setup` hook receives. */
-export interface ServiceSetupContext<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  H extends Record<string, any> = Record<string, never>,
-> extends ComponentContext {
-  /** The service's key in the services map (container + DNS name). */
-  name: string;
-  /** The record the service's `helpers` factory returned (cached — setup
-   *  and tests share one instance), or `{}` when it ships none. */
-  helpers: H;
-}
-
-/** What a service's `helpers` factory receives. */
-export interface ServiceHelpersContext extends ComponentContext {
-  /** The service's key in the services map (container + DNS name). */
-  name: string;
-}
-
-/**
- * Same shape as `ServiceConfig` plus an optional `helpers` factory that
- * opens a namespace under `ctx.svc.<name>` inside tests. The factory
- * returns a record — each key becomes `ctx.svc.<name>.<key>`. Components
- * like `postgres(...)` use this to expose a pre-wired SQL pool at
- * `ctx.svc.db.client`; nothing stops a component from exposing several
- * helpers under one service (e.g. `client`, `admin`, `truncate()`).
- */
-export interface ServiceDefinition<
-  // `any` (not `unknown`) so closed-shape interfaces — like
-  // `PostgresHelpers` — are assignable. The constraint is only here to
-  // signal intent ("helpers is a record of named conveniences");
-  // `ServiceHandlesFor<S>` infers the helpers' real type at use sites.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  H extends Record<string, any> = Record<string, never>,
-> extends ServiceConfig {
-  /**
-   * Build the helpers exposed at `ctx.svc.<name>.<key>`. Called by the
-   * daemon the first time a test touches this service; the result is
-   * cached for the lifetime of the daemon (it survives snapshot/fork
-   * along with the rest of daemon memory). `args.name` is the key the
-   * user chose in the services map and matches the in-VM DNS name; the
-   * rest of the {@link ServiceHelpersContext} (exec, projectRoot) lets a
-   * component reach into its containers without daemon internals.
-   */
-  helpers?: (args: ServiceHelpersContext) => H | Promise<H>;
-  /**
-   * One-shot setup after the container's `readyCheck` passes, before
-   * dependents start and before any test runs. Awaited in-line with
-   * bootstrap, so anything it produces (an ingress controller deployed
-   * into k3s, a schema applied to a database) is part of the warm-template
-   * snapshot and never re-runs on warm starts.
-   *
-   * `helpers` is the same record the `helpers` factory returns — building
-   * it is cached, so `setup` and tests share one instance. If the service
-   * doesn't declare `helpers`, the field is the empty object. The rest of
-   * the {@link ServiceSetupContext} carries `exec` (docker exec with
-   * stdin) and `projectRoot`/`readProjectFile` for project-file access.
-   */
-  setup?: (args: ServiceSetupContext<H>) => void | Promise<void>;
-}
-
-/** A services map — what users pass to `environment.services`. Entries
- * can be plain `ServiceConfig` literals or `ServiceDefinition`s that
- * carry a `helpers` factory (e.g. what `postgres(...)` returns). */
-export type ServicesMap = Record<string, ServiceConfig>;
-
-/** Awaited return type of a service's `helpers` factory, or `never` if
- * the service doesn't ship one. */
-type HelpersOf<D> = D extends {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  helpers: (...args: any) => infer R;
-}
-  ? Awaited<R>
-  : never;
-
-/**
- * Per-service handles derived from a concrete services map. Only
- * services that ship a `helpers` factory appear here; `ctx.svc.<name>`
- * is exactly the record the factory returned (e.g. `{ client: SqlClient }`
- * for `postgres(...)`). Services without helpers don't show up at all,
- * so plain `services: { api: { image: ... } }` adds no noise.
- */
-export type ServiceHandlesFor<S extends ServicesMap> = {
-  [K in keyof S as HelpersOf<S[K]> extends never ? never : K]: HelpersOf<S[K]>;
-};
-
-/** Loose, runtime-friendly shape of `ctx.svc` for code that doesn't
- * know the concrete services map (the daemon, generic helpers). The
- * typed `ctx.svc` in test bodies is `ServiceHandlesFor<S>`. */
-export type ServiceHandles = Record<string, Record<string, unknown>>;
-
-// ──────────────────────────────────────────────────────────────────────────
-// Service groups — one services-map entry that expands to several services.
-//
-// A single container is a `ServiceConfig`/`ServiceDefinition`; a component
-// that is inherently a *constellation* of containers (Supabase ≈ 7 of them)
-// is a `ServiceGroup`. The user mounts the whole group under ONE key:
-//
-//   services: { supabase: sb.group, app: { ... } }
-//
-// and `defineEnvironment` expands it: the group's `primary` part takes the
-// group's own key (`supabase`), every other part lands at `<key>-<part>`
-// (`supabase-db`, `supabase-auth`, …). Inside the group, `dependsOn`
-// entries naming a relative part are rewritten to the final keys, so a
-// group author never manually prefixes anything. Groups are pure sugar —
-// they expand to plain services before validation, so the wire config the
-// control plane sees is unchanged.
-// ──────────────────────────────────────────────────────────────────────────
-
-/** Symbol marking a value in the services map as a group to expand.
- * Enumerable-symbol convention (like the ingress `provides` decls): it
- * survives object spread but `JSON.stringify` drops it — not that a group
- * ever reaches the wire; expansion happens before the config exists. */
-const SERVICE_GROUP: unique symbol = Symbol.for("spectest.service.group");
-
-/**
- * Naming context handed to a group's `services` factory. Lets the factory
- * embed *final* DNS names in env vars and config files without knowing the
- * key the user will mount the group under.
- */
-export interface GroupNaming {
-  /** The services-map key the user chose for the group. */
-  name: string;
-  /** Final services-map key of a member part: `key(primary)` is `name`
-   *  itself; any other part maps to `` `${name}-${part}` ``. */
-  key(part: string): string;
-}
-
-export interface ServiceGroupInput<
-  P extends ServicesMap,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  H extends Record<string, any> = Record<string, never>,
-  Primary extends keyof P & string = keyof P & string,
-> {
-  /**
-   * Build the group's member services, keyed by RELATIVE part name
-   * (`db`, `auth`, …). Called at expansion time with the final naming
-   * context, so strings that must carry final DNS names (connection
-   * URLs, embedded config) use `g.key("db")`. `dependsOn` entries that
-   * name a relative part are rewritten to final keys automatically
-   * (entries that don't match a part pass through untouched, so a group
-   * service may still depend on an outside service).
-   */
-  services: (g: GroupNaming) => P;
-  /**
-   * The part that represents the group: it takes the group's own map key
-   * (so `dependsOn: ["<groupKey>"]` from outside waits for it), and it
-   * carries the group's consolidated `helpers`/`setup`. The primary is
-   * made the group's dependency **sink** — every other member is added to
-   * its `dependsOn` — so "the primary is ready" means "the whole group is
-   * up, setup included". Consequently no member may depend on the
-   * primary (that would be a cycle); pick a gateway/front-door part.
-   */
-  primary: Primary;
-  /**
-   * The group's consolidated handle: helpers exposed at
-   * `ctx.svc.<groupKey>` — one typed surface for the whole group (e.g.
-   * `{ sql, url, anonKey }` for Supabase). Attached to the primary
-   * service; the primary part itself must not also declare `helpers`.
-   */
-  helpers?: (args: ServiceHelpersContext) => H | Promise<H>;
-  /**
-   * Group-level setup: runs once every member service is ready (run →
-   * probe → per-part setup), before anything that `dependsOn` the group
-   * starts and before any test runs. The home for "the whole stack is
-   * up, now do X". Runs after the primary part's own `setup`, if any.
-   */
-  setup?: (args: ServiceSetupContext<H>) => void | Promise<void>;
-  /**
-   * Pin the services-map key the group must be mounted under. For
-   * components whose *derived* surface (connection URLs, env for the app
-   * under test) is computed from a name option before expansion — a
-   * mismatched key would silently split the two. Expansion errors with a
-   * pointer to the component's `name` option instead.
-   */
-  expectKey?: string;
-}
-
-/**
- * A multi-service component — the value `serviceGroup(...)` returns, and
- * what a constellation component (e.g. `supabase()`) hands you to put in
- * the services map. Opaque; `defineEnvironment` expands it.
- */
-export interface ServiceGroup<
-  P extends ServicesMap = ServicesMap,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  H extends Record<string, any> = Record<string, never>,
-  Primary extends keyof P & string = keyof P & string,
-> extends ServiceGroupInput<P, H, Primary> {
-  readonly [SERVICE_GROUP]: true;
-}
-
-/**
- * Define a multi-service group. See {@link ServiceGroupInput} for the
- * fields; the result goes straight into a services map:
- *
- * ```ts
- * const stack = serviceGroup({
- *   primary: "gateway",
- *   services: (g) => ({
- *     db:      { image: ..., ... },
- *     gateway: { image: ..., env: { DB_URL: `postgres://${g.key("db")}:5432/db` },
- *                dependsOn: ["db"] },
- *   }),
- *   helpers: () => ({ url: "http://..." }),
- * });
- *
- * defineEnvironment({ name: "app", services: { stack } });
- * // expands to services `stack` (the gateway) + `stack-db`;
- * // ctx.svc.stack is the helpers record.
- * ```
- */
-export function serviceGroup<
-  P extends ServicesMap,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  H extends Record<string, any> = Record<string, never>,
-  Primary extends keyof P & string = keyof P & string,
->(input: ServiceGroupInput<P, H, Primary>): ServiceGroup<P, H, Primary> {
-  if (typeof input.services !== "function") {
-    throw new Error("serviceGroup: `services` must be a factory function");
-  }
-  if (!input.primary || typeof input.primary !== "string") {
-    throw new Error("serviceGroup: `primary` (a relative part name) is required");
-  }
-  const group = { ...input } as ServiceGroup<P, H, Primary>;
-  Object.defineProperty(group, SERVICE_GROUP, {
-    value: true,
-    enumerable: true,
-    configurable: true,
-    writable: false,
-  });
-  return group;
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function isServiceGroup(v: unknown): v is ServiceGroup<any, any, any> {
-  return (
-    typeof v === "object" &&
-    v !== null &&
-    (v as Record<symbol, unknown>)[SERVICE_GROUP] === true
-  );
-}
-
-/** What users pass as `services` to `defineEnvironment`: plain services
- * and/or groups to expand. */
-export type InputServicesMap = Record<
-  string,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ServiceConfig | ServiceGroup<any, any, any>
->;
-
-type UnionToIntersection<U> = (
-  U extends unknown ? (x: U) => void : never
-) extends (x: infer I) => void
-  ? I
-  : never;
-
-/** Flatten an intersection of records into one mapped type (which also
- * gives it the implicit index signature `ServicesMap` needs). */
-type Reify<T> = { [K in keyof T]: T[K] };
-
-/** The primary part with the group's consolidated `helpers` grafted on,
- * so `ServiceHandlesFor` surfaces the group handle at the group key. */
-type PrimaryWithHandle<C, H> = [H] extends [Record<string, never>]
-  ? C
-  : Omit<C, "helpers"> & { helpers: (args: ServiceHelpersContext) => H };
-
-type ExpandGroupEntry<K extends string, G> = G extends ServiceGroup<
-  infer P,
-  infer H,
-  infer Primary
->
-  ? {
-      [Q in Exclude<keyof P & string, Primary> as `${K}-${Q}`]: P[Q];
-    } & { [Q in K]: PrimaryWithHandle<P[Primary & keyof P], H> }
-  : never;
-
-/**
- * The services map after group expansion — what `ctx.svc` and the wire
- * config are typed against. Groups expand to `<key>` (primary, carrying
- * the group handle) + `<key>-<part>` entries; plain services pass through.
- */
-export type ExpandServices<SI extends InputServicesMap> = Reify<
-  UnionToIntersection<
-    {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      [K in keyof SI & string]: SI[K] extends ServiceGroup<any, any, any>
-        ? ExpandGroupEntry<K, SI[K]>
-        : { [Q in K]: SI[K] };
-    }[keyof SI & string]
-  >
-> extends infer S extends ServicesMap
-  ? S
-  : ServicesMap;
-
-/**
- * Runtime counterpart of {@link ExpandServices}: expand every group entry
- * into plain services. Throws on key collisions, a missing primary,
- * nested groups, a violated `expectKey`, and members depending on the
- * primary (the primary is the group's sink — see
- * {@link ServiceGroupInput.primary}).
- */
-function expandServiceGroups(input: InputServicesMap): ServicesMap {
-  const out: ServicesMap = {};
-  const ownerOf = new Map<string, string>();
-  const claim = (key: string, owner: string): void => {
-    const prior = ownerOf.get(key);
-    if (prior !== undefined) {
-      throw new Error(
-        `service key ${JSON.stringify(key)} is produced by both ${prior} and ${owner}`,
-      );
-    }
-    ownerOf.set(key, owner);
-  };
-
-  for (const [key, entry] of Object.entries(input)) {
-    if (!isServiceGroup(entry)) {
-      claim(key, "the services map");
-      out[key] = entry;
-      continue;
-    }
-    const owner = `group ${JSON.stringify(key)}`;
-    if (entry.expectKey !== undefined && entry.expectKey !== key) {
-      throw new Error(
-        `service group at key ${JSON.stringify(key)} expects to be mounted at ` +
-          `${JSON.stringify(entry.expectKey)} — its derived names (URLs, app env) were built ` +
-          `from that name. Mount it at ${JSON.stringify(entry.expectKey)}, or pass ` +
-          `\`name: ${JSON.stringify(key)}\` to the component so both agree.`,
-      );
-    }
-    const naming: GroupNaming = {
-      name: key,
-      key: (part: string) => (part === entry.primary ? key : `${key}-${part}`),
-    };
-    const parts: ServicesMap = entry.services(naming);
-    const partKeys = new Set(Object.keys(parts));
-    if (!partKeys.has(entry.primary)) {
-      throw new Error(
-        `${owner}: primary part ${JSON.stringify(entry.primary)} is not in the parts the ` +
-          `services factory returned (${[...partKeys].join(", ")})`,
-      );
-    }
-    // No member may depend on the primary (directly or transitively within
-    // the group): the primary is about to become the group's sink.
-    const reachesPrimary = (part: string, seen = new Set<string>()): boolean => {
-      if (seen.has(part)) return false;
-      seen.add(part);
-      for (const dep of parts[part]?.dependsOn ?? []) {
-        if (!partKeys.has(dep)) continue;
-        if (dep === entry.primary || reachesPrimary(dep, seen)) return true;
-      }
-      return false;
-    };
-    for (const part of partKeys) {
-      if (isServiceGroup(parts[part])) {
-        throw new Error(`${owner}: part ${JSON.stringify(part)} is itself a group — groups don't nest`);
-      }
-      if (part !== entry.primary && reachesPrimary(part)) {
-        throw new Error(
-          `${owner}: part ${JSON.stringify(part)} depends on the primary ` +
-            `${JSON.stringify(entry.primary)} — the primary must be the group's sink ` +
-            `(everything else becomes its dependency so "primary ready" means "group up")`,
-        );
-      }
-    }
-    for (const [part, svc] of Object.entries(parts)) {
-      const finalKey = naming.key(part);
-      claim(finalKey, owner);
-      // Rewrite relative dependsOn to final keys; a spread keeps function
-      // fields (helpers/setup) and the enumerable-symbol ingress decls.
-      const final: ServiceConfig = { ...svc };
-      if (svc.dependsOn?.length) {
-        final.dependsOn = svc.dependsOn.map((d) =>
-          partKeys.has(d) ? naming.key(d) : d,
-        );
-      }
-      if (part === entry.primary) {
-        // Sink: the primary waits for every other member, so an outside
-        // `dependsOn: ["<groupKey>"]` (and the group `setup` below) means
-        // the whole group. Members already in dependsOn stay put.
-        const deps = new Set(final.dependsOn ?? []);
-        for (const other of partKeys) {
-          if (other !== entry.primary) deps.add(naming.key(other));
-        }
-        final.dependsOn = [...deps];
-        const def = final as ServiceDefinition<Record<string, unknown>>;
-        if (entry.helpers) {
-          if (def.helpers) {
-            throw new Error(
-              `${owner}: both the group and its primary part declare \`helpers\` — ` +
-                `declare them once, on the group`,
-            );
-          }
-          def.helpers = entry.helpers as (
-            args: ServiceHelpersContext,
-          ) => Record<string, unknown> | Promise<Record<string, unknown>>;
-        }
-        if (entry.setup) {
-          const partSetup = def.setup;
-          const groupSetup = entry.setup as (
-            args: ServiceSetupContext<Record<string, unknown>>,
-          ) => void | Promise<void>;
-          def.setup = async (args) => {
-            if (partSetup) await partSetup(args);
-            await groupSetup(args);
-          };
-        }
-      }
-      out[finalKey] = final;
-    }
-  }
-  return out;
-}
-
-/**
- * One TLS-terminated hostname for a service. The daemon binds the
- * hostname on `:443` (with a leaf cert signed by the in-VM root CA)
- * and `:80`, and reverse-proxies each request to `http://<service>:<port>`
- * inside the docker network. WebSocket upgrades are bridged.
- */
-export interface ServiceTls {
-  /** Fully-qualified hostname clients use (e.g. `app.test`). Must be
-   * multi-label, lowercase, not under the reserved `.internal` TLD,
-   * and unique across all services and fakes in this environment. */
-  hostname: string;
-  /** HTTP port the service listens on inside its container. The
-   * daemon forwards proxied requests here over `spectest-net`. */
-  port: number;
-}
-
-export type ServiceImage =
-  | { type: "registry"; reference: string }
-  | {
-      type: "dockerfile";
-      /**
-       * Dockerfile contents, written verbatim into the build context. The
-       * build context is the project root (where `spectest/` lives), so any
-       * `COPY` / `ADD` references resolve relative to that directory.
-       */
-      content: string;
-      /** Extra glob patterns to exclude from the build context. */
-      exclude?: readonly string[];
-    };
-
-export interface VolumeMount {
-  /**
-   * Named shared volume. Two services mounting the same `name` share one
-   * backing directory — the fit for sidecar pairs that exchange files
-   * (e.g. an image proxy reading what a storage API wrote). The directory
-   * lives in the per-env state tree, so it snapshots/forks with the rest
-   * of the environment and is torn down for fresh-state like any other
-   * volume. Names are environment-global: prefix with your service/group
-   * name in a reusable component so two instances never collide.
-   * Mutually exclusive with `source`.
-   */
-  name?: string;
-  /**
-   * Host path. Relative paths resolve under
-   * `.spectest/volumes/<service>/`. Defaults to a path derived from `target`.
-   */
-  source?: string;
-  /** Container path. */
-  target: string;
-  readOnly?: boolean;
-  /**
-   * Cache volume: the backing dir lives outside the per-env state tree and
-   * survives a delta-restore teardown (which recreates every container,
-   * volume, and the daemon for fresh-state semantics). Reserve this for
-   * content-addressed data whose presence is purely an accelerator — an
-   * image/layer store, a package cache — never for app state: anything in
-   * a cache volume is visible to the "fresh" environment.
-   */
-  cache?: boolean;
-}
-
-export interface FileMount {
-  /** Absolute path inside the container where the file is mounted. */
-  path: string;
-  /**
-   * File contents. The literal token `{{SPECTEST_SERVICE}}` is expanded
-   * to the owning service's name (its services-map key) before the file
-   * is written — handy for self-referential config like a registry host
-   * of `<key>.internal`, where a component can't know the key in advance.
-   */
-  content: string;
-  /**
-   * Optional octal mode string (e.g. `"0644"`) applied to the staged
-   * file before it's bind-mounted. Defaults to the writer's umask.
-   */
-  mode?: string;
-}
-
-export type ReadyCheck =
-  | { type: "tcp"; port: number; timeoutSecs?: number }
-  | {
-      type: "http";
-      port: number;
-      path?: string;
-      /**
-       * Extra request headers sent with each probe — for health endpoints
-       * behind auth (`{ Authorization: "Bearer …" }`). Keeps the probe
-       * image-agnostic where an `exec` + curl would depend on curl being
-       * in the image.
-       */
-      headers?: Record<string, string>;
-      /**
-       * Exact status code that counts as ready. Default: any 2xx. Use for
-       * endpoints whose healthy answer isn't 2xx (e.g. a root path that
-       * 301s or 401s once the server is actually up).
-       */
-      expectStatus?: number;
-      timeoutSecs?: number;
-    }
-  /**
-   * Run a shell command inside the container; exit 0 = ready. Used when
-   * the readiness signal isn't reachable via plain TCP/HTTP from outside
-   * (k3s API server uses mTLS, so the natural probe is `kubectl get
-   * --raw=/readyz` from inside).
-   */
-  | { type: "exec"; command: string; timeoutSecs?: number };
-
-// ──────────────────────────────────────────────────────────────────────────
-// Runtime services — containers started *during* a test/eval/setup or from
-// inside a fake handler, rather than declared up-front in `services`.
-// ──────────────────────────────────────────────────────────────────────────
-
-/**
- * Spec for a service started at runtime via {@link TestContext.startService}
- * (or the `ctx` handed to a fake). It's a normal {@link ServiceConfig} plus a
- * required `name`, minus only `dependsOn` (there is no boot DAG at runtime;
- * the caller orders `startService` calls itself with `await`).
- *
- * The container joins `spectest-net` with its own IP and is resolvable by
- * `name` (single-label, via the resolver / docker embedded DNS) and by any
- * `hostnames` (extra `--network-alias`es). Like everything else in the VM it
- * is captured by the per-test post-state snapshot, so a `dependsOn` child
- * inherits the live container while siblings never see it.
- *
- * `tls: [{ hostname, port }]` works exactly as it does for a boot service:
- * the daemon mints a leaf cert from the in-VM root CA and stands up a
- * TLS-terminating reverse proxy at `https://<hostname>/` (and plain
- * `http://<hostname>/`) → the container's `port`, binding it onto the live
- * `:443`/`:80` ingress listeners the moment the container is ready. The
- * hostname resolves to the daemon gateway for tests, `ctx.browser()`, and
- * peer containers. Because the route lives in daemon memory (and the
- * resolver registry file), it forks with the per-test snapshot like fake
- * state, and is torn down when the service is stopped. This lets a runtime
- * provider mint a CA-trusted HTTPS endpoint on demand — e.g. a per-DB proxy
- * the Neon serverless driver reaches at its *default* `https://<host>/sql`.
- */
-export interface RuntimeServiceSpec extends Omit<ServiceConfig, "dependsOn"> {
-  /**
-   * Container name and primary DNS name on `spectest-net`. Must be unique
-   * within the current fork — generate a fresh one per provisioned instance
-   * (e.g. `db-${crypto.randomUUID().slice(0, 8)}`).
-   */
-  name: string;
-}
-
-/** What {@link TestContext.startService} resolves to once the container is up
- *  and its `readyCheck` (if any) has passed. */
-export interface RuntimeServiceHandle {
-  /** The container/DNS name — the spec's `name`. */
-  name: string;
-  /** The container's IP on `spectest-net`. Reachable directly from peer
-   *  containers and from VM-host/test code. */
-  ip: string;
-}
-
-/**
- * The slice of the environment a fake can mutate at runtime — the same
- * primitives {@link TestContext} exposes to tests. Passed as the third
- * argument to a fake's `handler` and as `ctx` to its `helpers` factory, so
- * a fake (e.g. a database-provider control plane) can provision real
- * backing services on demand and wire up DNS for them, exactly as a test
- * would.
- */
-export interface FakeContext {
-  /** Start a real container on `spectest-net` at runtime. See
-   *  {@link RuntimeServiceSpec}. */
-  startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
-  /** Stop and remove a runtime service started earlier (no-op if gone). */
-  stopService(name: string): Promise<void>;
-  /** Map a DNS name onto a service IP (or the daemon ingress). See
-   *  {@link TestContext.dnsName}. */
-  dnsName(hostname: string, target: DnsTarget): Promise<void>;
-}
-
-function validateEnvironmentConfig<S extends ServicesMap>(
-  config: EnvironmentConfig<S>,
-): void {
-  const entries = Object.entries(config.services);
-  const serviceNames = new Set(entries.map(([n]) => n));
-  const claimedBy = new Map<string, string>();
-  const claimBy = (h: string, name: string, kind: "hostname" | "tls"): void => {
-    const prior = claimedBy.get(h);
-    if (prior !== undefined && prior !== name) {
-      throw new Error(
-        `hostname ${JSON.stringify(h)} is claimed by both "${prior}" and "${name}"`,
-      );
-    }
-    if (serviceNames.has(h)) {
-      throw new Error(
-        `${kind} ${JSON.stringify(h)} collides with service name "${h}"`,
-      );
-    }
-    claimedBy.set(h, name);
-  };
-  for (const [name, svc] of entries) {
-    if (name.length === 0) {
-      throw new Error(
-        "service name (services map key) must be a non-empty string",
-      );
-    }
-    for (const dep of svc.dependsOn ?? []) {
-      if (!serviceNames.has(dep)) {
-        throw new Error(
-          `service "${name}" dependsOn "${dep}" which is not a service in this environment`,
-        );
-      }
-    }
-    for (const vol of svc.volumes ?? []) {
-      if (vol.name !== undefined && vol.source !== undefined) {
-        throw new Error(
-          `service "${name}" volume for ${JSON.stringify(vol.target)} sets both \`name\` and \`source\` — a named shared volume derives its backing dir from the name`,
-        );
-      }
-      if (vol.name !== undefined && !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(vol.name)) {
-        throw new Error(
-          `service "${name}" volume name ${JSON.stringify(vol.name)} must be alphanumeric plus [._-]`,
-        );
-      }
-    }
-    for (const raw of svc.hostnames ?? []) {
-      const h = raw.toLowerCase();
-      if (!HOSTNAME_RE.test(h)) {
-        throw new Error(
-          `service "${name}" declares invalid hostname ${JSON.stringify(raw)} — must be a multi-label DNS name (e.g. "api.stripe.com")`,
-        );
-      }
-      if (h === "internal" || h.endsWith(".internal")) {
-        throw new Error(
-          `service "${name}" declares hostname ${JSON.stringify(raw)} — the ".internal" TLD is reserved; every service already answers to "<name>.internal" automatically`,
-        );
-      }
-      claimBy(h, name, "hostname");
-    }
-    for (const entry of svc.tls ?? []) {
-      if (!entry || typeof entry.hostname !== "string" || typeof entry.port !== "number") {
-        throw new Error(
-          `service "${name}" tls entry must be { hostname: string, port: number }; got ${JSON.stringify(entry)}`,
-        );
-      }
-      const h = entry.hostname.toLowerCase();
-      if (!HOSTNAME_RE.test(h)) {
-        throw new Error(
-          `service "${name}" tls hostname ${JSON.stringify(entry.hostname)} is not a multi-label DNS name (e.g. "app.test")`,
-        );
-      }
-      if (h === "internal" || h.endsWith(".internal")) {
-        throw new Error(
-          `service "${name}" tls hostname ${JSON.stringify(entry.hostname)} ends in reserved ".internal" TLD`,
-        );
-      }
-      if (!Number.isInteger(entry.port) || entry.port <= 0 || entry.port > 65535) {
-        throw new Error(
-          `service "${name}" tls hostname ${JSON.stringify(entry.hostname)} has invalid port ${entry.port}`,
-        );
-      }
-      claimBy(h, name, "tls");
-    }
-  }
-}
-
-// Multi-label hostname: at least one dot, each label 1–63 chars of
-// [a-z0-9-], no leading/trailing hyphen.
-const HOSTNAME_RE =
-  /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/;
-
-// ──────────────────────────────────────────────────────────────────────────
-// Test framework
-// ──────────────────────────────────────────────────────────────────────────
-
-/**
- * A single test step. Created via `test(...)` or `createTest(services)`.
- * Tests are referenced (not named by string) when one test depends on
- * another — keeps refactors and type-checking honest.
- *
- * `T` is the return type of the test body; it surfaces as `ctx.parent`
- * in children that `dependsOn` this case. `S` is the project's services
- * map (threaded through `defineEnvironment(...).test`) so `ctx.svc.<key>`
- * is strongly typed.
- */
-export interface TestCase<
-  T = unknown,
-  S extends ServicesMap = ServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  /** Stable id (slug of name). Used in MCP responses and CLI flags. */
-  readonly id: string;
-  readonly name: string;
-  /** Parent test, if any. Single-parent for now. */
-  readonly dependsOn?: TestCase<unknown, S, F>;
-  /** Override the default per-test timeout (default 60s). */
-  readonly timeoutMs?: number;
-  /** @internal — the body that the in-sandbox daemon invokes. */
-  readonly run: TestFn<T, unknown, S, F>;
-}
-
-export interface TestOpts<
-  P = undefined,
-  S extends ServicesMap = ServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  dependsOn?: TestCase<P, S, F>;
-  timeoutMs?: number;
-}
-
-export type TestFn<
-  T = void,
-  P = undefined,
-  S extends ServicesMap = ServicesMap,
-  F extends FakesMap = FakesMap,
-> = (ctx: TestContext<P, S, F>) => T | Promise<T>;
-
-/**
- * Context object passed to every test function.
- *
- * `P` is the return type of the parent test (the one named in
- * `dependsOn`); for root tests it's `undefined`. `S` is the project's
- * services map (threaded through `defineEnvironment(...).test`) so
- * `ctx.svc` only includes services with a `client` factory, each typed
- * as the factory's output (e.g. a Bun SQL pool for `postgres(...)`).
- */
-export interface TestContext<
-  P = undefined,
-  S extends ServicesMap = ServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  /**
-   * Instrumented `fetch`, exposed on `ctx`. Each call is recorded on the
-   * test timeline and resolves to a {@link WrappedResponse}: reads carry
-   * provenance so `expect(res.status)` / `expect(await res.json())` nest
-   * under the HTTP call. Because the status-line accessors are
-   * {@link Carrier}s, a raw `res.status === 200` is a *type error* — use
-   * `res.status.unwrap()` / `res.unwrap().status`, or assert via `expect`.
-   *
-   * (The plain global `fetch` is wrapped the same way at runtime but keeps
-   * the standard `Response` type, so prefer `ctx.fetch` for honestly-typed
-   * results.)
-   */
-  fetch: SpectestFetch;
-  /** Run `sh -lc <command>` inside a service container. The result is
-   *  {@link Wrapped}, so `res.stdout` is a `Carrier<string>` — assert via
-   *  `expect(res.stdout)` or recover the raw string with `res.stdout.unwrap()`.
-   *  (In `setup`/`eval` the result is wrapped too, just without a timeline
-   *  link, so `.unwrap()` works there the same way.)
-   *
-   *  The full run is also captured as an asciicast and replayed in the
-   *  web UI — one recording per call, with output timestamped as it
-   *  streamed, so slow or animated CLI output can be watched rather
-   *  than read as a final blob. Unlike `terminal` there is no PTY: the
-   *  program sees plain pipes (`isatty` false), so stdout/stderr stay
-   *  byte-identical to what `exec` always returned and TTY-gated
-   *  spinners/colour won't be emitted — reach for `terminal` when the
-   *  CLI needs to believe it's on a TTY.
-   *
-   *  Pass `{ cwd }` to run the command from a working directory instead of
-   *  prefixing it with `cd <dir> && ` — the cwd is kept off the command
-   *  string, so the timeline sidebar shows just the command and the
-   *  directory surfaces in the detail view. */
-  exec(
-    service: string,
-    command: string,
-    opts?: ExecOpts,
-  ): Promise<Wrapped<ExecResult>>;
-  /**
-   * Run a command inside a service container under a PTY and record the
-   * full terminal session as an asciicast for replay in the web UI.
-   * Unlike `exec`, the program sees a TTY (`isatty(1)` true, colour
-   * codes preserved, line-buffered), so the byte stream may differ from
-   * what `exec` returns. Reach for `terminal` when you're driving a CLI
-   * and want a recording; reach for `exec` for plain piped output.
-   *
-   * One-shot convenience: this is a thin wrapper over `openTerminal` —
-   * spawn `command`, wait for exit, close, return the captured output
-   * and exit code. Reach for `openTerminal` when you want to keep the
-   * session alive across multiple sends or `waitFor` predicates (e.g.
-   * driving an interactive REPL or waiting on a loading spinner).
-   */
-  terminal(
-    service: string,
-    command: string,
-    opts?: TerminalOpts,
-  ): Promise<Wrapped<TerminalResult>>;
-  /**
-   * Open a long-lived interactive terminal in a service container.
-   * Returns a `Terminal` you can `send` keystrokes to, poll the
-   * rendered screen with `waitFor`, and `close` when done. Every byte
-   * the PTY emits is captured as an asciicast and replayed in the web
-   * UI the same way a one-shot `terminal(...)` is.
-   *
-   * Terminals are NOT auto-closed when the test ends. A docker exec
-   * subprocess is cheap to keep alive and Freestyle captures it
-   * cleanly in the snapshot along with the rest of the container, so
-   * leaking the handle past test end is fine. Call `.close()`
-   * explicitly if you want a `close` step in the timeline; otherwise
-   * `await term.exited` (after the program self-terminates) is the
-   * natural way to assert on the exit code.
-   */
-  openTerminal(service: string, opts?: TerminalOpts): Promise<Terminal>;
-  /**
-   * Open the headless browser. Backed by Chromium-over-CDP inside the VM.
-   *
-   * There is ONE persistent browser per environment: every `ctx.browser()`
-   * call returns it, and it stays alive across tests — the browser is part
-   * of the state a test's snapshot captures, so a `dependsOn` child resumes
-   * the exact live page its parent left (cookies, localStorage, signed-in
-   * SPA state). Sign in once in a parent test; every descendant is already
-   * signed in. Sibling tests fork from the same parent snapshot, so they
-   * can't see each other's browsing. A test with no browser-using ancestor
-   * gets a fresh browser on first call (first call's options win).
-   *
-   * `.close()` destroys the shared instance — the next `ctx.browser()`
-   * starts fresh. Don't call it for routine cleanup; recording is detached
-   * automatically at test end.
-   */
-  browser(opts?: BrowserOptions): Promise<Browser>;
-  /**
-   * Open a phone-emulated session for a mobile app and return a {@link Mobile}
-   * handle already pointed at it — no `navigate`. Pass the app handle a
-   * mobile-app component exposes on `ctx.svc`, e.g. a service declared with
-   * `expo()`:
-   *
-   * ```ts
-   * services: { app: expo() }
-   * // in a test:
-   * const m = await ctx.mobile(ctx.svc.app);
-   * await m.getByTestId("email").fill("a@b.com");
-   * await m.getByRole("button", { name: "Sign in" }).tap();
-   * await expect(m.getByText(/Welcome/)).toBeVisible();
-   * ```
-   *
-   * The session emulates the latest iPhone (viewport + DPR + mobile UA +
-   * touch) and the dashboard replays it inside a phone bezel.
-   *
-   * Sessions are persistent, one per app: like `ctx.browser()`, the live
-   * session is captured in the test's snapshot, so a `dependsOn` child
-   * picks up the app exactly where the parent left it (already signed in,
-   * mid-flow) instead of reloading it. `.close()` discards the session;
-   * the next `ctx.mobile(app)` opens the app fresh.
-   */
-  mobile(app: MobileApp): Promise<Mobile>;
-  /** The test's display name. */
-  readonly testName: string;
-  /**
-   * Value returned by the parent test. Carried across the fork in the
-   * daemon's own memory (Freestyle's snapshot is memory + filesystem), so
-   * any JS value works — including Maps, Sets, class instances, and live
-   * connections that survive the fork. `undefined` for root tests or when
-   * the parent returned nothing.
-   */
-  readonly parent: P;
-  /**
-   * Per-service helper namespaces, keyed by service name. Only services
-   * whose definition ships a `helpers` factory appear here; the value at
-   * `ctx.svc.<name>` is exactly the record that factory returned. For a
-   * `postgres(...)` service that ships `{ client }`, tests do
-   * `await ctx.svc.db.client\`SELECT 1\``.
-   */
-  readonly svc: ServiceHandlesFor<S>;
-  /**
-   * Per-fake helper namespaces, keyed by fake name. Each is the record
-   * of functions the fake's `helpers` factory returned (or `{ state }`
-   * when it ships none — tests never touch a fake's private state
-   * directly). Those functions read/mutate the fake's state internally;
-   * the state itself is in-process and lives across the fork along with
-   * the rest of daemon memory, so calls in a child test see the fork's
-   * own copy as mutated by its ancestors. Every helper call is recorded
-   * as a step and its return value tracked, so assertions on it nest
-   * under the call in the timeline.
-   *
-   * Strongly typed against the project's fakes map when fakes are
-   * declared in `defineEnvironment({ ..., fakes })`: `ctx.fakes.stripe`
-   * is exactly the helpers record `defineFake`'s `helpers` factory
-   * returned — no cast. (Falls back to a loose record only when the
-   * environment declares no fakes.)
-   */
-  readonly fakes: FakeHandlesFor<F>;
-  /**
-   * Poll a predicate until it returns a truthy value, then return that
-   * value. Records one `wait` event for the whole loop (with attempt
-   * count, total duration, and the description) instead of one event
-   * per probe — useful for "wait until pod Running"-style checks where
-   * the intermediate states are noise.
-   *
-   * - `null`, `undefined`, or `false` from `fn` mean "not yet" — wait
-   *   `intervalMs` and try again.
-   * - Anything else is the success value and is returned, tagged with
-   *   the wait event's seq. Downstream `expect(...)` on it links to
-   *   the wait (one logical step), not to N suppressed HTTP calls.
-   * - Throws from `fn` propagate out immediately; the wait event is
-   *   still recorded (with `error` set) so the timeline reflects the
-   *   abort.
-   * - Defaults: `timeoutMs = 30_000`, `intervalMs = 1_000`.
-   *
-   * Side-effect calls inside `fn` (fetch, ctx.svc.* helpers, etc.)
-   * don't show up on the event log — the recorder is paused for the
-   * duration. Use `ctx.poll` for read-only observation, not for
-   * stateful work you want recorded.
-   */
-  poll<T>(
-    description: string,
-    fn: () => T | null | undefined | false | Promise<T | null | undefined | false>,
-    opts?: { timeoutMs?: number; intervalMs?: number },
-  ): Promise<Wrapped<T>>;
-  /**
-   * Register a DNS name at runtime so the rest of this test (and anything
-   * downstream of it) can reach it. `{ ingress: true }` points the name at
-   * the daemon (a fake / TLS proxy); `{ service }` points it at a
-   * container's live IP; a `*.suffix` wildcard (e.g. `"*.example.com"`)
-   * routes a whole domain — the natural fit for k3s Ingress hosts a test
-   * applies on the fly.
-   *
-   * Answered by spectest-resolver, so it works for VM-host/test code,
-   * `ctx.browser()`, and peer containers (Docker forwards unknown names to
-   * the host resolver). It does NOT land in any container's `/etc/hosts`.
-   * The registration mutates in-daemon state, so it's isolated to this
-   * test's fork — like fake state.
-   *
-   * ```ts
-   * await ctx.svc.k8s.apply(ingressFor("foo.example.com"));
-   * await ctx.dnsName("foo.example.com", { service: "k8s" });
-   * const res = await ctx.fetch("http://foo.example.com");
-   * ```
-   */
-  dnsName(hostname: string, target: DnsTarget): Promise<void>;
-  /**
-   * Start a real container on `spectest-net` at runtime — a peer machine
-   * with its own IP, reachable like any boot service. Returns once the
-   * container is up and its `readyCheck` (if any) has passed.
-   *
-   * The new container is part of this test's post-state snapshot, so a
-   * `dependsOn` child inherits it (same PID, same data) while siblings,
-   * which fork from the parent's earlier snapshot, never see it — the same
-   * isolation fake `state` and {@link dnsName} get. Reach it by `name`
-   * (single-label, via the resolver) or by any `hostnames` you pass; map a
-   * multi-label name onto it with `ctx.dnsName(host, { service: name })`.
-   *
-   * The image is pulled on first use (fast through the host cache). See
-   * {@link RuntimeServiceSpec}.
-   *
-   * ```ts
-   * const { name } = await ctx.startService({
-   *   name: `db-${crypto.randomUUID().slice(0, 8)}`,
-   *   image: { type: "registry", reference: "postgres:16-alpine" },
-   *   env: { POSTGRES_PASSWORD: "secret" },
-   *   readyCheck: { type: "exec", command: "pg_isready -h 127.0.0.1 -p 5432" },
-   * });
-   * const sql = new Bun.SQL(`postgres://postgres:secret@${name}:5432/postgres`);
-   * ```
-   */
-  startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
-  /** Stop and remove a runtime service started via {@link startService}
-   *  (no-op if it's already gone). */
-  stopService(name: string): Promise<void>;
-}
-
-export interface ExecResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
-
-/** Options for {@link TestContext.exec}. */
-export interface ExecOpts {
-  /**
-   * Working directory inside the container to run the command from.
-   * Equivalent to prefixing the command with `cd <cwd> && `, but the
-   * directory is kept off the command string: the recorded step's
-   * sidebar summary shows just the command, while the working directory
-   * is surfaced in the detail view (the prompt line of the captured
-   * terminal and the step's panel header). Implemented as `docker exec
-   * -w <cwd>`, so a relative path resolves against the image's WORKDIR.
-   */
-  cwd?: string;
-}
-
-export interface TestSuite<
-  S extends ServicesMap = ServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  tests: TestCase<unknown, S, F>[];
-}
-
-// ──────────────────────────────────────────────────────────────────────────
-// Fakes — in-daemon HTTP servers that masquerade as external APIs.
-// ──────────────────────────────────────────────────────────────────────────
-
-/**
- * A fake server hosted in the spectest-daemon. Use this to stand in for
- * external HTTP APIs (auth providers, payment gateways, …) that you can't
- * call directly from the hermetic test VM.
- *
- * Each fake declares one or more `hostnames` it answers to. The daemon
- * binds an HTTP listener per unique `port` on 0.0.0.0 (the bridge gateway
- * is reachable from every service container), and `spectest-resolver`
- * answers DNS for those hostnames with the bridge gateway IP. Containers
- * doing `fetch("http://api.stripe.com/v1/charges")` route into the daemon,
- * which dispatches to the matching fake by Host header.
- *
- * Internal state lives in plain JS memory — it forks with the rest of the
- * snapshot, so per-test forks start from a known baseline and each fork
- * has its own copy. State is private to the fake; expose it for assertions
- * via `helpers` functions that tests call as `ctx.fakes.<name>.<fn>(...)`.
- *
- * HTTPS works out of the box. Every fake is auto-bound on :443 with a
- * leaf cert signed by the in-VM root CA (SANs = `hostnames`), and
- * every service container trusts that CA via bind-mount + system-trust
- * layer — point your app at `https://api.stripe.com` and it Just Works.
- * HTTP also stays bound on `port` (default 80) for back-compat.
- */
-export interface FakeDefinition<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  S = any,
-  H extends Record<string, unknown> = Record<string, never>,
-> {
-  /** Stable name. Used as the key in `ctx.fakes` and in logs/UI. */
-  name: string;
-  /**
-   * Fully-qualified hostnames the fake answers to (e.g.
-   * `"api.stripe.com"`). Same rules as service `hostnames`: multi-label,
-   * lowercase, no `.internal` suffix, no collisions with services or
-   * other fakes.
-   */
-  hostnames: readonly string[];
-  /** TCP port the fake listens on. Default `80`. */
-  port?: number;
-  /**
-   * Build the fake's initial state. Called once when the project loads.
-   * The returned value lives in daemon memory for the rest of the
-   * environment's life — it survives `bootstrap`, the warm-template
-   * snapshot, and every per-test fork (each fork sees its own copy).
-   */
-  state?: () => S | Promise<S>;
-  /**
-   * HTTP handler. Receives a standard `Request` (Bun-native), the fake's
-   * mutable `state`, and a {@link FakeContext} `ctx` for mutating the
-   * environment at runtime (e.g. `ctx.startService(...)` to provision a
-   * real backing instance, `ctx.dnsName(...)` to name it). Return any
-   * `Response`. Thrown errors surface as 500s. The request URL is the
-   * absolute URL the client used — useful for routing on the path.
-   */
-  handler: (req: Request, state: S, ctx: FakeContext) => Response | Promise<Response>;
-  /**
-   * Build the helpers exposed at `ctx.fakes.<name>` — a record of
-   * **functions** that read or mutate the fake's `state` (received here)
-   * via closure. Called the first time a test touches the fake; result
-   * is cached for the daemon's life. Omit it and tests see `{}`: state
-   * stays private, reachable only through the functions you expose
-   * (e.g. `{ lastCharge(), declineSource(src) }`). Don't expose raw
-   * `state` or use getters — return copies/derived values from functions
-   * instead.
-   *
-   * Every call is tracked in the test timeline: it records a `fake` step
-   * and the return value is tagged so a later `expect(...)` on it nests
-   * under that step in the UI (same provenance as `fetch`/db results).
-   *
-   * Receives the fake's `state` plus a {@link FakeContext} `ctx`, so a
-   * helper can provision/teardown runtime services just like the handler.
-   */
-  helpers?: (args: { name: string; state: S; ctx: FakeContext }) => H | Promise<H>;
-  /**
-   * Internal. Platform secret references this fake needs at *record* time
-   * (set by {@link replayFake}). The daemon reports the union of these to
-   * the control plane, which resolves each via its `SecretResolver` and
-   * pushes the values on the eval path only — they never enter project
-   * files, the config hash, or a cassette. Not part of the authoring
-   * surface; `JSON.stringify` ignores it (fakes never serialize to config).
-   */
-  secretRefs?: readonly string[];
-}
-
-/**
- * Define a fake. `defineFake({ ... })` is a thin wrapper that pins the
- * generic `S` and `H` so `helpers`/`handler` see the inferred state type
- * without the caller having to spell it out twice.
- */
-export function defineFake<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  S = any,
-  H extends Record<string, unknown> = Record<string, never>,
->(opts: FakeDefinition<S, H>): FakeDefinition<S, H> {
-  if (!opts.name || opts.name.length === 0) {
-    throw new Error("defineFake: `name` is required");
-  }
-  if (!Array.isArray(opts.hostnames) || opts.hostnames.length === 0) {
-    throw new Error(`defineFake(${opts.name}): at least one hostname is required`);
-  }
-  for (const h of opts.hostnames) {
-    const lower = h.toLowerCase();
-    if (!HOSTNAME_RE.test(lower)) {
-      throw new Error(
-        `defineFake(${opts.name}): invalid hostname ${JSON.stringify(h)} — must be a multi-label DNS name (e.g. "api.stripe.com")`,
-      );
-    }
-    if (lower === "internal" || lower.endsWith(".internal")) {
-      throw new Error(
-        `defineFake(${opts.name}): hostname ${JSON.stringify(h)} ends in reserved ".internal" TLD`,
-      );
-    }
-  }
-  if (typeof opts.handler !== "function") {
-    throw new Error(`defineFake(${opts.name}): \`handler\` is required`);
-  }
-  return opts;
-}
-
-/** Map of fake-name -> FakeDefinition, keyed by stable name. `any` for
- * both generic args (not the bare `FakeDefinition` default of
- * `<any, Record<string, never>>`) so a concrete fake that ships real
- * `helpers` — whose `helpers`/`handler` function types would otherwise be
- * invariant-incompatible with the narrower default — is still assignable.
- * The precise per-fake helper types are recovered by `FakeHandlesFor<F>`
- * at use sites. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type FakesMap = Record<string, FakeDefinition<any, any>>;
-
-/** Rewrite a helpers record so each function's result is inspect-wrapped
- * ({@link Wrapped}) — mirroring the runtime, where `trackFakeHelpers` wraps
- * every helper return value for assertion provenance. Without this the raw
- * return type (e.g. `Charge[]`) reaches `expect`, which the `Provenanced`
- * gate rejects. Handles sync and async helpers; non-function members (and
- * `void` side-effect helpers) pass through untouched. Mirrors `Tagged<T>` in
- * `components/k3s.ts`, extended to cover synchronous returns. */
-type WrappedHelpers<H> = {
-  [K in keyof H]: H[K] extends (...args: infer A) => Promise<infer R>
-    ? (...args: A) => Promise<Wrapped<R>>
-    : H[K] extends (...args: infer A) => infer R
-      ? (...args: A) => [R] extends [void] ? void : Wrapped<R>
-      : H[K];
-};
-
-/** Awaited return type of a fake's `helpers` factory (with each result
- * inspect-wrapped, see {@link WrappedHelpers}), or `{ state: S }` (the
- * default) when the user didn't ship one. */
-type FakeHelpersOf<F> = F extends FakeDefinition<infer S, infer H>
-  ? [H] extends [Record<string, never>]
-    ? { state: S }
-    : WrappedHelpers<H>
-  : never;
-
-/** Per-fake handles derived from a concrete fakes map; what tests see at
- * `ctx.fakes`. For a concrete map (fakes declared in `defineEnvironment`)
- * each key is the precise helpers record. When `F` is the loose default
- * `FakesMap` (no fakes declared, or generic daemon-side code), this
- * collapses to a permissive record so untyped access still compiles. */
-export type FakeHandlesFor<F extends FakesMap> = string extends keyof F
-  ? Record<string, Record<string, unknown>>
-  : { [K in keyof F]: FakeHelpersOf<F[K]> };
-
-/**
- * A `test(...)` function bound to a concrete services map (and fakes map).
- * Returned by `defineEnvironment(...).test`; gives tests fully-typed access
- * to `ctx.svc.<key>` and `ctx.fakes.<key>` without per-call casts.
- */
-export interface TypedTest<
-  S extends ServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  <T = void>(name: string, fn: TestFn<T, undefined, S, F>): TestCase<T, S, F>;
-  <T = void, P = undefined>(
-    name: string,
-    opts: TestOpts<P, S, F>,
-    fn: TestFn<T, P, S, F>,
-  ): TestCase<T, S, F>;
-}
-
-// ──────────────────────────────────────────────────────────────────────────
-// Project (the unified default export)
-// ──────────────────────────────────────────────────────────────────────────
-
-/**
- * A complete project definition: an environment, an optional one-shot
- * setup hook, and an optional test suite. `spectest/index.ts`
- * default-exports one of these via `env.project([...tests])` or
- * `env.project({ setup, tests })`.
- */
-export interface Project<
-  S extends ServicesMap = ServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  environment: EnvironmentConfig<S>;
-  /**
-   * Fake servers hosted in the spectest-daemon (see {@link defineFake}).
-   * Keyed by stable fake name; the key becomes the slot in
-   * `ctx.fakes.<key>` from test code. Populated from the `fakes` declared
-   * in `defineEnvironment(...)`.
-   */
-  fakes?: F;
-  /**
-   * Project-level setup. Runs once, after every service is Ready and
-   * its per-service `setup` has completed, before the warm-template
-   * snapshot. Use this for state that's part of "the environment as
-   * the tests expect to find it" — seed data in a database, an initial
-   * Deployment in k3s, etc. Like service-level setup, the result is
-   * captured by every snapshot taken from that point, so warm restore
-   * and per-test forks inherit it without re-running.
-   *
-   * The ctx here is a slimmer cousin of TestContext: no recorder, no
-   * timeout, no browser/terminal — setup is not a test and doesn't
-   * appear in the timeline.
-   */
-  setup?: ProjectSetupFn<S, F>;
-  tests?: TestSuite<S, F>;
-}
-
-/**
- * Slim context handed to the project-level `setup` hook. Same shape as
- * `TestContext` but pared down — no testName, no parent, no recording
- * surfaces (browser, terminal, poll). If you need polling inside setup,
- * write a plain loop: setup runs outside the test timeline so there's
- * nothing to record into.
- */
-export interface ProjectSetupContext<
-  S extends ServicesMap = ServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  fetch: SpectestFetch;
-  exec(
-    service: string,
-    command: string,
-    opts?: ExecOpts,
-  ): Promise<Wrapped<ExecResult>>;
-  readonly svc: ServiceHandlesFor<S>;
-  /** Same surface tests see — fakes are already up by setup time. Typed
-   * against the declared fakes map (see {@link TestContext.fakes}). */
-  readonly fakes: FakeHandlesFor<F>;
-  /**
-   * Register a DNS name (see {@link TestContext.dnsName}). Useful here to
-   * wire a wildcard like `"*.example.com"` to a k3s cluster once, before
-   * any test runs — it's captured into the warm-template snapshot, so every
-   * test inherits the route without re-registering.
-   */
-  dnsName(hostname: string, target: DnsTarget): Promise<void>;
-  /**
-   * Start a runtime service (see {@link TestContext.startService}). Started
-   * here, it's captured into the warm-template snapshot and inherited by
-   * every test — use it for backing instances that should exist before any
-   * test runs but aren't worth a boot-time `services` entry.
-   */
-  startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
-  /** Stop a runtime service (see {@link TestContext.stopService}). */
-  stopService(name: string): Promise<void>;
-}
-
-export type ProjectSetupFn<
-  S extends ServicesMap = ServicesMap,
-  F extends FakesMap = FakesMap,
-> = (ctx: ProjectSetupContext<S, F>) => void | Promise<void>;
-
-/**
- * A defined environment. Returned by `defineEnvironment(...)` and used to
- * (a) build typed tests against this environment's services and (b)
- * bundle those tests into the project's default export.
- *
- * ```ts
- * const env = defineEnvironment({
- *   name: "todos",
- *   services: {
- *     db: postgres({ database: "todos", user: "todos", password: "todos" }),
- *   },
- * });
- *
- * const createTodo = env.test("create todo", async (ctx) => {
- *   // ctx.svc.db.client is the Bun SQL pool (the helper postgres ships).
- *   await ctx.svc.db.client`SELECT 1`;
- *   return { id: 1 };
- * });
- *
- * const markDone = env.test(
- *   "mark done",
- *   { dependsOn: createTodo },
- *   async (ctx) => {
- *     // ctx.parent is { id: number }
- *     await ctx.svc.db.client`UPDATE todos SET done = TRUE WHERE id = ${ctx.parent.id}`;
- *   },
- * );
- *
- * export default env.project([createTodo, markDone]);
- * ```
- */
-export interface ProjectOpts<
-  S extends ServicesMap = ServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  /** Optional project-level setup. See `Project.setup`. */
-  setup?: ProjectSetupFn<S, F>;
-  /** Test cases for this project's suite. */
-  tests?: TestCase<unknown, S, F>[];
-}
-
-/**
- * Input to {@link defineEnvironment}: the environment config plus an
- * optional `fakes` map. `fakes` is declared here (rather than on
- * `project(...)`) so the fakes' types are bound when `env.test(...)`
- * creates a test — that's what makes `ctx.fakes.<key>` strongly typed.
- * `fakes` is stripped from `config` before it's stored/serialised, so the
- * wire `EnvironmentConfig` the Rust control plane sees never carries it.
- *
- * Unlike the wire {@link EnvironmentConfig}, `services` entries here may
- * be {@link ServiceGroup}s — they're expanded to plain services (primary
- * at the group's key, other parts at `<key>-<part>`) before validation.
- */
-export interface EnvironmentInput<
-  SI extends InputServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  /** Human-friendly name for the environment, e.g. "my-app". */
-  name: string;
-  /** Services and/or service groups, keyed by name. See
-   *  {@link EnvironmentConfig.services} and {@link ServiceGroup}. */
-  services: SI;
-  /** Sandbox timeout in seconds (default 1h). */
-  timeoutSecs?: number;
-  /** Fake servers — see {@link defineFake}. Keyed by stable name; the key
-   * shows up as `ctx.fakes.<key>` in tests, typed as that fake's helpers
-   * record. */
-  fakes?: F;
-}
-
-export interface DefinedEnvironment<
-  S extends ServicesMap,
-  F extends FakesMap = FakesMap,
-> {
-  /** The validated environment config. Plain data, JSON-serialisable —
-   * the in-VM daemon ships this to the control plane on `/load`. */
-  readonly config: EnvironmentConfig<S>;
-  /** Define a test against this environment. `ctx.svc.<key>` and
-   * `ctx.fakes.<key>` are strongly typed against the services and fakes
-   * maps. */
-  readonly test: TypedTest<S, F>;
-  /** Bundle this environment with a test suite into the project default
-   * export. Pass tests as a plain array for the common case, or an
-   * options bag to attach project-level `setup`. (Fakes are declared on
-   * `defineEnvironment`, not here.) */
-  project(tests?: TestCase<unknown, S, F>[]): Project<S, F>;
-  project(opts: ProjectOpts<S, F>): Project<S, F>;
-}
-
-/**
- * The `ctx` type for an environment, for typing shared test helpers without
- * `any`. Instantiate with the environment from `defineEnvironment`:
- *
- * ```ts
- * const env = defineEnvironment({ ... });
- * export type AppCtx = Ctx<typeof env>;
- *
- * // A helper reaching into ctx.svc / ctx.fakes stays fully typed:
- * async function runJob(ctx: AppCtx) {
- *   await ctx.svc.db.client`SELECT 1`;
- * }
- * ```
- *
- * This is the same `ctx` an `env.test(...)` callback receives. The parent
- * return type is left as `unknown` (helpers rarely touch `ctx.parent` — read
- * it in the test body and pass the value in). Prefer this over `ctx: any`:
- * an `any`-typed ctx also defeats the `expect(...)` overloads, silently
- * resolving `expect(value)` to the `expect(locator)` overload so value
- * matchers like `.toBe(...)` disappear.
- */
-export type Ctx<E> =
-  E extends DefinedEnvironment<infer S, infer F>
-    ? TestContext<unknown, S, F>
-    : never;
-
-/**
- * Define an environment and get back a builder you can hang tests off.
- * The builder's `.test(...)` returns test cases typed against the
- * environment's services (and any declared `fakes`), and `.project([...])`
- * produces the file's default export.
- */
-export function defineEnvironment<
-  SI extends InputServicesMap,
-  F extends FakesMap = FakesMap,
->(input: EnvironmentInput<SI, F>): DefinedEnvironment<ExpandServices<SI>, F> {
-  type S = ExpandServices<SI>;
-  // Split fakes off the wire config and expand service groups; only
-  // { name, services, timeoutSecs } — with plain, fully-expanded services —
-  // is stored as `config` and shipped to the control plane.
-  const { fakes, services: rawServices, ...rest } = input;
-  const config: EnvironmentConfig<S> = {
-    ...rest,
-    services: expandServiceGroups(rawServices) as S,
-  };
-  validateEnvironmentConfig(config);
-  if (fakes) validateFakes(config, fakes);
-
-  // Every test created via this env's `.test(...)` is registered here. A
-  // split-layout project keeps its tests in `spectest/tests/**` — each file
-  // imports this `env` (for types + `dependsOn` refs) and calls `env.test`,
-  // which appends to `registry`. The daemon imports those files and then
-  // reads the suite back off the default-exported Project's lazy `tests`
-  // getter (installed in `project()` below). Keeping the env definition
-  // itself free of test bodies is what lets the warm-template cache key
-  // ignore test edits — see `project_content_hash` in the control plane.
-  const registry: TestCase<unknown, S, F>[] = [];
-  const test = ((
-    name: string,
-    optsOrFn: TestOpts<unknown, S, F> | TestFn<unknown, undefined, S, F>,
-    maybeFn?: TestFn<unknown, unknown, S, F>,
-  ): TestCase<unknown, S, F> => {
-    const tc = (
-      buildTestCase as unknown as (
-        n: string,
-        o: typeof optsOrFn,
-        f?: typeof maybeFn,
-      ) => TestCase<unknown, S, F>
-    )(name, optsOrFn, maybeFn);
-    registry.push(tc);
-    return tc;
-  }) as unknown as TypedTest<S, F>;
-
-  function project(
-    arg?: TestCase<unknown, S, F>[] | ProjectOpts<S, F>,
-  ): Project<S, F> {
-    const opts: ProjectOpts<S, F> = Array.isArray(arg)
-      ? { tests: arg }
-      : (arg ?? {});
-    const proj: Project<S, F> = { environment: config };
-    if (opts.setup) proj.setup = opts.setup;
-    if (fakes) proj.fakes = fakes;
-    if (opts.tests && opts.tests.length > 0) {
-      // Explicit suite (single-file / legacy layout): the tests are listed
-      // right here, so freeze them now.
-      proj.tests = validateSuite({ tests: opts.tests });
-    } else {
-      // Split layout: tests are defined in separate files and collected from
-      // the registry as those files are imported. Expose them lazily so the
-      // daemon sees whatever has registered by the time it reads `.tests`
-      // (i.e. after it has imported `spectest/tests/**` on `/load-tests`).
-      Object.defineProperty(proj, "tests", {
-        enumerable: true,
-        configurable: true,
-        get(): TestSuite<S, F> | undefined {
-          return registry.length > 0
-            ? validateSuite({ tests: [...registry] })
-            : undefined;
-        },
-      });
-    }
-    return proj;
-  }
-  return {
-    config,
-    test,
-    project,
-  };
-}
-
-/**
- * Cross-check fakes against the environment's services: no duplicate
- * hostnames, no collisions with service names or service hostnames, and
- * each fake's name is unique (the user passed a map, so JS guarantees
- * the second condition — but we re-check defensively for the case where
- * an object literal is built programmatically).
- */
-function validateFakes(env: EnvironmentConfig, fakes: FakesMap): void {
-  const claimedByService = new Map<string, string>();
-  for (const [svcName, svc] of Object.entries(env.services)) {
-    claimedByService.set(svcName.toLowerCase(), svcName);
-    claimedByService.set(`${svcName.toLowerCase()}.internal`, svcName);
-    for (const h of svc.hostnames ?? []) {
-      claimedByService.set(h.toLowerCase(), svcName);
-    }
-    for (const entry of svc.tls ?? []) {
-      claimedByService.set(entry.hostname.toLowerCase(), svcName);
-    }
-  }
-  const claimedByFake = new Map<string, string>();
-  for (const [key, fake] of Object.entries(fakes)) {
-    if (!fake || typeof fake !== "object" || typeof fake.handler !== "function") {
-      throw new Error(
-        `fake ${JSON.stringify(key)} is not a FakeDefinition — pass the result of defineFake({...})`,
-      );
-    }
-    for (const raw of fake.hostnames) {
-      const h = raw.toLowerCase();
-      const owningSvc = claimedByService.get(h);
-      if (owningSvc !== undefined) {
-        throw new Error(
-          `fake ${JSON.stringify(key)} hostname ${JSON.stringify(raw)} collides with service ${JSON.stringify(owningSvc)}`,
-        );
-      }
-      const owningFake = claimedByFake.get(h);
-      if (owningFake !== undefined && owningFake !== key) {
-        throw new Error(
-          `hostname ${JSON.stringify(raw)} is claimed by both fake ${JSON.stringify(owningFake)} and fake ${JSON.stringify(key)}`,
-        );
-      }
-      claimedByFake.set(h, key);
-    }
-  }
-}
-
-// `buildTestCase` is the runtime implementation behind every typed
-// `env.test(...)`. The DefinedEnvironment exposes it cast to TypedTest<S>
-// so callers see the strongly-typed overloads while the body stays
-// generic — TestFn is contravariant in `ctx`, so a single implementation
-// satisfies every TypedTest<S>.
-function buildTestCase(
-  name: string,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  optsOrFn: TestOpts<any> | TestFn<unknown, any>,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  maybeFn?: TestFn<unknown, any>,
-): TestCase<unknown> {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const [opts, fn]: [TestOpts<any>, TestFn<unknown, any>] =
-    typeof optsOrFn === "function" ? [{}, optsOrFn] : [optsOrFn, maybeFn!];
-  if (typeof fn !== "function") {
-    throw new TypeError(
-      `test(${JSON.stringify(name)}): missing test function`,
-    );
-  }
-  return {
-    id: slugify(name),
-    name,
-    dependsOn: opts.dependsOn,
-    timeoutMs: opts.timeoutMs,
-    run: fn,
-  };
-}
-
-function validateSuite<
-  S extends ServicesMap,
-  F extends FakesMap,
->(suite: TestSuite<S, F>): TestSuite<S, F> {
-  const seenIds = new Map<string, string>();
-  for (const t of suite.tests) {
-    const prior = seenIds.get(t.id);
-    if (prior !== undefined) {
-      throw new Error(
-        `duplicate test id "${t.id}" (from ${JSON.stringify(
-          prior,
-        )} and ${JSON.stringify(t.name)}) — rename one`,
-      );
-    }
-    seenIds.set(t.id, t.name);
-  }
-  // Validate that each dependsOn ref is in the suite. Catches typos /
-  // imports forgotten in the tests array.
-  for (const t of suite.tests) {
-    if (t.dependsOn && !suite.tests.includes(t.dependsOn)) {
-      throw new Error(
-        `test "${t.name}" depends on "${t.dependsOn.name}" which is not in the suite`,
-      );
-    }
-  }
-  return suite;
-}
-
-function slugify(name: string): string {
-  const slug = name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-  if (!slug) {
-    throw new Error(`cannot derive id from test name ${JSON.stringify(name)}`);
-  }
-  return slug;
-}
-
-// ──────────────────────────────────────────────────────────────────────────
-// Assertions
-// ──────────────────────────────────────────────────────────────────────────
-
-export class ExpectationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "ExpectationError";
-  }
-}
-
-interface Matchers {
-  toBe(expected: unknown): void;
-  toEqual(expected: unknown): void;
-  toBeTruthy(): void;
-  toBeFalsy(): void;
-  toBeGreaterThan(n: number): void;
-  toBeLessThan(n: number): void;
-  toBeGreaterThanOrEqual(n: number): void;
-  toBeLessThanOrEqual(n: number): void;
-  toContain(expected: unknown): void;
-  toMatch(re: RegExp): void;
-  toHaveLength(n: number): void;
-}
-
-export interface Expectation extends Matchers {
-  not: Matchers;
-}
-
-/**
- * Auto-retrying web-first assertions for a {@link Locator} — Playwright's
- * `expect(locator)` matchers. Each polls the element until it passes or a
- * deadline elapses (default 5 s, `{ timeout }` overrides) and records an
- * assertion event just like a value `expect`. `await` them — they are async.
- */
-export interface LocatorMatchers {
-  /** The element is present and visible. */
-  toBeVisible(opts?: { timeout?: number }): Promise<void>;
-  /** The element is absent or hidden. */
-  toBeHidden(opts?: { timeout?: number }): Promise<void>;
-  /** The element's (trimmed) text equals `expected` (or matches a RegExp). */
-  toHaveText(expected: string | RegExp, opts?: { timeout?: number }): Promise<void>;
-  /** The element's text contains `expected`. */
-  toContainText(expected: string, opts?: { timeout?: number }): Promise<void>;
-  /** The input's value equals `expected` (or matches a RegExp). */
-  toHaveValue(expected: string | RegExp, opts?: { timeout?: number }): Promise<void>;
-  /** The locator resolves to exactly `expected` elements. */
-  toHaveCount(expected: number, opts?: { timeout?: number }): Promise<void>;
-  toBeEnabled(opts?: { timeout?: number }): Promise<void>;
-  toBeDisabled(opts?: { timeout?: number }): Promise<void>;
-  toBeChecked(opts?: { timeout?: number }): Promise<void>;
-}
-
-export interface LocatorAssertion extends LocatorMatchers {
-  /** Negate every matcher (retries until the negated condition holds). */
-  not: LocatorMatchers;
-}
-
-// `expect(locator)` returns the async web-first matchers; `expect(value)` the
-// synchronous value matchers. The Locator overload is listed first so a
-// locator (an object with no `unwrap`, hence not `Provenanced`) resolves to it.
-export function expect(actual: Locator, message?: string): LocatorAssertion;
-export function expect(actual: Provenanced, message?: string): Expectation;
-export function expect(
-  actual: Provenanced | Locator,
-  message?: string,
-): Expectation | LocatorAssertion {
-  if (isLocator(actual)) return buildLocatorAssertion(actual, message);
-  return expectValue(actual, message);
-}
-
-function expectValue(actual: Provenanced, message?: string): Expectation {
-  // The first parameter is typed to the {@link Provenanced} family so a raw
-  // value (`expect(res.status === 200)`, `expect(2 + 2)`) is a *compile error* —
-  // every assertion that reaches the timeline this way carries a provenance link
-  // back to the op that produced it. Assert on a genuinely raw value with
-  // `expectRaw(value, message)` instead.
-  //
-  // `message` is an **optional** human label for the assertion. The UI already
-  // renders the target, matcher, and expected value, so a message that just
-  // restates them is noise — supply one *only* when the check's intent isn't
-  // obvious from those alone (e.g.
-  // `expect(res.status, "blocked once the rate limit trips").toBe(429)`). When
-  // present it leads the assertion's summary, the same way `expectRaw`'s does.
-  //
-  // A `null`/`undefined` read off a wrapped op result reaches here untagged
-  // (a symbol can't ride on nullish). `adoptNullishTag` recovers the tag from
-  // the proxy's most-recent nullish-leaf note and mints a tagged holder, so
-  // `expect(dep.status.readyReplicas).toBeFalsy()` nests under its op just like
-  // a non-nullish read. Done once here (not in `buildMatchers`) so the `.not`
-  // re-pass reuses the same tagged holder instead of re-consuming the note.
-  return buildMatchers(adoptNullishTag(actual), false, message);
-}
-
-// ── expect(locator): auto-retrying web-first matchers ─────────────────────
-
-/** Poll interval for locator matchers. */
-const LOCATOR_POLL_MS = 50;
-
-function buildLocatorAssertion(loc: Locator, message?: string): LocatorAssertion {
-  return Object.assign(buildLocatorMatchers(loc, false, message), {
-    not: buildLocatorMatchers(loc, true, message),
-  });
-}
-
-function buildLocatorMatchers(
-  loc: Locator,
-  negated: boolean,
-  message?: string,
-): LocatorMatchers {
-  const probe = getLocatorProbe(loc);
-
-  // Poll `check` (a silent, non-recorded read) until the desired condition
-  // holds or the deadline elapses, then emit ONE settled browser step (the
-  // locator label + replay seek point) and record ONE assertion nested under
-  // it via `sourceSeq` — so a web-first `expect(locator)` assertion carries
-  // the same provenance a value assertion does (`expect(await loc.isVisible())`
-  // renders identically). Without the anchor step these assertions floated as
-  // disconnected top-level "value ✓" rows with no element and no replay seek.
-  // `check` returns whether the base condition is satisfied plus the observed
-  // value for the timeline.
-  const run = async (
-    matcher: string,
-    timeout: number | undefined,
-    check: () => Promise<{ satisfied: boolean; actual: unknown }>,
-    describe: (actual: unknown) => string,
-    expected?: unknown,
-  ): Promise<void> => {
-    const started = Date.now();
-    const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
-    let actual: unknown;
-    for (;;) {
-      let satisfied: boolean;
-      try {
-        const r = await check();
-        satisfied = r.satisfied;
-        actual = r.actual;
-      } catch (err) {
-        if (Date.now() < deadline) {
-          await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
-          continue;
-        }
-        satisfied = false;
-        actual = `<error: ${(err as Error)?.message ?? String(err)}>`;
-      }
-      const passed = satisfied !== negated;
-      if (passed) {
-        const sourceSeq = await probe.settle(matcher, Date.now() - started);
-        recordAssertion({
-          matcher,
-          negated,
-          passed: true,
-          actual: safeSerialize(actual),
-          expected: expected === undefined ? undefined : safeSerialize(expected),
-          message,
-          sourceSeq,
-        });
-        return;
-      }
-      if (Date.now() >= deadline) {
-        const msg = describe(actual);
-        const sourceSeq = await probe.settle(matcher, Date.now() - started, msg);
-        recordAssertion({
-          matcher,
-          negated,
-          passed: false,
-          actual: safeSerialize(actual),
-          expected: expected === undefined ? undefined : safeSerialize(expected),
-          error: msg,
-          message,
-          sourceSeq,
-        });
-        throw new ExpectationError(msg);
-      }
-      await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
-    }
-  };
-
-  const not = negated ? " not" : "";
-  const matchesText = (v: string, expected: string | RegExp): boolean =>
-    expected instanceof RegExp ? expected.test(v) : v === expected;
-
-  return {
-    toBeVisible: (opts) =>
-      run(
-        "toBeVisible",
-        opts?.timeout,
-        async () => {
-          const v = await probe.isVisible();
-          return { satisfied: v, actual: v };
-        },
-        () => `expected ${probe.label}${not} to be visible`,
-      ),
-    toBeHidden: (opts) =>
-      run(
-        "toBeHidden",
-        opts?.timeout,
-        async () => {
-          const v = await probe.isVisible();
-          return { satisfied: !v, actual: v };
-        },
-        () => `expected ${probe.label}${not} to be hidden`,
-      ),
-    toHaveText: (expected, opts) =>
-      run(
-        "toHaveText",
-        opts?.timeout,
-        async () => {
-          const t = (await probe.textContent(opts?.timeout)) ?? "";
-          return { satisfied: matchesText(t.trim(), expected), actual: t };
-        },
-        (a) => `expected ${probe.label}${not} to have text ${fmt(expected)}, got ${fmt(a)}`,
-        expected instanceof RegExp ? String(expected) : expected,
-      ),
-    toContainText: (expected, opts) =>
-      run(
-        "toContainText",
-        opts?.timeout,
-        async () => {
-          const t = (await probe.textContent(opts?.timeout)) ?? "";
-          return { satisfied: t.includes(expected), actual: t };
-        },
-        (a) => `expected ${probe.label}${not} to contain text ${fmt(expected)}, got ${fmt(a)}`,
-        expected,
-      ),
-    toHaveValue: (expected, opts) =>
-      run(
-        "toHaveValue",
-        opts?.timeout,
-        async () => {
-          const v = await probe.inputValue(opts?.timeout);
-          return { satisfied: matchesText(v, expected), actual: v };
-        },
-        (a) => `expected ${probe.label}${not} to have value ${fmt(expected)}, got ${fmt(a)}`,
-        expected instanceof RegExp ? String(expected) : expected,
-      ),
-    toHaveCount: (expected, opts) =>
-      run(
-        "toHaveCount",
-        opts?.timeout,
-        async () => {
-          const c = await probe.count();
-          return { satisfied: c === expected, actual: c };
-        },
-        (a) => `expected ${probe.label}${not} to have count ${expected}, got ${fmt(a)}`,
-        expected,
-      ),
-    toBeEnabled: (opts) =>
-      run(
-        "toBeEnabled",
-        opts?.timeout,
-        async () => {
-          const v = await probe.isEnabled(opts?.timeout);
-          return { satisfied: v, actual: v };
-        },
-        () => `expected ${probe.label}${not} to be enabled`,
-      ),
-    toBeDisabled: (opts) =>
-      run(
-        "toBeDisabled",
-        opts?.timeout,
-        async () => {
-          const v = await probe.isEnabled(opts?.timeout);
-          return { satisfied: !v, actual: v };
-        },
-        () => `expected ${probe.label}${not} to be disabled`,
-      ),
-    toBeChecked: (opts) =>
-      run(
-        "toBeChecked",
-        opts?.timeout,
-        async () => {
-          const v = await probe.isChecked(opts?.timeout);
-          return { satisfied: v, actual: v };
-        },
-        () => `expected ${probe.label}${not} to be checked`,
-      ),
-  };
-}
-
-/**
- * Assert on a value with **no provenance** — a computed number, a raw
- * WebSocket frame, anything that didn't flow from a recorded op. `message` is
- * required (it's the second argument) and reads as the natural follow-on to
- * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
- * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
- * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
- * the value carries provenance — only reach for this when the type gate would
- * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
- * mandatory, since the label is the only human-meaningful summary a raw
- * assertion has.)
- */
-export function expectRaw(actual: unknown, message: string): Expectation {
-  // Force the raw form so no stray tag is read even if a wrapped value is
-  // passed: an `expectRaw` assertion is *deliberately* unlinked, rendered at
-  // top level under its own message rather than nested beneath an op.
-  return buildMatchers(readRaw(actual), false, message);
-}
-
-function buildMatchers(wrapped: unknown, negated: boolean, message?: string): Expectation {
-  // If `wrapped` is an inspect-tagged value (from fetch / db / browser),
-  // pull its origin metadata and run matchers against the raw underlying
-  // value. Plain `expect(value)` is unaffected. Tag + raw are read once here
-  // and threaded explicitly into `buildCore`, so `.not` and transforms re-pass
-  // them directly instead of re-reading the wrapper (and re-consuming any
-  // adopted nullish note).
-  return buildCore(readRaw(wrapped), readTag(wrapped), negated, message);
-}
-
-/**
- * The matcher/transform factory, working off an already-unwrapped `actual` and
- * an explicit `tag`. `pendingError`, when set, marks a transform that failed
- * upstream: every matcher then records a failed assertion carrying that error
- * (irrespective of negation) and throws, and further transforms propagate it.
- */
-function buildCore(
-  actual: unknown,
-  tag: OpTag | undefined,
-  negated: boolean,
-  message?: string,
-  pendingError?: string,
-): Expectation {
-  // Wraps a matcher: it computes the raw condition, the failure message,
-  // records the assertion event, then throws iff the result is a failure.
-  // `expectedFor` lets matchers record their expected value where it
-  // makes sense (toBe / toEqual / toContain / toMatch) while matchers
-  // like toBeTruthy leave it unset.
-  const run = (
-    matcher: string,
-    cond: boolean,
-    msg: string,
-    expectedFor?: unknown,
-    opts?: { actual?: unknown },
-  ): void => {
-    // A failed upstream transform short-circuits every matcher to a failure —
-    // there is no meaningful value to match, and negation can't rescue a value
-    // that never decoded — so we record `pendingError` and throw regardless of
-    // `cond`/`negated`.
-    if (pendingError !== undefined) {
-      recordAssertion({
-        matcher,
-        negated,
-        passed: false,
-        actual: safeSerialize(actual),
-        expected: expectedFor === undefined ? undefined : safeSerialize(expectedFor),
-        error: pendingError,
-        message,
-        sourceSeq: tag?.sourceSeq,
-        path: tag ? [...tag.path] : undefined,
-      });
-      throw new ExpectationError(pendingError);
-    }
-    const passed = cond !== negated;
-    recordAssertion({
-      matcher,
-      negated,
-      passed,
-      actual: safeSerialize(opts && "actual" in opts ? opts.actual : actual),
-      expected: expectedFor === undefined ? undefined : safeSerialize(expectedFor),
-      error: passed ? undefined : msg,
-      message,
-      sourceSeq: tag?.sourceSeq,
-      path: tag ? [...tag.path] : undefined,
-    });
-    if (!passed) throw new ExpectationError(msg);
-  };
-  return {
-    toBe(expected) {
-      const exp = readRaw(expected);
-      run(
-        "toBe",
-        Object.is(actual, exp),
-        `expected ${fmt(actual)}${negated ? " not" : ""} to be ${fmt(exp)}`,
-        exp,
-      );
-    },
-    toEqual(expected) {
-      const exp = readRaw(expected);
-      let equal = true;
-      try {
-        nodeAssert.deepStrictEqual(actual, exp);
-      } catch {
-        equal = false;
-      }
-      run(
-        "toEqual",
-        equal,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to deep-equal ${fmt(exp)}`,
-        exp,
-      );
-    },
-    toBeTruthy() {
-      run(
-        "toBeTruthy",
-        !!actual,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to be truthy`,
-      );
-    },
-    toBeFalsy() {
-      run(
-        "toBeFalsy",
-        !actual,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to be falsy`,
-      );
-    },
-    toBeGreaterThan(n) {
-      run(
-        "toBeGreaterThan",
-        typeof actual === "number" && actual > n,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to be > ${n}`,
-        n,
-      );
-    },
-    toBeLessThan(n) {
-      run(
-        "toBeLessThan",
-        typeof actual === "number" && actual < n,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to be < ${n}`,
-        n,
-      );
-    },
-    toBeGreaterThanOrEqual(n) {
-      run(
-        "toBeGreaterThanOrEqual",
-        typeof actual === "number" && actual >= n,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to be >= ${n}`,
-        n,
-      );
-    },
-    toBeLessThanOrEqual(n) {
-      run(
-        "toBeLessThanOrEqual",
-        typeof actual === "number" && actual <= n,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to be <= ${n}`,
-        n,
-      );
-    },
-    toContain(expected) {
-      const exp = readRaw(expected);
-      let contained = false;
-      if (typeof actual === "string" && typeof exp === "string") {
-        contained = actual.includes(exp);
-      } else if (Array.isArray(actual)) {
-        contained = actual.some((v) => {
-          try {
-            nodeAssert.deepStrictEqual(v, exp);
-            return true;
-          } catch {
-            return false;
-          }
-        });
-      }
-      run(
-        "toContain",
-        contained,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to contain ${fmt(exp)}`,
-        exp,
-      );
-    },
-    toMatch(re) {
-      run(
-        "toMatch",
-        typeof actual === "string" && re.test(actual),
-        `expected ${fmt(actual)}${negated ? " not" : ""} to match ${re}`,
-        String(re),
-      );
-    },
-    toHaveLength(n) {
-      // Provenance-preserving count assertion. A wrapped array's `.length`
-      // is deliberately raw (so `rows.length === 1` works), which means
-      // `expect(rows.length)` can't link back to the originating op —
-      // pass the container itself instead: `expect(rows).toHaveLength(1)`
-      // keeps the tag, and we read the length off the raw value here.
-      const len =
-        typeof actual === "string" || Array.isArray(actual)
-          ? actual.length
-          : actual !== null &&
-              typeof actual === "object" &&
-              typeof (actual as { length?: unknown }).length === "number"
-            ? ((actual as { length: number }).length as number)
-            : undefined;
-      // The provenance `path` stays the container's own path — `.length` is
-      // the matcher's internal read, not a property access the author wrote,
-      // so it doesn't belong in the path (recording it produced a redundant
-      // "length toHaveLength N" in the UI, since the matcher name already says
-      // "length"). `actual` is still the length number: that's what's worth
-      // showing on failure, and the `toHaveLength` matcher disambiguates it.
-      run(
-        "toHaveLength",
-        len === n,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to have length ${n}` +
-          (len === undefined ? " (value has no length)" : ` (got ${len})`),
-        n,
-        { actual: len },
-      );
-    },
-    get not(): Matchers {
-      // Re-pass the already-unwrapped value, tag and message so the tag and raw
-      // label are preserved for the negated branch's AssertionEvent.
-      return buildCore(actual, tag, !negated, message, pendingError);
-    },
-  } as Expectation;
-}
-
-function fmt(v: unknown): string {
-  if (typeof v === "string") return JSON.stringify(v);
-  if (typeof v === "bigint") return `${v}n`;
-  if (v === undefined) return "undefined";
-  try {
-    return JSON.stringify(v);
-  } catch {
-    return String(v);
-  }
-}
-
-/** `node:assert/strict` re-exported for users who prefer Node's built-in API. */
-export const assert = nodeAssert;