@specific.dev/spectest 0.39.0 → 0.43.0

package/src/inspect.ts

@@ -0,0 +1,739 @@
+// Provenance wrappers for op return values.
+//
+// When a tracked op (fetch, db query, browser.evaluate) records its
+// event, it wraps its return value via `wrap(value, sourceSeq)`. The
+// wrapper carries an `OP_TAG` describing which op produced it and the
+// access path within that op's payload. When the wrapped value reaches
+// `expect()`, the matcher reads the tag and attaches `sourceSeq` + `path`
+// to its AssertionEvent so the UI can nest the assertion under its
+// originating op.
+//
+// Two shapes of wrapper:
+//   - Objects/arrays: lazy `Proxy`. Reading a property returns a fresh
+//     wrapped child with the path extended. Structural shape stays raw:
+//     an array's `length` is a real number (provenance belongs on the
+//     data, not the container's size — `rows.length === 1` must work).
+//   - Primitives: a small `Carrier` object holding the value and tag.
+//     Coercion sinks (`valueOf`/`toString`/`toJSON`/`Symbol.toPrimitive`)
+//     recover the raw primitive, so template interpolation, arithmetic,
+//     loose equality, and `JSON.stringify` all behave. The one remaining
+//     sharp edge is strict `===` against a primitive (always false — an
+//     object can never `===` a number); `.unwrap()` first, and the
+//     `Carrier<T>` typing makes that a compile-time error in TS.
+//
+// Cannot tag: `null` / `undefined` (no place to attach a symbol) and
+// functions (we don't currently need to). Those pass through as-is — but a
+// nullish *leaf read* off a proxy is recorded in the pending-nullish register
+// below so `expect()` can still recover its provenance (see `adoptNullishTag`).
+//
+// Escape: every wrapper exposes `.unwrap()` returning the fully raw value (it
+// walks every wrapper layer, so one call always reaches raw). That is the
+// public escape hatch; there is no `unwrap(x)` free function — a spectest op
+// result is always wrapped (see below), so the value always has `.unwrap()`.
+// (`readRaw` is the internal, never-throws primitive `.unwrap()` and `expect()`
+// are built on; it isn't part of the public surface.)
+//
+// Wrapping is UNCONDITIONAL: a spectest op (fetch/exec/terminal/poll/db/
+// browser.evaluate) always returns a wrapped value, in every context — a test,
+// a `ctx.poll` predicate, `setup`, `eval`, a fake handler. Whether the op also
+// recorded a timeline *event* is a separate decision (the recorder may be
+// absent, paused, or have truncated the event): when there is no event the
+// wrapper simply carries no provenance (`sourceSeq: undefined`), so `expect()`
+// can't nest it under an op — but the wrapper SHAPE (`.unwrap()`, coercion
+// sinks, the proxy) is always present. That keeps `Wrapped`/`WrappedResponse`/
+// `Carrier<T>` honest at runtime everywhere, instead of silently collapsing to
+// a raw value wherever recording happened to be off.
+
+// Registered in the GLOBAL symbol registry (`Symbol.for`), not module-private
+// (`Symbol`), so a value tagged by ONE copy of this module unwraps correctly in
+// ANOTHER. This matters whenever two copies of the SDK load in the same runtime:
+// the in-VM daemon runs the baked SDK at /opt/spectest/sdk and mints the
+// provenance carriers (ctx.fetch / ctx.browser / db results), while a user's
+// test file resolving `@specific.dev/spectest` to a registry-pinned copy gets
+// its `expect`. With module-private symbols the two `UNWRAP`s differed, so
+// `expect`'s auto-unwrap silently no-op'd and wrapped assertions failed
+// nonsensically (`expect("Hello Spec").toContain("Hello")` -> false). The
+// control plane also repoints the dep at the baked copy so normally only one
+// copy loads; this is defense-in-depth for the cases where it can't (and only
+// takes full effect once both copies ship this `Symbol.for`).
+export const OP_TAG = Symbol.for("spectest.opTag");
+export const UNWRAP = Symbol.for("spectest.unwrap");
+
+// The escape hatch from a wrapped value to its raw form is the `.unwrap()`
+// method that lives on the `Carrier` / `WrappedObject` / `WrappedArray` /
+// `WrappedResponse` types. We deliberately do NOT augment the global
+// `Number`/`String`/`Boolean`/`Object` prototypes with a phantom `unwrap()`:
+// that made `.unwrap()` typecheck on *every* value, including a genuinely raw
+// primitive (a third-party return, or a plain `fetch` the project code calls
+// itself), where `.unwrap()` would compile but throw at runtime. Without the
+// phantom, `.unwrap()` only typechecks on a value whose static type is one of
+// the wrapper types — and because spectest ops now wrap unconditionally (see
+// above), those static types are honest at runtime in every context. A value
+// that is raw *and* typed raw (it came from outside a spectest op) neither
+// needs nor offers `.unwrap()` — use it directly.
+
+export interface OpTag {
+  /** Seq of the timeline event this value came from, or `undefined` when the
+   *  value was wrapped without a recorded event (no recorder, paused, or the
+   *  event was truncated). `expect()` only nests under a defined `sourceSeq`. */
+  sourceSeq: number | undefined;
+  path: readonly string[];
+}
+
+/** Read the tag if present; returns undefined for raw values. */
+export function readTag(x: unknown): OpTag | undefined {
+  if (x === null || x === undefined) return undefined;
+  if (typeof x !== "object" && typeof x !== "function") return undefined;
+  return (x as { [OP_TAG]?: OpTag })[OP_TAG];
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Pending nullish-leaf register
+//
+// Reading a `null`/`undefined` leaf off a wrapped object (`dep.status.readyReplicas`
+// on a failed deployment) hands back a raw nullish value with no tag — a symbol
+// can't ride on `null`/`undefined`, and minting a stand-in object would break
+// every `=== null` / `if (!x)` in real code (see `wrap`). So the natural
+// `expect(dep.status.readyReplicas).toBeFalsy()` used to lose its provenance and
+// render as a disconnected top-level assertion, even though `field(...)` could
+// recover it manually.
+//
+// To make the natural form work too, the proxy *notes* every nullish leaf read
+// here (source op + access path). `expect()` consults the register when it
+// receives an untagged nullish value via `adoptNullishTag`, matching the most
+// recent note. The note is single-consume, freshest-wins, and invalidated by
+// any subsequent recorded op (the recorder calls `clearPendingNullish`), so the
+// window for misattribution is one untagged nullish read immediately followed by
+// an `expect` of an unrelated nullish literal with no op in between — narrow,
+// and the worst case points at a contextually-adjacent field rather than losing
+// the link entirely. The note never reaches program control flow: it is read
+// only inside `expect()`, which `readRaw`s back to the real nullish value.
+// ───────────────────────────────────────────────────────────────────────────
+
+let pendingNullish: { value: null | undefined; tag: OpTag } | undefined;
+
+function noteNullishLeaf(
+  value: null | undefined,
+  sourceSeq: number | undefined,
+  path: readonly string[],
+): void {
+  pendingNullish = { value, tag: { sourceSeq, path: [...path] } };
+}
+
+/** Forget any pending nullish-leaf note. Called by the recorder whenever a new
+ *  op is recorded, so a note can't outlive the read that produced it. */
+export function clearPendingNullish(): void {
+  pendingNullish = undefined;
+}
+
+/**
+ * If `value` is an untagged `null`/`undefined` that matches the most recent
+ * nullish-leaf read, mint a tagged {@link makeCarrier} holder for it (the same
+ * stand-in `field`/`retag` use) and clear the note; otherwise return `value`
+ * unchanged. The holder is safe because it goes straight to `expect()`, which
+ * `readRaw`s it before matching — it never escapes into control flow.
+ */
+export function adoptNullishTag<T>(value: T): T {
+  if (value !== null && value !== undefined) return value;
+  const p = pendingNullish;
+  if (!p || !Object.is(p.value, value)) return value;
+  pendingNullish = undefined;
+  return makeCarrier(value, p.tag.sourceSeq, p.tag.path) as unknown as T;
+}
+
+/** If x is wrapped, return the raw value; otherwise return x. */
+export function readRaw<T>(x: T): T {
+  // Walks the chain — a value can carry more than one wrapper at once
+  // (e.g. a polled k8s pod is wrapped by the component's `withTagging`
+  // with the HTTP seq, then by `ctx.poll`'s `wrap(...)` with the wait
+  // seq). A single-step unwrap would still hand callers a proxy.
+  let cur: unknown = x;
+  while (cur !== null && cur !== undefined) {
+    const t = typeof cur;
+    if (t !== "object" && t !== "function") return cur as T;
+    // Presence check, NOT `next === undefined`: a carrier minted by `field`
+    // may wrap `undefined` itself (`[UNWRAP] = undefined`). Testing the value
+    // would mistake that for "no wrapper" and hand the carrier object back, so
+    // a `toBeFalsy()` would see a truthy object.
+    if (!(UNWRAP in (cur as object))) return cur as T;
+    const next = (cur as { [UNWRAP]?: unknown })[UNWRAP];
+    if (next === cur) return cur as T;
+    cur = next;
+  }
+  return cur as T;
+}
+
+/**
+ * Strip provenance wrappers from a value AND from anything nested inside a
+ * plain object/array it holds. The inbound counterpart of {@link wrap}: for
+ * values crossing *back* into code that expects raw data — a fake's `helpers`,
+ * a k8s client method's arguments. Without it a helper that takes a value some
+ * earlier op produced gets a `Carrier`/proxy, and the first `.matchAll(...)` /
+ * typed-client call inside it throws a `TypeError` from deep in the callee,
+ * far from the call site that passed the wrapper. Coercion sinks
+ * ({@link makeCarrier}) rescue only the interpolation cases; a callee that
+ * calls a method on the value, or checks its `typeof`, still sees an object.
+ *
+ * One {@link readRaw} finishes a wrapped value: a wrapper's target is raw all
+ * the way down (the proxy wraps children lazily, on read), so there is nothing
+ * left to walk underneath it. The recursion is for the other shape — a
+ * container the *caller* built around wrapped leaves: `{ to: msg.to }`,
+ * `[row.id, row.email]`.
+ *
+ * Rebuilds only what changed, and only plain objects/arrays: a `Date`,
+ * `Buffer`, `Map`, `Response` or class instance is returned untouched rather
+ * than flattened into a plain object. Cyclic containers are left in place at
+ * the point the cycle closes.
+ */
+export function deepUnwrap<T>(value: T): T {
+  return deepUnwrapInner(value, new Set()) as T;
+}
+
+function deepUnwrapInner(value: unknown, seen: Set<object>): unknown {
+  if (value === null || value === undefined) return value;
+  const raw = readRaw(value);
+  // It was wrapped, so it's now fully raw — and recursing into it would be
+  // wrong anyway (the raw form may be an exotic object we must not rebuild).
+  if (raw !== value) return raw;
+  if (typeof raw !== "object") return raw;
+  const obj = raw as object;
+  if (seen.has(obj)) return obj;
+  if (Array.isArray(obj)) {
+    seen.add(obj);
+    let changed = false;
+    const out = obj.map((el) => {
+      const next = deepUnwrapInner(el, seen);
+      if (next !== el) changed = true;
+      return next;
+    });
+    seen.delete(obj);
+    return changed ? out : obj;
+  }
+  const proto = Object.getPrototypeOf(obj);
+  if (proto !== Object.prototype && proto !== null) return obj;
+  seen.add(obj);
+  let changed = false;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+    const next = deepUnwrapInner(v, seen);
+    if (next !== v) changed = true;
+    out[k] = next;
+  }
+  seen.delete(obj);
+  return changed ? out : obj;
+}
+
+/** The raw type behind a wrapper: a `Carrier`/`WrappedObject`/`WrappedArray`/
+ *  `WrappedResponse` resolves to its `unwrap()` return type; anything else is
+ *  already raw and passes through unchanged. */
+export type Unwrap<T> = T extends { unwrap(): infer V } ? V : T;
+
+/**
+ * Wrap a value so reads through it carry an `OpTag`. Recursion is lazy:
+ * a property read on an object Proxy wraps its child on demand.
+ */
+export function wrap<T>(
+  raw: T,
+  sourceSeq: number | undefined,
+  path: readonly string[] = [],
+): T {
+  if (raw === null || raw === undefined) return raw;
+  const t = typeof raw;
+  if (t === "object") {
+    return wrapObject(raw as object, sourceSeq, path) as unknown as T;
+  }
+  if (t === "function") return raw;
+  // primitive
+  return makeCarrier(raw, sourceSeq, path) as unknown as T;
+}
+
+/**
+ * Like {@link wrap}, but for values read *through* a wrapped container, where a
+ * `null`/`undefined` leaf must still leave a provenance trail. `wrap` passes
+ * nullish through raw (a symbol can't ride on it); here we additionally
+ * {@link noteNullishLeaf note} the read so `expect()` can adopt the tag via
+ * {@link adoptNullishTag}. The returned value is identical to `wrap`'s — raw
+ * nullish or a proxy/carrier — so control flow is unaffected.
+ */
+function wrapChild<T>(value: T, sourceSeq: number | undefined, path: readonly string[]): T {
+  if (value === null || value === undefined) {
+    noteNullishLeaf(value as null | undefined, sourceSeq, path);
+    return value;
+  }
+  return wrap(value, sourceSeq, path);
+}
+
+// Array methods whose return value derives from the array's contents.
+// We re-wrap their results so assertions on `arr.find(...)` etc. still
+// fold under the originating op. Predicates still see raw items (the
+// method runs on the raw target), so `===` comparisons keep working.
+const ARRAY_TAGGED_METHODS = new Set([
+  "find",
+  "findLast",
+  "at",
+  "map",
+  "filter",
+  "slice",
+  "flat",
+  "flatMap",
+  "concat",
+  "includes",
+  "indexOf",
+  "lastIndexOf",
+  "findIndex",
+  "findLastIndex",
+  "some",
+  "every",
+]);
+
+function wrapObject<T extends object>(
+  raw: T,
+  sourceSeq: number | undefined,
+  path: readonly string[],
+): T {
+  const tag: OpTag = { sourceSeq, path };
+  const isArray = Array.isArray(raw);
+  const handler: ProxyHandler<T> = {
+    get(target, prop, receiver) {
+      if (prop === OP_TAG) return tag;
+      if (prop === UNWRAP) return target;
+      if (prop === "unwrap") {
+        // Only intercept when the underlying object doesn't already have
+        // its own `unwrap` — otherwise we'd shadow a legitimate property.
+        // `readRaw` (not a bare `target`) so a value carrying more than one
+        // wrapper — e.g. a `ctx.poll` result whose inner value was already
+        // tagged by a component's `withTagging` — unwraps all the way to raw
+        // in one call, not just one layer.
+        if (!(prop in (target as 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).
+      if (prop === "then" && !(prop in (target as object))) return undefined;
+
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof prop === "symbol") {
+        // Symbols (iterator, toPrimitive, etc.) — pass through bound.
+        return typeof value === "function"
+          ? (value as (...a: unknown[]) => unknown).bind(target)
+          : value;
+      }
+      // Container shape stays raw: `rows.length === 1` must be a plain
+      // number comparison, not carrier-vs-number (silently false).
+      // Provenance for "how many" assertions still works — `expect`
+      // accepts raw values, it just won't nest under the op.
+      if (isArray && prop === "length") return value;
+      const childPath = path.concat(String(prop));
+      if (typeof value === "function") {
+        if (isArray && ARRAY_TAGGED_METHODS.has(prop)) {
+          const method = value as (...a: unknown[]) => unknown;
+          const taggedPath = path.concat(`<${prop}>`);
+          return (...args: unknown[]) => {
+            const result = method.apply(target, args);
+            return wrapChild(result, sourceSeq, taggedPath);
+          };
+        }
+        // Other methods stay bound to the raw target; their return
+        // values aren't wrapped here — call sites that need
+        // promise-returning methods (e.g. Response.json()) install a
+        // bespoke wrapper.
+        return (value as (...a: unknown[]) => unknown).bind(target);
+      }
+      return wrapChild(value, sourceSeq, childPath);
+    },
+    has(target, prop) {
+      if (prop === OP_TAG || prop === UNWRAP) return true;
+      return Reflect.has(target, prop);
+    },
+    // Block writes; wrappers are read-only views.
+    set() {
+      return false;
+    },
+    deleteProperty() {
+      return false;
+    },
+  };
+  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.
+interface CarrierCell<T> extends Carrier<T> {
+  [OP_TAG]: OpTag;
+  [UNWRAP]: T;
+}
+
+function makeCarrier<T>(
+  raw: T,
+  sourceSeq: number | undefined,
+  path: readonly string[],
+): CarrierCell<T> {
+  const tag: OpTag = { sourceSeq, path };
+  return {
+    [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
+    // `JSON.stringify` now behaves like its value — silent wrongness
+    // (a bogus "[object Object]" namespace in a kubectl command) was
+    // the most expensive failure mode this wrapper ever produced.
+    valueOf: () => raw,
+    toString: () => String(raw),
+    toJSON: () => raw,
+    [Symbol.toPrimitive]: () => raw,
+  };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Provenance-preserving field selection
+//
+// The proxy/carrier only carries the OpTag across *property reads* (and a
+// whitelist of array methods), and it can't carry it across `null`/`undefined`
+// at all — those are primitives with nowhere to hang a symbol, and `wrap`
+// 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*.
+// (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.)
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * Re-tag a value against an existing source op. Uses the normal `wrap` for
+ * non-nullish results (object → proxy, primitive → carrier) but a
+ * {@link makeCarrier} *holder* for `null`/`undefined` — those can't hold a
+ * symbol, and `wrap` deliberately passes them through raw. The holder is an
+ * object masquerading as null/undefined, which is ONLY safe because it never
+ * escapes into program control flow: it goes straight to `expect()`, which
+ * `readRaw`s it back to the real value before matching.
+ */
+function retag(raw: unknown, sourceSeq: number | undefined, path: readonly string[]): unknown {
+  return raw === null || raw === undefined
+    ? makeCarrier(raw, sourceSeq, path)
+    : wrap(raw, sourceSeq, path);
+}
+
+/**
+ * Provenance-preserving, null-safe field selector — for asserting on a leaf
+ * that is `null`/`undefined`. Reading such a leaf off a wrapped object hands
+ * back a raw `null`/`undefined` (a symbol tag can't ride on those, and minting
+ * a stand-in object would break every `=== null` / `if (!x)` in real code), so
+ * the raw value alone loses its link to the originating op. `field` reads the
+ * tag from the *container* and navigates the raw value, returning a tagged
+ * handle even when the leaf is nullish — safe because the handle only ever
+ * feeds `expect()`. Pass it straight to `expect(...)`; works with every matcher.
+ *
+ * Mostly redundant now: the plain `expect(dep.status.readyReplicas).toBeFalsy()`
+ * form recovers provenance on its own — the proxy notes each nullish leaf read
+ * and `expect` adopts the note (see {@link adoptNullishTag}). Reach for `field`
+ * when the nullish read and the `expect` are separated by another recorded op
+ * (which clears the note), or to make the navigation explicit.
+ *
+ * ```ts
+ * expect(field(created, "branched_from_environment_id")).toBe(null);
+ * expect(field(dep, "status", "readyReplicas")).toBeFalsy();
+ * ```
+ */
+export function field(value: unknown, ...path: Array<string | number>): unknown {
+  const tag = readTag(value);
+  let cur: unknown = readRaw(value);
+  for (const key of path) {
+    if (cur === null || cur === undefined) {
+      cur = undefined;
+      break;
+    }
+    cur = (cur as Record<string | number, unknown>)[key];
+  }
+  if (!tag) return cur;
+  return retag(cur, tag.sourceSeq, [...tag.path, ...path.map(String)]);
+}
+
+/**
+ * A provenance-carrying handle to a value produced by a tracked op
+ * (`ctx.fetch`, a db query, `browser.evaluate`). Pass it straight to
+ * `expect(...)` — the matcher reads the provenance and nests the
+ * assertion under the originating op in the timeline.
+ *
+ * At runtime, coercion sinks recover the raw value (`` `${carrier}` ``,
+ * `JSON.stringify(carrier)` behave as if raw). But the *type* is honestly an
+ * object, not `T`, so arithmetic (`carrier + 1`), `==`/`===`, and handing it
+ * to a typed API are all compile errors — `carrier.unwrap()` (or `expect(...)`,
+ * which unwraps for you) first. This is deliberate: a wrapped value is a
+ * handle, and the type says so rather than masquerading as its raw type.
+ */
+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). */
+  toString(): string;
+  /** Serializes as the raw value under `JSON.stringify`. */
+  toJSON(): T;
+  /** Coerces to the raw value. */
+  [Symbol.toPrimitive](hint?: string): T;
+}
+
+/**
+ * The values `expect()` accepts: anything carrying provenance from a recorded
+ * op (fetch / db / exec / browser / fakes / k8s) — every member of the
+ * {@link wrap} family ({@link Carrier}, {@link WrappedObject},
+ * {@link WrappedArray}, {@link WrappedResponse}) exposes `.unwrap()`, so this
+ * structural shape admits them all and rejects a raw primitive / object.
+ *
+ * `null`/`undefined` are also admitted: a nullish leaf can't carry the symbol
+ * tag, but `adoptNullishTag` recovers its provenance at runtime, so
+ * `expect(rows[0]?.text)` and `expect(dep.status.readyReplicas)` stay on
+ * `expect`.
+ *
+ * When this gate rejects a value, the fix is usually to stop flattening it —
+ * `.transform(label, fn)` instead of a decode-then-`.unwrap()`, `toHaveLength`
+ * instead of `.length` — not to switch to `expectRaw`, which accepts anything
+ * but renders the assertion unlinked. Reach for `expectRaw(value, message)`
+ * only when the value never flowed from a recorded op at all (a computed
+ * number, a frame off a raw WebSocket); see its own doc comment.
+ */
+export type Provenanced = { unwrap(): unknown } | null | undefined;
+
+/**
+ * What a tracked op's value looks like once wrapped — applied *deeply*, so the
+ * type matches the runtime at every level (the proxy lazily wraps each leaf you
+ * read). A primitive becomes a {@link Carrier}; an object keeps its keys but
+ * each property is itself `Wrapped`, plus an `.unwrap()`; an array keeps a raw
+ * `.length` and indexes to `Wrapped` elements (see {@link WrappedArray}).
+ *
+ * Because leaves are `Carrier`s rather than their raw type, using one as raw
+ * data — arithmetic, string methods, a typed client — is a compile error;
+ * `x.unwrap()` (or `expect(x)`, which unwraps) recovers the raw value. That's
+ * the whole point: the type tells you it's a handle instead of pretending to be
+ * the underlying value and blowing up at runtime.
+ *
+ * **Distributes over unions** so the nullish members of an optional property
+ * survive as `null`/`undefined` rather than collapsing into a `Carrier<undefined>`.
+ * That's what lets `?.` narrow a wrapped optional leaf: `Wrapped<V1PodStatus |
+ * undefined>` is `WrappedObject<V1PodStatus> | undefined` (so `pod.status?.phase`
+ * type-checks), not `Carrier<undefined> | WrappedObject<…>` (where `?.` can't see
+ * the `Carrier` as nullish). A nullish leaf still reaches `expect` untagged and is
+ * recovered at runtime by {@link adoptNullishTag}; `Provenanced` admits it because
+ * it includes `null | undefined`.
+ */
+export type Wrapped<T> = T extends null | undefined
+  ? T
+  : T extends readonly (infer U)[]
+    ? WrappedArray<U>
+    : // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+      T extends (...args: never[]) => unknown
+      ? T
+      : T extends object
+        ? WrappedObject<T>
+        : Carrier<T>;
+
+/** A wrapped object: every own property is itself {@link Wrapped}, plus an
+ *  `.unwrap()` that recovers the fully-raw value (all nested leaves raw). */
+export type WrappedObject<T> = {
+  readonly [K in keyof T]: Wrapped<T[K]>;
+} & {
+  /** 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>;
+};
+
+/**
+ * A wrapped array. Indexing and the content-deriving methods (`find`, `map`,
+ * `filter`, `slice`, …) return {@link Wrapped} values so assertions on them
+ * still fold under the originating op; their *predicates* receive raw elements
+ * (the method runs on the raw target), so `=== ` comparisons inside a predicate
+ * keep working. `.length` stays a real `number` — provenance belongs on the
+ * data, not the container's size, so `rows.length === 1` must be a plain
+ * comparison. Iteration (`for…of`, spread) yields raw elements.
+ */
+export interface WrappedArray<U> {
+  readonly length: number;
+  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,
+  ): Wrapped<U> | undefined;
+  findLast(
+    predicate: (value: U, index: number, obj: U[]) => unknown,
+  ): Wrapped<U> | undefined;
+  findIndex(predicate: (value: U, index: number, obj: U[]) => unknown): number;
+  findLastIndex(
+    predicate: (value: U, index: number, obj: U[]) => unknown,
+  ): number;
+  filter(
+    predicate: (value: U, index: number, array: U[]) => unknown,
+  ): WrappedArray<U>;
+  map<R>(callback: (value: U, index: number, array: U[]) => R): WrappedArray<R>;
+  slice(start?: number, end?: number): WrappedArray<U>;
+  concat(...items: U[][]): WrappedArray<U>;
+  flat(): WrappedArray<unknown>;
+  flatMap<R>(callback: (value: U, index: number, array: U[]) => R): WrappedArray<R>;
+  /** Note: returns a `Carrier<boolean>` at runtime (re-wrapped for provenance),
+   *  so use `arr.includes(x).unwrap()` or `expect(arr.includes(x))` rather than
+   *  a bare `if`. */
+  includes(value: U, fromIndex?: number): Carrier<boolean>;
+  indexOf(value: U, fromIndex?: number): Carrier<number>;
+  lastIndexOf(value: U, fromIndex?: number): Carrier<number>;
+  some(predicate: (value: U, index: number, array: U[]) => unknown): Carrier<boolean>;
+  every(predicate: (value: U, index: number, array: U[]) => unknown): Carrier<boolean>;
+  /** Iteration yields *raw* elements (the runtime forwards the raw iterator). */
+  [Symbol.iterator](): IterableIterator<U>;
+}
+
+/**
+ * The view `ctx.fetch` resolves to in every context (a spectest op wraps
+ * unconditionally): a {@link Response} whose status-line accessors are
+ * {@link Carrier}s — so a raw `res.status === 200` is a *type error*
+ * (status is a `Carrier<number>`, not a number), the exact mistake that
+ * used to silently always be false. Compare `res.status.unwrap() === 200`
+ * or `res.unwrap().status === 200`, or assert with `expect(res.status)`.
+ *
+ * `json<T>()` / `text()` return {@link Wrapped} body values; `.unwrap()`
+ * (or {@link unwrap the whole response}) recovers the plain `Response`.
+ */
+export interface WrappedResponse {
+  readonly status: Carrier<number>;
+  readonly ok: Carrier<boolean>;
+  readonly statusText: Carrier<string>;
+  readonly url: Carrier<string>;
+  readonly redirected: Carrier<boolean>;
+  readonly type: Carrier<string>;
+  readonly headers: Headers;
+  readonly bodyUsed: boolean;
+  json<T = unknown>(): Promise<Wrapped<T>>;
+  text(): Promise<Carrier<string>>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  blob(): Promise<Blob>;
+  formData(): Promise<FormData>;
+  clone(): WrappedResponse;
+  /** Recover the underlying raw {@link Response} (a real `number` status,
+   *  an unwrapped body, etc.). */
+  unwrap(): Response;
+}
+
+/** The signature of `ctx.fetch`: a `fetch` that resolves to a
+ *  {@link WrappedResponse} so reads carry provenance into assertions. */
+export type SpectestFetch = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<WrappedResponse>;
+
+/**
+ * Bespoke wrapper for `fetch` responses. Reads on `status` / `ok` /
+ * `statusText` / `url` / `redirected` / `type` return carriers tagged
+ * to `sourceSeq`. The body-reading methods (`json`, `text`) return the
+ * resolved value wrapped under `path: ["body"]`. Everything else passes
+ * through bound to the real Response.
+ */
+export function wrapResponse(res: Response, sourceSeq: number | undefined): WrappedResponse {
+  const tag: OpTag = { sourceSeq, path: [] };
+  const carrierProps = new Set([
+    "status",
+    "ok",
+    "statusText",
+    "url",
+    "redirected",
+    "type",
+  ]);
+  const bodyMethods = new Set(["json", "text"]);
+  const handler: ProxyHandler<Response> = {
+    get(target, prop) {
+      if (prop === OP_TAG) return tag;
+      if (prop === UNWRAP) return target;
+      // Full recursive unwrap (see the note in `wrapObject`).
+      if (prop === "unwrap") return () => readRaw(target);
+      if (prop === "then") return undefined;
+
+      if (typeof prop === "string" && carrierProps.has(prop)) {
+        const value = (target as unknown as Record<string, unknown>)[prop];
+        return wrap(value, sourceSeq, [prop]);
+      }
+      if (typeof prop === "string" && bodyMethods.has(prop)) {
+        const fn = (target as unknown as Record<string, unknown>)[prop] as
+          | ((...a: unknown[]) => Promise<unknown>)
+          | undefined;
+        if (typeof fn !== "function") return fn;
+        return async (...args: unknown[]) => {
+          const value = await fn.apply(target, args);
+          return wrap(value, sourceSeq, ["body"]);
+        };
+      }
+      const value = (target as unknown as Record<string | symbol, unknown>)[
+        prop as string | symbol
+      ];
+      return typeof value === "function"
+        ? (value as (...a: unknown[]) => unknown).bind(target)
+        : value;
+    },
+    has(target, prop) {
+      if (prop === OP_TAG || prop === UNWRAP) return true;
+      return Reflect.has(target, prop);
+    },
+  };
+  return new Proxy(res, handler) as unknown as WrappedResponse;
+}