@specific.dev/spectest 0.26.0 → 0.27.0

package/dist/index.d.ts

@@ -0,0 +1,1183 @@
+import { strict as nodeAssert } from "node:assert";
+export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedResponse, Provenanced, SpectestFetch, Unwrap, } from "./inspect.js";
+import type { Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
+export { field } from "./inspect.js";
+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";
+export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, } from "./locator.js";
+import type { Locator } from "./locator.js";
+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";
+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";
+export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
+    /** Human-friendly name for the environment, e.g. "my-app". */
+    name: string;
+    /**
+     * Services that make up the environment, keyed by service name. The key
+     * is the container name, the DNS hostname on `spectest-net`, and the
+     * string used in `dependsOn` references.
+     */
+    services: S;
+    /** Sandbox timeout in seconds (default 1h). */
+    timeoutSecs?: number;
+}
+/**
+ * The shape that ends up in the JSON config the control plane and Rust
+ * mirror care about. `ServiceDefinition` is the same thing with an extra
+ * non-serialisable `client` factory tacked on; `JSON.stringify` drops
+ * functions, so the wire format is `ServiceConfig`.
+ */
+export interface ServiceConfig {
+    /** Image definition: registry pull or inline build. */
+    image: ServiceImage;
+    /**
+     * Shell command to run (sh -c). Defaults to the image's CMD. NB: this
+     * **replaces the image's entrypoint** with `/bin/sh -c` — an
+     * init-wrapped image (postgres's `docker-entrypoint.sh`) skips its
+     * initialization. Use {@link args} to keep the entrypoint.
+     */
+    command?: string;
+    /**
+     * Arguments appended after the image name (`docker run <image>
+     * <args…>`) — a CMD override that **keeps the image's entrypoint**.
+     * E.g. `args: ["postgres", "-c", "wal_level=logical"]` still runs
+     * postgres's `docker-entrypoint.sh` initialization. Mutually
+     * exclusive with {@link command}.
+     */
+    args?: readonly string[];
+    env?: Record<string, string>;
+    /**
+     * Ports the container listens on. Advisory only — surfaced in
+     * `spectest list` output. Peer services reach each other by `<service>:<port>`
+     * without any port declaration.
+     */
+    ports?: readonly number[];
+    /**
+     * Extra DNS names this service answers to inside the environment.
+     * Each entry must be a fully-qualified, multi-label hostname (e.g.
+     * `api.stripe.com`). Both peer containers (via Docker's embedded DNS)
+     * and code on the VM host (via spectest-resolver) resolve these names
+     * to the service's IP on `spectest-net`. Useful for mocking external
+     * APIs — point an SDK at `http://api.stripe.com` and a service of
+     * yours answers directly (no proxy). For HTTPS, use {@link tls}
+     * instead — those names terminate TLS in the daemon and reverse-proxy
+     * to the service's HTTP port.
+     *
+     * The `.internal` TLD is reserved: every service automatically
+     * answers to `<name>.internal` in addition to its bare `<name>`, and
+     * user-supplied hostnames may not end in `.internal`.
+     */
+    hostnames?: readonly string[];
+    /**
+     * Expose this service over HTTPS via a TLS-terminating reverse proxy
+     * hosted in the spectest-daemon. Each entry maps a fully-qualified
+     * hostname to the HTTP port the service listens on inside its
+     * container; the daemon binds the hostname on `:443` (SNI-multiplexed,
+     * with a leaf cert signed by the in-VM root CA) and on `:80`, and
+     * proxies the request to `http://<service>:<port>`. WebSocket
+     * upgrades are forwarded.
+     *
+     * The in-VM root CA is already trusted by Chromium (`ctx.browser()`)
+     * and by service-container runtimes (Node, Python, Go, etc.) via
+     * the env-var bundle, so `https://<hostname>/` Just Works from
+     * tests and from peer services. Hostname rules match {@link hostnames}:
+     * multi-label, lowercase, no `.internal` suffix, no collision with
+     * services, other service TLS hostnames, or fakes.
+     */
+    tls?: readonly ServiceTls[];
+    /** Bind-mounted volumes for state that survives snapshot/fork. */
+    volumes?: readonly VolumeMount[];
+    /**
+     * Files seeded into the container's filesystem **before it starts**.
+     * Each entry's `content` is written to a VM-host staging path and
+     * bind-mounted (read-only) at `path` inside the container. Unlike a
+     * `setup` hook — which runs after the container is up — `files` is the
+     * way to inject configuration a process reads at boot, e.g. k3s's
+     * `/etc/rancher/k3s/registries.yaml`, which must exist before
+     * `k3s server` starts.
+     */
+    files?: readonly FileMount[];
+    /** Other services (keys in the services map) that must be ready first. */
+    dependsOn?: readonly string[];
+    readyCheck?: ReadyCheck;
+    /** Container workdir override. */
+    workdir?: string;
+    /**
+     * Run the container with `--privileged`. Required by workloads that
+     * embed their own container runtime (e.g. k3s) and need full access
+     * to the host kernel surface. Off by default.
+     */
+    privileged?: boolean;
+    /**
+     * Tmpfs mounts (one `--tmpfs <path>` per entry). Required by some
+     * workloads — k3s wants `/run` and `/var/run` writable and
+     * non-persistent. Snapshots/forks preserve tmpfs contents along with
+     * the rest of process memory.
+     */
+    tmpfs?: readonly string[];
+    /**
+     * Cgroup namespace mode — `"host"` or `"private"`. Omit for docker's
+     * default. k3s needs `"host"` so its embedded containerd can manage
+     * cgroups for the pods it schedules.
+     */
+    cgroupns?: string;
+}
+/**
+ * The slice of the in-VM world a component's `setup` / `helpers` hooks can
+ * reach — beyond what the service definition itself declares. Handed to
+ * both hooks (see {@link ServiceSetupContext} / {@link ServiceHelpersContext})
+ * so components stop hand-rolling `child_process` docker execs and stop
+ * hard-coding control-plane paths like `/workspace`.
+ */
+export interface ComponentContext {
+    /**
+     * Absolute path of the extracted project root inside the VM — the
+     * directory the user's repo lands in, with `spectest/` directly under
+     * it. Use this (never a hard-coded path) to locate project files a
+     * component consumes, e.g. `supabase/migrations/**`.
+     */
+    projectRoot: string;
+    /** Read a project file as UTF-8. Relative paths resolve against
+     *  {@link projectRoot}; absolute paths are read as-is. */
+    readProjectFile(path: string): Promise<string>;
+    /**
+     * Run a command inside a service container (a raw `docker exec` — not
+     * recorded on any test timeline, result is plain, not
+     * provenance-wrapped). Pass an **array** for exact argv with no shell
+     * (`["psql", "-f", "-"]`), or a **string** to run via `sh -lc`.
+     * `opts.stdin` is piped to the process — the natural way to feed a SQL
+     * file to `psql -f -` or a manifest to `kubectl apply -f -`.
+     *
+     * Never throws on non-zero exit — inspect `exitCode` yourself.
+     */
+    exec(service: string, command: string | string[], opts?: ComponentExecOpts): Promise<ExecResult>;
+}
+/** Options for {@link ComponentContext.exec}. */
+export interface ComponentExecOpts {
+    /** Piped to the command's stdin, then closed. */
+    stdin?: string;
+    /** Working directory inside the container (`docker exec -w`). */
+    cwd?: string;
+    /** Kill the exec after this long. Default 120_000. */
+    timeoutMs?: number;
+}
+/** What a service's `setup` hook receives. */
+export interface ServiceSetupContext<H extends Record<string, any> = Record<string, never>> extends ComponentContext {
+    /** The service's key in the services map (container + DNS name). */
+    name: string;
+    /** The record the service's `helpers` factory returned (cached — setup
+     *  and tests share one instance), or `{}` when it ships none. */
+    helpers: H;
+}
+/** What a service's `helpers` factory receives. */
+export interface ServiceHelpersContext extends ComponentContext {
+    /** The service's key in the services map (container + DNS name). */
+    name: string;
+}
+/**
+ * Same shape as `ServiceConfig` plus an optional `helpers` factory that
+ * opens a namespace under `ctx.svc.<name>` inside tests. The factory
+ * returns a record — each key becomes `ctx.svc.<name>.<key>`. Components
+ * like `postgres(...)` use this to expose a pre-wired SQL pool at
+ * `ctx.svc.db.client`; nothing stops a component from exposing several
+ * helpers under one service (e.g. `client`, `admin`, `truncate()`).
+ */
+export interface ServiceDefinition<H extends Record<string, any> = Record<string, never>> extends ServiceConfig {
+    /**
+     * Build the helpers exposed at `ctx.svc.<name>.<key>`. Called by the
+     * daemon the first time a test touches this service; the result is
+     * cached for the lifetime of the daemon (it survives snapshot/fork
+     * along with the rest of daemon memory). `args.name` is the key the
+     * user chose in the services map and matches the in-VM DNS name; the
+     * rest of the {@link ServiceHelpersContext} (exec, projectRoot) lets a
+     * component reach into its containers without daemon internals.
+     */
+    helpers?: (args: ServiceHelpersContext) => H | Promise<H>;
+    /**
+     * One-shot setup after the container's `readyCheck` passes, before
+     * dependents start and before any test runs. Awaited in-line with
+     * bootstrap, so anything it produces (an ingress controller deployed
+     * into k3s, a schema applied to a database) is part of the warm-template
+     * snapshot and never re-runs on warm starts.
+     *
+     * `helpers` is the same record the `helpers` factory returns — building
+     * it is cached, so `setup` and tests share one instance. If the service
+     * doesn't declare `helpers`, the field is the empty object. The rest of
+     * the {@link ServiceSetupContext} carries `exec` (docker exec with
+     * stdin) and `projectRoot`/`readProjectFile` for project-file access.
+     */
+    setup?: (args: ServiceSetupContext<H>) => void | Promise<void>;
+}
+/** A services map — what users pass to `environment.services`. Entries
+ * can be plain `ServiceConfig` literals or `ServiceDefinition`s that
+ * carry a `helpers` factory (e.g. what `postgres(...)` returns). */
+export type ServicesMap = Record<string, ServiceConfig>;
+/** Awaited return type of a service's `helpers` factory, or `never` if
+ * the service doesn't ship one. */
+type HelpersOf<D> = D extends {
+    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>>;
+/** 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. */
+declare const SERVICE_GROUP: unique symbol;
+/**
+ * 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, 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, 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 declare function serviceGroup<P extends ServicesMap, 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>;
+/** What users pass as `services` to `defineEnvironment`: plain services
+ * and/or groups to expand. */
+export type InputServicesMap = Record<string, 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<{
+    [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;
+/**
+ * One TLS-terminated hostname for a service. The daemon binds the
+ * hostname on `:443` (with a leaf cert signed by the in-VM root CA)
+ * and `:80`, and reverse-proxies each request to `http://<service>:<port>`
+ * inside the docker network. WebSocket upgrades are bridged.
+ */
+export interface ServiceTls {
+    /** Fully-qualified hostname clients use (e.g. `app.test`). Must be
+     * multi-label, lowercase, not under the reserved `.internal` TLD,
+     * and unique across all services and fakes in this environment. */
+    hostname: string;
+    /** HTTP port the service listens on inside its container. The
+     * daemon forwards proxied requests here over `spectest-net`. */
+    port: number;
+}
+export type ServiceImage = {
+    type: "registry";
+    reference: string;
+} | {
+    type: "dockerfile";
+    /**
+     * Dockerfile contents, written verbatim into the build context. The
+     * build context is the project root (where `spectest/` lives), so any
+     * `COPY` / `ADD` references resolve relative to that directory.
+     */
+    content: string;
+    /** Extra glob patterns to exclude from the build context. */
+    exclude?: readonly string[];
+};
+export interface VolumeMount {
+    /**
+     * Named shared volume. Two services mounting the same `name` share one
+     * backing directory — the fit for sidecar pairs that exchange files
+     * (e.g. an image proxy reading what a storage API wrote). The directory
+     * lives in the per-env state tree, so it snapshots/forks with the rest
+     * of the environment and is torn down for fresh-state like any other
+     * volume. Names are environment-global: prefix with your service/group
+     * name in a reusable component so two instances never collide.
+     * Mutually exclusive with `source`.
+     */
+    name?: string;
+    /**
+     * Host path. Relative paths resolve under
+     * `.spectest/volumes/<service>/`. Defaults to a path derived from `target`.
+     */
+    source?: string;
+    /** Container path. */
+    target: string;
+    readOnly?: boolean;
+    /**
+     * Cache volume: the backing dir lives outside the per-env state tree and
+     * survives a delta-restore teardown (which recreates every container,
+     * volume, and the daemon for fresh-state semantics). Reserve this for
+     * content-addressed data whose presence is purely an accelerator — an
+     * image/layer store, a package cache — never for app state: anything in
+     * a cache volume is visible to the "fresh" environment.
+     */
+    cache?: boolean;
+}
+export interface FileMount {
+    /** Absolute path inside the container where the file is mounted. */
+    path: string;
+    /**
+     * File contents. The literal token `{{SPECTEST_SERVICE}}` is expanded
+     * to the owning service's name (its services-map key) before the file
+     * is written — handy for self-referential config like a registry host
+     * of `<key>.internal`, where a component can't know the key in advance.
+     */
+    content: string;
+    /**
+     * Optional octal mode string (e.g. `"0644"`) applied to the staged
+     * file before it's bind-mounted. Defaults to the writer's umask.
+     */
+    mode?: string;
+}
+export type ReadyCheck = {
+    type: "tcp";
+    port: number;
+    timeoutSecs?: number;
+} | {
+    type: "http";
+    port: number;
+    path?: string;
+    /**
+     * Extra request headers sent with each probe — for health endpoints
+     * behind auth (`{ Authorization: "Bearer …" }`). Keeps the probe
+     * image-agnostic where an `exec` + curl would depend on curl being
+     * in the image.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Exact status code that counts as ready. Default: any 2xx. Use for
+     * endpoints whose healthy answer isn't 2xx (e.g. a root path that
+     * 301s or 401s once the server is actually up).
+     */
+    expectStatus?: number;
+    timeoutSecs?: number;
+}
+/**
+ * Run a shell command inside the container; exit 0 = ready. Used when
+ * the readiness signal isn't reachable via plain TCP/HTTP from outside
+ * (k3s API server uses mTLS, so the natural probe is `kubectl get
+ * --raw=/readyz` from inside).
+ */
+ | {
+    type: "exec";
+    command: string;
+    timeoutSecs?: number;
+};
+/**
+ * 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>;
+}
+/**
+ * A single test step. Created via `test(...)` or `createTest(services)`.
+ * Tests are referenced (not named by string) when one test depends on
+ * another — keeps refactors and type-checking honest.
+ *
+ * `T` is the return type of the test body; it surfaces as `ctx.parent`
+ * in children that `dependsOn` this case. `S` is the project's services
+ * map (threaded through `defineEnvironment(...).test`) so `ctx.svc.<key>`
+ * is strongly typed.
+ */
+export interface TestCase<T = unknown, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    /** Stable id (slug of name). Used in MCP responses and CLI flags. */
+    readonly id: string;
+    readonly name: string;
+    /** Parent test, if any. Single-parent for now. */
+    readonly dependsOn?: TestCase<unknown, S, F>;
+    /** Override the default per-test timeout (default 60s). */
+    readonly timeoutMs?: number;
+    /** @internal — the body that the in-sandbox daemon invokes. */
+    readonly run: TestFn<T, unknown, S, F>;
+}
+export interface TestOpts<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    dependsOn?: TestCase<P, S, F>;
+    timeoutMs?: number;
+}
+export type TestFn<T = void, P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> = (ctx: TestContext<P, S, F>) => T | Promise<T>;
+/**
+ * Context object passed to every test function.
+ *
+ * `P` is the return type of the parent test (the one named in
+ * `dependsOn`); for root tests it's `undefined`. `S` is the project's
+ * services map (threaded through `defineEnvironment(...).test`) so
+ * `ctx.svc` only includes services with a `client` factory, each typed
+ * as the factory's output (e.g. a Bun SQL pool for `postgres(...)`).
+ */
+export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    /**
+     * Instrumented `fetch`, exposed on `ctx`. Each call is recorded on the
+     * test timeline and resolves to a {@link WrappedResponse}: reads carry
+     * provenance so `expect(res.status)` / `expect(await res.json())` nest
+     * under the HTTP call. Because the status-line accessors are
+     * {@link Carrier}s, a raw `res.status === 200` is a *type error* — use
+     * `res.status.unwrap()` / `res.unwrap().status`, or assert via `expect`.
+     *
+     * (The plain global `fetch` is wrapped the same way at runtime but keeps
+     * the standard `Response` type, so prefer `ctx.fetch` for honestly-typed
+     * results.)
+     */
+    fetch: SpectestFetch;
+    /** Run `sh -lc <command>` inside a service container. The result is
+     *  {@link Wrapped}, so `res.stdout` is a `Carrier<string>` — assert via
+     *  `expect(res.stdout)` or recover the raw string with `res.stdout.unwrap()`.
+     *  (In `setup`/`eval` the result is wrapped too, just without a timeline
+     *  link, so `.unwrap()` works there the same way.)
+     *
+     *  The full run is also captured as an asciicast and replayed in the
+     *  web UI — one recording per call, with output timestamped as it
+     *  streamed, so slow or animated CLI output can be watched rather
+     *  than read as a final blob. Unlike `terminal` there is no PTY: the
+     *  program sees plain pipes (`isatty` false), so stdout/stderr stay
+     *  byte-identical to what `exec` always returned and TTY-gated
+     *  spinners/colour won't be emitted — reach for `terminal` when the
+     *  CLI needs to believe it's on a TTY.
+     *
+     *  Pass `{ cwd }` to run the command from a working directory instead of
+     *  prefixing it with `cd <dir> && ` — the cwd is kept off the command
+     *  string, so the timeline sidebar shows just the command and the
+     *  directory surfaces in the detail view. */
+    exec(service: string, command: string, opts?: ExecOpts): Promise<Wrapped<ExecResult>>;
+    /**
+     * Run a command inside a service container under a PTY and record the
+     * full terminal session as an asciicast for replay in the web UI.
+     * Unlike `exec`, the program sees a TTY (`isatty(1)` true, colour
+     * codes preserved, line-buffered), so the byte stream may differ from
+     * what `exec` returns. Reach for `terminal` when you're driving a CLI
+     * and want a recording; reach for `exec` for plain piped output.
+     *
+     * One-shot convenience: this is a thin wrapper over `openTerminal` —
+     * spawn `command`, wait for exit, close, return the captured output
+     * and exit code. Reach for `openTerminal` when you want to keep the
+     * session alive across multiple sends or `waitFor` predicates (e.g.
+     * driving an interactive REPL or waiting on a loading spinner).
+     */
+    terminal(service: string, command: string, opts?: TerminalOpts): Promise<Wrapped<TerminalResult>>;
+    /**
+     * Open a long-lived interactive terminal in a service container.
+     * Returns a `Terminal` you can `send` keystrokes to, poll the
+     * rendered screen with `waitFor`, and `close` when done. Every byte
+     * the PTY emits is captured as an asciicast and replayed in the web
+     * UI the same way a one-shot `terminal(...)` is.
+     *
+     * Terminals are NOT auto-closed when the test ends. A docker exec
+     * subprocess is cheap to keep alive and Freestyle captures it
+     * cleanly in the snapshot along with the rest of the container, so
+     * leaking the handle past test end is fine. Call `.close()`
+     * explicitly if you want a `close` step in the timeline; otherwise
+     * `await term.exited` (after the program self-terminates) is the
+     * natural way to assert on the exit code.
+     */
+    openTerminal(service: string, opts?: TerminalOpts): Promise<Terminal>;
+    /**
+     * Open the headless browser. Backed by Chromium-over-CDP inside the VM.
+     *
+     * There is ONE persistent browser per environment: every `ctx.browser()`
+     * call returns it, and it stays alive across tests — the browser is part
+     * of the state a test's snapshot captures, so a `dependsOn` child resumes
+     * the exact live page its parent left (cookies, localStorage, signed-in
+     * SPA state). Sign in once in a parent test; every descendant is already
+     * signed in. Sibling tests fork from the same parent snapshot, so they
+     * can't see each other's browsing. A test with no browser-using ancestor
+     * gets a fresh browser on first call (first call's options win).
+     *
+     * `.close()` destroys the shared instance — the next `ctx.browser()`
+     * starts fresh. Don't call it for routine cleanup; recording is detached
+     * automatically at test end.
+     */
+    browser(opts?: BrowserOptions): Promise<Browser>;
+    /**
+     * Open a phone-emulated session for a mobile app and return a {@link Mobile}
+     * handle already pointed at it — no `navigate`. Pass the app handle a
+     * mobile-app component exposes on `ctx.svc`, e.g. a service declared with
+     * `expo()`:
+     *
+     * ```ts
+     * services: { app: expo() }
+     * // in a test:
+     * const m = await ctx.mobile(ctx.svc.app);
+     * await m.getByTestId("email").fill("a@b.com");
+     * await m.getByRole("button", { name: "Sign in" }).tap();
+     * await expect(m.getByText(/Welcome/)).toBeVisible();
+     * ```
+     *
+     * The session emulates the latest iPhone (viewport + DPR + mobile UA +
+     * touch) and the dashboard replays it inside a phone bezel.
+     *
+     * Sessions are persistent, one per app: like `ctx.browser()`, the live
+     * session is captured in the test's snapshot, so a `dependsOn` child
+     * picks up the app exactly where the parent left it (already signed in,
+     * mid-flow) instead of reloading it. `.close()` discards the session;
+     * the next `ctx.mobile(app)` opens the app fresh.
+     */
+    mobile(app: MobileApp): Promise<Mobile>;
+    /** The test's display name. */
+    readonly testName: string;
+    /**
+     * Value returned by the parent test. Carried across the fork in the
+     * daemon's own memory (Freestyle's snapshot is memory + filesystem), so
+     * any JS value works — including Maps, Sets, class instances, and live
+     * connections that survive the fork. `undefined` for root tests or when
+     * the parent returned nothing.
+     */
+    readonly parent: P;
+    /**
+     * Per-service helper namespaces, keyed by service name. Only services
+     * whose definition ships a `helpers` factory appear here; the value at
+     * `ctx.svc.<name>` is exactly the record that factory returned. For a
+     * `postgres(...)` service that ships `{ client }`, tests do
+     * `await ctx.svc.db.client\`SELECT 1\``.
+     */
+    readonly svc: ServiceHandlesFor<S>;
+    /**
+     * Per-fake helper namespaces, keyed by fake name. Each is the record
+     * of functions the fake's `helpers` factory returned (or `{ state }`
+     * when it ships none — tests never touch a fake's private state
+     * directly). Those functions read/mutate the fake's state internally;
+     * the state itself is in-process and lives across the fork along with
+     * the rest of daemon memory, so calls in a child test see the fork's
+     * own copy as mutated by its ancestors. Every helper call is recorded
+     * as a step and its return value tracked, so assertions on it nest
+     * under the call in the timeline.
+     *
+     * Strongly typed against the project's fakes map when fakes are
+     * declared in `defineEnvironment({ ..., fakes })`: `ctx.fakes.stripe`
+     * is exactly the helpers record `defineFake`'s `helpers` factory
+     * returned — no cast. (Falls back to a loose record only when the
+     * environment declares no fakes.)
+     */
+    readonly fakes: FakeHandlesFor<F>;
+    /**
+     * Poll a predicate until it returns a truthy value, then return that
+     * value. Records one `wait` event for the whole loop (with attempt
+     * count, total duration, and the description) instead of one event
+     * per probe — useful for "wait until pod Running"-style checks where
+     * the intermediate states are noise.
+     *
+     * - `null`, `undefined`, or `false` from `fn` mean "not yet" — wait
+     *   `intervalMs` and try again.
+     * - Anything else is the success value and is returned, tagged with
+     *   the wait event's seq. Downstream `expect(...)` on it links to
+     *   the wait (one logical step), not to N suppressed HTTP calls.
+     * - Throws from `fn` propagate out immediately; the wait event is
+     *   still recorded (with `error` set) so the timeline reflects the
+     *   abort.
+     * - Defaults: `timeoutMs = 30_000`, `intervalMs = 1_000`.
+     *
+     * Side-effect calls inside `fn` (fetch, ctx.svc.* helpers, etc.)
+     * don't show up on the event log — the recorder is paused for the
+     * duration. Use `ctx.poll` for read-only observation, not for
+     * stateful work you want recorded.
+     */
+    poll<T>(description: string, fn: () => T | null | undefined | false | Promise<T | null | undefined | false>, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<Wrapped<T>>;
+    /**
+     * Register a DNS name at runtime so the rest of this test (and anything
+     * downstream of it) can reach it. `{ ingress: true }` points the name at
+     * the daemon (a fake / TLS proxy); `{ service }` points it at a
+     * container's live IP; a `*.suffix` wildcard (e.g. `"*.example.com"`)
+     * routes a whole domain — the natural fit for k3s Ingress hosts a test
+     * applies on the fly.
+     *
+     * Answered by spectest-resolver, so it works for VM-host/test code,
+     * `ctx.browser()`, and peer containers (Docker forwards unknown names to
+     * the host resolver). It does NOT land in any container's `/etc/hosts`.
+     * The registration mutates in-daemon state, so it's isolated to this
+     * test's fork — like fake state.
+     *
+     * ```ts
+     * await ctx.svc.k8s.apply(ingressFor("foo.example.com"));
+     * await ctx.dnsName("foo.example.com", { service: "k8s" });
+     * const res = await ctx.fetch("http://foo.example.com");
+     * ```
+     */
+    dnsName(hostname: string, target: DnsTarget): Promise<void>;
+    /**
+     * Start a real container on `spectest-net` at runtime — a peer machine
+     * with its own IP, reachable like any boot service. Returns once the
+     * container is up and its `readyCheck` (if any) has passed.
+     *
+     * The new container is part of this test's post-state snapshot, so a
+     * `dependsOn` child inherits it (same PID, same data) while siblings,
+     * which fork from the parent's earlier snapshot, never see it — the same
+     * isolation fake `state` and {@link dnsName} get. Reach it by `name`
+     * (single-label, via the resolver) or by any `hostnames` you pass; map a
+     * multi-label name onto it with `ctx.dnsName(host, { service: name })`.
+     *
+     * The image is pulled on first use (fast through the host cache). See
+     * {@link RuntimeServiceSpec}.
+     *
+     * ```ts
+     * const { name } = await ctx.startService({
+     *   name: `db-${crypto.randomUUID().slice(0, 8)}`,
+     *   image: { type: "registry", reference: "postgres:16-alpine" },
+     *   env: { POSTGRES_PASSWORD: "secret" },
+     *   readyCheck: { type: "exec", command: "pg_isready -h 127.0.0.1 -p 5432" },
+     * });
+     * const sql = new Bun.SQL(`postgres://postgres:secret@${name}:5432/postgres`);
+     * ```
+     */
+    startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
+    /** Stop and remove a runtime service started via {@link startService}
+     *  (no-op if it's already gone). */
+    stopService(name: string): Promise<void>;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Options for {@link TestContext.exec}. */
+export interface ExecOpts {
+    /**
+     * Working directory inside the container to run the command from.
+     * Equivalent to prefixing the command with `cd <cwd> && `, but the
+     * directory is kept off the command string: the recorded step's
+     * sidebar summary shows just the command, while the working directory
+     * is surfaced in the detail view (the prompt line of the captured
+     * terminal and the step's panel header). Implemented as `docker exec
+     * -w <cwd>`, so a relative path resolves against the image's WORKDIR.
+     */
+    cwd?: string;
+}
+export interface TestSuite<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    tests: TestCase<unknown, S, F>[];
+}
+/**
+ * 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<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 declare function defineFake<S = any, H extends Record<string, unknown> = Record<string, never>>(opts: FakeDefinition<S, H>): FakeDefinition<S, H>;
+/** 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. */
+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>;
+}
+/**
+ * A complete project definition: an environment, an optional one-shot
+ * setup hook, and an optional test suite. `spectest/index.ts`
+ * default-exports one of these via `env.project([...tests])` or
+ * `env.project({ setup, tests })`.
+ */
+export interface Project<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    environment: EnvironmentConfig<S>;
+    /**
+     * Fake servers hosted in the spectest-daemon (see {@link defineFake}).
+     * Keyed by stable fake name; the key becomes the slot in
+     * `ctx.fakes.<key>` from test code. Populated from the `fakes` declared
+     * in `defineEnvironment(...)`.
+     */
+    fakes?: F;
+    /**
+     * Project-level setup. Runs once, after every service is Ready and
+     * its per-service `setup` has completed, before the warm-template
+     * snapshot. Use this for state that's part of "the environment as
+     * the tests expect to find it" — seed data in a database, an initial
+     * Deployment in k3s, etc. Like service-level setup, the result is
+     * captured by every snapshot taken from that point, so warm restore
+     * and per-test forks inherit it without re-running.
+     *
+     * The ctx here is a slimmer cousin of TestContext: no recorder, no
+     * timeout, no browser/terminal — setup is not a test and doesn't
+     * appear in the timeline.
+     */
+    setup?: ProjectSetupFn<S, F>;
+    tests?: TestSuite<S, F>;
+}
+/**
+ * Slim context handed to the project-level `setup` hook. Same shape as
+ * `TestContext` but pared down — no testName, no parent, no recording
+ * surfaces (browser, terminal, poll). If you need polling inside setup,
+ * write a plain loop: setup runs outside the test timeline so there's
+ * nothing to record into.
+ */
+export interface ProjectSetupContext<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    fetch: SpectestFetch;
+    exec(service: string, command: string, opts?: ExecOpts): Promise<Wrapped<ExecResult>>;
+    readonly svc: ServiceHandlesFor<S>;
+    /** Same surface tests see — fakes are already up by setup time. Typed
+     * against the declared fakes map (see {@link TestContext.fakes}). */
+    readonly fakes: FakeHandlesFor<F>;
+    /**
+     * Register a DNS name (see {@link TestContext.dnsName}). Useful here to
+     * wire a wildcard like `"*.example.com"` to a k3s cluster once, before
+     * any test runs — it's captured into the warm-template snapshot, so every
+     * test inherits the route without re-registering.
+     */
+    dnsName(hostname: string, target: DnsTarget): Promise<void>;
+    /**
+     * Start a runtime service (see {@link TestContext.startService}). Started
+     * here, it's captured into the warm-template snapshot and inherited by
+     * every test — use it for backing instances that should exist before any
+     * test runs but aren't worth a boot-time `services` entry.
+     */
+    startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
+    /** Stop a runtime service (see {@link TestContext.stopService}). */
+    stopService(name: string): Promise<void>;
+}
+export type ProjectSetupFn<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> = (ctx: ProjectSetupContext<S, F>) => void | Promise<void>;
+/**
+ * A defined environment. Returned by `defineEnvironment(...)` and used to
+ * (a) build typed tests against this environment's services and (b)
+ * bundle those tests into the project's default export.
+ *
+ * ```ts
+ * const env = defineEnvironment({
+ *   name: "todos",
+ *   services: {
+ *     db: postgres({ database: "todos", user: "todos", password: "todos" }),
+ *   },
+ * });
+ *
+ * const createTodo = env.test("create todo", async (ctx) => {
+ *   // ctx.svc.db.client is the Bun SQL pool (the helper postgres ships).
+ *   await ctx.svc.db.client`SELECT 1`;
+ *   return { id: 1 };
+ * });
+ *
+ * const markDone = env.test(
+ *   "mark done",
+ *   { dependsOn: createTodo },
+ *   async (ctx) => {
+ *     // ctx.parent is { id: number }
+ *     await ctx.svc.db.client`UPDATE todos SET done = TRUE WHERE id = ${ctx.parent.id}`;
+ *   },
+ * );
+ *
+ * export default env.project([createTodo, markDone]);
+ * ```
+ */
+export interface ProjectOpts<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    /** Optional project-level setup. See `Project.setup`. */
+    setup?: ProjectSetupFn<S, F>;
+    /** Test cases for this project's suite. */
+    tests?: TestCase<unknown, S, F>[];
+}
+/**
+ * Input to {@link defineEnvironment}: the environment config plus an
+ * optional `fakes` map. `fakes` is declared here (rather than on
+ * `project(...)`) so the fakes' types are bound when `env.test(...)`
+ * creates a test — that's what makes `ctx.fakes.<key>` strongly typed.
+ * `fakes` is stripped from `config` before it's stored/serialised, so the
+ * wire `EnvironmentConfig` the Rust control plane sees never carries it.
+ *
+ * Unlike the wire {@link EnvironmentConfig}, `services` entries here may
+ * be {@link ServiceGroup}s — they're expanded to plain services (primary
+ * at the group's key, other parts at `<key>-<part>`) before validation.
+ */
+export interface EnvironmentInput<SI extends InputServicesMap, F extends FakesMap = FakesMap> {
+    /** Human-friendly name for the environment, e.g. "my-app". */
+    name: string;
+    /** Services and/or service groups, keyed by name. See
+     *  {@link EnvironmentConfig.services} and {@link ServiceGroup}. */
+    services: SI;
+    /** Sandbox timeout in seconds (default 1h). */
+    timeoutSecs?: number;
+    /** Fake servers — see {@link defineFake}. Keyed by stable name; the key
+     * shows up as `ctx.fakes.<key>` in tests, typed as that fake's helpers
+     * record. */
+    fakes?: F;
+}
+export interface DefinedEnvironment<S extends ServicesMap, F extends FakesMap = FakesMap> {
+    /** The validated environment config. Plain data, JSON-serialisable —
+     * the in-VM daemon ships this to the control plane on `/load`. */
+    readonly config: EnvironmentConfig<S>;
+    /** Define a test against this environment. `ctx.svc.<key>` and
+     * `ctx.fakes.<key>` are strongly typed against the services and fakes
+     * maps. */
+    readonly test: TypedTest<S, F>;
+    /** Bundle this environment with a test suite into the project default
+     * export. Pass tests as a plain array for the common case, or an
+     * options bag to attach project-level `setup`. (Fakes are declared on
+     * `defineEnvironment`, not here.) */
+    project(tests?: TestCase<unknown, S, F>[]): Project<S, F>;
+    project(opts: ProjectOpts<S, F>): Project<S, F>;
+}
+/**
+ * The `ctx` type for an environment, for typing shared test helpers without
+ * `any`. Instantiate with the environment from `defineEnvironment`:
+ *
+ * ```ts
+ * const env = defineEnvironment({ ... });
+ * export type AppCtx = Ctx<typeof env>;
+ *
+ * // A helper reaching into ctx.svc / ctx.fakes stays fully typed:
+ * async function runJob(ctx: AppCtx) {
+ *   await ctx.svc.db.client`SELECT 1`;
+ * }
+ * ```
+ *
+ * This is the same `ctx` an `env.test(...)` callback receives. The parent
+ * return type is left as `unknown` (helpers rarely touch `ctx.parent` — read
+ * it in the test body and pass the value in). Prefer this over `ctx: any`:
+ * an `any`-typed ctx also defeats the `expect(...)` overloads, silently
+ * resolving `expect(value)` to the `expect(locator)` overload so value
+ * matchers like `.toBe(...)` disappear.
+ */
+export type Ctx<E> = E extends DefinedEnvironment<infer S, infer F> ? TestContext<unknown, S, F> : never;
+/**
+ * Define an environment and get back a builder you can hang tests off.
+ * The builder's `.test(...)` returns test cases typed against the
+ * environment's services (and any declared `fakes`), and `.project([...])`
+ * produces the file's default export.
+ */
+export declare function defineEnvironment<SI extends InputServicesMap, F extends FakesMap = FakesMap>(input: EnvironmentInput<SI, F>): DefinedEnvironment<ExpandServices<SI>, F>;
+export declare class ExpectationError extends Error {
+    constructor(message: string);
+}
+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;
+}
+export declare function expect(actual: Locator, message?: string): LocatorAssertion;
+export declare function expect(actual: Provenanced, message?: string): Expectation;
+/**
+ * Assert on a value with **no provenance** — a computed number, a raw
+ * WebSocket frame, anything that didn't flow from a recorded op. `message` is
+ * required (it's the second argument) and reads as the natural follow-on to
+ * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
+ * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
+ * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
+ * the value carries provenance — only reach for this when the type gate would
+ * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
+ * mandatory, since the label is the only human-meaningful summary a raw
+ * assertion has.)
+ */
+export declare function expectRaw(actual: unknown, message: string): Expectation;
+/** `node:assert/strict` re-exported for users who prefer Node's built-in API. */
+export declare const assert: typeof nodeAssert;