@ultimat3/testing 29.3.2 → 30.0.0

package/src/fake-identity-provider.ts

@@ -0,0 +1,191 @@
+// A fake OpenID provider, served through `mockFetch` with no socket: a discovery document, a JWKS
+// from a key generated per instance, `/authorize` auto-approving as a chosen user, `/token` (PKCE
+// checked) and `/userinfo`. `tamper()` mints the failures that matter — wrong audience, expired,
+// wrong key, no `email_verified` — so a sign-in test proves the refusals, not just the happy path.
+
+import type { Clock } from '@ultimat3/core';
+import { assert, systemClock, timingSafeEqual } from '@ultimat3/core';
+import { mockFetch } from './sealed-network';
+
+export interface FakeIdpUser {
+  readonly sub: string;
+  readonly email: string;
+  /** Defaults to `true`. `tamper({ noEmailVerified })` drops the claim entirely. */
+  readonly emailVerified?: boolean | undefined;
+  readonly name?: string | undefined;
+}
+
+export interface FakeIdpTamper {
+  /** `aud` names another client. */
+  readonly wrongAudience?: boolean | undefined;
+  /** `exp` an hour ago. */
+  readonly expired?: boolean | undefined;
+  /** Signed by a key the JWKS does not publish, under the same `kid`. */
+  readonly wrongKey?: boolean | undefined;
+  /** No `email_verified` claim, in the id token or `/userinfo`. */
+  readonly noEmailVerified?: boolean | undefined;
+}
+
+export interface FakeIdentityProviderInput {
+  /** Defaults to `https://idp.test`. */
+  readonly issuer?: string | undefined;
+  readonly users: readonly FakeIdpUser[];
+  readonly clock?: Clock | undefined;
+  /** Defaults to `fake-client`. */
+  readonly clientId?: string | undefined;
+}
+
+export interface FakeIdentityProvider {
+  readonly issuer: string;
+  readonly clientId: string;
+  readonly clientSecret: string;
+  readonly jwksUri: string;
+  /** Who `/authorize` approves as next. Defaults to the first user. */
+  signInAs(sub: string): void;
+  /** Applies to every token minted after it; `tamper({})` restores honesty. */
+  tamper(flags: FakeIdpTamper): void;
+  /** An id token minted directly, for a test that skips the redirect leg. */
+  idToken(input: { readonly sub: string; readonly nonce?: string | undefined }): Promise<string>;
+}
+
+type KeyPair = CryptoKeyPair;
+const KID = 'fake-idp-key';
+const encoder = new TextEncoder();
+
+const b64url = (bytes: Uint8Array): string => Buffer.from(bytes).toString('base64url');
+const segment = (value: unknown): string => b64url(encoder.encode(JSON.stringify(value)));
+const random = (bytes = 24): string => b64url(crypto.getRandomValues(new Uint8Array(bytes)));
+const es256 = (): Promise<KeyPair> =>
+  crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']);
+
+interface PendingCode {
+  readonly sub: string;
+  readonly nonce: string | null;
+  readonly challenge: string | null;
+}
+
+export async function fakeIdentityProvider(
+  input: FakeIdentityProviderInput,
+): Promise<FakeIdentityProvider> {
+  assert(
+    input.users.length > 0,
+    'fakeIdentityProvider was given no users',
+    'pass users: [{ sub, email }]',
+  );
+  const issuer = (input.issuer ?? 'https://idp.test').replace(/\/+$/, '');
+  const clientId = input.clientId ?? 'fake-client';
+  const clientSecret = random();
+  const clock = input.clock ?? systemClock;
+  const [published, rogue] = await Promise.all([es256(), es256()]);
+  const jwk = await crypto.subtle.exportKey('jwk', published.publicKey);
+  const users = new Map(input.users.map((user) => [user.sub, user]));
+  const codes = new Map<string, PendingCode>();
+  const accessTokens = new Map<string, string>();
+  let chosen = input.users[0]?.sub ?? '';
+  let flags: FakeIdpTamper = {};
+
+  const claimsOf = (user: FakeIdpUser) => ({
+    email: user.email,
+    ...(flags.noEmailVerified === true ? {} : { email_verified: user.emailVerified ?? true }),
+    ...(user.name === undefined ? {} : { name: user.name }),
+  });
+
+  async function idToken(token: { sub: string; nonce?: string | undefined }): Promise<string> {
+    const user = users.get(token.sub);
+    assert(user !== undefined, `fake IdP has no user ${token.sub}`, 'add it to users: [...]');
+    const now = Math.floor(clock.now().getTime() / 1000);
+    const body = `${segment({ alg: 'ES256', kid: KID, typ: 'JWT' })}.${segment({
+      iss: issuer,
+      sub: user.sub,
+      aud: flags.wrongAudience === true ? 'another-client' : clientId,
+      iat: now,
+      exp: flags.expired === true ? now - 3600 : now + 3600,
+      ...(token.nonce === undefined ? {} : { nonce: token.nonce }),
+      ...claimsOf(user),
+    })}`;
+    const key = (flags.wrongKey === true ? rogue : published).privateKey;
+    const signature = await crypto.subtle.sign(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      key,
+      encoder.encode(body),
+    );
+    return `${body}.${b64url(new Uint8Array(signature))}`;
+  }
+
+  const json = (body: unknown, status = 200) => Response.json(body, { status });
+  mockFetch(`GET ${issuer}/.well-known/openid-configuration`, () =>
+    json({
+      issuer,
+      authorization_endpoint: `${issuer}/authorize`,
+      token_endpoint: `${issuer}/token`,
+      userinfo_endpoint: `${issuer}/userinfo`,
+      jwks_uri: `${issuer}/jwks`,
+      response_types_supported: ['code'],
+      subject_types_supported: ['public'],
+      id_token_signing_alg_values_supported: ['ES256'],
+      code_challenge_methods_supported: ['S256'],
+    }),
+  );
+  mockFetch(`GET ${issuer}/jwks`, () =>
+    json({ keys: [{ ...jwk, kid: KID, alg: 'ES256', use: 'sig' }] }),
+  );
+  mockFetch(`GET ${issuer}/authorize*`, (request) => {
+    const params = new URL(request.url).searchParams;
+    const redirect = params.get('redirect_uri');
+    if (redirect === null || params.get('client_id') !== clientId) {
+      return json({ error: 'invalid_request' }, 400);
+    }
+    const code = random();
+    codes.set(code, {
+      sub: chosen,
+      nonce: params.get('nonce'),
+      challenge: params.get('code_challenge'),
+    });
+    const back = new URL(redirect);
+    back.searchParams.set('code', code);
+    const state = params.get('state');
+    if (state !== null) back.searchParams.set('state', state);
+    return new Response(null, { status: 302, headers: { location: back.toString() } });
+  });
+  mockFetch(`POST ${issuer}/token`, async (request) => {
+    const form = new URLSearchParams(await request.text());
+    const pending = codes.get(form.get('code') ?? '');
+    codes.delete(form.get('code') ?? '');
+    if (pending === undefined) return json({ error: 'invalid_grant' }, 400);
+    const verifier = form.get('code_verifier') ?? '';
+    const digest = new Bun.CryptoHasher('sha256').update(verifier).digest('base64url');
+    if (pending.challenge !== null && !timingSafeEqual(digest, pending.challenge)) {
+      return json({ error: 'invalid_grant' }, 400);
+    }
+    const access = random();
+    accessTokens.set(access, pending.sub);
+    return json({
+      access_token: access,
+      token_type: 'Bearer',
+      expires_in: 3600,
+      scope: 'openid email profile',
+      id_token: await idToken({ sub: pending.sub, nonce: pending.nonce ?? undefined }),
+    });
+  });
+  mockFetch(`GET ${issuer}/userinfo`, (request) => {
+    const access = (request.headers.get('authorization') ?? '').replace(/^Bearer /i, '');
+    const user = users.get(accessTokens.get(access) ?? '');
+    if (user === undefined) return json({ error: 'invalid_token' }, 401);
+    return json({ sub: user.sub, ...claimsOf(user) });
+  });
+
+  return {
+    issuer,
+    clientId,
+    clientSecret,
+    jwksUri: `${issuer}/jwks`,
+    signInAs(sub) {
+      assert(users.has(sub), `fake IdP has no user ${sub}`, 'add it to users: [...]');
+      chosen = sub;
+    },
+    tamper(next) {
+      flags = { ...next };
+    },
+    idToken,
+  };
+}

package/src/fault-proxy.ts

@@ -0,0 +1,342 @@
+// A TCP proxy in front of one real service, with the fault switchable mid-run: what `x drill` puts
+// between an app's roles and its Postgres, Redis and NATS. Bun's own sockets, no container and no
+// kernel rule — so a drill runs the same on a laptop and a free CI runner. The faults are the
+// outages this plan reproduced by hand: an unanswered path, a slow one, a reset, a refusal.
+
+import { assert, finiteCount, MAX_TIMER_MS } from '@ultimat3/core';
+import type { Socket, TCPSocketListener } from 'bun';
+
+/**
+ * `blackhole` accepts and never answers — a node loss, where the server is healthy and the path is
+ * not. Bytes that arrive meanwhile are HELD, never dropped, and cross once the mode lets them.
+ */
+export type FaultMode =
+  | { readonly kind: 'pass' }
+  | { readonly kind: 'delay'; readonly ms: number }
+  | { readonly kind: 'blackhole' }
+  | { readonly kind: 'reset' }
+  | { readonly kind: 'refuse' };
+
+export type FaultModeKind = FaultMode['kind'];
+
+export const FAULT_MODE_KINDS: readonly FaultModeKind[] = [
+  'pass',
+  'delay',
+  'blackhole',
+  'reset',
+  'refuse',
+];
+
+export interface FaultProxyCounts {
+  /** Connections the proxy accepted and dialled through. */
+  readonly accepted: number;
+  /** Connections cut: by a `reset` or `refuse`, or accepted under `reset`. */
+  readonly reset: number;
+  /** Connections whose dial to the real service failed. */
+  readonly upstreamFailed: number;
+  /** Connections open right now. */
+  readonly open: number;
+  readonly bytesUp: number;
+  readonly bytesDown: number;
+  /** Bytes held by a `blackhole`, not yet delivered. */
+  readonly held: number;
+}
+
+export interface FaultProxy {
+  /** The loopback port the app dials instead of the service's. Kept across a `refuse`. */
+  readonly port: number;
+  readonly mode: FaultMode;
+  /** Switch the fault. Takes effect on the next byte; held bytes are re-judged under `mode`. */
+  set(mode: FaultMode): Promise<void>;
+  counts(): FaultProxyCounts;
+  /** Cut every connection and stop listening. Idempotent. */
+  close(): void;
+}
+
+export interface FaultProxyOptions {
+  readonly target: { readonly hostname: string; readonly port: number };
+  readonly mode?: FaultMode | undefined;
+  /** Listen here rather than on a port of the OS's choosing. */
+  readonly port?: number | undefined;
+  /** How a `delay` waits. A test injects a gate it opens; a drill takes the wall clock's. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+
+type Direction = 'up' | 'down';
+
+/** A socket's unsent bytes, flushed on `drain`: a write the kernel half-took is never lost. */
+interface Outbox {
+  readonly queue: Uint8Array[];
+}
+
+interface Pair {
+  readonly client: Socket<Leg>;
+  upstream: Socket<Leg> | undefined;
+  /** Client bytes that arrived before the dial landed. */
+  readonly early: Uint8Array[];
+  readonly held: Map<Direction, Uint8Array[]>;
+  /** Per direction, the delivery a `delay` chains on, so order survives the wait. */
+  readonly chain: Map<Direction, Promise<void>>;
+}
+
+interface Leg {
+  pair: Pair | undefined;
+  readonly out: Outbox;
+}
+
+const LOOPBACK = '127.0.0.1';
+
+/** The mode, screened: a `delay` of NaN would arm `setTimeout(…, 0)` and drill nothing. */
+export function screenFaultMode(mode: FaultMode): FaultMode {
+  assert(
+    FAULT_MODE_KINDS.includes(mode.kind),
+    `faultProxy was given the mode ${JSON.stringify(mode.kind)}, which is none of ${FAULT_MODE_KINDS.join(', ')}`,
+    "proxy.set({ kind: 'blackhole' })   # one of pass, delay, blackhole, reset, refuse",
+  );
+  if (mode.kind === 'delay') {
+    finiteCount('faultProxy', 'delay ms', mode.ms);
+    assert(
+      mode.ms <= MAX_TIMER_MS,
+      `faultProxy delay ms is ${String(mode.ms)}, past the longest a timer holds`,
+      "proxy.set({ kind: 'blackhole' })   # a delay no timer can hold is a blackhole; say so",
+    );
+  }
+  return mode;
+}
+
+function send(socket: Socket<Leg>, bytes: Uint8Array): void {
+  const out = socket.data.out;
+  if (out.queue.length > 0) {
+    out.queue.push(bytes);
+    return;
+  }
+  const written = socket.write(bytes);
+  if (written < bytes.length) out.queue.push(bytes.subarray(Math.max(0, written)));
+}
+
+function flush(socket: Socket<Leg>): void {
+  const queue = socket.data.out.queue;
+  while (queue.length > 0) {
+    const head = queue[0];
+    if (head === undefined) return;
+    const written = socket.write(head);
+    if (written < head.length) {
+      queue[0] = head.subarray(Math.max(0, written));
+      return;
+    }
+    queue.shift();
+  }
+}
+
+/** `{ target }` behind a loopback port whose fault `set` switches. */
+export async function faultProxy(options: FaultProxyOptions): Promise<FaultProxy> {
+  let mode = screenFaultMode(options.mode ?? { kind: 'pass' });
+  const sleep = options.sleep ?? ((ms: number) => Bun.sleep(ms));
+  const pairs = new Set<Pair>();
+  const counts = { accepted: 0, reset: 0, upstreamFailed: 0, bytesUp: 0, bytesDown: 0 };
+  let closed = false;
+
+  const heldBytes = (): number => {
+    let total = 0;
+    for (const pair of pairs) {
+      for (const chunks of pair.held.values()) {
+        for (const chunk of chunks) total += chunk.length;
+      }
+    }
+    return total;
+  };
+
+  const cut = (pair: Pair): void => {
+    if (!pairs.delete(pair)) return;
+    counts.reset += 1;
+    pair.client.terminate();
+    pair.upstream?.terminate();
+  };
+
+  const write = (pair: Pair, direction: Direction, bytes: Uint8Array): void => {
+    if (!pairs.has(pair)) return;
+    if (direction === 'down') {
+      send(pair.client, bytes);
+      return;
+    }
+    if (pair.upstream === undefined) pair.early.push(bytes);
+    else send(pair.upstream, bytes);
+  };
+
+  /** One chunk, judged by the mode in force NOW — so a byte a delay held re-meets a blackhole. */
+  const route = (pair: Pair, direction: Direction, bytes: Uint8Array): void => {
+    if (!pairs.has(pair)) return;
+    if (mode.kind === 'blackhole') {
+      pair.held.get(direction)?.push(bytes);
+      return;
+    }
+    if (mode.kind === 'delay') {
+      const timer = sleep(mode.ms);
+      const previous = pair.chain.get(direction) ?? Promise.resolve();
+      const next = Promise.all([previous, timer]).then(() => {
+        // A switch to blackhole while this waited holds it; a pass writes it.
+        if (mode.kind === 'blackhole') pair.held.get(direction)?.push(bytes);
+        else write(pair, direction, bytes);
+      });
+      pair.chain.set(direction, next);
+      return;
+    }
+    write(pair, direction, bytes);
+  };
+
+  const dial = (pair: Pair): void => {
+    void Bun.connect<Leg>({
+      hostname: options.target.hostname,
+      port: options.target.port,
+      socket: {
+        open(upstream) {
+          upstream.data = { pair, out: { queue: [] } };
+          if (!pairs.has(pair)) {
+            upstream.terminate();
+            return;
+          }
+          pair.upstream = upstream;
+          for (const bytes of pair.early.splice(0)) send(upstream, bytes);
+        },
+        data(_upstream, chunk) {
+          counts.bytesDown += chunk.length;
+          // Copied: the runtime reuses the chunk's buffer once this handler returns.
+          route(pair, 'down', Uint8Array.from(chunk));
+        },
+        drain: flush,
+        close() {
+          if (pairs.delete(pair)) pair.client.end();
+        },
+        error() {
+          if (pairs.delete(pair)) pair.client.end();
+        },
+      },
+    }).catch(() => {
+      counts.upstreamFailed += 1;
+      if (pairs.delete(pair)) pair.client.terminate();
+    });
+  };
+
+  const listen = (port: number): TCPSocketListener<Leg> =>
+    Bun.listen<Leg>({
+      hostname: LOOPBACK,
+      port,
+      socket: {
+        open(client) {
+          client.data = { pair: undefined, out: { queue: [] } };
+          if (mode.kind === 'reset' || mode.kind === 'refuse') {
+            counts.reset += 1;
+            client.terminate();
+            return;
+          }
+          const pair: Pair = {
+            client,
+            upstream: undefined,
+            early: [],
+            held: new Map([
+              ['up', []],
+              ['down', []],
+            ]),
+            chain: new Map(),
+          };
+          client.data.pair = pair;
+          pairs.add(pair);
+          counts.accepted += 1;
+          dial(pair);
+        },
+        data(client, chunk) {
+          counts.bytesUp += chunk.length;
+          const pair = client.data.pair;
+          if (pair !== undefined) route(pair, 'up', Uint8Array.from(chunk));
+        },
+        drain: flush,
+        close(client) {
+          const pair = client.data.pair;
+          if (pair !== undefined && pairs.delete(pair)) pair.upstream?.end();
+        },
+        error(client) {
+          const pair = client.data.pair;
+          if (pair !== undefined && pairs.delete(pair)) pair.upstream?.terminate();
+        },
+      },
+    });
+
+  let listener: TCPSocketListener<Leg> | undefined = listen(
+    finiteCount('faultProxy', 'port', options.port ?? 0),
+  );
+  const port = listener.port;
+  if (mode.kind === 'refuse') {
+    listener.stop(true);
+    listener = undefined;
+  }
+
+  return {
+    port,
+    get mode() {
+      return mode;
+    },
+    async set(next: FaultMode): Promise<void> {
+      assert(
+        !closed,
+        'faultProxy.set() was called after close(), so there is no proxy to switch',
+        'faultProxy({ target }) again — close() is final',
+      );
+      mode = screenFaultMode(next);
+      if (mode.kind === 'reset' || mode.kind === 'refuse') {
+        for (const pair of [...pairs]) cut(pair);
+      }
+      if (mode.kind === 'refuse') {
+        listener?.stop(true);
+        listener = undefined;
+        return;
+      }
+      // Back from a refusal: listening again on the SAME port, where every role still dials.
+      if (listener === undefined) listener = listen(port);
+      if (mode.kind === 'blackhole') return;
+      for (const pair of pairs) {
+        for (const [direction, chunks] of pair.held) {
+          for (const bytes of chunks.splice(0)) route(pair, direction, bytes);
+        }
+      }
+    },
+    counts: () => ({ ...counts, open: pairs.size, held: heldBytes() }),
+    close(): void {
+      if (closed) return;
+      closed = true;
+      for (const pair of [...pairs]) cut(pair);
+      listener?.stop(true);
+      listener = undefined;
+    },
+  };
+}
+
+/**
+ * `url` re-pointed at a proxy on loopback: scheme, credentials, database and query kept, since the
+ * proxy forwards bytes and the service still authenticates them. One rewriter for every service.
+ */
+export function throughFaultProxy(url: string, port: number): string {
+  const parsed = new URL(url);
+  parsed.hostname = LOOPBACK;
+  parsed.port = String(port);
+  return parsed.toString();
+}
+
+/** Where a service URL points: what `faultProxy({ target })` dials. */
+export function faultTarget(url: string): { readonly hostname: string; readonly port: number } {
+  const parsed = new URL(url);
+  const fallback = DEFAULT_PORTS.get(parsed.protocol);
+  const port = parsed.port === '' ? fallback : Number.parseInt(parsed.port, 10);
+  assert(
+    port !== undefined,
+    `${parsed.protocol}// names no port and has no default this proxy knows`,
+    'TEST_DATABASE_URL=postgres://ultimate:ultimate@127.0.0.1:5432/postgres   # name the port in the URL',
+  );
+  return { hostname: parsed.hostname, port };
+}
+
+const DEFAULT_PORTS: ReadonlyMap<string, number> = new Map([
+  ['postgres:', 5432],
+  ['postgresql:', 5432],
+  ['redis:', 6379],
+  ['nats:', 4222],
+]);

package/src/file-boundary.ts

@@ -4,7 +4,7 @@
 // Since 22.7 `x test` / `x verify` run each worker WITHOUT `--isolate`: one global and one module
 // registry per worker, reused across every file it runs (2-5x faster, measured in
 // `@ultimat3/cli`'s `test-workers.ts`). What a file leaves on `globalThis` then reaches every
-// later file on that worker. Measured on notificado.co: one island test that never disposed its
+// later file on that worker. Measured on one adopter's app: one island test that never disposed its
 // mount left the fake `window`/`document` installed, PGlite then took the process for a browser
 // (`window.location.pathname` of undefined), and 264 unrelated tests failed.
 //
@@ -130,6 +130,9 @@ export function runBoundaryHooks(): void {
   }
 }
 
+/** Whether a test file has loaded yet: before it, a call is a preload's, which every file inherits. */
+export const inTestFile = (): boolean => baseline !== undefined;
+
 /** Called by the leak guard as each test file loads. The first call only takes the baseline. */
 export function runFileBoundary(): void {
   if (baseline === undefined) {

package/src/fixture-jobs.ts

@@ -221,7 +221,9 @@ export async function testJobs(): Promise<RunJobs> {
       queue: handle.queue,
       input,
       idempotencyKey: handle.idempotencyKeyFor(input),
-      maxAttempts: handle.retry.attempts,
+      // The row's count, never the policy's: a `compensates` job carries the unwind margin, so a
+      // final attempt whose worker died is re-offered to unwind instead of buried.
+      maxAttempts: jobs.enqueuedAttempts(handle.retry, handle.compensates),
       ...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
     });
 

package/src/fixture-statements.ts

@@ -2,6 +2,9 @@
 // repeats past the threshold throws where it happened, so an N+1 fails the test that caused it
 // instead of warning in a dev server nobody is watching.
 //
+// Both drivers report here: Postgres per statement, `memoryRepo` per repository operation, so a
+// loop in a unit test on the in-memory driver is the same verdict under the same `entity.op`.
+//
 // Strict by construction: there is no `strict: true` to remember, because a fixture nobody
 // destructured is a fixture nobody built. Opting in is naming `statements` in the test body.
 
@@ -12,7 +15,7 @@ export interface ObservedStatement {
   /** What it is counted under: `members.findById` when attributed, else its own collapsed text. */
   readonly fingerprint: string;
   readonly kind: 'read' | 'write';
-  /** The statement as sent, parameters still `$1..$n`. */
+  /** The statement as sent, parameters still `$1..$n`. The memory driver sends none: its label. */
   readonly text: string;
   /** The entity and operation that compiled it; absent for hand-written SQL and queue traffic. */
   readonly attribution?: StatementAttribution | undefined;

package/src/free-port.ts

@@ -57,3 +57,62 @@ export const freePortApartFrom = (
     for (const probe of held) probe.stop();
   }
 };
+
+/**
+ * The addresses `localhost` can name. A dual-stack host (GitHub's Ubuntu runner, a Debian container)
+ * maps it to both, and Bun binds the FIRST it resolves: a holder on `::1` left `localhost` free on
+ * `127.0.0.1`, so a probe on `localhost`, or on Bun's default `::`, answered "free" for a port
+ * `x dev` then met held (scaffold-smoke, CI run 41764752262). Each is asked on its own.
+ */
+export const LOOPBACK_ADDRESSES: readonly string[] = ['127.0.0.1', '::1'];
+
+/** An address this host does not have — IPv6 switched off — holds nothing. */
+const ABSENT = new Set(['EADDRNOTAVAIL', 'EAFNOSUPPORT', 'EINVAL']);
+
+/** Whether `port` is free on every loopback address `localhost` may resolve to. */
+export const loopbackFree = (
+  port: number,
+  addresses: readonly string[] = LOOPBACK_ADDRESSES,
+): boolean =>
+  addresses.every((hostname) => {
+    try {
+      Bun.listen({ hostname, port, socket: { data: () => undefined } }).stop(true);
+      return true;
+    } catch (error) {
+      const code = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : '';
+      return typeof code === 'string' && ABSENT.has(code);
+    }
+  });
+
+/**
+ * A free port whose NEIGHBOUR is free too, both ones a browser opens. `x dev` binds the web role on
+ * `port` and the sync node on `port + 1`, so a lone free port whose neighbour another process held
+ * was an e2e app that listened, failed its sync bind and exited before `/readyz` — the CLI's own
+ * `freeDevPort` rule (`dev-supervisor.ts`), which this package cannot import. A candidate is held
+ * while the next is asked for, as a refused port is, so the walk ends. The candidate itself is held
+ * on Bun's dual-stack `::`, which covers both loopbacks; the neighbour is asked of each.
+ */
+export const freePortPair = (
+  listen: () => PortProbe = listenOnAnyPort,
+  canBind: (port: number) => boolean = loopbackFree,
+): number => {
+  const held: PortProbe[] = [];
+  try {
+    for (;;) {
+      const probe = listen();
+      const next = probe.port + 1;
+      if (
+        BROWSER_REFUSED_PORTS.has(probe.port) ||
+        BROWSER_REFUSED_PORTS.has(next) ||
+        !canBind(next)
+      ) {
+        held.push(probe);
+        continue;
+      }
+      probe.stop();
+      return probe.port;
+    }
+  } finally {
+    for (const probe of held) probe.stop();
+  }
+};