@specific.dev/spectest 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.9.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

@@ -26,13 +26,24 @@ import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 // `field` — a provenance-preserving, null-safe selector: a `null`/`undefined`
 // leaf read off a wrapped op result is raw and untagged, so an `expect(...)` on
 // it renders detached from its source op; `field` tags from the container so the
-// assertion still nests. (Base64-decoded values lose provenance the same way;
-// that case is the `.base64Decoded()` provenance transform on `expect(...)`.)
+// assertion still nests. (A decoded value loses provenance the same way — that
+// case is the `.transform(label, fn)` method every wrapped value carries, which
+// runs the still-tagged value through `fn` and re-wraps the result.)
 // To recover a raw value, call `.unwrap()` on it — spectest op results are
 // always wrapped (in every context), so the method is always there; there is no
 // `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
 export { field } from "./inspect.js";
 
+// 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,
@@ -1344,52 +1355,7 @@ interface Matchers {
   toHaveLength(n: number): void;
 }
 
-/**
- * Provenance-preserving transforms. Each returns a fresh {@link Expectation}
- * bound to the *decoded* value but still carrying the originating op's tag (its
- * path extended by a marker like `<base64>`), so the eventual assertion nests
- * under the source read in the timeline. This is what lets a value that must be
- * decoded through a plain function — `Buffer.from(x,"base64").toString()`,
- * `decodeURIComponent(x)` — be asserted on with the *full* matcher vocabulary
- * (`toHaveLength`, `toContain`, `toMatch`, …) without dropping to `expectRaw`,
- * which severs the link. Transforms chain (`.base64Decoded().urlDecoded()`),
- * and the matcher you finish with may be negated (`.base64Decoded().not.…`).
- *
- * They supersede the old `toBeBase64Of` matcher, which was equality-only:
- * `expect(secret.data?.X).base64Decoded().toBe("plain")` is the direct
- * replacement, and `.toHaveLength(32)` / `.toContain("redis://")` / `.toMatch(re)`
- * are the cases it couldn't express.
- */
-interface Transforms {
-  /** Interpret the value as a base64 string and decode it (UTF-8), mirroring
-   *  `Buffer.from(x, "base64").toString()`. Throws-as-failed-assertion if the
-   *  value isn't a string. */
-  base64Decoded(): Expectation;
-  /** URL-decode the value, mirroring `decodeURIComponent(x)`. Chains after
-   *  `base64Decoded()` for base64-then-URL-encoded values. */
-  urlDecoded(): Expectation;
-  /** Parse the value as JSON (`JSON.parse(x)`) and assert on the result with the
-   *  full matcher vocabulary — `toEqual` against the decoded object/array,
-   *  `toContain`/`toHaveLength` against a decoded array. Throws-as-failed-assertion
-   *  if the value isn't a string or isn't valid JSON. Chains after other
-   *  transforms (e.g. `base64Decoded().jsonDecoded()` for a base64-wrapped JSON
-   *  payload). The optional type parameter `T` annotates the decoded shape at the
-   *  call site (`jsonDecoded<User>()`) — it casts the parsed value, but, like the
-   *  matchers, is not enforced at runtime. */
-  jsonDecoded<T = unknown>(): Expectation;
-  /**
-   * Generic escape hatch: apply an arbitrary `fn` to the raw value and assert on
-   * the result, keeping provenance. `label` is a plain word (`"json"`,
-   * `"decompressed"`) appended to the op path so the timeline shows what was
-   * derived; the UI brackets it (`<json>`) to mark it as a derived step, so do
-   * **not** include the brackets yourself. Sugar like {@link base64Decoded} is
-   * built on this. If `fn` throws, the next assertion records as a failure
-   * describing the transform error.
-   */
-  transform(label: string, fn: (value: unknown) => unknown): Expectation;
-}
-
-export interface Expectation extends Matchers, Transforms {
+export interface Expectation extends Matchers {
   not: Matchers;
 }
 
@@ -1495,31 +1461,6 @@ function buildCore(
     });
     if (!passed) throw new ExpectationError(msg);
   };
-  // Apply `fn` to the raw value and rebuild against the result, extending the
-  // op path by a derived-step marker so the decoded value still nests under the
-  // source read. `label` is a plain word ("base64", "json"); the `<…>` marker
-  // syntax that distinguishes a transform from a real property read in the
-  // timeline is added here, so it lives in one place and never leaks into the
-  // API surface — the same convention `inspect.ts` uses for array methods
-  // (`<find>`, `<map>`). A throw becomes a `pendingError` on the returned
-  // Expectation rather than escaping — a malformed decode renders as a failed
-  // assertion in the timeline, not an unhandled exception. Propagates an
-  // existing `pendingError` untouched.
-  const applyTransform = (label: string, fn: (value: unknown) => unknown): Expectation => {
-    const marker = `<${label}>`;
-    const nextTag: OpTag | undefined = tag
-      ? { sourceSeq: tag.sourceSeq, path: [...tag.path, marker] }
-      : undefined;
-    if (pendingError !== undefined) {
-      return buildCore(undefined, nextTag, false, message, pendingError);
-    }
-    try {
-      return buildCore(fn(actual), nextTag, false, message);
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      return buildCore(undefined, nextTag, false, message, `${marker}: ${detail}`);
-    }
-  };
   return {
     toBe(expected) {
       const exp = readRaw(expected);
@@ -1628,25 +1569,6 @@ function buildCore(
         { actual: len, pathSuffix: "length" },
       );
     },
-    transform(label, fn) {
-      return applyTransform(label, fn);
-    },
-    base64Decoded() {
-      return applyTransform("base64", (v) => {
-        if (typeof v !== "string") {
-          throw new Error(`base64Decoded expects a string, got ${typeof v}`);
-        }
-        return Buffer.from(v, "base64").toString();
-      });
-    },
-    urlDecoded() {
-      return applyTransform("urldecode", (v) => {
-        if (typeof v !== "string") {
-          throw new Error(`urlDecoded expects a string, got ${typeof v}`);
-        }
-        return decodeURIComponent(v);
-      });
-    },
     get not(): Matchers {
       // Re-pass the already-unwrapped value, tag and message so the tag and raw
       // label are preserved for the negated branch's AssertionEvent.

package/src/inspect.ts

@@ -248,6 +248,12 @@ function wrapObject<T extends object>(
           return () => readRaw(target);
         }
       }
+      // `.transform(label, fn)` — same shape/guard as `unwrap`: only intercept
+      // when the underlying object has no own `transform`, so a real data field
+      // named `transform` is never shadowed.
+      if (prop === "transform" && !(prop in (target as object))) {
+        return makeTransform(readRaw(target), sourceSeq, path);
+      }
       // Hide thenable-ness from `await`. We must never accidentally
       // implement `then`, or `await fetch(...)` would resolve to the
       // wrong thing if we ever wrapped a Promise (we don't, but be safe).
@@ -298,6 +304,34 @@ function wrapObject<T extends object>(
   return new Proxy(raw, handler);
 }
 
+// The `.transform(label, fn)` method every wrapper (carrier + object/array
+// proxy) carries — the value-level analogue of `.unwrap()`. It runs the raw
+// value through `fn` and re-`wrap`s the result with `path` extended by a
+// `<label>` derived-step marker, so the decoded value keeps the source op's
+// provenance (`sourceSeq`) and stays navigable: a later `expect(...)` on it, or
+// on a subfield, still nests under the originating op (`secret.data.config.<json>.tier`).
+// `label` is a plain word; the `<…>` brackets are added here so they never leak
+// into the call site (the same convention array methods use, `<find>`/`<map>`).
+// A throw in `fn` (a non-string value, malformed base64/JSON) is rethrown
+// prefixed with `<label>:`, failing the test at the bad value.
+function makeTransform(
+  raw: unknown,
+  sourceSeq: number | undefined,
+  path: readonly string[],
+): (label: string, fn: (raw: never) => unknown) => unknown {
+  return (label, fn) => {
+    const nextPath = [...path, `<${label}>`];
+    let result: unknown;
+    try {
+      result = (fn as (r: unknown) => unknown)(raw);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`<${label}>: ${detail}`);
+    }
+    return wrap(result, sourceSeq, nextPath);
+  };
+}
+
 // Runtime shape of a primitive carrier: the public `Carrier<T>` surface
 // (`unwrap()`) plus the internal provenance symbols. Kept private so the
 // exported `Carrier<T>` stays clean.
@@ -316,6 +350,7 @@ function makeCarrier<T>(
     [OP_TAG]: tag,
     [UNWRAP]: raw,
     unwrap: () => raw,
+    transform: makeTransform(raw, sourceSeq, path) as unknown as Carrier<T>["transform"],
     // Coercion sinks recover the raw primitive instead of inheriting
     // Object.prototype's defaults ("[object Object]" / NaN / {}). A
     // carrier interpolated into a string, fed to arithmetic, `==`, or
@@ -338,10 +373,10 @@ function makeCarrier<T>(
 // passes them through raw. So `expect(row.deleted_at).toBe(null)` reaches
 // `expect()` as a bare `null` with no tag and renders as a disconnected
 // top-level row. `field` recovers the link by tagging from the *container*.
-// (Base64-decoded values lose their tag the same way, via the transform; that
-// case is handled by the `.base64Decoded()` provenance transform in index.ts,
-// which decodes the still-tagged value internally and rebuilds the Expectation
-// against the result.)
+// (A decoded value loses its tag the same way, through the decode; the
+// `.transform(label, fn)` method every wrapper carries (see `makeTransform`)
+// recovers it — it runs the still-tagged value through `fn` and re-`wrap`s the
+// result with the source path extended by a `<label>` marker.)
 // ───────────────────────────────────────────────────────────────────────────
 
 /**
@@ -410,6 +445,22 @@ export function field(value: unknown, ...path: Array<string | number>): unknown
 export interface Carrier<T> {
   /** Recover the raw underlying value. */
   unwrap(): T;
+  /**
+   * Run the raw value through `fn` and get back a provenance-carrying handle to
+   * the result — for asserting on a *decoded* value (base64, JSON, JWT, …) while
+   * keeping its link to the op that produced it. The op path is extended by a
+   * `<label>` marker, so a later `expect(...)` on the result still nests under
+   * the source op. `label` is a plain word (`"base64"`, `"json"`); the UI adds
+   * the `<…>` brackets, so don't include them yourself. `fn` receives the raw
+   * value (typed `T`), so no cast is needed. `R` types the result. A throw in
+   * `fn` is rethrown prefixed with `<label>:`, failing the test at the value.
+   *
+   * ```ts
+   * expect(secret.data.url.transform("base64", (s) => Buffer.from(s, "base64").toString()))
+   *   .toContain("redis://");
+   * ```
+   */
+  transform<R = unknown>(label: string, fn: (raw: T) => R): Wrapped<R>;
   /** Coerces to the raw value (arithmetic, `==`). */
   valueOf(): T;
   /** Renders the raw value (template interpolation). */
@@ -475,6 +526,9 @@ export type WrappedObject<T> = {
 } & {
   /** Recover the fully raw value (nested leaves unwrapped too). */
   unwrap(): T;
+  /** Run the raw object through `fn`, keeping provenance (op path + `<label>`),
+   *  and get back a navigable handle to the result. See {@link Carrier.transform}. */
+  transform<R = unknown>(label: string, fn: (raw: T) => R): Wrapped<R>;
 };
 
 /**
@@ -491,6 +545,9 @@ export interface WrappedArray<U> {
   readonly [index: number]: Wrapped<U>;
   /** Recover the raw array (elements unwrapped). */
   unwrap(): U[];
+  /** Run the raw array through `fn`, keeping provenance (op path + `<label>`),
+   *  and get back a navigable handle to the result. See {@link Carrier.transform}. */
+  transform<R = unknown>(label: string, fn: (raw: U[]) => R): Wrapped<R>;
   at(index: number): Wrapped<U> | undefined;
   find(
     predicate: (value: U, index: number, obj: U[]) => unknown,