@specific.dev/spectest 0.83.0 → 0.85.0

package/src/components/supabase.ts

@@ -27,7 +27,7 @@
 //     supabase: sb.group,      // expands to supabase, supabase-db, supabase-auth, ...
 //     app: {
 //       image: { type: "dockerfile", content: "..." },
-//       env: { ...sb.appEnv }, // SUPABASE_URL / _ANON_KEY / _SERVICE_ROLE_KEY / DATABASE_URL
+//       env: { SUPABASE_URL: sb.url, SUPABASE_ANON_KEY: sb.anonKey, DATABASE_URL: sb.dbUrl },
 //       dependsOn: [sb.ready], // wait for the gateway (and the stack behind it)
 //     },
 //   },
@@ -47,7 +47,7 @@
 // the group naming context, so two Supabase stacks (or a user service
 // innocently named `db`) never collide. The group must be mounted at the key
 // matching the `name` option (default `"supabase"`) since the derived surface
-// (`sb.url`, `sb.appEnv`) embeds it — a mismatch errors at load.
+// (`sb.url`, `sb.dbUrl`) embeds it — a mismatch errors at load.
 
 import { createHmac } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
@@ -69,6 +69,8 @@ import { email, emailHelpers, type EmailHelpers } from "./email.js";
 import { github } from "./github.js";
 import { google } from "./google.js";
 import { microsoft } from "./microsoft.js";
+import { SUPABASE_WEBHOOKS_SQL } from "./supabase-webhooks.js";
+import { postgresTls } from "./postgres-tls.js";
 import {
   mapSupabaseConfig,
   parseSupabaseConfigFile,
@@ -99,6 +101,17 @@ const IMAGES = {
   templates: "busybox:1.37",
 } as const;
 
+/** Override tables without mutating the parsed project config. */
+function mergeConfig(base: unknown, overrides: Record<string, unknown>): Record<string, unknown> {
+  const table = (v: unknown): v is Record<string, unknown> =>
+    v !== null && typeof v === "object" && !Array.isArray(v);
+  const result: Record<string, unknown> = Object.assign(Object.create(null), table(base) ? base : {});
+  for (const [key, value] of Object.entries(overrides)) {
+    result[key] = table(value) ? mergeConfig(result[key], value) : value;
+  }
+  return result;
+}
+
 /**
  * Social sign-in providers this stack can serve, by the name GoTrue (and
  * `[auth.external.<name>]`) uses. Each factory builds one container answering
@@ -204,6 +217,22 @@ function absProjectPath(p: string): string {
 }
 
 export interface SupabaseOptions {
+  /** Database image and extensions installed before project migrations. */
+  db?: {
+    /** Native database TLS, enabled by default using the environment CA. */
+    tls?: boolean;
+    /** Full Supabase-compatible Postgres image reference. Defaults to the pinned SDK image. */
+    image?: string;
+    /**
+     * Explicit extension overrides for projects whose migrations pin versions
+     * absent from the image. Omit version to use the image's default, or use
+     * db.image to supply an image containing the exact required version.
+     * Existing extensions must match the requested schema/version.
+     * Example: `{ vector: { schema: "public" } }` opts into the image's vector
+     * version before a historical CREATE EXTENSION IF NOT EXISTS migration.
+     */
+    extensions?: Record<string, { schema?: string; version?: string }>;
+  };
   /**
    * Key of the API-gateway service and the prefix for every other piece.
    * Default `"supabase"`. The gateway is reachable at `http://<name>:8000`
@@ -239,7 +268,7 @@ export interface SupabaseOptions {
   /**
    * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
    * daemon's CA-trusted TLS reverse proxy (in addition to the plain
-   * `http://<name>:8000`). `sb.url` and `sb.appEnv` then point at the HTTPS
+   * `http://<name>:8000`). `sb.url` then points at the HTTPS
    * address. Use TLS wherever you can: set this when a browser reaches the
    * gateway, because a page that is open over `https://` cannot call an
    * `http://` origin (Chromium blocks the request before it leaves the
@@ -298,14 +327,21 @@ export interface SupabaseOptions {
    * written one. Nothing is derived unless you name the folder, and each piece
    * is optional inside it — a folder with only a `config.toml` is fine.
    *
-   * There is deliberately no per-piece path option and no way to configure
-   * mail, OTP, redirect or JWT behaviour here: those live in `config.toml`,
-   * where your project already declares them and where the Supabase CLI reads
-   * them too. One source of truth, and the environment matches the one you run
-   * locally.
+   * Use `configOverrides` for environment-specific config values without
+   * moving this folder's migrations, seed, templates or functions.
    */
   dir?: string;
 
+  /**
+   * Values recursively merged into the project's parsed Supabase config.
+   * Tables merge; arrays and scalar values replace their originals. Uses the
+   * same nested keys as config.toml, e.g.:
+   * `{ auth: { hook: { before_user_created: { uri: "https://app.test/hook" } } } }`.
+   * `env(...)` in overrides resolves through `env` just as it does in the file.
+   * Also works without `dir` for a stack with no project SQL or functions.
+   */
+  configOverrides?: Record<string, unknown>;
+
   /**
    * The `.env` of this environment — the values your `config.toml` reads with
    * `env(...)`.
@@ -484,9 +520,6 @@ export interface SupabaseStack {
    * share the one mailbox: `env: { SMTP_HOST: sb.smtp.host, SMTP_PORT: String(sb.smtp.port) }`.
    */
   smtp?: { host: string; port: number };
-  /** Ready-to-spread env for the app under test: `SUPABASE_URL`,
-   *  `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `DATABASE_URL`. */
-  appEnv: Record<string, string>;
 }
 
 // Supabase's well-known demo secret (≥32 chars). Local-only; override via opts.
@@ -542,6 +575,31 @@ function pgLiteral(s: string): string {
   return `'${s.replace(/'/g, "''")}'`;
 }
 
+function pgIdentifier(s: string): string {
+  if (!s || s.includes("\0")) throw new Error("supabase(): an SQL identifier must be non-empty and contain no NUL");
+  return `"${s.replace(/"/g, '""')}"`;
+}
+
+function extensionSql(extensions: NonNullable<SupabaseOptions["db"]>["extensions"]): string {
+  return Object.entries(extensions ?? {}).map(([name, { schema, version }]) => {
+    const install = `CREATE EXTENSION IF NOT EXISTS ${pgIdentifier(name)}` +
+      (schema ? ` SCHEMA ${pgIdentifier(schema)}` : "") +
+      (version ? ` VERSION ${pgLiteral(version)}` : "") + ";";
+    // IF NOT EXISTS does not validate an already-installed extension.
+    const matches = [
+      version ? `e.extversion = ${pgLiteral(version)}` : "true",
+      schema ? `n.nspname = ${pgLiteral(schema)}` : "true",
+    ].join(" AND ");
+    const check = `BEGIN
+      IF EXISTS (SELECT 1 FROM pg_extension e JOIN pg_namespace n ON n.oid = e.extnamespace
+                 WHERE e.extname = ${pgLiteral(name)} AND NOT (${matches})) THEN
+        RAISE EXCEPTION USING MESSAGE = ${pgLiteral(`supabase: extension ${name} does not match the requested schema/version`)};
+      END IF;
+    END`;
+    return `${install}\nDO ${pgLiteral(check)};`;
+  }).join("\n");
+}
+
 function buildBootstrapSql(
   dbPassword: string,
   jwtSecret: string,
@@ -1654,11 +1712,14 @@ async function reloadPostgrestSchema(
 /**
  * A ready-to-use self-hosted Supabase stack. Mount `.group` at the key
  * matching the `name` option (default `"supabase"`) and wire the app with
- * `.appEnv` / `.ready`:
+ * its connection values and `.ready`:
  *
  * ```ts
  * const sb = supabase({ dbPassword: "postgres" });
- * services: { supabase: sb.group, app: { image, env: sb.appEnv, dependsOn: [sb.ready] } }
+ * services: { supabase: sb.group, app: {
+ *   image, env: { SUPABASE_URL: sb.url, SUPABASE_ANON_KEY: sb.anonKey },
+ *   dependsOn: [sb.ready],
+ * } }
  * ```
  *
  * See the file header for the full picture. Tests get an instrumented DB client
@@ -1722,11 +1783,29 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
   // services map is returned. `config.json` wins where a newer CLI wrote one.
   const configPath = inDir("config.json") ?? inDir("config.toml");
   let mapped: MappedSupabaseConfig | null = null;
-  if (configPath !== null) {
-    const shown = configPath.startsWith(projectRootPath())
+  if (configPath !== null || opts.configOverrides !== undefined) {
+    const shown = configPath === null ? "configOverrides" : configPath.startsWith(projectRootPath())
       ? configPath.slice(projectRootPath().length + 1)
       : configPath;
-    mapped = mapSupabaseConfig(parseSupabaseConfigFile(configPath));
+    mapped = mapSupabaseConfig(mergeConfig(
+      configPath === null ? {} : parseSupabaseConfigFile(configPath),
+      opts.configOverrides ?? {},
+    ));
+    for (const [target, { from, key }] of Object.entries(mapped.deferredAuth)) {
+      const enabled = target.replace(/_(URI|SECRETS)$/, "_ENABLED");
+      if (!withAuth || mapped.auth[enabled] !== "true") continue;
+      const value = opts.env?.[from];
+      if (value === undefined || value === "") {
+        throw new Error(`supabase(): ${key} reads env(${from}); supply a non-empty test value with env: { ${from}: "…" }.`);
+      }
+      mapped.auth[target] = value;
+    }
+    for (const key of mapped.encryptedValues) {
+      const hook = /^auth\.hook\.([^.]+)\.(uri|secrets)$/.exec(key);
+      if (withAuth && hook && mapped.auth[`GOTRUE_HOOK_${hook[1]!.toUpperCase()}_ENABLED`] === "true") {
+        throw new Error(`supabase(): ${key} is encrypted; override it with env(NAME) and supply the test value through env.`);
+      }
+    }
     // What the file asked for and did not get. Reported, never fatal: the
     // config belongs to the project and describes more than this environment,
     // so a key that is meaningless in a hermetic VM is not grounds to refuse
@@ -1756,6 +1835,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
     // and nothing says why.
     const referenced = new Set<string>([
       ...Object.values(mapped.deferredSecrets),
+      ...Object.values(mapped.deferredAuth).map(({ from }) => from),
       ...Object.values(mapped.externalProviders).flatMap((p) =>
         [p.clientIdFrom, p.secretFrom].filter((n): n is string => n !== undefined),
       ),
@@ -1837,17 +1917,20 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
   const anonKey = apiKey("anon", jwtSecret);
   const serviceRoleKey = apiKey("service_role", jwtSecret);
 
-  // Derived surface, embedded in `appEnv` / `url` before the group expands.
+  // Derived connection values, available before the group expands.
   // `expectKey: name` on the group guarantees these names and the expanded
   // service keys agree (`g.key("db")` at expansion === `${name}-db` here).
   const dbKey = `${name}-db`;
   const url = opts.hostname ? `https://${opts.hostname}` : `http://${name}:8000`;
   // App-facing URL: the conventional `postgres` role (owns migrated tables).
-  const dbUrl = `postgresql://postgres:${dbPassword}@${dbKey}:5432/postgres`;
+  const dbTls = opts.db?.tls !== false ? postgresTls() : undefined;
+  const dbUrl = `postgresql://postgres:${encodeURIComponent(dbPassword)}@${dbKey}:5432/postgres` +
+    (dbTls ? "?sslmode=verify-full" : "");
   // The test-side `ctx.svc.<name>.sql` helper connects as the superuser
   // `supabase_admin` so it can inspect everything — public tables plus the
   // `auth`/`storage` schemas — regardless of ownership.
-  const adminDbUrl = `postgresql://supabase_admin:${dbPassword}@${dbKey}:5432/postgres`;
+  const adminDbUrl = `postgresql://supabase_admin:${encodeURIComponent(dbPassword)}@${dbKey}:5432/postgres` +
+    (dbTls ? "?sslmode=verify-full" : "");
 
   // ── social sign-in ────────────────────────────────────────────────────
   // Every `[auth.external.<name>]` the config enables: served in-environment
@@ -1900,7 +1983,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
 
       // ── db ──────────────────────────────────────────────────────────
       const dbDef: ServiceDefinition = {
-        image: { type: "registry", reference: IMAGES.db },
+        image: { type: "registry", reference: opts.db?.image ?? IMAGES.db },
         // `args` (not `command`): keep the image's docker-entrypoint.sh so it
         // runs initdb + its baked init-scripts before starting.
         args: [
@@ -1909,7 +1992,9 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           "config_file=/etc/postgresql/postgresql.conf",
           "-c",
           "log_min_messages=fatal",
+          ...(dbTls?.args ?? []),
         ],
+        ...(dbTls ? { certificates: dbTls.certificates } : {}),
         env: {
           POSTGRES_HOST: "/var/run/postgresql",
           PGPORT: "5432",
@@ -1940,6 +2025,9 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             // superuser in modern supabase/postgres; `supabase_admin` is.
             "supabase_admin",
           );
+          await applySqlFile(ctx, SUPABASE_WEBHOOKS_SQL, "database webhooks", "supabase_admin");
+          const extensions = extensionSql(opts.db?.extensions);
+          if (extensions) await applySqlFile(ctx, extensions, "configured extensions", "postgres");
         },
       };
       parts.db = dbDef;
@@ -2345,13 +2433,6 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
     }),
   });
 
-  const appEnv = {
-    SUPABASE_URL: url,
-    SUPABASE_ANON_KEY: anonKey,
-    SUPABASE_SERVICE_ROLE_KEY: serviceRoleKey,
-    DATABASE_URL: dbUrl,
-  };
-
   return {
     group,
     url,
@@ -2359,7 +2440,6 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
     serviceRoleKey,
     dbUrl,
     ready: name,
-    appEnv,
     ...(withMail ? { smtp: { host: mailKey, port: 1025 } } : {}),
   };
 }

package/src/components/temporal.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+import { defineEnvironment } from "../index.js";
+import { temporal, temporalClient } from "./temporal.js";
+
+describe("temporal", () => {
+  test("uses one prebuilt headless server and gates on the namespace API", () => {
+    const t = temporal({ namespace: "specific", namespaces: ["customer"], searchAttributes: { SurveyId: "Keyword" } });
+    const env = defineEnvironment({ name: "test", services: { temporal: t.group } });
+    expect(Object.keys(env.config.services)).toEqual(["temporal"]);
+    const server = env.config.services.temporal;
+    expect(server.args).toContain("--headless");
+    expect(server.args).toContain("SurveyId=Keyword");
+    expect(server.args).toContain("customer");
+    expect(server.command).toBeUndefined();
+    expect(server.readyCheck).toMatchObject({ type: "http", path: "/api/v1/namespaces/specific" });
+  });
+  test("TLS has its own certificate and upstream dependency, never HTTP ingress", () => {
+    const t = temporal({ name: "cloud", tls: { hostname: "temporal.test" } });
+    const env = defineEnvironment({ name: "test", services: { cloud: t.group } });
+    expect(Object.keys(env.config.services).sort()).toEqual(["cloud", "cloud-server"]);
+    expect(env.config.services.cloud.dependsOn).toContain("cloud-server");
+    expect(env.config.services.cloud.certificates?.[0]?.hostnames).toEqual(["temporal.test"]);
+    expect(env.config.services.cloud.tls).toBeUndefined();
+    expect(t.address).toBe("temporal.test:7233");
+  });
+  test("rejects invalid ports and search attributes", () => {
+    expect(() => temporal({ port: 7243 })).toThrow("distinct");
+    expect(() => temporal({ searchAttributes: { "invalid=name": "Keyword" } })).toThrow("search attribute");
+  });
+});
+
+describe("Temporal API helpers", () => {
+  test("namespace registration is idempotent on the structured AlreadyExists code", async () => {
+    const methods: string[] = [];
+    const c = temporalClient("http://temporal", "default", async (_, init) => {
+      methods.push(init?.method ?? "GET");
+      return init?.method === "POST" ? Response.json({ code: 6, message: "exists" }, { status: 409 }) :
+        Response.json({ namespaceInfo: { name: "new", state: "NAMESPACE_STATE_REGISTERED", id: "id" } });
+    });
+    expect((await c.registerNamespace("new")).namespaceInfo.name).toBe("new");
+    expect(methods).toEqual(["POST", "GET"]);
+  });
+  test("requires both task types and rejects stale or unrelated pollers", async () => {
+    const urls: string[] = [];
+    const c = temporalClient("http://temporal", "default", async input => {
+      urls.push(String(input));
+      return Response.json({ pollers: [{ identity: "other", lastAccessTime: new Date().toISOString() },
+        { identity: "expected", lastAccessTime: new Date(Date.now() - 300000).toISOString() }] });
+    });
+    await expect(c.waitForWorkers("q", { identities: ["expected"], timeoutMs: 20 })).rejects.toThrow("Observed pollers");
+    expect(urls.some(u => u.endsWith("taskQueueType=1"))).toBe(true);
+    expect(urls.some(u => u.endsWith("taskQueueType=2"))).toBe(true);
+  });
+  test("recognizes a ready activity-only worker", async () => {
+    const c = temporalClient("http://temporal", "default", async () => Response.json({ pollers: [
+      { identity: "worker", lastAccessTime: new Date().toISOString() },
+    ] }));
+    expect((await c.waitForWorkers("q", { types: ["activity"], identities: ["worker"] })).activity).toHaveLength(1);
+  });
+  test("authentication failures fail immediately rather than waiting out the timeout", async () => {
+    let calls = 0;
+    const c = temporalClient("http://temporal", "default", async () => { calls++; return Response.json({ code: 16, message: "denied" }, { status: 401 }); });
+    await expect(c.waitForWorkers("q", { types: ["workflow"] })).rejects.toThrow("HTTP 401");
+    expect(calls).toBe(1);
+  });
+  test("namespace creation recovers from a lost response without changing an existing namespace", async () => {
+    let posts = 0;
+    const c = temporalClient("http://temporal", "default", async (_, init) => {
+      if (init?.method === "POST") {
+        if (++posts === 1) throw new TypeError("connection closed after registration");
+        return Response.json({ code: 6 }, { status: 409 });
+      }
+      return Response.json({ namespaceInfo: { name: "customer", state: "NAMESPACE_STATE_REGISTERED", id: "existing" } });
+    });
+    expect((await c.registerNamespace("customer")).namespaceInfo.id).toBe("existing");
+    expect(posts).toBe(2);
+  });
+  test("polling retries a gateway's non-JSON transient response", async () => {
+    let calls = 0;
+    const c = temporalClient("http://temporal", "default", async () => ++calls === 1
+      ? new Response("upstream unavailable", { status: 503 })
+      : Response.json({ pollers: [{ identity: "worker", lastAccessTime: new Date().toISOString() }] }));
+    expect((await c.waitForWorkers("q", { types: ["activity"] })).activity).toHaveLength(1);
+    expect(calls).toBe(2);
+  });
+});

package/src/components/temporal.ts

@@ -0,0 +1,188 @@
+import { serviceGroup, type ServiceDefinition, type ServicesMap } from "../index.js";
+import { rawFetch } from "../harness/raw-fetch.js";
+import { readRaw } from "../inspect.js";
+
+export type TemporalSearchAttributeType = "Text" | "Keyword" | "Int" | "Double" | "Bool" | "Datetime" | "KeywordList";
+export type TemporalTaskType = "workflow" | "activity";
+export interface TemporalPoller { identity: string; lastAccessTime?: string }
+export interface TemporalWorkerOptions {
+  namespace?: string;
+  /** Both by default; activity-only workers can select ["activity"]. */
+  types?: TemporalTaskType[];
+  /** Require every named worker identity on each requested queue type. */
+  identities?: string[];
+  minPollers?: number;
+  maxAgeMs?: number;
+  timeoutMs?: number;
+}
+export interface TemporalNamespace {
+  namespaceInfo: { name: string; state: string; id: string };
+  config?: { workflowExecutionRetentionTtl?: string };
+}
+export interface TemporalOptions {
+  name?: string;
+  /** Pinned CLI image, including the real Temporal server and SQLite. */
+  image?: string;
+  namespace?: string;
+  namespaces?: string[];
+  searchAttributes?: Record<string, TemporalSearchAttributeType>;
+  port?: number;
+  httpPort?: number;
+  /** Off by default; no UI process or assets are needed by workers. */
+  ui?: boolean;
+  /** Optional native gRPC TLS endpoint; adds a small TLS terminator. */
+  tls?: { hostname: string };
+}
+
+class TemporalApiError extends Error {
+  constructor(readonly status: number, readonly code: number | undefined, message: string) { super(message); }
+}
+class TemporalTransportError extends Error {}
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+const positive = (name: string, n: number) => {
+  if (!Number.isFinite(n) || n <= 0) throw new Error(`temporal(): ${name} must be positive`);
+  return n;
+};
+const namespaceName = (name: string) => {
+  if (!name || name.includes("\0")) throw new Error("temporal(): namespace must be non-empty and contain no NUL");
+  return name;
+};
+
+/** Stateless HTTP client, also usable inside a fake that provisions real namespaces.
+ * No gRPC channel survives a VM restore, and no CLI process is spawned per request.
+ */
+export function temporalClient(httpUrl: string, namespace = "default", fetcher: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response> = rawFetch) {
+  const nsPath = (ns: string) => `/api/v1/namespaces/${encodeURIComponent(namespaceName(ns))}`;
+  async function request<T>(path: string, init?: RequestInit, timeoutMs = 5000): Promise<T> {
+    let response: Response;
+    let body: string;
+    try {
+      response = await fetcher(`${httpUrl}${path}`, { ...init, signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutMs))) });
+      body = await response.text();
+    } catch (cause) {
+      throw new TemporalTransportError(`Temporal ${path}: ${String(cause)}`, { cause });
+    }
+    let value: any;
+    try { value = body ? JSON.parse(body) : {}; }
+    catch {
+      if (response.ok) throw new Error(`Temporal ${path}: invalid JSON (HTTP ${response.status}): ${body.slice(0, 500)}`);
+      value = {}; // Gateways may return plain text or HTML for a transient error.
+    }
+    if (!response.ok) throw new TemporalApiError(response.status, value?.code,
+      `Temporal ${path}: HTTP ${response.status}: ${value?.message ?? body.slice(0, 500)}`);
+    return value as T;
+  }
+  async function until<T>(description: string, timeoutMs: number, probe: (remaining: number) => Promise<T | null>) {
+    const deadline = Date.now() + positive("timeoutMs", timeoutMs);
+    let last: unknown = "condition not met";
+    let interval = 50;
+    do {
+      try { const value = await probe(Math.min(5000, Math.max(1, deadline - Date.now()))); if (value !== null) return value; }
+      catch (error) {
+        if (!(error instanceof TemporalTransportError) &&
+            !(error instanceof TemporalApiError && [404, 429, 502, 503, 504].includes(error.status))) throw error;
+        last = error;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await delay(Math.min(interval, remaining));
+      interval = Math.min(500, interval * 2);
+    } while (Date.now() < deadline);
+    throw new Error(`Timed out after ${timeoutMs}ms waiting for ${description}. Last result: ${String(last)}`);
+  }
+  return {
+    httpUrl, namespace,
+    describeNamespace(name = namespace) { return request<TemporalNamespace>(nsPath(name)); },
+    async registerNamespace(name: string, options: { retentionDays?: number; timeoutMs?: number } = {}) {
+      namespaceName(name);
+      const timeoutMs = positive("timeoutMs", options.timeoutMs ?? 10000);
+      const deadline = Date.now() + timeoutMs;
+      const retentionSeconds = positive("retentionDays", options.retentionDays ?? 1) * 86400;
+      await until(`Temporal namespace ${JSON.stringify(name)} creation`, timeoutMs, async remaining => {
+        try {
+          await request("/api/v1/namespaces", { method: "POST", headers: { "content-type": "application/json" },
+            body: JSON.stringify({ namespace: name, workflowExecutionRetentionPeriod: `${retentionSeconds}s` }) }, remaining);
+        } catch (error) {
+          // A retry after a lost response is safe: names are unique, and an
+          // existing namespace is never updated by this operation.
+          if (!(error instanceof TemporalApiError && error.code === 6)) throw error;
+        }
+        return true;
+      });
+      return until(`Temporal namespace ${JSON.stringify(name)} to be registered`, Math.max(1, deadline - Date.now()), async remaining => {
+        const result = await request<TemporalNamespace>(nsPath(name), undefined, remaining);
+        return result.namespaceInfo?.state === "NAMESPACE_STATE_REGISTERED" ? result : null;
+      });
+    },
+    async waitForWorkers(taskQueue: string, options: TemporalWorkerOptions = {}) {
+      if (!taskQueue) throw new Error("temporal(): taskQueue must be non-empty");
+      const ns = options.namespace ?? namespace;
+      const types = [...new Set(options.types ?? ["workflow", "activity"])];
+      if (!types.length || types.some(t => t !== "workflow" && t !== "activity")) throw new Error("temporal(): types must contain workflow and/or activity");
+      const minPollers = positive("minPollers", options.minPollers ?? 1);
+      if (!Number.isInteger(minPollers)) throw new Error("temporal(): minPollers must be an integer");
+      const maxAgeMs = positive("maxAgeMs", options.maxAgeMs ?? 120000);
+      let observed: Record<string, string[]> = {};
+      try {
+        return await until(`Temporal workers on ${ns}/${taskQueue} (${types.join(", ")})`, options.timeoutMs ?? 30000, async remaining => {
+          const entries = await Promise.all(types.map(async type => {
+            const result = await request<{ pollers?: TemporalPoller[] }>(`${nsPath(ns)}/task-queues/${encodeURIComponent(taskQueue)}?taskQueueType=${type === "workflow" ? 1 : 2}`, undefined, remaining);
+            const pollers = (result.pollers ?? []).filter(p => p.identity && p.lastAccessTime && Date.now() - Date.parse(p.lastAccessTime) <= maxAgeMs);
+            return [type, pollers] as const;
+          }));
+          observed = Object.fromEntries(entries.map(([t, ps]) => [t, ps.map(p => p.identity)]));
+          return entries.every(([, ps]) => new Set(ps.map(p => p.identity)).size >= minPollers &&
+            (options.identities ?? []).every(id => ps.some(p => p.identity === id))) ? Object.fromEntries(entries) : null;
+        });
+      } catch (error) {
+        if (error instanceof Error) error.message += ` Observed pollers: ${JSON.stringify(observed)}`;
+        throw error;
+      }
+    },
+  };
+}
+export type TemporalClient = ReturnType<typeof temporalClient>;
+
+export function temporal(opts: TemporalOptions = {}) {
+  const name = opts.name ?? "temporal";
+  const namespace = namespaceName(opts.namespace ?? "default");
+  const port = opts.port ?? 7233;
+  const httpPort = opts.httpPort ?? 7243;
+  for (const p of [port, httpPort]) if (!Number.isInteger(p) || p < 1 || p > 65535) throw new Error("temporal(): ports must be integers between 1 and 65535");
+  if (port === httpPort || (opts.ui && [port, httpPort].includes(8233))) throw new Error("temporal(): listener ports must be distinct");
+  if (opts.tls && !/^(?:[a-z0-9-]+\.)+[a-z0-9-]+$/.test(opts.tls.hostname)) throw new Error("temporal(): TLS hostname must be a multi-label DNS name");
+  const serverName = opts.tls ? `${name}-server` : name;
+  const address = `${opts.tls?.hostname ?? name}:${port}`;
+  const httpUrl = `http://${serverName}:${httpPort}`;
+  const namespaces = [...new Set([namespace, ...(opts.namespaces ?? [])])].map(namespaceName);
+  const args = ["server", "start-dev", "--ip", "0.0.0.0", "--port", String(port), "--http-port", String(httpPort), "--log-format", "json"];
+  args.push(...(opts.ui ? ["--ui-port", "8233", "--ui-disable-news-fetch"] : ["--headless"]));
+  for (const ns of namespaces) if (ns !== "default") args.push("--namespace", ns);
+  for (const [key, type] of Object.entries(opts.searchAttributes ?? {})) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || !["Text", "Keyword", "Int", "Double", "Bool", "Datetime", "KeywordList"].includes(type)) throw new Error(`temporal(): invalid search attribute ${key}=${type}`);
+    args.push("--search-attribute", `${key}=${type}`);
+  }
+  const primary = opts.tls ? "tls" : "server";
+  const group = serviceGroup({
+    primary, expectKey: name,
+    services: (): ServicesMap => {
+      const server: ServiceDefinition = {
+        image: { type: "registry", reference: opts.image ?? "temporalio/temporal:1.9.1" }, args,
+        ports: [port, httpPort, ...(opts.ui ? [8233] : [])],
+        readyCheck: { type: "http", port: httpPort, path: `/api/v1/namespaces/${encodeURIComponent(namespace)}`, timeoutSecs: 30 },
+      };
+      if (!opts.tls) return { server };
+      return { server, tls: {
+        image: { type: "registry", reference: "nginx:1.29.6-alpine" },
+        ports: [port], hostnames: [opts.tls.hostname], dependsOn: [serverName],
+        certificates: [{ hostnames: [opts.tls.hostname], certPath: "/tls/server.crt", keyPath: "/tls/server.key" }],
+        files: [{ path: "/etc/nginx/nginx.conf", content: `worker_processes 1;\nevents { worker_connections 1024; }\nstream { server { listen ${port} ssl; ssl_certificate /tls/server.crt; ssl_certificate_key /tls/server.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_alpn h2; proxy_pass ${serverName}:${port}; } }\n` }],
+        readyCheck: { type: "tcp", port, timeoutSecs: 30 },
+      } };
+    },
+    helpers: (ctx) => temporalClient(httpUrl, namespace,
+      async (input, init) => readRaw(await ctx.fetch(String(input), init)) as unknown as Response),
+  });
+  return { group, address, httpUrl, namespace, ready: name,
+    client: temporalClient(httpUrl, namespace) };
+}