@specific.dev/spectest 0.26.0 → 0.27.0

package/dist/resolver.js

@@ -0,0 +1,309 @@
+// spectest-resolver: a tiny DNS server that mirrors Docker's embedded
+// DNS, but from the VM host instead of from inside a container.
+//
+// Single-label lookups (no dots, e.g. `api`) hit the Docker socket by
+// container name. Multi-label lookups (e.g. `api.stripe.com`) scan
+// containers on `spectest-net` for one whose network aliases include the
+// queried name — set via service `hostnames` in env.ts. Anything we
+// can't resolve from Docker is forwarded to an upstream DNS server
+// (default 1.1.1.1). The daemon and any test code running on the VM
+// host can do `fetch("http://api:8000")` or `fetch("http://api.stripe.com")`
+// exactly like a container on the same bridge would.
+//
+// Designed to be tiny: one process, no caching beyond DNS TTL (5s), no
+// docker event subscription — every query asks Docker fresh. The latency
+// is ~1ms per query and the failure mode (Docker socket down) is rare
+// enough that simplicity wins.
+//
+// Listens on two *specific* addresses (never 0.0.0.0 — see the bind logic
+// at the bottom): 127.0.0.53, the nameserver the VM's /etc/resolv.conf
+// points at (daemon, host-side test code, and dockerd's embedded DNS as
+// its ExtServer all use it), and the spectest-net bridge gateway IP,
+// which is how an in-cluster k3s pod reaches us (k3s CoreDNS is pointed
+// there; see components/k3s.ts). Binding the specific gateway IP rather
+// than 0.0.0.0 matters: a 0.0.0.0 socket replies to a 127.0.0.53 query
+// from a kernel-chosen source (127.0.0.1), and glibc's resolver drops the
+// answer because its source doesn't match the queried server.
+import { createSocket } from "node:dgram";
+import { request as httpRequest } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import * as dnsPacket from "dns-packet";
+const NETWORK_NAME = process.env.SPECTEST_NETWORK ?? "spectest-net";
+const DOCKER_SOCKET = process.env.DOCKER_SOCKET ?? "/var/run/docker.sock";
+const UPSTREAM_DNS = process.env.SPECTEST_UPSTREAM_DNS ?? "1.1.1.1";
+const UPSTREAM_PORT = Number(process.env.SPECTEST_UPSTREAM_PORT ?? "53");
+// Primary listen address: the loopback nameserver in the VM's
+// /etc/resolv.conf. Always bound at startup.
+const LISTEN_ADDR = process.env.SPECTEST_RESOLVER_ADDR ?? "127.0.0.53";
+const LISTEN_PORT = Number(process.env.SPECTEST_RESOLVER_PORT ?? "53");
+const TTL_SECONDS = Number(process.env.SPECTEST_RESOLVER_TTL ?? "5");
+/** Path the spectest-daemon writes when it brings fakes up. */
+const FAKES_REGISTRY_PATH = process.env.SPECTEST_FAKES_REGISTRY ?? "/run/spectest-fakes.json";
+function dockerGet(path) {
+    return new Promise((resolve) => {
+        const req = httpRequest({ socketPath: DOCKER_SOCKET, path, method: "GET" }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+            res.on("error", () => resolve(null));
+        });
+        req.on("error", () => resolve(null));
+        req.end();
+    });
+}
+/**
+ * Single-label lookup: ask Docker for the container with this exact name
+ * and read its IP on spectest-net. Cheap — one container fetch.
+ */
+async function dockerLookupByName(name) {
+    const body = (await dockerGet(`/containers/${encodeURIComponent(name)}/json`));
+    const ip = body?.NetworkSettings?.Networks?.[NETWORK_NAME]?.IPAddress;
+    return ip && ip.length > 0 ? ip : null;
+}
+/**
+ * Multi-label lookup: scan containers on spectest-net for one whose
+ * Aliases include `name`. Aliases are set with `--network-alias` at
+ * `docker run` time (see runContainer in daemon.ts).
+ *
+ * `/containers/json` returns `Aliases: null` in many Docker versions
+ * even when --network-alias was set, so we use it only to enumerate
+ * container IDs and then inspect each one — inspect reliably surfaces
+ * the alias list. The fan-out is bounded by service count (~handful),
+ * so the extra roundtrips are cheap.
+ */
+async function dockerLookupByAlias(name) {
+    const filters = encodeURIComponent(JSON.stringify({ network: [NETWORK_NAME] }));
+    const list = (await dockerGet(`/containers/json?filters=${filters}`));
+    if (!Array.isArray(list))
+        return null;
+    for (const c of list) {
+        if (!c.Id)
+            continue;
+        const info = (await dockerGet(`/containers/${c.Id}/json`));
+        const net = info?.NetworkSettings?.Networks?.[NETWORK_NAME];
+        if (!net)
+            continue;
+        if ((net.Aliases ?? []).includes(name) && net.IPAddress) {
+            return net.IPAddress;
+        }
+    }
+    return null;
+}
+let registryCache = { mtimeMs: 0, hosts: {}, wildcards: [] };
+async function refreshRegistry() {
+    try {
+        const st = await stat(FAKES_REGISTRY_PATH);
+        if (st.mtimeMs !== registryCache.mtimeMs) {
+            const raw = await readFile(FAKES_REGISTRY_PATH, "utf8");
+            const parsed = JSON.parse(raw);
+            registryCache = {
+                mtimeMs: st.mtimeMs,
+                hosts: parsed.hosts ?? {},
+                wildcards: parsed.wildcards ?? [],
+            };
+        }
+    }
+    catch {
+        // File missing or unreadable — treat as empty.
+        registryCache = { mtimeMs: 0, hosts: {}, wildcards: [] };
+    }
+}
+/** Exact names-registry lookup. */
+async function lookupFake(name) {
+    await refreshRegistry();
+    return registryCache.hosts[name] ?? null;
+}
+/** Wildcard suffix lookup — consulted only after an exact miss. The
+ *  longest (most specific) matching suffix wins. */
+async function lookupWildcard(name) {
+    await refreshRegistry();
+    let best = null;
+    for (const w of registryCache.wildcards) {
+        if (name.endsWith(w.suffix) && (!best || w.suffix.length > best.suffix.length)) {
+            best = w;
+        }
+    }
+    return best?.ip ?? null;
+}
+async function forwardUpstream(query) {
+    return new Promise((resolve) => {
+        const sock = createSocket("udp4");
+        let done = false;
+        const finish = (b) => {
+            if (done)
+                return;
+            done = true;
+            try {
+                sock.close();
+            }
+            catch {
+                // ignore
+            }
+            resolve(b);
+        };
+        sock.on("message", (msg) => finish(msg));
+        sock.on("error", () => finish(null));
+        sock.send(query, UPSTREAM_PORT, UPSTREAM_DNS, (err) => {
+            if (err)
+                finish(null);
+        });
+        setTimeout(() => finish(null), 3_000);
+    });
+}
+function emptyAnswer(query) {
+    return dnsPacket.encode({
+        type: "response",
+        id: query.id,
+        flags: dnsPacket.AUTHORITATIVE_ANSWER | dnsPacket.RECURSION_DESIRED,
+        questions: query.questions,
+        answers: [],
+    });
+}
+function aAnswer(query, name, ip) {
+    return dnsPacket.encode({
+        type: "response",
+        id: query.id,
+        flags: dnsPacket.AUTHORITATIVE_ANSWER | dnsPacket.RECURSION_DESIRED,
+        questions: query.questions,
+        answers: [{ type: "A", name, ttl: TTL_SECONDS, data: ip }],
+    });
+}
+// Shared query handler. Replies are sent back through the *same* socket
+// the query arrived on so the reply's source address matches the address
+// the client sent to — which is why each listener is bound to a specific
+// IP rather than 0.0.0.0 (glibc drops answers whose source differs from
+// the queried server).
+async function handleQuery(sock, msg, rinfo) {
+    let query;
+    try {
+        query = dnsPacket.decode(msg);
+    }
+    catch {
+        return;
+    }
+    const q = query.questions?.[0];
+    if (q && (q.type === "A" || q.type === "AAAA")) {
+        const name = q.name.toLowerCase();
+        const isSingleLabel = !name.includes(".");
+        // Fakes win over docker — they're explicitly registered by the
+        // daemon and a fake's hostname (e.g. api.stripe.com) might collide
+        // with a real upstream we don't want to call.
+        const fakeIp = isSingleLabel ? null : await lookupFake(name);
+        const ip = fakeIp
+            ?? (isSingleLabel
+                ? await dockerLookupByName(name)
+                : await dockerLookupByAlias(name));
+        if (ip) {
+            // For AAAA we still answer empty — Docker bridges are IPv4 only, but
+            // we own this name so libc should fall back to A instead of chasing
+            // a stray upstream AAAA for the real public hostname.
+            const resp = q.type === "A" ? aAnswer(query, q.name, ip) : emptyAnswer(query);
+            sock.send(resp, rinfo.port, rinfo.address);
+            return;
+        }
+        if (isSingleLabel) {
+            // Bare hostname we don't own — reply NOERROR with no answers so the
+            // resolver moves on quickly. Forwarding bare hostnames upstream just
+            // causes timeouts.
+            sock.send(emptyAnswer(query), rinfo.port, rinfo.address);
+            return;
+        }
+        // Multi-label exact miss: try wildcard suffixes (e.g. *.example.com
+        // → the k3s cluster) before forwarding upstream. Exact lookups above
+        // always win, so a specific alias beats a covering wildcard.
+        const wildIp = await lookupWildcard(name);
+        if (wildIp) {
+            const resp = q.type === "A" ? aAnswer(query, q.name, wildIp) : emptyAnswer(query);
+            sock.send(resp, rinfo.port, rinfo.address);
+            return;
+        }
+        // Still nothing — fall through and forward to upstream below.
+    }
+    // Anything we don't own — forward.
+    const upstream = await forwardUpstream(msg);
+    if (upstream) {
+        sock.send(upstream, rinfo.port, rinfo.address);
+        return;
+    }
+    // Upstream unreachable; return SERVFAIL (rcode 2 in low 4 bits of flags).
+    const resp = dnsPacket.encode({
+        type: "response",
+        id: query.id,
+        flags: dnsPacket.RECURSION_DESIRED | 0x2,
+        questions: query.questions ?? [],
+    });
+    sock.send(resp, rinfo.port, rinfo.address);
+}
+/** Bind one UDP listener on `addr`, wired to the shared handler. A bind
+ * error on the primary loopback address is fatal (DNS is fully down);
+ * on the secondary bridge address it's logged and retried by the caller. */
+function bindListener(addr, fatalOnError) {
+    return new Promise((resolve) => {
+        const sock = createSocket("udp4");
+        sock.on("message", (msg, rinfo) => {
+            void handleQuery(sock, msg, rinfo);
+        });
+        sock.on("error", (err) => {
+            // eslint-disable-next-line no-console
+            console.error(`[spectest-resolver] socket error on ${addr}:`, err);
+            if (fatalOnError)
+                process.exit(1);
+            try {
+                sock.close();
+            }
+            catch {
+                // ignore
+            }
+            resolve(false);
+        });
+        sock.bind(LISTEN_PORT, addr, () => {
+            // eslint-disable-next-line no-console
+            console.log(`[spectest-resolver] listening on ${addr}:${LISTEN_PORT} (network=${NETWORK_NAME}, upstream=${UPSTREAM_DNS}:${UPSTREAM_PORT})`);
+            resolve(true);
+        });
+    });
+}
+/** Read the spectest-net bridge gateway IP from Docker — the address an
+ * in-cluster k3s pod (or any off-bridge client routed through the node)
+ * uses to reach the VM host. Null until the network exists. */
+async function bridgeGatewayIp() {
+    const net = (await dockerGet(`/networks/${encodeURIComponent(NETWORK_NAME)}`));
+    const gw = net?.IPAM?.Config?.find((c) => c.Gateway)?.Gateway;
+    return gw && gw.length > 0 ? gw : null;
+}
+// Primary listener: the loopback nameserver. Fatal if it can't bind.
+void bindListener(LISTEN_ADDR, true);
+// Secondary listener: the spectest-net bridge gateway, for k3s pods.
+// The network is created by the daemon at /load — after this process
+// starts and after it's captured into the base snapshot — so poll until
+// the gateway appears, bind once, then stop. The gateway is stable for a
+// VM's life (the daemon only creates the network when it's missing), so a
+// single successful bind survives snapshot/restore/fork. Opt out with
+// SPECTEST_RESOLVER_NO_BRIDGE=1.
+if (process.env.SPECTEST_RESOLVER_NO_BRIDGE !== "1") {
+    let bound = false;
+    const poll = setInterval(async () => {
+        if (bound)
+            return;
+        const gw = await bridgeGatewayIp().catch(() => null);
+        if (!gw)
+            return;
+        bound = true;
+        if (!(await bindListener(gw, false)))
+            bound = false; // retry on failure
+    }, 2_000);
+    // Don't keep the event loop alive solely for the poll timer.
+    poll.unref?.();
+}

package/dist/s3.d.ts

@@ -0,0 +1,89 @@
+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 `S3Options`,
+ *  passed through to `Bun.S3Client` verbatim. */
+export interface S3ClientOptions {
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    sessionToken?: string;
+    bucket?: string;
+    region?: string;
+    endpoint?: string;
+    [opt: string]: unknown;
+}
+interface S3Constructor {
+    new (options?: S3ClientOptions): S3ClientLike;
+    (options?: S3ClientOptions): S3ClientLike;
+}
+/**
+ * Open an instrumented S3 client. Usable with or without `new`. Requires the
+ * Bun runtime — it runs inside the spectest daemon.
+ */
+export declare const S3Client: S3Constructor;
+/**
+ * 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 declare function instrumentS3(raw: RawS3Client, bucket?: string): S3ClientLike;
+export {};

package/dist/s3.js

@@ -0,0 +1,198 @@
+// `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";
+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) {
+    const bun = globalThis.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);
+};
+/** Record an awaitable S3 op, wrapping its settled result for provenance. */
+function runS3(base, invoke, describe) {
+    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);
+    }, (err) => {
+        const e = err;
+        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(base, invoke) {
+    const started = Date.now();
+    try {
+        const value = invoke();
+        recordS3({ ...base, durationMs: Date.now() - started }, undefined);
+        return value;
+    }
+    catch (err) {
+        const e = err;
+        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, bucket) {
+    const handler = {
+        get(target, prop, receiver) {
+            if (typeof prop !== "string")
+                return Reflect.get(target, prop, receiver);
+            switch (prop) {
+                case "file":
+                    return (path, options) => instrumentS3File(target.file(path, options), path, bucket);
+                case "write":
+                    return (path, data, options) => runS3({ op: "write", bucket, key: path }, () => target.write(path, data, options), () => describeData(data));
+                case "delete":
+                case "unlink":
+                    return (path, options) => runS3({ op: "delete", bucket, key: path }, () => target.delete(path, options));
+                case "exists":
+                    return (path, options) => runS3({ op: "exists", bucket, key: path }, () => target.exists(path, options));
+                case "size":
+                    return (path, options) => runS3({ op: "stat", bucket, key: path }, () => target.size(path, options), (n) => ({
+                        size: typeof n === "number" ? n : undefined,
+                    }));
+                case "stat":
+                    return (path, options) => runS3({ op: "stat", bucket, key: path }, () => target.stat(path, options), describeStat);
+                case "list":
+                    return (input, options) => runS3({ op: "list", bucket }, () => target.list(input, options), (r) => ({
+                        count: listCount(r),
+                    }));
+                case "presign":
+                    return (path, options) => runS3Sync({ op: "presign", bucket, key: path }, () => target.presign(path, options));
+                default: {
+                    const v = Reflect.get(target, prop, receiver);
+                    return typeof v === "function" ? v.bind(target) : v;
+                }
+            }
+        },
+    };
+    return new Proxy(raw, handler);
+}
+function instrumentS3File(raw, key, bucket) {
+    const b = raw.bucket ?? bucket;
+    const handler = {
+        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, options) => 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) => runS3Sync({ op: "presign", bucket: b, key }, () => target.presign(options));
+                default: {
+                    const v = Reflect.get(target, prop, receiver);
+                    return typeof v === "function" ? v.bind(target) : v;
+                }
+            }
+        },
+    };
+    return new Proxy(raw, handler);
+}
+/** Byte size + small text preview of a written/read body. */
+function describeData(value) {
+    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) {
+    if (stat && typeof stat === "object") {
+        const s = stat;
+        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) {
+    if (result && typeof result === "object") {
+        const r = result;
+        if (Array.isArray(r.contents))
+            return r.contents.length;
+        if (typeof r.keyCount === "number")
+            return r.keyCount;
+    }
+    return undefined;
+}
+function isBinary(value) {
+    return (value instanceof ArrayBuffer ||
+        ArrayBuffer.isView(value) ||
+        (typeof Blob !== "undefined" && value instanceof Blob));
+}
+function byteLength(value) {
+    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/dist/sql.d.ts

@@ -0,0 +1,74 @@
+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 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 declare const SQL: SqlConstructor;
+/**
+ * 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 declare function instrumentSql(raw: RawSqlClient, label: string): SqlClient;
+export {};