@specific.dev/spectest 0.38.0 → 0.41.0

package/src/index.ts

@@ -0,0 +1,2725 @@
+// 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,
+  isBrowserSession,
+  getBrowserProbe,
+  DEFAULT_ACTION_TIMEOUT_MS,
+} from "./locator.js";
+
+export type { UrlPattern } from "./url-match.js";
+import type { UrlPattern } from "./url-match.js";
+import { describeUrlPattern, matchesUrl } from "./url-match.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";
+import { isWildcard as isWildcardHost } 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.
+   *
+   * A `*.suffix` wildcard (e.g. `"*.example.com"`) points a whole domain
+   * at this service. Wildcards are answered by spectest-resolver only —
+   * they never land in a container's `/etc/hosts` — which peer containers
+   * still reach, since Docker forwards unknown names to that resolver.
+   *
+   * 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 harness. 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.
+   *
+   * A `*.suffix` wildcard claims a whole domain with one entry — e.g.
+   * `{ hostname: "*.us-east-1.amazonaws.com", port: 4566 }` puts every
+   * AWS regional endpoint on one emulator container, so an unmodified SDK
+   * reaches it at its production URL. The leaf cert gets a wildcard SAN,
+   * which (as in every TLS client) covers exactly **one** label: declare
+   * a separate entry for anything deeper. An exact `tls` hostname always
+   * beats a wildcard, so a single endpoint can be split off to another
+   * service.
+   */
+  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[];
+  /**
+   * Leaf certificates minted from the in-VM root CA and written into the
+   * container **before it starts**, so the service can terminate TLS
+   * *itself* with a certificate the whole environment already trusts.
+   *
+   * This is the counterpart to {@link ServiceConfig.tls}. `tls` puts the
+   * daemon in front as a terminating reverse proxy and forwards plain
+   * HTTP to the service — right for an ordinary web app, wrong for
+   * anything that has to see the TLS handshake: a gateway that routes by
+   * SNI, a server that verifies client certificates, or a protocol with
+   * its own TLS layer. Those need key material, and the only alternative
+   * was a self-signed cert plus `rejectUnauthorized: false` — which
+   * tests a code path production never runs.
+   *
+   * ```ts
+   * services: {
+   *   gateway: {
+   *     image: { type: "registry", reference: "…" },
+   *     hostnames: ["sql.gateway.test"],
+   *     certificates: [{
+   *       hostnames: ["sql.gateway.test", "*.sql.gateway.test"],
+   *       certPath: "/tls/tls.crt",
+   *       keyPath: "/tls/tls.key",
+   *       mode: "0600",
+   *     }],
+   *   },
+   * }
+   * // a test then connects with full verification on:
+   * //   new Client({ connectionString, ssl: { rejectUnauthorized: true } })
+   * ```
+   *
+   * For a certificate a *test* needs as a value — to load into a
+   * Kubernetes Secret, say — use `ctx.certificate(hostnames)` instead,
+   * which returns the PEMs rather than mounting them.
+   */
+  certificates?: readonly CertificateMount[];
+  /** 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;
+}
+
+/**
+ * Everything test-side code can reach inside the VM, in every
+ * context it runs in: a test body, `spectest env eval`, a project-level
+ * `setup`, and a component's service-level `setup` / `helpers` hooks.
+ *
+ * This is deliberately ONE type. The setup surfaces used to be two
+ * disjoint sets — a component hook could read project files but not mint
+ * a certificate; a project `setup` could mint a certificate but not read
+ * a project file — so bring-up logic got split across files by which
+ * context happened to carry which method. A component is now written
+ * against exactly the primitives an end user has in a test.
+ *
+ * The one member that differs by context is {@link exec}: in a test it
+ * returns a {@link Wrapped} result (its output carries provenance into
+ * the timeline), everywhere else a plain one. See {@link TestContext}.
+ *
+ * `svc` is scoped in a service-level hook: a service's `setup`/`helpers`
+ * can reach its own handle and those of its (transitive) `dependsOn`
+ * services — the ones the DAG guarantees are already up — and reading
+ * any other key throws with the dependency it's missing. Everywhere else
+ * (tests, eval, project `setup`) the whole map is live.
+ */
+export interface SpectestContext<
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  /**
+   * 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, and never `import.meta.url` —
+   * that only reaches files under `spectest/`) to locate project files:
+   * a manifest set, `supabase/migrations/**`, a fixture.
+   */
+  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. 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.
+   *
+   * In a test this is the instrumented variant (recorded on the timeline,
+   * result {@link Wrapped}); in `setup`/`helpers` there is no timeline, so
+   * the result is a plain {@link ExecResult}.
+   */
+  exec(
+    service: string,
+    command: string | string[],
+    opts?: ExecOpts,
+  ): Promise<ExecResult>;
+  /**
+   * Instrumented `fetch`. In a test each call is recorded on the 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`. Outside a test the
+   * result is wrapped the same way, just with no timeline to link to.
+   *
+   * (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;
+  /**
+   * 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\``.
+   *
+   * In a service-level `setup`/`helpers` hook only the service itself and
+   * its transitive `dependsOn` are reachable (see {@link SpectestContext}).
+   */
+  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. In a test 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. In a test it 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. In `setup` there's no
+   * timeline; it's just the loop you'd otherwise hand-roll.
+   *
+   * - `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 so the rest of this context (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.
+   *
+   * 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 from a test it's isolated
+   * to that test's fork (like fake state); from `setup` it's captured by
+   * the warm-template snapshot and every test inherits it.
+   *
+   * ```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>;
+  /**
+   * Mint a leaf certificate from the in-VM root CA and return the PEMs.
+   *
+   * The value-returning counterpart to the `certificates` service field
+   * (see {@link ServiceConfig.certificates}): that one hands a
+   * certificate to a container before it boots, this one hands it to
+   * *you* — for loading into a Kubernetes `kubernetes.io/tls` Secret,
+   * posting to a control-plane API that provisions TLS endpoints, or
+   * driving a client-certificate handshake.
+   *
+   * The returned `ca` is the same root the whole environment already
+   * trusts (`ctx.fetch`, `ctx.browser()`, every service container), so a
+   * server configured with these PEMs verifies cleanly — no
+   * `rejectUnauthorized: false`, no `sslmode=require` downgrade.
+   * Wildcards (`*.example.com`) are allowed in `hostnames`.
+   *
+   * ```ts
+   * const { cert, key } = await ctx.certificate(["*.apps.test"]);
+   * await ctx.svc.k8s.apply(`
+   * apiVersion: v1
+   * kind: Secret
+   * metadata: { name: apps-tls, namespace: default }
+   * type: kubernetes.io/tls
+   * stringData:
+   *   tls.crt: |
+   * ${cert.replace(/^/gm, "    ")}
+   *   tls.key: |
+   * ${key.replace(/^/gm, "    ")}
+   * `);
+   * ```
+   */
+  certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
+  /**
+   * 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.
+   *
+   * Started from a test, the new container is part of that 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. Started from `setup`, it's captured into the
+   * warm template and every test inherits it. 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>;
+}
+
+/**
+ * @deprecated Use {@link SpectestContext} — component hooks and test
+ * bodies now receive the same capabilities. Kept as an alias so existing
+ * component code keeps compiling.
+ */
+export type ComponentContext = SpectestContext;
+
+/**
+ * Options for {@link SpectestContext.exec} — one type for every context,
+ * deliberately aliased rather than redeclared: the surfaces drifted once
+ * (the component one grew `stdin`/`timeoutMs`, the test one silently
+ * ignored them), and an alias makes that impossible to repeat.
+ *
+ * The one behavioural difference is the `timeoutMs` default: a
+ * service-level `setup`/`helpers` exec runs during boot, where nothing
+ * else bounds it, so it defaults to 120 s. Elsewhere there is no default —
+ * in a test the enclosing test's own timeout is the ceiling, and a
+ * project `setup` runs unbounded (it routinely waits on rollouts).
+ */
+export type ComponentExecOpts = ExecOpts;
+
+/** What a service's `setup` hook receives: the full
+ *  {@link SpectestContext} plus the service's own name and helpers. */
+export interface ServiceSetupContext<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  H extends Record<string, any> = Record<string, never>,
+> extends SpectestContext {
+  /** 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: the full
+ *  {@link SpectestContext} plus the service's own name. Note `ctx.svc`
+ *  here reaches the service's `dependsOn` only — never itself, since this
+ *  hook is what builds that handle. */
+export interface ServiceHelpersContext extends SpectestContext {
+  /** 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).
+ *
+ * The entry type is `ServiceDefinition`, not `ServiceConfig`: at runtime
+ * the map really does hold `helpers`/`setup` (the daemon reads them off
+ * each entry), and both are optional, so every plain `ServiceConfig`
+ * still satisfies it. Narrowing this to `ServiceConfig` — the wire type,
+ * which by definition carries no functions — made the natural way to
+ * hoist a services map out of `index.ts` (`… satisfies ServicesMap`) fail
+ * the typecheck on any service declaring a hook, while the same literal
+ * written inline passed. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ServicesMap = Record<string, ServiceDefinition<any>>;
+
+/** 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`.
+   *
+   * An absolute path that already exists and is not a directory is
+   * bind-mounted as-is — the way to hand a service the VM's docker socket
+   * (`source: "/var/run/docker.sock"`), which LocalStack's Lambda executor
+   * and dind-style builders need. Such a mount is VM-host infrastructure,
+   * so unlike a volume directory it is never created or wiped by spectest.
+   */
+  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;
+  /**
+   * Owner of the staged file — a user name from the image's
+   * `/etc/passwd` (resolved against the image, so `"postgres"` works),
+   * or a numeric uid. A bind mount carries the staged file's ownership
+   * straight through, so a file written by the daemon lands as `root`:
+   * pair a restrictive `mode` with `user` or the container's own
+   * process can't read it.
+   */
+  user?: string;
+  /** Group of the staged file — a group name from the image's
+   *  `/etc/group`, or a numeric gid. */
+  group?: string;
+}
+
+/** PEM material returned by `ctx.certificate(hostnames)`. */
+export interface CertificateMaterial {
+  /** PEM certificate, signed by the in-VM root CA. */
+  cert: string;
+  /** PEM private key for {@link cert}. */
+  key: string;
+  /** PEM root CA certificate — the one the environment already trusts. */
+  ca: string;
+}
+
+/** One leaf certificate materialized into a service container — see
+ *  {@link ServiceConfig.certificates}. */
+export interface CertificateMount {
+  /** SANs the leaf covers. Wildcards (`*.example.com`) are allowed. */
+  hostnames: readonly string[];
+  /** Absolute path inside the container for the PEM certificate. */
+  certPath: string;
+  /** Absolute path inside the container for the PEM private key. */
+  keyPath: string;
+  /**
+   * Optional absolute path for the root CA certificate. Every container
+   * already trusts the CA (`SSL_CERT_FILE` and friends are pre-set), so
+   * this is only for software that wants an explicit CA file — client
+   * certificate verification, a `sslrootcert=` connection parameter.
+   */
+  caPath?: string;
+  /**
+   * Optional octal mode (e.g. `"0600"`) applied to the staged key.
+   * Servers that refuse a group/world-readable key (postgres, ssh) need
+   * this. The default is the writer's umask — or, once `user`/`group`
+   * says who reads the key, the strictest mode that owner can still
+   * read (`0600`, or `0640` when only `group` is given).
+   */
+  mode?: string;
+  /**
+   * Owner of the staged key and certificate — a user name from the
+   * image's `/etc/passwd` (resolved against the image, so
+   * `"postgres"` works), or a numeric uid.
+   *
+   * A bind mount carries the staged file's ownership through, and the
+   * daemon writes as `root`, so a strict `mode` alone gives a
+   * non-root server a key it cannot open — postgres reports
+   * `could not access private key file`. `user` is what makes the
+   * pair work, with no entrypoint wrapper and no custom image.
+   */
+  user?: string;
+  /** Group of the staged key and certificate — a group name from the
+   *  image's `/etc/group`, or a numeric gid. Enough on its own for a
+   *  server that accepts a root-owned key readable by its group
+   *  (postgres does, at `0640`). */
+  group?: 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>;
+  /** Mint a CA-signed leaf certificate. See
+   *  {@link TestContext.certificate} — the primitive a fake standing in
+   *  for a TLS-provisioning provider hands back to the app under test. */
+  certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
+}
+
+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(hostPatternBody(h))) {
+        throw new Error(
+          `service "${name}" declares invalid hostname ${JSON.stringify(raw)} — must be a multi-label DNS name or a wildcard (e.g. "api.stripe.com", "*.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(hostPatternBody(h))) {
+        throw new Error(
+          `service "${name}" tls hostname ${JSON.stringify(entry.hostname)} is not a multi-label DNS name or wildcard (e.g. "app.test", "*.us-east-1.amazonaws.com")`,
+        );
+      }
+      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])?)+$/;
+
+/** The part of a declared name that must be a valid hostname: a `*.suffix`
+ *  wildcard is checked by its suffix, so `*.example.com` passes but `*.com`
+ *  (single-label, too broad) and `*` do not. Keeps the `.internal` checks
+ *  honest too — `*.foo.internal` reduces to `foo.internal`. */
+function hostPatternBody(lowercased: string): string {
+  return isWildcardHost(lowercased) ? lowercased.slice(2) : lowercased;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// 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 run results 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,
+> extends Omit<SpectestContext<S, F>, "exec"> {
+  /** Run a command inside a service container — a string via `sh -lc`,
+   *  or an array as exact argv. 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()`. (This is the
+   *  one place {@link SpectestContext.exec} differs: in `setup`/`helpers`
+   *  there's no timeline to link to, so the result is plain.)
+   *
+   *  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 | 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 the VM snapshot captures it
+   * cleanly 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 (a VM 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;
+}
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/** Options for {@link TestContext.exec}.
+ *
+ * Unknown properties are rejected at runtime (`ctx.exec` throws), not
+ * silently ignored — the type-level excess-property check is advisory
+ * here, since `spectest test`'s typecheck never gates a run. */
+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;
+  /**
+   * Piped to the command's stdin, then closed — the natural way to feed
+   * a manifest to `kubectl apply -f -` or a SQL file to `psql -f -`
+   * without staging a temp file in the container:
+   *
+   * ```ts
+   * await ctx.exec("k8s", "kubectl apply -f -", { stdin: manifestYaml });
+   * ```
+   *
+   * The payload is written after the process starts and the stream is
+   * closed immediately after, so a command that never reads stdin still
+   * exits normally (the write is allowed to fail with EPIPE).
+   */
+  stdin?: string;
+  /**
+   * Kill the command (SIGKILL) after this long and return `exitCode`
+   * 124 with a `timeout after <n>ms` note on stderr, rather than
+   * hanging until the enclosing test's own timeout fires.
+   *
+   * **There is no default** — an `exec` runs as long as it likes. In a
+   * test the enclosing `env.test(..., { timeoutMs })` (60 s by default)
+   * is the real ceiling; in `setup`/`eval`, where no test timeout
+   * applies, an unbounded command hangs the boot, so set this when the
+   * command can plausibly wedge.
+   */
+  timeoutMs?: number;
+}
+
+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 harness. 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 harness (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>;
+}
+
+/**
+ * Context handed to the project-level `setup` hook: the full
+ * {@link SpectestContext}, minus only what a timeline gives a test
+ * (testName, parent, browser/mobile/terminal). Everything a test can do
+ * to the environment — exec, fetch, `svc`/`fakes` helpers, `poll`,
+ * `dnsName`, `certificate`, `startService`, and project-file access via
+ * `projectRoot`/`readProjectFile` — is available here too, and whatever it
+ * produces is captured into the warm-template snapshot, so every test
+ * inherits it without re-running.
+ */
+export interface ProjectSetupContext<
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> extends SpectestContext<S, F> {}
+
+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;
+
+/**
+ * The `ctx` type a `setup` hook receives for an environment — the
+ * {@link Ctx} counterpart for bring-up code. Use it to type the deploy /
+ * seed helpers a project's `setup` calls, instead of hand-rolling a
+ * structural `{ exec, certificate }` interface:
+ *
+ * ```ts
+ * const env = defineEnvironment({ ... });
+ * export type AppSetupCtx = SetupCtx<typeof env>;
+ *
+ * async function deployPlatform(ctx: AppSetupCtx) {
+ *   const manifests = await ctx.readProjectFile("deploy/platform.yaml");
+ *   const { cert, key } = await ctx.certificate(["*.apps.test"]);
+ *   await ctx.svc.k8s.apply(manifests);
+ * }
+ * ```
+ *
+ * A service-level `setup`/`helpers` hook gets the same capabilities plus
+ * its own `name`/`helpers` — see {@link ServiceSetupContext}. Since
+ * {@link ProjectSetupContext} is a {@link SpectestContext}, a helper typed
+ * with `SetupCtx` also accepts a service `setup` ctx, so one function can
+ * serve both.
+ */
+export type SetupCtx<E> =
+  E extends DefinedEnvironment<infer S, infer F>
+    ? ProjectSetupContext<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;
+}
+
+/**
+ * Auto-retrying assertions for a browser/mobile **session** — Playwright's
+ * `expect(page)` matchers. Like the locator ones, they poll until the
+ * condition holds or the deadline elapses (default 5 s) and record one
+ * assertion under a settled browser step.
+ */
+export interface BrowserMatchers {
+  /**
+   * The page's URL matches `expected` — a glob string (`*` within a path
+   * segment, `**` across `/`), a RegExp, or a predicate over the parsed URL.
+   * The settling twin of {@link Browser.waitForURL}: use `waitForURL` when
+   * you want the matched URL back, this when you only mean to assert.
+   */
+  toHaveURL(expected: UrlPattern, opts?: { timeout?: number }): Promise<void>;
+}
+
+export interface BrowserAssertion extends BrowserMatchers {
+  /** Negate every matcher (retries until the negated condition holds). */
+  not: BrowserMatchers;
+}
+
+// `expect(locator)`/`expect(browser)` return the async web-first matchers;
+// `expect(value)` the synchronous value matchers. The two object overloads are
+// listed first so they win over `Provenanced` (neither has `unwrap`); a
+// Locator and a Browser are structurally disjoint, so their order is free.
+export function expect(actual: Locator, message?: string): LocatorAssertion;
+export function expect(actual: Browser, message?: string): BrowserAssertion;
+export function expect(actual: Provenanced, message?: string): Expectation;
+export function expect(
+  actual: Provenanced | Locator | Browser,
+  message?: string,
+): Expectation | LocatorAssertion | BrowserAssertion {
+  if (isLocator(actual)) return buildLocatorAssertion(actual, message);
+  if (isBrowserSession(actual)) return buildBrowserAssertion(actual, message);
+  return expectValue(actual as Provenanced, 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`,
+      ),
+  };
+}
+
+// ── expect(browser): auto-retrying session matchers ───────────────────────
+
+function buildBrowserAssertion(session: unknown, message?: string): BrowserAssertion {
+  return Object.assign(buildBrowserMatchers(session, false, message), {
+    not: buildBrowserMatchers(session, true, message),
+  });
+}
+
+function buildBrowserMatchers(
+  session: unknown,
+  negated: boolean,
+  message?: string,
+): BrowserMatchers {
+  const probe = getBrowserProbe(session);
+  const not = negated ? " not" : "";
+
+  return {
+    toHaveURL: async (expected, opts) => {
+      const started = Date.now();
+      const deadline = started + (opts?.timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
+      // `probe.url()` is a synchronous unrecorded read, so the poll costs
+      // nothing and emits nothing — one settled step at the end, exactly like
+      // the locator matchers.
+      const label = describeUrlPattern(expected);
+      for (;;) {
+        const actual = probe.url();
+        if (matchesUrl(actual, expected) !== negated) {
+          const sourceSeq = await probe.settle("toHaveURL", Date.now() - started);
+          recordAssertion({
+            matcher: "toHaveURL",
+            negated,
+            passed: true,
+            actual: safeSerialize(actual),
+            expected: label,
+            message,
+            sourceSeq,
+          });
+          return;
+        }
+        if (Date.now() >= deadline) {
+          const msg = `expected page URL${not} to match ${label}, got ${fmt(actual)}`;
+          const sourceSeq = await probe.settle("toHaveURL", Date.now() - started, msg);
+          recordAssertion({
+            matcher: "toHaveURL",
+            negated,
+            passed: false,
+            actual: safeSerialize(actual),
+            expected: label,
+            error: msg,
+            message,
+            sourceSeq,
+          });
+          throw new ExpectationError(msg);
+        }
+        await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
+      }
+    },
+  };
+}
+
+/**
+ * Assert on a value with **no provenance** — a computed number, a frame read
+ * off a raw `WebSocket` you opened yourself, anything that never flowed 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. (`expect`'s own `message` is optional;
+ * here it is mandatory, since the label is the only human-meaningful summary a
+ * raw assertion has.)
+ *
+ * **This is an escape hatch, and reaching for it is almost always a mistake.**
+ * A raw assertion is *deliberately* unlinked: it renders as a disconnected
+ * top-level row with no op above it, so whoever reads the failure can't see the
+ * request, query, or command the value came from. Using it to get past
+ * `expect`'s compile-time provenance gate is an anti-pattern — the gate rejects
+ * a value precisely because its provenance was destroyed on the way in, and
+ * this doesn't restore it, it just accepts the loss.
+ *
+ * Nearly every real use is a *wrapped* value that got flattened by `.unwrap()`,
+ * `String(x)`, `JSON.parse(x)`, `x.length`, or a home-grown coercion helper.
+ * Keep it wrapped instead:
+ *
+ * ```ts
+ * // ✗ flattened, then asserted raw — the link to the op is gone
+ * expectRaw(JSON.parse(res.body.unwrap()).tier, "tier is pro").toBe("pro");
+ * expectRaw(rows.length, "one row").toBe(1);
+ *
+ * // ✓ same checks, still nested under the http / db step
+ * expect(res.body.transform<{ tier: string }>("json", (s) => JSON.parse(s)).tier).toBe("pro");
+ * expect(rows).toHaveLength(1);
+ * ```
+ *
+ * `.transform(label, fn)` carries the source op's tag through a decode,
+ * `toHaveLength` reads a length without severing it, and a nullish leaf read
+ * inline in `expect(...)` (or via `field`) recovers its own tag. If the value
+ * came from a `fetch`/db/exec/browser/fake/kube op at any point, there is a
+ * wrapped way to assert on it — see the `/tests` docs page.
+ */
+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;