@specific.dev/spectest 0.24.0 → 0.27.0

package/src/inspect.ts

@@ -1,673 +0,0 @@
-// 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;
-}
-
-/** 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`. To assert on a value with no provenance (a computed number, a raw
- * WebSocket frame), use `expectRaw(value, message)` instead.
- */
-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;
-}