@specific.dev/spectest 0.4.0

package/src/index.ts

@@ -0,0 +1,1601 @@
+// 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. (Base64-decoded values lose provenance the same way;
+// that case is the `.base64Decoded()` provenance transform on `expect(...)`.)
+// 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";
+
+export type {
+  Browser,
+  BrowserOptions,
+  ScreenshotFormat,
+  ScreenshotOptions,
+} from "./browser.js";
+
+import type { Browser, BrowserOptions } from "./browser.js";
+
+export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
+
+import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
+
+// Low-level ingress primitives + the framework lowering that the friendly
+// `tls` / `hostnames` fields and `defineFake(...)` are built on. See
+// `ingress.ts`.
+export {
+  certificate,
+  dnsName,
+  proxy,
+  provides,
+  lowerIngress,
+  isWildcard,
+  SELF_SERVICE_TOKEN,
+} from "./ingress.js";
+export type {
+  CertificateDecl,
+  DnsDecl,
+  ProxyDecl,
+  IngressDecl,
+  DnsTarget,
+  LoweredIngress,
+} from "./ingress.js";
+import type { DnsTarget } from "./ingress.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Environment configuration
+// ──────────────────────────────────────────────────────────────────────────
+
+export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
+  /** Human-friendly name for the environment, e.g. "my-app". */
+  name: string;
+  /**
+   * Services that make up the environment, keyed by service name. The key
+   * is the container name, the DNS hostname on `spectest-net`, and the
+   * string used in `dependsOn` references.
+   */
+  services: S;
+  /** Sandbox timeout in seconds (default 1h). */
+  timeoutSecs?: number;
+}
+
+/**
+ * The shape that ends up in the JSON config the control plane and Rust
+ * mirror care about. `ServiceDefinition` is the same thing with an extra
+ * non-serialisable `client` factory tacked on; `JSON.stringify` drops
+ * functions, so the wire format is `ServiceConfig`.
+ */
+export interface ServiceConfig {
+  /** Image definition: registry pull or inline build. */
+  image: ServiceImage;
+  /**
+   * Shell command to run (sh -c). Defaults to the image's CMD. NB: this
+   * **replaces the image's entrypoint** with `/bin/sh -c` — an
+   * init-wrapped image (postgres's `docker-entrypoint.sh`) skips its
+   * initialization. Use {@link args} to keep the entrypoint.
+   */
+  command?: string;
+  /**
+   * Arguments appended after the image name (`docker run <image>
+   * <args…>`) — a CMD override that **keeps the image's entrypoint**.
+   * E.g. `args: ["postgres", "-c", "wal_level=logical"]` still runs
+   * postgres's `docker-entrypoint.sh` initialization. Mutually
+   * exclusive with {@link command}.
+   */
+  args?: 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?: number[];
+  /**
+   * Extra DNS names this service answers to inside the environment.
+   * Each entry must be a fully-qualified, multi-label hostname (e.g.
+   * `api.stripe.com`). Both peer containers (via Docker's embedded DNS)
+   * and code on the VM host (via spectest-resolver) resolve these names
+   * to the service's IP on `spectest-net`. Useful for mocking external
+   * APIs — point an SDK at `http://api.stripe.com` and a service of
+   * yours answers directly (no proxy). For HTTPS, use {@link tls}
+   * instead — those names terminate TLS in the daemon and reverse-proxy
+   * to the service's HTTP port.
+   *
+   * The `.internal` TLD is reserved: every service automatically
+   * answers to `<name>.internal` in addition to its bare `<name>`, and
+   * user-supplied hostnames may not end in `.internal`.
+   */
+  hostnames?: string[];
+  /**
+   * Expose this service over HTTPS via a TLS-terminating reverse proxy
+   * hosted in the spectest-daemon. Each entry maps a fully-qualified
+   * hostname to the HTTP port the service listens on inside its
+   * container; the daemon binds the hostname on `:443` (SNI-multiplexed,
+   * with a leaf cert signed by the in-VM root CA) and on `:80`, and
+   * proxies the request to `http://<service>:<port>`. WebSocket
+   * upgrades are forwarded.
+   *
+   * The in-VM root CA is already trusted by Chromium (`ctx.browser()`)
+   * and by service-container runtimes (Node, Python, Go, etc.) via
+   * the env-var bundle, so `https://<hostname>/` Just Works from
+   * tests and from peer services. Hostname rules match {@link hostnames}:
+   * multi-label, lowercase, no `.internal` suffix, no collision with
+   * services, other service TLS hostnames, or fakes.
+   */
+  tls?: ServiceTls[];
+  /** Bind-mounted volumes for state that survives snapshot/fork. */
+  volumes?: 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?: FileMount[];
+  /** Other services (keys in the services map) that must be ready first. */
+  dependsOn?: 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?: 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;
+}
+
+/**
+ * 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). `name` is the key the user
+   * chose in the services map and matches the in-VM DNS name.
+   */
+  helpers?: (args: { name: string }) => 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.
+   */
+  setup?: (args: { name: string; helpers: H }) => void | Promise<void>;
+}
+
+/** A services map — what users pass to `environment.services`. Entries
+ * can be plain `ServiceConfig` literals or `ServiceDefinition`s that
+ * carry a `helpers` factory (e.g. what `postgres(...)` returns). */
+export type ServicesMap = Record<string, ServiceConfig>;
+
+/** Awaited return type of a service's `helpers` factory, or `never` if
+ * the service doesn't ship one. */
+type HelpersOf<D> = D extends {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  helpers: (...args: any) => infer R;
+}
+  ? Awaited<R>
+  : never;
+
+/**
+ * Per-service handles derived from a concrete services map. Only
+ * services that ship a `helpers` factory appear here; `ctx.svc.<name>`
+ * is exactly the record the factory returned (e.g. `{ client: SqlClient }`
+ * for `postgres(...)`). Services without helpers don't show up at all,
+ * so plain `services: { api: { image: ... } }` adds no noise.
+ */
+export type ServiceHandlesFor<S extends ServicesMap> = {
+  [K in keyof S as HelpersOf<S[K]> extends never ? never : K]: HelpersOf<S[K]>;
+};
+
+/** Loose, runtime-friendly shape of `ctx.svc` for code that doesn't
+ * know the concrete services map (the daemon, generic helpers). The
+ * typed `ctx.svc` in test bodies is `ServiceHandlesFor<S>`. */
+export type ServiceHandles = Record<string, Record<string, unknown>>;
+
+/**
+ * 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?: string[];
+    };
+
+export interface VolumeMount {
+  /**
+   * Host path. Relative paths resolve under
+   * `.spectest/volumes/<service>/`. Defaults to a path derived from `target`.
+   */
+  source?: string;
+  /** Container path. */
+  target: string;
+  readOnly?: boolean;
+  /**
+   * Cache volume: the backing dir lives outside the per-env state tree and
+   * survives a delta-restore teardown (which recreates every container,
+   * volume, and the daemon for fresh-state semantics). Reserve this for
+   * content-addressed data whose presence is purely an accelerator — an
+   * image/layer store, a package cache — never for app state: anything in
+   * a cache volume is visible to the "fresh" environment.
+   */
+  cache?: boolean;
+}
+
+export interface FileMount {
+  /** Absolute path inside the container where the file is mounted. */
+  path: string;
+  /**
+   * File contents. The literal token `{{SPECTEST_SERVICE}}` is expanded
+   * to the owning service's name (its services-map key) before the file
+   * is written — handy for self-referential config like a registry host
+   * of `<key>.internal`, where a component can't know the key in advance.
+   */
+  content: string;
+  /**
+   * Optional octal mode string (e.g. `"0644"`) applied to the staged
+   * file before it's bind-mounted. Defaults to the writer's umask.
+   */
+  mode?: string;
+}
+
+export type ReadyCheck =
+  | { type: "tcp"; port: number; timeoutSecs?: number }
+  | { type: "http"; port: number; path?: string; 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 the two fields that only make sense at boot:
+ *
+ *  - `tls` — runtime services are reached *directly* by their own IP on
+ *    `spectest-net` (like a real machine on a network), not through the
+ *    daemon's HTTP ingress, so there's no proxy/cert to configure. Map a
+ *    friendly DNS name onto one with {@link TestContext.dnsName}.
+ *  - `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.
+ */
+export interface RuntimeServiceSpec extends Omit<ServiceConfig, "tls" | "dependsOn"> {
+  /**
+   * Container name and primary DNS name on `spectest-net`. Must be unique
+   * within the current fork — generate a fresh one per provisioned instance
+   * (e.g. `db-${crypto.randomUUID().slice(0, 8)}`).
+   */
+  name: string;
+}
+
+/** What {@link TestContext.startService} resolves to once the container is up
+ *  and its `readyCheck` (if any) has passed. */
+export interface RuntimeServiceHandle {
+  /** The container/DNS name — the spec's `name`. */
+  name: string;
+  /** The container's IP on `spectest-net`. Reachable directly from peer
+   *  containers and from VM-host/test code. */
+  ip: string;
+}
+
+/**
+ * The slice of the environment a fake can mutate at runtime — the same
+ * primitives {@link TestContext} exposes to tests. Passed as the third
+ * argument to a fake's `handler` and as `ctx` to its `helpers` factory, so
+ * a fake (e.g. a database-provider control plane) can provision real
+ * backing services on demand and wire up DNS for them, exactly as a test
+ * would.
+ */
+export interface FakeContext {
+  /** Start a real container on `spectest-net` at runtime. See
+   *  {@link RuntimeServiceSpec}. */
+  startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
+  /** Stop and remove a runtime service started earlier (no-op if gone). */
+  stopService(name: string): Promise<void>;
+  /** Map a DNS name onto a service IP (or the daemon ingress). See
+   *  {@link TestContext.dnsName}. */
+  dnsName(hostname: string, target: DnsTarget): Promise<void>;
+}
+
+function validateEnvironmentConfig<S extends ServicesMap>(
+  config: EnvironmentConfig<S>,
+): void {
+  const entries = Object.entries(config.services);
+  const serviceNames = new Set(entries.map(([n]) => n));
+  const claimedBy = new Map<string, string>();
+  const claimBy = (h: string, name: string, kind: "hostname" | "tls"): void => {
+    const prior = claimedBy.get(h);
+    if (prior !== undefined && prior !== name) {
+      throw new Error(
+        `hostname ${JSON.stringify(h)} is claimed by both "${prior}" and "${name}"`,
+      );
+    }
+    if (serviceNames.has(h)) {
+      throw new Error(
+        `${kind} ${JSON.stringify(h)} collides with service name "${h}"`,
+      );
+    }
+    claimedBy.set(h, name);
+  };
+  for (const [name, svc] of entries) {
+    if (name.length === 0) {
+      throw new Error(
+        "service name (services map key) must be a non-empty string",
+      );
+    }
+    for (const dep of svc.dependsOn ?? []) {
+      if (!serviceNames.has(dep)) {
+        throw new Error(
+          `service "${name}" dependsOn "${dep}" which is not a service in this environment`,
+        );
+      }
+    }
+    for (const raw of svc.hostnames ?? []) {
+      const h = raw.toLowerCase();
+      if (!HOSTNAME_RE.test(h)) {
+        throw new Error(
+          `service "${name}" declares invalid hostname ${JSON.stringify(raw)} — must be a multi-label DNS name (e.g. "api.stripe.com")`,
+        );
+      }
+      if (h === "internal" || h.endsWith(".internal")) {
+        throw new Error(
+          `service "${name}" declares hostname ${JSON.stringify(raw)} — the ".internal" TLD is reserved; every service already answers to "<name>.internal" automatically`,
+        );
+      }
+      claimBy(h, name, "hostname");
+    }
+    for (const entry of svc.tls ?? []) {
+      if (!entry || typeof entry.hostname !== "string" || typeof entry.port !== "number") {
+        throw new Error(
+          `service "${name}" tls entry must be { hostname: string, port: number }; got ${JSON.stringify(entry)}`,
+        );
+      }
+      const h = entry.hostname.toLowerCase();
+      if (!HOSTNAME_RE.test(h)) {
+        throw new Error(
+          `service "${name}" tls hostname ${JSON.stringify(entry.hostname)} is not a multi-label DNS name (e.g. "app.test")`,
+        );
+      }
+      if (h === "internal" || h.endsWith(".internal")) {
+        throw new Error(
+          `service "${name}" tls hostname ${JSON.stringify(entry.hostname)} ends in reserved ".internal" TLD`,
+        );
+      }
+      if (!Number.isInteger(entry.port) || entry.port <= 0 || entry.port > 65535) {
+        throw new Error(
+          `service "${name}" tls hostname ${JSON.stringify(entry.hostname)} has invalid port ${entry.port}`,
+        );
+      }
+      claimBy(h, name, "tls");
+    }
+  }
+}
+
+// Multi-label hostname: at least one dot, each label 1–63 chars of
+// [a-z0-9-], no leading/trailing hyphen.
+const HOSTNAME_RE =
+  /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/;
+
+// ──────────────────────────────────────────────────────────────────────────
+// Test framework
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * A single test step. Created via `test(...)` or `createTest(services)`.
+ * Tests are referenced (not named by string) when one test depends on
+ * another — keeps refactors and type-checking honest.
+ *
+ * `T` is the return type of the test body; it surfaces as `ctx.parent`
+ * in children that `dependsOn` this case. `S` is the project's services
+ * map (threaded through `defineEnvironment(...).test`) so `ctx.svc.<key>`
+ * is strongly typed.
+ */
+export interface TestCase<
+  T = unknown,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  /** Stable id (slug of name). Used in MCP responses and CLI flags. */
+  readonly id: string;
+  readonly name: string;
+  /** Parent test, if any. Single-parent for now. */
+  readonly dependsOn?: TestCase<unknown, S, F>;
+  /** Override the default per-test timeout (default 60s). */
+  readonly timeoutMs?: number;
+  /** @internal — the body that the in-sandbox daemon invokes. */
+  readonly run: TestFn<T, unknown, S, F>;
+}
+
+export interface TestOpts<
+  P = undefined,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  dependsOn?: TestCase<P, S, F>;
+  timeoutMs?: number;
+}
+
+export type TestFn<
+  T = void,
+  P = undefined,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> = (ctx: TestContext<P, S, F>) => T | Promise<T>;
+
+/**
+ * Context object passed to every test function.
+ *
+ * `P` is the return type of the parent test (the one named in
+ * `dependsOn`); for root tests it's `undefined`. `S` is the project's
+ * services map (threaded through `defineEnvironment(...).test`) so
+ * `ctx.svc` only includes services with a `client` factory, each typed
+ * as the factory's output (e.g. a Bun SQL pool for `postgres(...)`).
+ */
+export interface TestContext<
+  P = undefined,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  /**
+   * Instrumented `fetch`, exposed on `ctx`. Each call is recorded on the
+   * test timeline and resolves to a {@link WrappedResponse}: reads carry
+   * provenance so `expect(res.status)` / `expect(await res.json())` nest
+   * under the HTTP call. Because the status-line accessors are
+   * {@link Carrier}s, a raw `res.status === 200` is a *type error* — use
+   * `res.status.unwrap()` / `res.unwrap().status`, or assert via `expect`.
+   *
+   * (The plain global `fetch` is wrapped the same way at runtime but keeps
+   * the standard `Response` type, so prefer `ctx.fetch` for honestly-typed
+   * results.)
+   */
+  fetch: SpectestFetch;
+  /** Run `sh -lc <command>` inside a service container. The result is
+   *  {@link Wrapped}, so `res.stdout` is a `Carrier<string>` — assert via
+   *  `expect(res.stdout)` or recover the raw string with `res.stdout.unwrap()`.
+   *  (In `setup`/`eval` the result is wrapped too, just without a timeline
+   *  link, so `.unwrap()` works there the same way.)
+   *
+   *  The full run is also captured as an asciicast and replayed in the
+   *  web UI — one recording per call, with output timestamped as it
+   *  streamed, so slow or animated CLI output can be watched rather
+   *  than read as a final blob. Unlike `terminal` there is no PTY: the
+   *  program sees plain pipes (`isatty` false), so stdout/stderr stay
+   *  byte-identical to what `exec` always returned and TTY-gated
+   *  spinners/colour won't be emitted — reach for `terminal` when the
+   *  CLI needs to believe it's on a TTY. */
+  exec(service: string, command: string): Promise<Wrapped<ExecResult>>;
+  /**
+   * Run a command inside a service container under a PTY and record the
+   * full terminal session as an asciicast for replay in the web UI.
+   * Unlike `exec`, the program sees a TTY (`isatty(1)` true, colour
+   * codes preserved, line-buffered), so the byte stream may differ from
+   * what `exec` returns. Reach for `terminal` when you're driving a CLI
+   * and want a recording; reach for `exec` for plain piped output.
+   *
+   * One-shot convenience: this is a thin wrapper over `openTerminal` —
+   * spawn `command`, wait for exit, close, return the captured output
+   * and exit code. Reach for `openTerminal` when you want to keep the
+   * session alive across multiple sends or `waitFor` predicates (e.g.
+   * driving an interactive REPL or waiting on a loading spinner).
+   */
+  terminal(
+    service: string,
+    command: string,
+    opts?: TerminalOpts,
+  ): Promise<Wrapped<TerminalResult>>;
+  /**
+   * Open a long-lived interactive terminal in a service container.
+   * Returns a `Terminal` you can `send` keystrokes to, poll the
+   * rendered screen with `waitFor`, and `close` when done. Every byte
+   * the PTY emits is captured as an asciicast and replayed in the web
+   * UI the same way a one-shot `terminal(...)` is.
+   *
+   * Terminals are NOT auto-closed when the test ends. A docker exec
+   * subprocess is cheap to keep alive and Freestyle captures it
+   * cleanly in the snapshot along with the rest of the container, so
+   * leaking the handle past test end is fine. Call `.close()`
+   * explicitly if you want a `close` step in the timeline; otherwise
+   * `await term.exited` (after the program self-terminates) is the
+   * natural way to assert on the exit code.
+   */
+  openTerminal(service: string, opts?: TerminalOpts): Promise<Terminal>;
+  /**
+   * Open a headless browser. Backed by Chromium-over-CDP inside the VM.
+   * Every view is auto-closed when the test finishes; call `.close()` to
+   * release earlier if you're opening many.
+   */
+  browser(opts?: BrowserOptions): Promise<Browser>;
+  /** The test's display name. */
+  readonly testName: string;
+  /**
+   * Value returned by the parent test. Carried across the fork in the
+   * daemon's own memory (Freestyle's snapshot is memory + filesystem), so
+   * any JS value works — including Maps, Sets, class instances, and live
+   * connections that survive the fork. `undefined` for root tests or when
+   * the parent returned nothing.
+   */
+  readonly parent: P;
+  /**
+   * Per-service helper namespaces, keyed by service name. Only services
+   * whose definition ships a `helpers` factory appear here; the value at
+   * `ctx.svc.<name>` is exactly the record that factory returned. For a
+   * `postgres(...)` service that ships `{ client }`, tests do
+   * `await ctx.svc.db.client\`SELECT 1\``.
+   */
+  readonly svc: ServiceHandlesFor<S>;
+  /**
+   * Per-fake helper namespaces, keyed by fake name. Each is the record
+   * of functions the fake's `helpers` factory returned (or `{ state }`
+   * when it ships none — tests never touch a fake's private state
+   * directly). Those functions read/mutate the fake's state internally;
+   * the state itself is in-process and lives across the fork along with
+   * the rest of daemon memory, so calls in a child test see the fork's
+   * own copy as mutated by its ancestors. Every helper call is recorded
+   * as a step and its return value tracked, so assertions on it nest
+   * under the call in the timeline.
+   *
+   * Strongly typed against the project's fakes map when fakes are
+   * declared in `defineEnvironment({ ..., fakes })`: `ctx.fakes.stripe`
+   * is exactly the helpers record `defineFake`'s `helpers` factory
+   * returned — no cast. (Falls back to a loose record only when the
+   * environment declares no fakes.)
+   */
+  readonly fakes: FakeHandlesFor<F>;
+  /**
+   * Poll a predicate until it returns a truthy value, then return that
+   * value. Records one `wait` event for the whole loop (with attempt
+   * count, total duration, and the description) instead of one event
+   * per probe — useful for "wait until pod Running"-style checks where
+   * the intermediate states are noise.
+   *
+   * - `null`, `undefined`, or `false` from `fn` mean "not yet" — wait
+   *   `intervalMs` and try again.
+   * - Anything else is the success value and is returned, tagged with
+   *   the wait event's seq. Downstream `expect(...)` on it links to
+   *   the wait (one logical step), not to N suppressed HTTP calls.
+   * - Throws from `fn` propagate out immediately; the wait event is
+   *   still recorded (with `error` set) so the timeline reflects the
+   *   abort.
+   * - Defaults: `timeoutMs = 30_000`, `intervalMs = 1_000`.
+   *
+   * Side-effect calls inside `fn` (fetch, ctx.svc.* helpers, etc.)
+   * don't show up on the event log — the recorder is paused for the
+   * duration. Use `ctx.poll` for read-only observation, not for
+   * stateful work you want recorded.
+   */
+  poll<T>(
+    description: string,
+    fn: () => T | null | undefined | false | Promise<T | null | undefined | false>,
+    opts?: { timeoutMs?: number; intervalMs?: number },
+  ): Promise<Wrapped<T>>;
+  /**
+   * Register a DNS name at runtime so the rest of this test (and anything
+   * downstream of it) can reach it. `{ ingress: true }` points the name at
+   * the daemon (a fake / TLS proxy); `{ service }` points it at a
+   * container's live IP; a `*.suffix` wildcard (e.g. `"*.example.com"`)
+   * routes a whole domain — the natural fit for k3s Ingress hosts a test
+   * applies on the fly.
+   *
+   * Answered by spectest-resolver, so it works for VM-host/test code,
+   * `ctx.browser()`, and peer containers (Docker forwards unknown names to
+   * the host resolver). It does NOT land in any container's `/etc/hosts`.
+   * The registration mutates in-daemon state, so it's isolated to this
+   * test's fork — like fake state.
+   *
+   * ```ts
+   * await ctx.svc.k8s.apply(ingressFor("foo.example.com"));
+   * await ctx.dnsName("foo.example.com", { service: "k8s" });
+   * const res = await ctx.fetch("http://foo.example.com");
+   * ```
+   */
+  dnsName(hostname: string, target: DnsTarget): Promise<void>;
+  /**
+   * Start a real container on `spectest-net` at runtime — a peer machine
+   * with its own IP, reachable like any boot service. Returns once the
+   * container is up and its `readyCheck` (if any) has passed.
+   *
+   * The new container is part of this test's post-state snapshot, so a
+   * `dependsOn` child inherits it (same PID, same data) while siblings,
+   * which fork from the parent's earlier snapshot, never see it — the same
+   * isolation fake `state` and {@link dnsName} get. Reach it by `name`
+   * (single-label, via the resolver) or by any `hostnames` you pass; map a
+   * multi-label name onto it with `ctx.dnsName(host, { service: name })`.
+   *
+   * The image is pulled on first use (fast through the host cache). See
+   * {@link RuntimeServiceSpec}.
+   *
+   * ```ts
+   * const { name } = await ctx.startService({
+   *   name: `db-${crypto.randomUUID().slice(0, 8)}`,
+   *   image: { type: "registry", reference: "postgres:16-alpine" },
+   *   env: { POSTGRES_PASSWORD: "secret" },
+   *   readyCheck: { type: "exec", command: "pg_isready -h 127.0.0.1 -p 5432" },
+   * });
+   * const sql = new Bun.SQL(`postgres://postgres:secret@${name}:5432/postgres`);
+   * ```
+   */
+  startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
+  /** Stop and remove a runtime service started via {@link startService}
+   *  (no-op if it's already gone). */
+  stopService(name: string): Promise<void>;
+}
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface TestSuite<
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  tests: TestCase<unknown, S, F>[];
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Fakes — in-daemon HTTP servers that masquerade as external APIs.
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * A fake server hosted in the spectest-daemon. Use this to stand in for
+ * external HTTP APIs (auth providers, payment gateways, …) that you can't
+ * call directly from the hermetic test VM.
+ *
+ * Each fake declares one or more `hostnames` it answers to. The daemon
+ * binds an HTTP listener per unique `port` on 0.0.0.0 (the bridge gateway
+ * is reachable from every service container), and `spectest-resolver`
+ * answers DNS for those hostnames with the bridge gateway IP. Containers
+ * doing `fetch("http://api.stripe.com/v1/charges")` route into the daemon,
+ * which dispatches to the matching fake by Host header.
+ *
+ * Internal state lives in plain JS memory — it forks with the rest of the
+ * snapshot, so per-test forks start from a known baseline and each fork
+ * has its own copy. State is private to the fake; expose it for assertions
+ * via `helpers` functions that tests call as `ctx.fakes.<name>.<fn>(...)`.
+ *
+ * HTTPS works out of the box. Every fake is auto-bound on :443 with a
+ * leaf cert signed by the in-VM root CA (SANs = `hostnames`), and
+ * every service container trusts that CA via bind-mount + system-trust
+ * layer — point your app at `https://api.stripe.com` and it Just Works.
+ * HTTP also stays bound on `port` (default 80) for back-compat.
+ */
+export interface FakeDefinition<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  S = any,
+  H extends Record<string, unknown> = Record<string, never>,
+> {
+  /** Stable name. Used as the key in `ctx.fakes` and in logs/UI. */
+  name: string;
+  /**
+   * Fully-qualified hostnames the fake answers to (e.g.
+   * `"api.stripe.com"`). Same rules as service `hostnames`: multi-label,
+   * lowercase, no `.internal` suffix, no collisions with services or
+   * other fakes.
+   */
+  hostnames: 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?: string[];
+}
+
+/**
+ * Define a fake. `defineFake({ ... })` is a thin wrapper that pins the
+ * generic `S` and `H` so `helpers`/`handler` see the inferred state type
+ * without the caller having to spell it out twice.
+ */
+export function defineFake<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  S = any,
+  H extends Record<string, unknown> = Record<string, never>,
+>(opts: FakeDefinition<S, H>): FakeDefinition<S, H> {
+  if (!opts.name || opts.name.length === 0) {
+    throw new Error("defineFake: `name` is required");
+  }
+  if (!Array.isArray(opts.hostnames) || opts.hostnames.length === 0) {
+    throw new Error(`defineFake(${opts.name}): at least one hostname is required`);
+  }
+  for (const h of opts.hostnames) {
+    const lower = h.toLowerCase();
+    if (!HOSTNAME_RE.test(lower)) {
+      throw new Error(
+        `defineFake(${opts.name}): invalid hostname ${JSON.stringify(h)} — must be a multi-label DNS name (e.g. "api.stripe.com")`,
+      );
+    }
+    if (lower === "internal" || lower.endsWith(".internal")) {
+      throw new Error(
+        `defineFake(${opts.name}): hostname ${JSON.stringify(h)} ends in reserved ".internal" TLD`,
+      );
+    }
+  }
+  if (typeof opts.handler !== "function") {
+    throw new Error(`defineFake(${opts.name}): \`handler\` is required`);
+  }
+  return opts;
+}
+
+/** Map of fake-name -> FakeDefinition, keyed by stable name. `any` for
+ * both generic args (not the bare `FakeDefinition` default of
+ * `<any, Record<string, never>>`) so a concrete fake that ships real
+ * `helpers` — whose `helpers`/`handler` function types would otherwise be
+ * invariant-incompatible with the narrower default — is still assignable.
+ * The precise per-fake helper types are recovered by `FakeHandlesFor<F>`
+ * at use sites. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type FakesMap = Record<string, FakeDefinition<any, any>>;
+
+/** Rewrite a helpers record so each function's result is inspect-wrapped
+ * ({@link Wrapped}) — mirroring the runtime, where `trackFakeHelpers` wraps
+ * every helper return value for assertion provenance. Without this the raw
+ * return type (e.g. `Charge[]`) reaches `expect`, which the `Provenanced`
+ * gate rejects. Handles sync and async helpers; non-function members (and
+ * `void` side-effect helpers) pass through untouched. Mirrors `Tagged<T>` in
+ * `components/k3s.ts`, extended to cover synchronous returns. */
+type WrappedHelpers<H> = {
+  [K in keyof H]: H[K] extends (...args: infer A) => Promise<infer R>
+    ? (...args: A) => Promise<Wrapped<R>>
+    : H[K] extends (...args: infer A) => infer R
+      ? (...args: A) => [R] extends [void] ? void : Wrapped<R>
+      : H[K];
+};
+
+/** Awaited return type of a fake's `helpers` factory (with each result
+ * inspect-wrapped, see {@link WrappedHelpers}), or `{ state: S }` (the
+ * default) when the user didn't ship one. */
+type FakeHelpersOf<F> = F extends FakeDefinition<infer S, infer H>
+  ? [H] extends [Record<string, never>]
+    ? { state: S }
+    : WrappedHelpers<H>
+  : never;
+
+/** Per-fake handles derived from a concrete fakes map; what tests see at
+ * `ctx.fakes`. For a concrete map (fakes declared in `defineEnvironment`)
+ * each key is the precise helpers record. When `F` is the loose default
+ * `FakesMap` (no fakes declared, or generic daemon-side code), this
+ * collapses to a permissive record so untyped access still compiles. */
+export type FakeHandlesFor<F extends FakesMap> = string extends keyof F
+  ? Record<string, Record<string, unknown>>
+  : { [K in keyof F]: FakeHelpersOf<F[K]> };
+
+/**
+ * A `test(...)` function bound to a concrete services map (and fakes map).
+ * Returned by `defineEnvironment(...).test`; gives tests fully-typed access
+ * to `ctx.svc.<key>` and `ctx.fakes.<key>` without per-call casts.
+ */
+export interface TypedTest<
+  S extends ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  <T = void>(name: string, fn: TestFn<T, undefined, S, F>): TestCase<T, S, F>;
+  <T = void, P = undefined>(
+    name: string,
+    opts: TestOpts<P, S, F>,
+    fn: TestFn<T, P, S, F>,
+  ): TestCase<T, S, F>;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Project (the unified default export)
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * A complete project definition: an environment, an optional one-shot
+ * setup hook, and an optional test suite. `spectest/index.ts`
+ * default-exports one of these via `env.project([...tests])` or
+ * `env.project({ setup, tests })`.
+ */
+export interface Project<
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  environment: EnvironmentConfig<S>;
+  /**
+   * Fake servers hosted in the spectest-daemon (see {@link defineFake}).
+   * Keyed by stable fake name; the key becomes the slot in
+   * `ctx.fakes.<key>` from test code. Populated from the `fakes` declared
+   * in `defineEnvironment(...)`.
+   */
+  fakes?: F;
+  /**
+   * Project-level setup. Runs once, after every service is Ready and
+   * its per-service `setup` has completed, before the warm-template
+   * snapshot. Use this for state that's part of "the environment as
+   * the tests expect to find it" — seed data in a database, an initial
+   * Deployment in k3s, etc. Like service-level setup, the result is
+   * captured by every snapshot taken from that point, so warm restore
+   * and per-test forks inherit it without re-running.
+   *
+   * The ctx here is a slimmer cousin of TestContext: no recorder, no
+   * timeout, no browser/terminal — setup is not a test and doesn't
+   * appear in the timeline.
+   */
+  setup?: ProjectSetupFn<S, F>;
+  tests?: TestSuite<S, F>;
+}
+
+/**
+ * Slim context handed to the project-level `setup` hook. Same shape as
+ * `TestContext` but pared down — no testName, no parent, no recording
+ * surfaces (browser, terminal, poll). If you need polling inside setup,
+ * write a plain loop: setup runs outside the test timeline so there's
+ * nothing to record into.
+ */
+export interface ProjectSetupContext<
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  fetch: SpectestFetch;
+  exec(service: string, command: string): Promise<Wrapped<ExecResult>>;
+  readonly svc: ServiceHandlesFor<S>;
+  /** Same surface tests see — fakes are already up by setup time. Typed
+   * against the declared fakes map (see {@link TestContext.fakes}). */
+  readonly fakes: FakeHandlesFor<F>;
+  /**
+   * Register a DNS name (see {@link TestContext.dnsName}). Useful here to
+   * wire a wildcard like `"*.example.com"` to a k3s cluster once, before
+   * any test runs — it's captured into the warm-template snapshot, so every
+   * test inherits the route without re-registering.
+   */
+  dnsName(hostname: string, target: DnsTarget): Promise<void>;
+  /**
+   * Start a runtime service (see {@link TestContext.startService}). Started
+   * here, it's captured into the warm-template snapshot and inherited by
+   * every test — use it for backing instances that should exist before any
+   * test runs but aren't worth a boot-time `services` entry.
+   */
+  startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
+  /** Stop a runtime service (see {@link TestContext.stopService}). */
+  stopService(name: string): Promise<void>;
+}
+
+export type ProjectSetupFn<
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> = (ctx: ProjectSetupContext<S, F>) => void | Promise<void>;
+
+/**
+ * A defined environment. Returned by `defineEnvironment(...)` and used to
+ * (a) build typed tests against this environment's services and (b)
+ * bundle those tests into the project's default export.
+ *
+ * ```ts
+ * const env = defineEnvironment({
+ *   name: "todos",
+ *   services: {
+ *     db: postgres({ database: "todos", user: "todos", password: "todos" }),
+ *   },
+ * });
+ *
+ * const createTodo = env.test("create todo", async (ctx) => {
+ *   // ctx.svc.db.client is the Bun SQL pool (the helper postgres ships).
+ *   await ctx.svc.db.client`SELECT 1`;
+ *   return { id: 1 };
+ * });
+ *
+ * const markDone = env.test(
+ *   "mark done",
+ *   { dependsOn: createTodo },
+ *   async (ctx) => {
+ *     // ctx.parent is { id: number }
+ *     await ctx.svc.db.client`UPDATE todos SET done = TRUE WHERE id = ${ctx.parent.id}`;
+ *   },
+ * );
+ *
+ * export default env.project([createTodo, markDone]);
+ * ```
+ */
+export interface ProjectOpts<
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  /** Optional project-level setup. See `Project.setup`. */
+  setup?: ProjectSetupFn<S, F>;
+  /** Test cases for this project's suite. */
+  tests?: TestCase<unknown, S, F>[];
+}
+
+/**
+ * Input to {@link defineEnvironment}: the environment config plus an
+ * optional `fakes` map. `fakes` is declared here (rather than on
+ * `project(...)`) so the fakes' types are bound when `env.test(...)`
+ * creates a test — that's what makes `ctx.fakes.<key>` strongly typed.
+ * `fakes` is stripped from `config` before it's stored/serialised, so the
+ * wire `EnvironmentConfig` the Rust control plane sees never carries it.
+ */
+export interface EnvironmentInput<
+  S extends ServicesMap,
+  F extends FakesMap = FakesMap,
+> extends EnvironmentConfig<S> {
+  /** 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>;
+}
+
+/**
+ * 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<
+  S extends ServicesMap,
+  F extends FakesMap = FakesMap,
+>(input: EnvironmentInput<S, F>): DefinedEnvironment<S, F> {
+  // Split fakes off the wire config; only { name, services, timeoutSecs }
+  // is stored as `config` and shipped to the control plane.
+  const { fakes, ...config } = input;
+  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;
+  toContain(expected: unknown): void;
+  toMatch(re: RegExp): void;
+  toHaveLength(n: number): void;
+}
+
+/**
+ * Provenance-preserving transforms. Each returns a fresh {@link Expectation}
+ * bound to the *decoded* value but still carrying the originating op's tag (its
+ * path extended by a marker like `<base64>`), so the eventual assertion nests
+ * under the source read in the timeline. This is what lets a value that must be
+ * decoded through a plain function — `Buffer.from(x,"base64").toString()`,
+ * `decodeURIComponent(x)` — be asserted on with the *full* matcher vocabulary
+ * (`toHaveLength`, `toContain`, `toMatch`, …) without dropping to `expectRaw`,
+ * which severs the link. Transforms chain (`.base64Decoded().urlDecoded()`),
+ * and the matcher you finish with may be negated (`.base64Decoded().not.…`).
+ *
+ * They supersede the old `toBeBase64Of` matcher, which was equality-only:
+ * `expect(secret.data?.X).base64Decoded().toBe("plain")` is the direct
+ * replacement, and `.toHaveLength(32)` / `.toContain("redis://")` / `.toMatch(re)`
+ * are the cases it couldn't express.
+ */
+interface Transforms {
+  /** Interpret the value as a base64 string and decode it (UTF-8), mirroring
+   *  `Buffer.from(x, "base64").toString()`. Throws-as-failed-assertion if the
+   *  value isn't a string. */
+  base64Decoded(): Expectation;
+  /** URL-decode the value, mirroring `decodeURIComponent(x)`. Chains after
+   *  `base64Decoded()` for base64-then-URL-encoded values. */
+  urlDecoded(): Expectation;
+  /**
+   * Generic escape hatch: apply an arbitrary `fn` to the raw value and assert on
+   * the result, keeping provenance. `label` is a plain word (`"json"`,
+   * `"decompressed"`) appended to the op path so the timeline shows what was
+   * derived; the UI brackets it (`<json>`) to mark it as a derived step, so do
+   * **not** include the brackets yourself. Sugar like {@link base64Decoded} is
+   * built on this. If `fn` throws, the next assertion records as a failure
+   * describing the transform error.
+   */
+  transform(label: string, fn: (value: unknown) => unknown): Expectation;
+}
+
+export interface Expectation extends Matchers, Transforms {
+  not: Matchers;
+}
+
+export function expect(actual: Provenanced): Expectation {
+  // The 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(message, value)` instead.
+  //
+  // 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);
+}
+
+/**
+ * Assert on a value with **no provenance** — a computed number, a raw
+ * WebSocket frame, anything that didn't flow from a recorded op. `message` is
+ * required and reads as the natural follow-on to "assert …" (e.g.
+ * `expectRaw("id matches the generated value", id)`); it renders as the
+ * assertion's label in the CLI/dashboard ("ASSERT <message>") since a raw
+ * assertion has no op to nest under. Prefer `expect(...)` whenever the value
+ * carries provenance — only reach for this when the type gate would (rightly)
+ * reject the value.
+ */
+export function expectRaw(message: string, actual: unknown): 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; pathSuffix?: string },
+  ): 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, ...(opts?.pathSuffix ? [opts.pathSuffix] : [])]
+        : undefined,
+    });
+    if (!passed) throw new ExpectationError(msg);
+  };
+  // Apply `fn` to the raw value and rebuild against the result, extending the
+  // op path by a derived-step marker so the decoded value still nests under the
+  // source read. `label` is a plain word ("base64", "json"); the `<…>` marker
+  // syntax that distinguishes a transform from a real property read in the
+  // timeline is added here, so it lives in one place and never leaks into the
+  // API surface — the same convention `inspect.ts` uses for array methods
+  // (`<find>`, `<map>`). A throw becomes a `pendingError` on the returned
+  // Expectation rather than escaping — a malformed decode renders as a failed
+  // assertion in the timeline, not an unhandled exception. Propagates an
+  // existing `pendingError` untouched.
+  const applyTransform = (label: string, fn: (value: unknown) => unknown): Expectation => {
+    const marker = `<${label}>`;
+    const nextTag: OpTag | undefined = tag
+      ? { sourceSeq: tag.sourceSeq, path: [...tag.path, marker] }
+      : undefined;
+    if (pendingError !== undefined) {
+      return buildCore(undefined, nextTag, false, message, pendingError);
+    }
+    try {
+      return buildCore(fn(actual), nextTag, false, message);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      return buildCore(undefined, nextTag, false, message, `${marker}: ${detail}`);
+    }
+  };
+  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,
+      );
+    },
+    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;
+      run(
+        "toHaveLength",
+        len === n,
+        `expected ${fmt(actual)}${negated ? " not" : ""} to have length ${n}` +
+          (len === undefined ? " (value has no length)" : ` (got ${len})`),
+        n,
+        { actual: len, pathSuffix: "length" },
+      );
+    },
+    transform(label, fn) {
+      return applyTransform(label, fn);
+    },
+    base64Decoded() {
+      return applyTransform("base64", (v) => {
+        if (typeof v !== "string") {
+          throw new Error(`base64Decoded expects a string, got ${typeof v}`);
+        }
+        return Buffer.from(v, "base64").toString();
+      });
+    },
+    urlDecoded() {
+      return applyTransform("urldecode", (v) => {
+        if (typeof v !== "string") {
+          throw new Error(`urlDecoded expects a string, got ${typeof v}`);
+        }
+        return decodeURIComponent(v);
+      });
+    },
+    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;