@specific.dev/spectest 0.24.0 → 0.27.0

package/dist/ingress.d.ts

@@ -0,0 +1,114 @@
+import type { Project, ServiceConfig } from "./index.js";
+/** Where a DNS name points. `ingress` = the spectest-daemon listener on the
+ *  bridge gateway (fakes, TLS-terminated proxies); `service` = a container's
+ *  live IP on spectest-net (a plain peer alias, no daemon hop). */
+export type DnsTarget = {
+    ingress: true;
+} | {
+    service: string;
+};
+export interface CertificateDecl {
+    kind: "certificate";
+    /** Hostnames the leaf cert's SANs cover. One cert is minted per decl. */
+    hostnames: string[];
+}
+export interface DnsDecl {
+    kind: "dns";
+    hostname: string;
+    target: DnsTarget;
+}
+export interface ProxyDecl {
+    kind: "proxy";
+    hostname: string;
+    upstream: {
+        service: string;
+        port: number;
+    };
+}
+export type IngressDecl = CertificateDecl | DnsDecl | ProxyDecl;
+/** Token a component can use in a decl where it can't know its own
+ *  services-map key yet — resolved to that key during `lowerIngress`.
+ *  Mirrors the `{{SPECTEST_SERVICE}}` token honoured in `files`. */
+export declare const SELF_SERVICE_TOKEN = "{{SPECTEST_SERVICE}}";
+/** A wildcard is `*.` + a normal multi-label hostname (e.g.
+ *  `*.example.com`). It matches any name ending in that suffix. */
+export declare function isWildcard(hostname: string): boolean;
+/**
+ * Request a leaf certificate (signed by the in-VM root CA) covering
+ * `hostnames`. The daemon binds it on the HTTPS ingress (:443, SNI per
+ * hostname). Pairs with a `proxy(...)` (TLS-terminated reverse proxy) or a
+ * fake handler; on its own it just makes those hostnames serve HTTPS.
+ */
+export declare function certificate(hostnames: string[]): CertificateDecl;
+/**
+ * Register `hostname` in spectest's DNS. `{ ingress: true }` points it at
+ * the daemon (for fakes / TLS proxies — resolved to the bridge gateway and
+ * injected as `--add-host` into every container); `{ service }` makes it an
+ * extra peer alias for that container (resolved live to its IP). The
+ * `SELF_SERVICE_TOKEN` may be used for `service` when a component can't yet
+ * know its own key.
+ */
+export declare function dnsName(hostname: string, target: DnsTarget): DnsDecl;
+/**
+ * Reverse-proxy `hostname` to `http://<service>:<port>` on spectest-net.
+ * Implies the hostname resolves to the daemon ingress, so containers reach
+ * it without any extra `dnsName(...)`. Add a `certificate([hostname])` to
+ * serve it over HTTPS as well as HTTP.
+ */
+export declare function proxy(hostname: string, upstream: {
+    service: string;
+    port: number;
+}): ProxyDecl;
+/**
+ * Attach low-level ingress decls to a service definition a component
+ * returns. The decls are read by `lowerIngress` at load time and never
+ * serialised into the wire config.
+ *
+ * ```ts
+ * return provides({ image, command }, [
+ *   certificate(["app.test"]),
+ *   dnsName("app.test", { ingress: true }),
+ *   proxy("app.test", { service: SELF_SERVICE_TOKEN, port: 3000 }),
+ * ]);
+ * ```
+ */
+export declare function provides<T extends ServiceConfig>(service: T, decls: IngressDecl[]): T;
+/** Everything the daemon needs to stand up ingress, derived once per
+ *  /load. The daemon executes this generically — it reads neither
+ *  `svc.tls` nor `svc.hostnames` directly. */
+export interface LoweredIngress {
+    /** One leaf cert per group; SANs = the group's hostnames. */
+    certificates: {
+        hostnames: string[];
+    }[];
+    /** Reverse-proxy routes: hostname → upstream service:port. */
+    proxies: {
+        hostname: string;
+        service: string;
+        port: number;
+    }[];
+    /** Hostnames that resolve to the daemon ingress gateway (DNS registry
+     *  + `--add-host` on every container). Covers fakes, TLS proxies, and
+     *  any `dnsName(h, { ingress: true })`. */
+    ingressHosts: string[];
+    /** service key → extra `--network-alias`es (from `hostnames` /
+     *  `dnsName(h, { service })`). */
+    aliasesByService: Record<string, string[]>;
+    /** Wildcard suffixes (`*.example.com` → `.example.com`) and where they
+     *  point. Resolved to a concrete IP in the daemon (service → that
+     *  container's IP, ingress → the bridge gateway) and written to the
+     *  resolver's wildcard table. Only the resolver answers these — they
+     *  can't be expressed as `--network-alias`/`--add-host`. */
+    wildcards: {
+        pattern: string;
+        target: DnsTarget;
+    }[];
+}
+/**
+ * Lower a project's friendly surface (`services.*.tls`,
+ * `services.*.hostnames`, component `provides(...)`, and `fakes`) into the
+ * generic `LoweredIngress` the daemon executes. This is the framework
+ * abstraction the user asked for: the special-casing lives here, in one
+ * pure function, instead of being scattered through the daemon.
+ */
+export declare function lowerIngress(project: Project): LoweredIngress;

package/dist/ingress.js

@@ -0,0 +1,210 @@
+// Low-level ingress primitives — the first-class building blocks the
+// daemon's networking is expressed in terms of. The friendly
+// `services.<name>.tls` / `services.<name>.hostnames` fields and
+// `defineFake(...)` are all *sugar* that lower onto these three:
+//
+//   certificate(hostnames)      — mint a leaf cert from the in-VM root CA
+//   dnsName(hostname, target)   — register a name → a container or the daemon
+//   proxy(hostname, upstream)   — reverse-proxy a hostname to a service:port
+//
+// The daemon consumes only the lowered result (see `lowerIngress`), so it
+// never special-cases tls/hostnames/fakes — it just executes a generic set
+// of certs, proxy routes, DNS registrations, and aliases. A user-authored
+// component emits the same primitives by attaching them with `provides(...)`,
+// so it can do anything the built-ins do without any daemon change.
+//
+// None of this is part of the wire `EnvironmentConfig` the control plane
+// deserialises: the decls live on the `Project` (daemon-side only) and,
+// when attached to a service, ride on a Symbol key that `JSON.stringify`
+// drops — so Rust's `deny_unknown_fields` never sees them.
+/** Token a component can use in a decl where it can't know its own
+ *  services-map key yet — resolved to that key during `lowerIngress`.
+ *  Mirrors the `{{SPECTEST_SERVICE}}` token honoured in `files`. */
+export const SELF_SERVICE_TOKEN = "{{SPECTEST_SERVICE}}";
+// Multi-label hostname: at least one dot, each label 1–63 chars of
+// [a-z0-9-], no leading/trailing hyphen. Kept in lockstep with index.ts.
+const HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/;
+function assertHostname(h, ctx) {
+    const lower = h.toLowerCase();
+    if (!HOSTNAME_RE.test(lower)) {
+        throw new Error(`${ctx}: invalid hostname ${JSON.stringify(h)} — must be a multi-label DNS name (e.g. "api.stripe.com")`);
+    }
+    if (lower === "internal" || lower.endsWith(".internal")) {
+        throw new Error(`${ctx}: hostname ${JSON.stringify(h)} ends in the reserved ".internal" TLD`);
+    }
+}
+/** A wildcard is `*.` + a normal multi-label hostname (e.g.
+ *  `*.example.com`). It matches any name ending in that suffix. */
+export function isWildcard(hostname) {
+    return hostname.startsWith("*.");
+}
+/** Validate an exact hostname OR a `*.suffix` wildcard. */
+function assertNameOrWildcard(h, ctx) {
+    if (isWildcard(h)) {
+        // The bit after `*.` must itself be a valid multi-label hostname, so
+        // `*.example.com` is fine but `*.com` (too broad) and `*` are not.
+        assertHostname(h.slice(2), `${ctx} wildcard`);
+        return;
+    }
+    assertHostname(h, ctx);
+}
+/**
+ * Request a leaf certificate (signed by the in-VM root CA) covering
+ * `hostnames`. The daemon binds it on the HTTPS ingress (:443, SNI per
+ * hostname). Pairs with a `proxy(...)` (TLS-terminated reverse proxy) or a
+ * fake handler; on its own it just makes those hostnames serve HTTPS.
+ */
+export function certificate(hostnames) {
+    if (!Array.isArray(hostnames) || hostnames.length === 0) {
+        throw new Error("certificate(): at least one hostname is required");
+    }
+    for (const h of hostnames)
+        assertHostname(h, "certificate()");
+    return { kind: "certificate", hostnames: hostnames.map((h) => h.toLowerCase()) };
+}
+/**
+ * Register `hostname` in spectest's DNS. `{ ingress: true }` points it at
+ * the daemon (for fakes / TLS proxies — resolved to the bridge gateway and
+ * injected as `--add-host` into every container); `{ service }` makes it an
+ * extra peer alias for that container (resolved live to its IP). The
+ * `SELF_SERVICE_TOKEN` may be used for `service` when a component can't yet
+ * know its own key.
+ */
+export function dnsName(hostname, target) {
+    assertNameOrWildcard(hostname, "dnsName()");
+    if (!("ingress" in target) && !("service" in target)) {
+        throw new Error(`dnsName(${JSON.stringify(hostname)}): target must be { ingress: true } or { service }`);
+    }
+    return { kind: "dns", hostname: hostname.toLowerCase(), target };
+}
+/**
+ * Reverse-proxy `hostname` to `http://<service>:<port>` on spectest-net.
+ * Implies the hostname resolves to the daemon ingress, so containers reach
+ * it without any extra `dnsName(...)`. Add a `certificate([hostname])` to
+ * serve it over HTTPS as well as HTTP.
+ */
+export function proxy(hostname, upstream) {
+    assertHostname(hostname, "proxy()");
+    if (!upstream || typeof upstream.service !== "string" || typeof upstream.port !== "number") {
+        throw new Error(`proxy(${JSON.stringify(hostname)}): upstream must be { service: string, port: number }`);
+    }
+    return { kind: "proxy", hostname: hostname.toLowerCase(), upstream };
+}
+/** Symbol key under which `provides(...)` stashes a component's ingress
+ *  decls on its service object. A Symbol so `JSON.stringify(environment)`
+ *  (the wire config shipped to the Rust control plane) drops it — symbol
+ *  keys are never serialised, regardless of enumerability. Kept
+ *  *enumerable* so it survives the common `{ ...component() }` spread (object
+ *  spread copies enumerable symbol props but skips non-enumerable ones). */
+const INGRESS_DECLS = Symbol.for("spectest.ingress.decls");
+/**
+ * Attach low-level ingress decls to a service definition a component
+ * returns. The decls are read by `lowerIngress` at load time and never
+ * serialised into the wire config.
+ *
+ * ```ts
+ * return provides({ image, command }, [
+ *   certificate(["app.test"]),
+ *   dnsName("app.test", { ingress: true }),
+ *   proxy("app.test", { service: SELF_SERVICE_TOKEN, port: 3000 }),
+ * ]);
+ * ```
+ */
+export function provides(service, decls) {
+    // Merge with any decls already attached (e.g. a component built via
+    // provides() that the caller then wraps again) so neither layer is lost.
+    const prior = readProvided(service);
+    Object.defineProperty(service, INGRESS_DECLS, {
+        value: [...prior, ...decls],
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+    return service;
+}
+function readProvided(service) {
+    const decls = service[INGRESS_DECLS];
+    return Array.isArray(decls) ? decls : [];
+}
+function resolveSelf(service, selfKey) {
+    return service === SELF_SERVICE_TOKEN ? selfKey : service;
+}
+/**
+ * Lower a project's friendly surface (`services.*.tls`,
+ * `services.*.hostnames`, component `provides(...)`, and `fakes`) into the
+ * generic `LoweredIngress` the daemon executes. This is the framework
+ * abstraction the user asked for: the special-casing lives here, in one
+ * pure function, instead of being scattered through the daemon.
+ */
+export function lowerIngress(project) {
+    const certificates = [];
+    const proxies = [];
+    const ingressSet = new Set();
+    const aliasesByService = {};
+    const wildcards = [];
+    const addAlias = (service, host) => {
+        (aliasesByService[service] ??= []).push(host.toLowerCase());
+    };
+    const applyDecl = (decl, selfKey) => {
+        switch (decl.kind) {
+            case "certificate":
+                certificates.push({ hostnames: decl.hostnames });
+                break;
+            case "proxy": {
+                const service = resolveSelf(decl.upstream.service, selfKey);
+                proxies.push({ hostname: decl.hostname, service, port: decl.upstream.port });
+                // A proxied hostname must route to the daemon.
+                ingressSet.add(decl.hostname);
+                break;
+            }
+            case "dns": {
+                // A wildcard can only be answered by the resolver (no
+                // --network-alias / --add-host equivalent), so route either kind
+                // of target through the wildcard table; the daemon resolves the IP.
+                if (isWildcard(decl.hostname)) {
+                    const target = "service" in decl.target
+                        ? { service: resolveSelf(decl.target.service, selfKey) }
+                        : decl.target;
+                    wildcards.push({ pattern: decl.hostname, target });
+                }
+                else if ("ingress" in decl.target) {
+                    ingressSet.add(decl.hostname);
+                }
+                else {
+                    addAlias(resolveSelf(decl.target.service, selfKey), decl.hostname);
+                }
+                break;
+            }
+        }
+    };
+    for (const [name, svc] of Object.entries(project.environment.services)) {
+        // Component-provided explicit decls.
+        for (const decl of readProvided(svc))
+            applyDecl(decl, name);
+        // `tls: [{ hostname, port }]` → cert + TLS-terminated reverse proxy.
+        for (const entry of svc.tls ?? []) {
+            applyDecl(certificate([entry.hostname]), name);
+            applyDecl(proxy(entry.hostname, { service: name, port: entry.port }), name);
+        }
+        // `hostnames: [h]` → plain peer alias (no daemon hop).
+        for (const h of svc.hostnames ?? []) {
+            applyDecl(dnsName(h, { service: name }), name);
+        }
+    }
+    // Fakes: in-daemon handlers. The handler routing stays keyed by hostname
+    // in the daemon's FAKES map; here we only contribute their networking
+    // (a leaf cert for HTTPS + ingress DNS).
+    for (const fake of Object.values(project.fakes ?? {})) {
+        const hostnames = fake.hostnames.map((h) => h.toLowerCase());
+        certificates.push({ hostnames });
+        for (const h of hostnames)
+            ingressSet.add(h);
+    }
+    return {
+        certificates,
+        proxies,
+        ingressHosts: [...ingressSet],
+        aliasesByService,
+        wildcards,
+    };
+}

package/dist/inspect.d.ts

@@ -0,0 +1,228 @@
+export declare const OP_TAG: unique symbol;
+export declare const UNWRAP: unique symbol;
+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 declare function readTag(x: unknown): OpTag | undefined;
+/** 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 declare function clearPendingNullish(): void;
+/**
+ * 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 declare function adoptNullishTag<T>(value: T): T;
+/** If x is wrapped, return the raw value; otherwise return x. */
+export declare function readRaw<T>(x: T): 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 declare function wrap<T>(raw: T, sourceSeq: number | undefined, path?: readonly string[]): T;
+/**
+ * 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 declare function field(value: unknown, ...path: Array<string | number>): unknown;
+/**
+ * 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> : 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 declare function wrapResponse(res: Response, sourceSeq: number | undefined): WrappedResponse;