@specific.dev/spectest 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/components/index.ts

@@ -8,10 +8,13 @@
 
 export {
   postgres,
-  sqlClient,
   type PostgresOptions,
-  type SqlClient,
+  type PostgresHelpers,
 } from "./postgres.js";
+// `SQL` / `SqlClient` now live in the core SDK (`@specific.dev/spectest`),
+// next to `expect` and `fetch` — re-exported here so existing
+// `from ".../components"` imports keep resolving.
+export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
 export {
   k3s,
   type K3sOptions,

package/src/components/postgres.ts

@@ -1,11 +1,16 @@
 import type { ServiceDefinition } from "../index.js";
-import { recordDb, reserveEvent, safeSerialize } from "../recorder.js";
-import { wrap } from "../inspect.js";
-import type { Wrapped } from "../inspect.js";
+import { SQL, type SqlClient } from "../sql.js";
 
 export interface PostgresOptions {
-  /** Image tag for the official `postgres` image. Default `"18-alpine"`. */
+  /** Image tag for the official `postgres` image. Default `"18-alpine"`.
+   *  Ignored when {@link image} is set. */
   version?: string;
+  /**
+   * Full image reference, overriding the default `postgres:<version>`. For a
+   * Bun-SQL-/wire-compatible image (timescaledb, postgis, pgvector, …) you
+   * still get the instrumented client on `ctx.svc.<name>.client`.
+   */
+  image?: string;
   /** Database created on first boot. */
   database: string;
   /** Superuser name created on first boot. */
@@ -21,94 +26,23 @@ export interface PostgresOptions {
   persistent?: boolean;
   /** TCP port the container listens on. Default `5432`. */
   port?: number;
+  /**
+   * CMD args appended after the image entrypoint (keeps the entrypoint, unlike
+   * `command`). For extension tuning, e.g.
+   * `["postgres", "-c", "timescaledb.max_background_workers=0"]`.
+   */
+  args?: string[];
   /** Extra environment variables forwarded to the container. */
   env?: Record<string, string>;
 }
 
-/**
- * Minimal structural type for the parts of `Bun.SQL` we use. Declared
- * locally so user projects don't need `@types/bun` for type-checking to
- * follow the SDK through to the daemon. The real type comes from Bun at
- * runtime via `globalThis.Bun.SQL`.
- *
- * `SqlClient` is callable as a tagged template (`sql\`...\``) and has an
- * `unsafe(text, params?)` escape hatch. Both return a thenable that
- * executes lazily; we wrap them so each settle is recorded as a DbEvent.
- *
- * Both forms are generic in the row type and resolve to an array of rows,
- * so callers name the shape once at the call site instead of casting the
- * result: `` await ctx.svc.db.client<TodoRow>`SELECT * FROM todos` `` is
- * `Promise<TodoRow[]>`. `T` defaults to `unknown` (the row shape is the
- * caller's to assert) — pass it to drop the cast.
- */
-interface SqlClientBase {
-  close?(opts?: { timeout?: number }): Promise<void>;
-  /** Close the connection / drain the pool (Bun's `SQL.end`). */
-  end(opts?: { timeout?: number }): Promise<void>;
-}
-
-export interface SqlClient extends SqlClientBase {
-  // Callable as a tagged template; resolves to the result rows.
-  <T = unknown>(
-    strings: TemplateStringsArray,
-    ...values: unknown[]
-  ): Promise<T[]>;
-  unsafe<T = unknown>(text: string, params?: unknown[]): Promise<T[]>;
-}
-
-/**
- * The recorder-instrumented client wired onto `ctx.svc.<name>.client`. Same
- * surface as {@link SqlClient}, but each query resolves to a **wrapped** row
- * array ({@link Wrapped}) rather than the raw rows: every settle is recorded
- * as a DbEvent, and the wrapper carries provenance back to it. That's why
- * `expect(rows)` / `expect(rows[0]!.id)` link under the query in the timeline
- * with no cast — and why you `.unwrap()` before feeding a row
- * value to a real client or a `===`. The raw escape-hatch {@link sqlClient}
- * stays un-instrumented (plain {@link SqlClient}), so its results are genuinely
- * raw and belong with `expectRaw`.
- */
-export interface RecordingSqlClient extends SqlClientBase {
-  <T = unknown>(
-    strings: TemplateStringsArray,
-    ...values: unknown[]
-  ): Promise<Wrapped<T[]>>;
-  unsafe<T = unknown>(text: string, params?: unknown[]): Promise<Wrapped<T[]>>;
-}
-
-interface BunGlobal {
-  SQL: new (url: string) => SqlClient;
-}
-
-/**
- * Open a raw Bun SQL client against `url`, typed as {@link SqlClient}.
- *
- * Unlike the pool `postgres(...)` wires onto `ctx.svc.<name>.client`, this
- * is **not** recorder-instrumented — reach for it when you only learn a
- * connection string at runtime (e.g. one a fake handed back after
- * provisioning a database via `ctx.startService(...)`), where the boot-time
- * component isn't an option. Queries are still generic in the row type:
- * `` await sqlClient(url)<{ name: string }>`SELECT name FROM t` ``.
- *
- * Requires the Bun runtime (it runs inside the spectest daemon), so it
- * replaces the `(globalThis as any).Bun` reach-around with a typed entry
- * point.
- */
-export function sqlClient(url: string): SqlClient {
-  const bun = (globalThis as { Bun?: BunGlobal }).Bun;
-  if (!bun?.SQL) {
-    throw new Error(
-      "sqlClient(url) requires Bun.SQL (Bun >= 1.2) — it runs inside the spectest daemon.",
-    );
-  }
-  return new bun.SQL(url);
-}
-
 /** Helpers a `postgres(...)` service exposes on `ctx.svc.<name>`. */
 export interface PostgresHelpers {
-  /** A Bun SQL pool, wrapped so each query lands on the test event
-   * log alongside http/exec/assertion events — its rows come back
-   * inspect-wrapped, so `expect(...)` on them links to the query. */
-  client: RecordingSqlClient;
+  /** An instrumented Bun SQL client — each query lands on the test event log
+   *  alongside http/exec/assertion events, and its rows come back
+   *  inspect-wrapped so `expect(...)` on them links to the query. See
+   *  {@link SQL}. */
+  client: SqlClient;
 }
 
 /**
@@ -125,9 +59,20 @@ export interface PostgresHelpers {
  * example above). Tests get a wired-up Bun SQL client at
  * `ctx.svc.<key>.client` — `await ctx.svc.db.client\`SELECT 1\`` — with
  * every query recorded on the test event log.
+ *
+ * Point it at a wire-compatible image with `image`/`args`:
+ *
+ * ```ts
+ * db: postgres({
+ *   image: "timescale/timescaledb:latest-pg17",
+ *   args: ["postgres", "-c", "timescaledb.max_background_workers=0"],
+ *   database: "app", user: "app", password: "app",
+ * }),
+ * ```
  */
 export function postgres(opts: PostgresOptions) {
   const version = opts.version ?? "18-alpine";
+  const reference = opts.image ?? `postgres:${version}`;
   const port = opts.port ?? 5432;
   const persistent = opts.persistent ?? true;
   // `satisfies` (instead of a return-type annotation) preserves the
@@ -135,7 +80,8 @@ export function postgres(opts: PostgresOptions) {
   // The mapped type in `ServiceHandlesFor<S>` reads that to type
   // `ctx.svc.<name>` as `{ client: SqlClient }`.
   return {
-    image: { type: "registry", reference: `postgres:${version}` },
+    image: { type: "registry", reference },
+    ...(opts.args ? { args: opts.args } : {}),
     env: {
       POSTGRES_DB: opts.database,
       POSTGRES_USER: opts.user,
@@ -149,133 +95,11 @@ export function postgres(opts: PostgresOptions) {
     ports: [port],
     readyCheck: { type: "tcp" as const, port, timeoutSecs: 60 },
     helpers: ({ name }: { name: string }): PostgresHelpers => {
-      const bun = (globalThis as { Bun?: BunGlobal }).Bun;
-      if (!bun?.SQL) {
-        throw new Error(
-          "postgres component requires Bun.SQL (Bun >= 1.2). " +
-            "This helpers factory is meant to run inside the spectest daemon.",
-        );
-      }
       const url =
         `postgres://${encodeURIComponent(opts.user)}` +
         `:${encodeURIComponent(opts.password)}` +
         `@${name}:${port}/${encodeURIComponent(opts.database)}`;
-      return { client: wrapSqlForRecording(new bun.SQL(url), name) };
+      return { client: new SQL(url, { label: name }) };
     },
   } satisfies ServiceDefinition<PostgresHelpers>;
 }
-
-/**
- * Proxy a Bun.SQL instance so each tagged-template call and each
- * `unsafe(...)` call emits a DbEvent into the active recorder when its
- * promise settles. Other Bun.SQL methods (`.transaction`, `.array`,
- * `.file`, …) pass through unwrapped.
- */
-function wrapSqlForRecording(raw: SqlClient, service: string): RecordingSqlClient {
-  const wrapResult = <T>(
-    result: PromiseLike<T>,
-    query: string,
-    params: unknown[],
-  ): Promise<T> => {
-    const started = Date.now();
-    const resv = reserveEvent();
-    return Promise.resolve(result).then(
-      (value) => {
-        const { rows, rowsTruncated, columns } = captureRows(value);
-        const seq = recordDb({
-          service,
-          query,
-          params: params.length > 0 ? params.map(safeSerialize) : undefined,
-          rowCount: rowCountOf(value),
-          rows,
-          rowsTruncated,
-          columns,
-          durationMs: Date.now() - started,
-        }, resv);
-        return wrap(value, seq) as T;
-      },
-      (err) => {
-        const e = err as Error;
-        recordDb({
-          service,
-          query,
-          params: params.length > 0 ? params.map(safeSerialize) : undefined,
-          durationMs: Date.now() - started,
-          error: e?.message ?? String(err),
-        }, resv);
-        throw err;
-      },
-    );
-  };
-
-  const handler: ProxyHandler<SqlClient> = {
-    apply(target, thisArg, args) {
-      const [strings, ...values] = args as [TemplateStringsArray, ...unknown[]];
-      const query = reconstructSqlTemplate(strings, values.length);
-      const result = Reflect.apply(
-        target as unknown as (...a: unknown[]) => PromiseLike<unknown>,
-        thisArg,
-        args,
-      );
-      return wrapResult(result, query, values);
-    },
-    get(target, prop, receiver) {
-      if (prop === "unsafe") {
-        return (text: string, params?: unknown[]) => {
-          const result = (
-            target.unsafe as (t: string, p?: unknown[]) => PromiseLike<unknown>
-          ).call(target, text, params);
-          return wrapResult(result, text, params ?? []);
-        };
-      }
-      const v = Reflect.get(target, prop, receiver);
-      return typeof v === "function" ? v.bind(target) : v;
-    },
-  };
-  return new Proxy(raw, handler) as unknown as RecordingSqlClient;
-}
-
-/** Rebuild a parameterized SQL string from a tagged-template's pieces.
- * Bun.SQL substitutes `${value}` for `$1`, `$2`, …; we do the same so
- * the recorded query matches what the server sees. */
-function reconstructSqlTemplate(
-  strings: TemplateStringsArray,
-  valueCount: number,
-): string {
-  let out = strings[0] ?? "";
-  for (let i = 0; i < valueCount; i++) {
-    out += `$${i + 1}` + (strings[i + 1] ?? "");
-  }
-  return out.trim();
-}
-
-function rowCountOf(value: unknown): number | undefined {
-  if (Array.isArray(value)) return value.length;
-  if (value && typeof value === "object") {
-    const obj = value as { count?: unknown; rowCount?: unknown };
-    if (typeof obj.count === "number") return obj.count;
-    if (typeof obj.rowCount === "number") return obj.rowCount;
-  }
-  return undefined;
-}
-
-const MAX_DB_ROWS = 50;
-
-function captureRows(value: unknown): {
-  rows?: unknown[];
-  rowsTruncated?: boolean;
-  columns?: string[];
-} {
-  if (!Array.isArray(value) || value.length === 0) return {};
-  const slice = value.slice(0, MAX_DB_ROWS).map(safeSerialize);
-  const first = slice[0];
-  const columns =
-    first && typeof first === "object" && !Array.isArray(first)
-      ? Object.keys(first as Record<string, unknown>)
-      : undefined;
-  return {
-    rows: slice,
-    rowsTruncated: value.length > MAX_DB_ROWS ? true : undefined,
-    columns,
-  };
-}

package/src/daemon.ts

@@ -166,6 +166,25 @@ function casesMetadata(suite: TestSuite | undefined): CaseMeta[] {
   }));
 }
 
+interface FakeMeta {
+  name: string;
+  hostnames: string[];
+  port: number;
+}
+
+// Display-only summary of the project's fakes for the control plane (folded
+// into the env config's `fakes`, surfaced on the run page). Fakes aren't part
+// of `project.environment`, so they ride alongside it as a separate field of
+// the /load response — just the routing surface, no handler/state/helpers.
+function fakesSummary(project: Project | undefined): FakeMeta[] {
+  if (!project?.fakes) return [];
+  return Object.entries(project.fakes).map(([name, def]) => ({
+    name,
+    hostnames: def.hostnames.map((h) => h.toLowerCase()),
+    port: def.port ?? DEFAULT_FAKE_PORT,
+  }));
+}
+
 function resolveEntry(): string {
   const explicit = process.env.SPECTEST_PROJECT_ENTRY;
   if (explicit && existsSync(explicit)) return explicit;
@@ -3935,6 +3954,7 @@ async function handle(req: http.IncomingMessage, res: http.ServerResponse, state
     jsonResponse(res, 200, {
       environment: proj.environment,
       cases: casesMetadata(proj.tests),
+      fakes: fakesSummary(proj),
     });
     return;
   }
@@ -3948,6 +3968,7 @@ async function handle(req: http.IncomingMessage, res: http.ServerResponse, state
     jsonResponse(res, 200, {
       environment: l.project.environment,
       cases: casesMetadata(l.project.tests),
+      fakes: fakesSummary(l.project),
     });
     return;
   }
@@ -3966,6 +3987,7 @@ async function handle(req: http.IncomingMessage, res: http.ServerResponse, state
     jsonResponse(res, 200, {
       environment: l.project.environment,
       cases: casesMetadata(l.project.tests),
+      fakes: fakesSummary(l.project),
     });
     return;
   }

package/src/index.ts

@@ -34,6 +34,16 @@ import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 // `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
 export { field } from "./inspect.js";
 
+// Instrumented client primitives — drop-in replacements for Bun's native
+// clients that record each operation on the test event log and return their
+// results inspect-wrapped, so `expect(...)` on a result links back to the op
+// in the timeline (same provenance mechanism as the wrapped `fetch`). Reach
+// for these over the raw `Bun.*` clients in service `helpers` and tests so
+// assertions stay tracked. See `sql.ts` / `redis.ts` / `s3.ts`.
+export { SQL, type SqlClient, type SqlOptions } from "./sql.js";
+export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js";
+export { S3Client, type S3ClientLike, type S3File, type S3Options } from "./s3.js";
+
 export type {
   Browser,
   BrowserOptions,

package/src/recorder.ts

@@ -19,6 +19,8 @@ export type TestEvent =
   | KubeEvent
   | BrowserEvent
   | DbEvent
+  | RedisEvent
+  | S3Event
   | TerminalEvent
   | TerminalStepEvent
   | WaitEvent
@@ -124,6 +126,67 @@ export interface DbEvent extends BaseEvent {
   error?: string;
 }
 
+/**
+ * One Redis/Valkey command issued through the instrumented {@link
+ * "../redis".RedisClient} (a drop-in for `Bun.RedisClient` / `Bun.redis`).
+ *
+ * The return value is `wrap()`ped against this event's seq, so a later
+ * `expect(...)` that drills into it nests under this step in the timeline
+ * (same mechanism as http/db).
+ */
+export interface RedisEvent extends BaseEvent {
+  kind: "redis";
+  /** Label for the connection — the URL host (often the service name). */
+  service: string;
+  /** Command name, upper-cased (`GET`, `SET`, `HGETALL`, `PUBLISH`, …). */
+  command: string;
+  /** First argument — almost always the key the command targets. Surfaced
+   *  separately so the UI can read `GET session:42` at a glance. */
+  key?: string;
+  /** Remaining arguments (best-effort JSON-safe; large/binary stringified).
+   *  Omitted when there are none. */
+  args?: unknown[];
+  /** Reply, best-effort JSON-safe and capped. Omitted when the command threw
+   *  or returned `null`/`undefined`. */
+  result?: unknown;
+  resultTruncated?: boolean;
+  durationMs: number;
+  /** Set if the command threw. */
+  error?: string;
+}
+
+/**
+ * One object-storage operation through the instrumented {@link
+ * "../s3".S3Client} (a drop-in for `Bun.S3Client` / `Bun.s3`), covering both
+ * client-level calls (`write`/`delete`/`exists`/`list`/`presign`/`stat`) and
+ * the `S3File` handle `.file(path)` returns (`text`/`json`/`write`/…).
+ *
+ * The return value is `wrap()`ped against this event's seq, so `expect(...)`
+ * drilling into it nests under this step (same mechanism as http/db).
+ */
+export interface S3Event extends BaseEvent {
+  kind: "s3";
+  /** Operation: `write` | `read` | `delete` | `exists` | `list` |
+   *  `presign` | `stat`. */
+  op: string;
+  /** Bucket, when the client/handle knows it. */
+  bucket?: string;
+  /** Object key (path) the op targeted. Omitted for bucket-wide `list`. */
+  key?: string;
+  /** Bytes written or read, when known. */
+  size?: number;
+  /** Content type, when known (read/write/stat). */
+  contentType?: string;
+  /** Small text preview of the body (read/write of text), capped. */
+  preview?: string;
+  previewTruncated?: boolean;
+  /** For `list`: number of keys returned. */
+  count?: number;
+  durationMs: number;
+  /** Set if the op threw. */
+  error?: string;
+}
+
 export interface HttpEvent extends BaseEvent {
   kind: "http";
   method: string;
@@ -556,6 +619,20 @@ export function recordDb(
   return active() ? current!.push({ kind: "db", ...ev }, reservation) : undefined;
 }
 
+export function recordRedis(
+  ev: Omit<RedisEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "redis", ...ev }, reservation) : undefined;
+}
+
+export function recordS3(
+  ev: Omit<S3Event, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "s3", ...ev }, reservation) : undefined;
+}
+
 export function recordTerminal(
   ev: Omit<TerminalEvent, "seq" | "tOffsetMs" | "kind">,
   reservation?: EventReservation,

package/src/redis.ts

@@ -0,0 +1,202 @@
+// `RedisClient` — a drop-in for `Bun.RedisClient` (`Bun.redis`) that records
+// every command on the test event log and returns its reply inspect-wrapped,
+// so `expect(await client.get("k"))` links the assertion back to the command in
+// the timeline (same provenance mechanism as the wrapped `fetch` / `SQL`). Swap
+// `new Bun.RedisClient(url)` → `new RedisClient(url)` and nothing else changes
+// at the call site; replies come back `Wrapped<T>` (that wrapper is what carries
+// provenance), so `.unwrap()` before a `===` or before feeding a value onward.
+//
+// Reach for it in service `helpers` when you stand up a redis/valkey yourself,
+// or directly in a test against a connection string a fake handed back.
+
+import { recordRedis, reserveEvent, safeSerialize } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
+
+/**
+ * Structural type for the parts of `Bun.RedisClient` we use, declared locally
+ * so user projects don't need `@types/bun`. The real implementation comes from
+ * Bun at runtime via `globalThis.Bun.RedisClient`. Commands resolve to their
+ * reply; lifecycle methods (`connect`/`close`/`subscribe`/…) are passed through
+ * un-instrumented.
+ */
+interface RawRedisClient {
+  send(command: string, args: string[]): Promise<unknown>;
+  close?(): void;
+  [method: string]: unknown;
+}
+
+/** The instrumented Redis surface — same shape as `Bun.RedisClient`, but every
+ *  command resolves to a {@link Wrapped} reply recorded as a `redis` event.
+ *  Indexable so every Bun command method is reachable without re-declaring the
+ *  whole (large) surface; the common ones are typed for ergonomics. */
+export interface RedisClientLike {
+  get(key: string): Promise<Wrapped<string | null>>;
+  set(key: string, value: string): Promise<Wrapped<string>>;
+  del(...keys: string[]): Promise<Wrapped<number>>;
+  exists(...keys: string[]): Promise<Wrapped<number>>;
+  incr(key: string): Promise<Wrapped<number>>;
+  hgetall(key: string): Promise<Wrapped<Record<string, string>>>;
+  /** Run an arbitrary command — `client.send("SET", ["k", "v"])`. */
+  send(command: string, args: string[]): Promise<Wrapped<unknown>>;
+  close(): void;
+  [method: string]: (...args: any[]) => any;
+}
+
+/** Options accepted by the {@link RedisClient} constructor beyond Bun's own. */
+export interface RedisOptions {
+  /** Label shown on each recorded `redis` event (the timeline step's tag).
+   *  Defaults to the connection URL's host (usually the service name). */
+  label?: string;
+}
+
+interface BunGlobal {
+  RedisClient: new (url?: string, options?: unknown) => RawRedisClient;
+}
+
+interface RedisConstructor {
+  new (url?: string, opts?: RedisOptions): RedisClientLike;
+  (url?: string, opts?: RedisOptions): RedisClientLike;
+}
+
+// Long-lived / connection-management methods that don't map to a single
+// request→reply step — passed straight through, never recorded.
+const REDIS_PASSTHROUGH = new Set([
+  "connect",
+  "close",
+  "disconnect",
+  "duplicate",
+  "subscribe",
+  "unsubscribe",
+  "psubscribe",
+  "punsubscribe",
+  "ssubscribe",
+  "sunsubscribe",
+  "onclose",
+  "ref",
+  "unref",
+]);
+
+const MAX_RESULT_BYTES = 2048;
+
+/**
+ * Open an instrumented Redis client against `url` (default: Bun's own
+ * `REDIS_URL`/`VALKEY_URL`). Usable with or without `new`. Requires the Bun
+ * runtime — it runs inside the spectest daemon.
+ */
+export const RedisClient = function RedisClient(
+  url?: string,
+  opts?: RedisOptions,
+): RedisClientLike {
+  const bun = (globalThis as unknown as { Bun?: BunGlobal }).Bun;
+  if (!bun?.RedisClient) {
+    throw new Error(
+      "RedisClient requires the Bun runtime (Bun >= 1.2.9) — it runs inside the spectest daemon.",
+    );
+  }
+  const raw = url !== undefined ? new bun.RedisClient(url, opts) : new bun.RedisClient();
+  return instrumentRedis(raw, opts?.label ?? hostLabel(url));
+} as unknown as RedisConstructor;
+
+function hostLabel(url?: string): string {
+  if (!url) return "redis";
+  try {
+    return new URL(url).hostname || "redis";
+  } catch {
+    return "redis";
+  }
+}
+
+/**
+ * Proxy a `Bun.RedisClient` so each command method (and `send(...)`) emits a
+ * `redis` event when its promise settles and resolves to a {@link Wrapped}
+ * reply. Lifecycle methods and non-function properties pass through.
+ *
+ * Exported so a client built another way can opt into the same instrumentation.
+ */
+export function instrumentRedis(raw: RawRedisClient, label: string): RedisClientLike {
+  const run = (
+    command: string,
+    key: string | undefined,
+    extra: unknown[],
+    invoke: () => unknown,
+  ): Promise<unknown> => {
+    const started = Date.now();
+    const resv = reserveEvent();
+    return Promise.resolve(invoke()).then(
+      (value) => {
+        const { preview, truncated } = capValue(value);
+        const seq = recordRedis(
+          {
+            service: label,
+            command,
+            key,
+            args: extra.length > 0 ? extra.map(safeSerialize) : undefined,
+            result: preview,
+            resultTruncated: truncated,
+            durationMs: Date.now() - started,
+          },
+          resv,
+        );
+        return wrap(value, seq);
+      },
+      (err) => {
+        const e = err as Error;
+        recordRedis(
+          {
+            service: label,
+            command,
+            key,
+            args: extra.length > 0 ? extra.map(safeSerialize) : undefined,
+            durationMs: Date.now() - started,
+            error: e?.message ?? String(err),
+          },
+          resv,
+        );
+        throw err;
+      },
+    );
+  };
+
+  const handler: ProxyHandler<RawRedisClient> = {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      const v = Reflect.get(target, prop, receiver);
+      if (typeof v !== "function") return v;
+      const fn = v as (...a: unknown[]) => unknown;
+      if (REDIS_PASSTHROUGH.has(prop)) return fn.bind(target);
+      // `send(command, args)` carries the real command in its first arg.
+      if (prop === "send") {
+        return (command: string, args: string[] = []) =>
+          run(String(command).toUpperCase(), args[0], args.slice(1), () =>
+            fn.call(target, command, args),
+          );
+      }
+      return (...args: unknown[]) =>
+        run(
+          prop.toUpperCase(),
+          typeof args[0] === "string" ? args[0] : undefined,
+          args.slice(1),
+          () => fn.apply(target, args),
+        );
+    },
+  };
+  return new Proxy(raw, handler) as unknown as RedisClientLike;
+}
+
+/** Best-effort JSON-safe preview of a reply, capped at {@link MAX_RESULT_BYTES}. */
+function capValue(value: unknown): { preview?: unknown; truncated?: boolean } {
+  if (value === null || value === undefined) return {};
+  const safe = safeSerialize(value);
+  const json = (() => {
+    try {
+      return JSON.stringify(safe);
+    } catch {
+      return undefined;
+    }
+  })();
+  if (json !== undefined && json.length > MAX_RESULT_BYTES) {
+    return { preview: `${json.slice(0, MAX_RESULT_BYTES)}…`, truncated: true };
+  }
+  return { preview: safe };
+}

package/src/s3.ts

@@ -0,0 +1,333 @@
+// `S3Client` — a drop-in for `Bun.S3Client` (`Bun.s3`) that records every
+// object-storage operation on the test event log and returns its result
+// inspect-wrapped, so `expect(await client.file("k").json())` links the
+// assertion back to the read in the timeline (same provenance mechanism as the
+// wrapped `fetch` / `SQL` / `RedisClient`). Swap `new Bun.S3Client(opts)` →
+// `new S3Client(opts)` and nothing else changes at the call site.
+//
+// Instrumentation covers both the client-level ops (`write`/`delete`/`exists`/
+// `list`/`presign`/`stat`/`size`) and the lazy `S3File` handle that
+// `.file(path)` returns (`text`/`json`/`arrayBuffer`/`bytes`/`write`/…). Reach
+// for it whenever you stand up S3-compatible storage (MinIO, real S3, R2) in a
+// service `helpers` factory or a test.
+
+import { recordS3, reserveEvent } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
+
+/** Structural types for the parts of `Bun.S3Client` we use, declared locally so
+ *  user projects don't need `@types/bun`. The real implementation comes from
+ *  Bun at runtime via `globalThis.Bun.S3Client`. */
+interface RawS3File {
+  name?: string;
+  bucket?: string;
+  size?: number;
+  type?: string;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  bytes(): Promise<Uint8Array>;
+  write(data: unknown, options?: unknown): Promise<number>;
+  exists(): Promise<boolean>;
+  delete(): Promise<void>;
+  unlink?(): Promise<void>;
+  stat(): Promise<unknown>;
+  presign(options?: unknown): string;
+  [m: string]: unknown;
+}
+
+interface RawS3Client {
+  file(path: string, options?: unknown): RawS3File;
+  write(path: string, data: unknown, options?: unknown): Promise<number>;
+  delete(path: string, options?: unknown): Promise<void>;
+  unlink?(path: string, options?: unknown): Promise<void>;
+  exists(path: string, options?: unknown): Promise<boolean>;
+  size?(path: string, options?: unknown): Promise<number>;
+  stat(path: string, options?: unknown): Promise<unknown>;
+  presign(path: string, options?: unknown): string;
+  list(input?: unknown, options?: unknown): Promise<unknown>;
+  [m: string]: unknown;
+}
+
+/** A lazy S3 object handle (Bun's `S3File`), wrapped so each read/write records
+ *  an `s3` event and returns a {@link Wrapped} result. */
+export interface S3File {
+  readonly name?: string;
+  readonly bucket?: string;
+  readonly size?: number;
+  text(): Promise<Wrapped<string>>;
+  json<T = unknown>(): Promise<Wrapped<T>>;
+  arrayBuffer(): Promise<Wrapped<ArrayBuffer>>;
+  bytes(): Promise<Wrapped<Uint8Array>>;
+  write(data: unknown, options?: unknown): Promise<Wrapped<number>>;
+  exists(): Promise<Wrapped<boolean>>;
+  delete(): Promise<Wrapped<void>>;
+  stat(): Promise<Wrapped<unknown>>;
+  presign(options?: unknown): string;
+}
+
+/** The instrumented S3 surface — same shape as `Bun.S3Client`, but every op
+ *  records an `s3` event and resolves to a {@link Wrapped} result. */
+export interface S3ClientLike {
+  file(path: string, options?: unknown): S3File;
+  write(path: string, data: unknown, options?: unknown): Promise<Wrapped<number>>;
+  delete(path: string, options?: unknown): Promise<Wrapped<void>>;
+  exists(path: string, options?: unknown): Promise<Wrapped<boolean>>;
+  stat(path: string, options?: unknown): Promise<Wrapped<unknown>>;
+  list(input?: unknown, options?: unknown): Promise<Wrapped<unknown>>;
+  presign(path: string, options?: unknown): string;
+  [m: string]: (...args: any[]) => any;
+}
+
+/** Options accepted by the {@link S3Client} constructor — Bun's own plus a
+ *  recording `label`. Passed through to `Bun.S3Client` verbatim. */
+export interface S3Options {
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+  bucket?: string;
+  region?: string;
+  endpoint?: string;
+  [opt: string]: unknown;
+}
+
+interface BunGlobal {
+  S3Client: new (options?: S3Options) => RawS3Client;
+}
+
+interface S3Constructor {
+  new (options?: S3Options): S3ClientLike;
+  (options?: S3Options): S3ClientLike;
+}
+
+const MAX_PREVIEW = 512;
+
+/**
+ * Open an instrumented S3 client. Usable with or without `new`. Requires the
+ * Bun runtime — it runs inside the spectest daemon.
+ */
+export const S3Client = function S3Client(options?: S3Options): S3ClientLike {
+  const bun = (globalThis as unknown as { Bun?: BunGlobal }).Bun;
+  if (!bun?.S3Client) {
+    throw new Error(
+      "S3Client requires the Bun runtime (Bun >= 1.1) — it runs inside the spectest daemon.",
+    );
+  }
+  return instrumentS3(new bun.S3Client(options), options?.bucket);
+} as unknown as S3Constructor;
+
+/** Record an awaitable S3 op, wrapping its settled result for provenance. */
+function runS3<T>(
+  base: { op: string; bucket?: string; key?: string },
+  invoke: () => PromiseLike<T>,
+  describe?: (value: T) => Partial<{
+    size: number;
+    contentType: string;
+    preview: string;
+    previewTruncated: boolean;
+    count: number;
+  }>,
+): Promise<T> {
+  const started = Date.now();
+  const resv = reserveEvent();
+  return Promise.resolve(invoke()).then(
+    (value) => {
+      const seq = recordS3(
+        { ...base, ...(describe?.(value) ?? {}), durationMs: Date.now() - started },
+        resv,
+      );
+      return wrap(value, seq) as T;
+    },
+    (err) => {
+      const e = err as Error;
+      recordS3(
+        { ...base, durationMs: Date.now() - started, error: e?.message ?? String(err) },
+        resv,
+      );
+      throw err;
+    },
+  );
+}
+
+/** Record a synchronous op (`presign`) — no result wrapping (returns a URL). */
+function runS3Sync<T>(base: { op: string; bucket?: string; key?: string }, invoke: () => T): T {
+  const started = Date.now();
+  try {
+    const value = invoke();
+    recordS3({ ...base, durationMs: Date.now() - started }, undefined);
+    return value;
+  } catch (err) {
+    const e = err as Error;
+    recordS3(
+      { ...base, durationMs: Date.now() - started, error: e?.message ?? String(err) },
+      undefined,
+    );
+    throw err;
+  }
+}
+
+/**
+ * Proxy a `Bun.S3Client` so each op records an `s3` event. `file(path)` returns
+ * a wrapped {@link S3File}; unknown methods pass through.
+ *
+ * Exported so a client built another way can opt into the same instrumentation.
+ */
+export function instrumentS3(raw: RawS3Client, bucket?: string): S3ClientLike {
+  const handler: ProxyHandler<RawS3Client> = {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      switch (prop) {
+        case "file":
+          return (path: string, options?: unknown) =>
+            instrumentS3File(target.file(path, options), path, bucket);
+        case "write":
+          return (path: string, data: unknown, options?: unknown) =>
+            runS3({ op: "write", bucket, key: path }, () => target.write(path, data, options), () =>
+              describeData(data),
+            );
+        case "delete":
+        case "unlink":
+          return (path: string, options?: unknown) =>
+            runS3({ op: "delete", bucket, key: path }, () => target.delete(path, options));
+        case "exists":
+          return (path: string, options?: unknown) =>
+            runS3({ op: "exists", bucket, key: path }, () => target.exists(path, options));
+        case "size":
+          return (path: string, options?: unknown) =>
+            runS3({ op: "stat", bucket, key: path }, () => target.size!(path, options), (n) => ({
+              size: typeof n === "number" ? n : undefined,
+            }));
+        case "stat":
+          return (path: string, options?: unknown) =>
+            runS3({ op: "stat", bucket, key: path }, () => target.stat(path, options), describeStat);
+        case "list":
+          return (input?: unknown, options?: unknown) =>
+            runS3({ op: "list", bucket }, () => target.list(input, options), (r) => ({
+              count: listCount(r),
+            }));
+        case "presign":
+          return (path: string, options?: unknown) =>
+            runS3Sync({ op: "presign", bucket, key: path }, () => target.presign(path, options));
+        default: {
+          const v = Reflect.get(target, prop, receiver);
+          return typeof v === "function" ? (v as (...a: unknown[]) => unknown).bind(target) : v;
+        }
+      }
+    },
+  };
+  return new Proxy(raw, handler) as unknown as S3ClientLike;
+}
+
+function instrumentS3File(raw: RawS3File, key: string, bucket?: string): S3File {
+  const b = raw.bucket ?? bucket;
+  const handler: ProxyHandler<RawS3File> = {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      switch (prop) {
+        case "text":
+          return () => runS3({ op: "read", bucket: b, key }, () => target.text(), describeData);
+        case "json":
+          return () => runS3({ op: "read", bucket: b, key }, () => target.json(), describeData);
+        case "arrayBuffer":
+          return () =>
+            runS3({ op: "read", bucket: b, key }, () => target.arrayBuffer(), describeData);
+        case "bytes":
+          return () => runS3({ op: "read", bucket: b, key }, () => target.bytes(), describeData);
+        case "write":
+          return (data: unknown, options?: unknown) =>
+            runS3({ op: "write", bucket: b, key }, () => target.write(data, options), () =>
+              describeData(data),
+            );
+        case "exists":
+          return () => runS3({ op: "exists", bucket: b, key }, () => target.exists());
+        case "delete":
+        case "unlink":
+          return () => runS3({ op: "delete", bucket: b, key }, () => target.delete());
+        case "stat":
+          return () => runS3({ op: "stat", bucket: b, key }, () => target.stat(), describeStat);
+        case "presign":
+          return (options?: unknown) =>
+            runS3Sync({ op: "presign", bucket: b, key }, () => target.presign(options));
+        default: {
+          const v = Reflect.get(target, prop, receiver);
+          return typeof v === "function" ? (v as (...a: unknown[]) => unknown).bind(target) : v;
+        }
+      }
+    },
+  };
+  return new Proxy(raw, handler) as unknown as S3File;
+}
+
+/** Byte size + small text preview of a written/read body. */
+function describeData(value: unknown): Partial<{
+  size: number;
+  contentType: string;
+  preview: string;
+  previewTruncated: boolean;
+}> {
+  if (typeof value === "string") {
+    const truncated = value.length > MAX_PREVIEW;
+    return {
+      size: byteLength(value),
+      preview: truncated ? value.slice(0, MAX_PREVIEW) : value,
+      previewTruncated: truncated || undefined,
+    };
+  }
+  if (value && typeof value === "object" && !isBinary(value)) {
+    // A parsed JSON body (from `.json()`): preview a capped serialization.
+    try {
+      const json = JSON.stringify(value);
+      const truncated = json.length > MAX_PREVIEW;
+      return {
+        contentType: "application/json",
+        preview: truncated ? `${json.slice(0, MAX_PREVIEW)}…` : json,
+        previewTruncated: truncated || undefined,
+      };
+    } catch {
+      /* fall through to size-only */
+    }
+  }
+  const size = byteLength(value);
+  return size !== undefined ? { size } : {};
+}
+
+function describeStat(stat: unknown): Partial<{ size: number; contentType: string }> {
+  if (stat && typeof stat === "object") {
+    const s = stat as { size?: unknown; type?: unknown; contentType?: unknown };
+    return {
+      size: typeof s.size === "number" ? s.size : undefined,
+      contentType:
+        typeof s.type === "string"
+          ? s.type
+          : typeof s.contentType === "string"
+            ? s.contentType
+            : undefined,
+    };
+  }
+  return {};
+}
+
+function listCount(result: unknown): number | undefined {
+  if (result && typeof result === "object") {
+    const r = result as { contents?: unknown[]; keyCount?: unknown };
+    if (Array.isArray(r.contents)) return r.contents.length;
+    if (typeof r.keyCount === "number") return r.keyCount;
+  }
+  return undefined;
+}
+
+function isBinary(value: unknown): boolean {
+  return (
+    value instanceof ArrayBuffer ||
+    ArrayBuffer.isView(value) ||
+    (typeof Blob !== "undefined" && value instanceof Blob)
+  );
+}
+
+function byteLength(value: unknown): number | undefined {
+  if (typeof value === "string") return Buffer.byteLength(value);
+  if (value instanceof ArrayBuffer) return value.byteLength;
+  if (ArrayBuffer.isView(value)) return value.byteLength;
+  if (typeof Blob !== "undefined" && value instanceof Blob) return value.size;
+  return undefined;
+}

package/src/sql.ts

@@ -0,0 +1,223 @@
+// `SQL` — a drop-in for `Bun.SQL` that records every query on the test event
+// log and returns its rows inspect-wrapped, so `expect(rows[0]!.id)` links the
+// assertion back to the query in the timeline (same provenance mechanism as
+// `fetch`). Swap `new Bun.SQL(url)` → `new SQL(url)` and nothing else changes
+// at the call site; query *results* come back `Wrapped<T[]>` instead of raw
+// `T[]` (that wrapper is what carries provenance), so `.unwrap()` before feeding
+// a row value to another real client or a `===` — exactly the rule that already
+// holds for `ctx.svc.<postgres>.client`.
+//
+// This is the core primitive; the `postgres(...)` component is a thin user of
+// it (its `helpers.client` is `new SQL(url, { label })`). Open one yourself
+// whenever you stand up a database without the component — a Bun-native image
+// like timescaledb/postgis, or a connection string a fake handed back after
+// provisioning a DB at runtime.
+
+import { recordDb, reserveEvent, safeSerialize } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
+
+/**
+ * Minimal structural type for the parts of `Bun.SQL` we use. Declared locally
+ * so user projects don't need `@types/bun` for type-checking to follow the SDK
+ * through to the daemon. The real type comes from Bun at runtime via
+ * `globalThis.Bun.SQL`.
+ */
+interface RawSqlClient {
+  <T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+  unsafe<T = unknown>(text: string, params?: unknown[]): Promise<T[]>;
+  close?(opts?: { timeout?: number }): Promise<void>;
+  end(opts?: { timeout?: number }): Promise<void>;
+}
+
+interface SqlClientBase {
+  close?(opts?: { timeout?: number }): Promise<void>;
+  /** Close the connection / drain the pool (Bun's `SQL.end`). */
+  end(opts?: { timeout?: number }): Promise<void>;
+}
+
+/**
+ * The instrumented SQL surface. Same shape as `Bun.SQL` — callable as a tagged
+ * template (`` sql`SELECT 1` ``) with an `unsafe(text, params?)` escape hatch —
+ * but each query resolves to a **wrapped** row array ({@link Wrapped}): every
+ * settle is recorded as a `db` event and the wrapper carries provenance back to
+ * it. That's why `expect(rows)` / `expect(rows[0]!.id)` link under the query in
+ * the timeline with no cast — and why you `.unwrap()` before feeding a row value
+ * to a real client or a `===`.
+ *
+ * Generic in the row type, so callers name the shape once at the call site
+ * instead of casting: `` await client<TodoRow>`SELECT * FROM todos` `` is
+ * `Promise<Wrapped<TodoRow[]>>`.
+ */
+export interface SqlClient extends SqlClientBase {
+  <T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<Wrapped<T[]>>;
+  unsafe<T = unknown>(text: string, params?: unknown[]): Promise<Wrapped<T[]>>;
+}
+
+/** Options accepted by the {@link SQL} constructor beyond Bun's own. */
+export interface SqlOptions {
+  /**
+   * Label shown on each recorded `db` event (the timeline step's service tag).
+   * Defaults to the connection URL's host — e.g. `db` for
+   * `postgres://…@db:5432/app` — which is usually the service name.
+   */
+  label?: string;
+}
+
+interface BunGlobal {
+  SQL: new (url: string) => RawSqlClient;
+}
+
+interface SqlConstructor {
+  new (url: string, opts?: SqlOptions): SqlClient;
+  (url: string, opts?: SqlOptions): SqlClient;
+}
+
+/**
+ * Open an instrumented SQL client against `url`. Usable with or without `new`
+ * (`new SQL(url)` mirrors `new Bun.SQL(url)`; a constructor that returns an
+ * object yields that object). Requires the Bun runtime — it runs inside the
+ * spectest daemon.
+ */
+export const SQL = function SQL(url: string, opts?: SqlOptions): SqlClient {
+  const bun = (globalThis as { Bun?: BunGlobal }).Bun;
+  if (!bun?.SQL) {
+    throw new Error(
+      "SQL(url) requires the Bun runtime (Bun >= 1.2) — it runs inside the spectest daemon.",
+    );
+  }
+  return instrumentSql(new bun.SQL(url), opts?.label ?? hostLabel(url));
+} as unknown as SqlConstructor;
+
+/** Derive a default event label from a connection URL's host. */
+function hostLabel(url: string): string {
+  try {
+    return new URL(url).hostname || "db";
+  } catch {
+    return "db";
+  }
+}
+
+/**
+ * Proxy a `Bun.SQL` instance so each tagged-template call and each
+ * `unsafe(...)` call emits a `db` event into the active recorder when its
+ * promise settles, and resolves to a {@link Wrapped} result. Other `Bun.SQL`
+ * methods (`.transaction`, `.array`, `.file`, …) pass through unwrapped.
+ *
+ * Exported so a client built some other way (e.g. a pool you already hold) can
+ * opt into the same instrumentation without going through {@link SQL}.
+ */
+export function instrumentSql(raw: RawSqlClient, label: string): SqlClient {
+  const wrapResult = <T>(
+    result: PromiseLike<T>,
+    query: string,
+    params: unknown[],
+  ): Promise<T> => {
+    const started = Date.now();
+    const resv = reserveEvent();
+    return Promise.resolve(result).then(
+      (value) => {
+        const { rows, rowsTruncated, columns } = captureRows(value);
+        const seq = recordDb(
+          {
+            service: label,
+            query,
+            params: params.length > 0 ? params.map(safeSerialize) : undefined,
+            rowCount: rowCountOf(value),
+            rows,
+            rowsTruncated,
+            columns,
+            durationMs: Date.now() - started,
+          },
+          resv,
+        );
+        return wrap(value, seq) as T;
+      },
+      (err) => {
+        const e = err as Error;
+        recordDb(
+          {
+            service: label,
+            query,
+            params: params.length > 0 ? params.map(safeSerialize) : undefined,
+            durationMs: Date.now() - started,
+            error: e?.message ?? String(err),
+          },
+          resv,
+        );
+        throw err;
+      },
+    );
+  };
+
+  const handler: ProxyHandler<RawSqlClient> = {
+    apply(target, thisArg, args) {
+      const [strings, ...values] = args as [TemplateStringsArray, ...unknown[]];
+      const query = reconstructSqlTemplate(strings, values.length);
+      const result = Reflect.apply(
+        target as unknown as (...a: unknown[]) => PromiseLike<unknown>,
+        thisArg,
+        args,
+      );
+      return wrapResult(result, query, values);
+    },
+    get(target, prop, receiver) {
+      if (prop === "unsafe") {
+        return (text: string, params?: unknown[]) => {
+          const result = (
+            target.unsafe as (t: string, p?: unknown[]) => PromiseLike<unknown>
+          ).call(target, text, params);
+          return wrapResult(result, text, params ?? []);
+        };
+      }
+      const v = Reflect.get(target, prop, receiver);
+      return typeof v === "function" ? v.bind(target) : v;
+    },
+  };
+  return new Proxy(raw, handler) as unknown as SqlClient;
+}
+
+/** Rebuild a parameterized SQL string from a tagged-template's pieces.
+ * Bun.SQL substitutes `${value}` for `$1`, `$2`, …; we do the same so
+ * the recorded query matches what the server sees. */
+function reconstructSqlTemplate(
+  strings: TemplateStringsArray,
+  valueCount: number,
+): string {
+  let out = strings[0] ?? "";
+  for (let i = 0; i < valueCount; i++) {
+    out += `$${i + 1}` + (strings[i + 1] ?? "");
+  }
+  return out.trim();
+}
+
+function rowCountOf(value: unknown): number | undefined {
+  if (Array.isArray(value)) return value.length;
+  if (value && typeof value === "object") {
+    const obj = value as { count?: unknown; rowCount?: unknown };
+    if (typeof obj.count === "number") return obj.count;
+    if (typeof obj.rowCount === "number") return obj.rowCount;
+  }
+  return undefined;
+}
+
+const MAX_DB_ROWS = 50;
+
+function captureRows(value: unknown): {
+  rows?: unknown[];
+  rowsTruncated?: boolean;
+  columns?: string[];
+} {
+  if (!Array.isArray(value) || value.length === 0) return {};
+  const slice = value.slice(0, MAX_DB_ROWS).map(safeSerialize);
+  const first = slice[0];
+  const columns =
+    first && typeof first === "object" && !Array.isArray(first)
+      ? Object.keys(first as Record<string, unknown>)
+      : undefined;
+  return {
+    rows: slice,
+    rowsTruncated: value.length > MAX_DB_ROWS ? true : undefined,
+    columns,
+  };
+}