@oxy.so/core 1.6.0 → 1.7.0

package/src/__tests__/httpServiceAbort.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Cancellation and timeout regressions.
+ *
+ * `HttpService` used to build its `AbortController` INSIDE the function
+ * `retryAsync` re-invokes, and link the caller's signal to each new controller
+ * with a bare `addEventListener`. Since `abort` is a once-only event, a signal
+ * that had already fired could not abort the controller built for attempt 2 —
+ * so a request the caller had CANCELLED was re-issued for real. A caller abort
+ * also reached the retry predicate as an `AbortError` carrying `status: 0`,
+ * which is not 4xx, so the predicate read it as a transient failure worth
+ * another try. With the 5s default timeout and 3 retries that is ~28s of work
+ * after the caller stopped waiting, inside a request queue ten slots deep.
+ *
+ * Every test here pins one half of "a cancellation is an instruction, not a
+ * failure": nothing retries it, nothing queues it, and nothing leaks after it.
+ */
+import { HttpService } from '../HttpService';
+import { ErrorCodes } from '../utils/errorUtils';
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify({ data }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/**
+ * A fetch that never responds, but DOES honour its abort signal — rejecting
+ * with an `AbortError` exactly as the real one does.
+ *
+ * Honouring the signal is not harness politeness, it is the whole point: the
+ * behaviour under test is what happens after an abort, so a fake that ignores
+ * the signal would hang instead of exercising it.
+ */
+function hangingFetch(): { fetch: typeof globalThis.fetch; calls: () => number } {
+  let calls = 0;
+  return {
+    fetch: ((_input: RequestInfo | URL, init?: RequestInit) => {
+      calls++;
+      return new Promise<Response>((_resolve, reject) => {
+        const signal = init?.signal;
+        const fail = (): void => reject(new DOMException('The operation was aborted.', 'AbortError'));
+        if (!signal) return;
+        if (signal.aborted) { fail(); return; }
+        signal.addEventListener('abort', fail, { once: true });
+      });
+    }) as typeof globalThis.fetch,
+    calls: () => calls,
+  };
+}
+
+/**
+ * Pin the retry backoff's jitter to zero.
+ *
+ * `retryAsync`'s delay is `baseDelay * 2**attempt + Math.random() * 1000`, so
+ * with real timers a retry can land up to a second later. A test that waits a
+ * fixed 80ms to prove "no retry happened" would then pass whether the bug was
+ * present or not — it would just be measuring the jitter. Pinning it makes the
+ * retry window exactly `baseDelay * (1 + 2 + 4)`, which a short wait covers
+ * decisively.
+ */
+function pinJitter(): void {
+  jest.spyOn(Math, 'random').mockReturnValue(0);
+}
+
+describe('HttpService cancellation', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.useRealTimers();
+  });
+
+  it('never calls fetch for a signal that was already aborted', async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => { calls++; return jsonResponse({}); }) as typeof globalThis.fetch;
+
+    const http = new HttpService({ baseURL: 'https://api.test' });
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(http.get('/thing', { signal: controller.signal })).rejects.toMatchObject({
+      code: ErrorCodes.CANCELLED,
+    });
+    expect(calls).toBe(0);
+  });
+
+  it('issues exactly one fetch when a request is cancelled mid-flight, with retry on', async () => {
+    pinJitter();
+    const { fetch, calls } = hangingFetch();
+    globalThis.fetch = fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 3,
+      retryDelay: 1,
+    });
+
+    const controller = new AbortController();
+    const pending = http.get('/thing', { signal: controller.signal });
+    const assertion = expect(pending).rejects.toMatchObject({ code: ErrorCodes.CANCELLED });
+
+    // Let the request reach fetch, then cancel it.
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(calls()).toBe(1);
+    controller.abort();
+    await assertion;
+
+    // The retry budget was 3 more attempts, whose backoff with jitter pinned is
+    // 1+2+4ms. Waiting well past that window is what proves none of them ran,
+    // and it is the crux of the defect: the re-issued request went out AFTER
+    // the rejection the caller saw, so a test that stopped at the rejection
+    // would have passed with the bug fully present.
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    expect(calls()).toBe(1);
+  });
+
+  it('leaves no abort listener on a caller signal that outlives the request', async () => {
+    globalThis.fetch = (async () => jsonResponse({ ok: true })) as typeof globalThis.fetch;
+
+    const controller = new AbortController();
+    const added: unknown[] = [];
+    const removed: unknown[] = [];
+    const realAdd = controller.signal.addEventListener.bind(controller.signal);
+    const realRemove = controller.signal.removeEventListener.bind(controller.signal);
+    jest.spyOn(controller.signal, 'addEventListener').mockImplementation(((type: string, fn: never, opts: never) => {
+      if (type === 'abort') added.push(fn);
+      return realAdd(type as 'abort', fn, opts);
+    }) as never);
+    jest.spyOn(controller.signal, 'removeEventListener').mockImplementation(((type: string, fn: never, opts: never) => {
+      if (type === 'abort') removed.push(fn);
+      return realRemove(type as 'abort', fn, opts);
+    }) as never);
+
+    const http = new HttpService({ baseURL: 'https://api.test' });
+    // A React Query query signal is reused across the query's whole lifetime,
+    // so a listener left behind per request is an unbounded leak, not a nit.
+    for (let i = 0; i < 5; i++) {
+      await http.get(`/thing-${i}`, { signal: controller.signal, cache: false, deduplicate: false });
+    }
+
+    expect(added.length).toBeGreaterThan(0);
+    expect(removed.length).toBe(added.length);
+  });
+
+  it('does not consume a queue slot for a cancelled request, so a live one still runs', async () => {
+    const live: string[] = [];
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/live')) {
+        live.push(url);
+        return jsonResponse({ ok: true });
+      }
+      // Cancelled requests never get here; if one does, it would hold a slot.
+      return new Promise<Response>(() => { /* never settles */ });
+    }) as typeof globalThis.fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      maxConcurrentRequests: 2,
+      enableRetry: false,
+    });
+
+    // Fill more than the pool with requests whose callers have already gone.
+    const dead = Array.from({ length: 6 }, (_, i) => {
+      const controller = new AbortController();
+      controller.abort();
+      return http.get(`/dead-${i}`, { signal: controller.signal }).catch(() => 'cancelled');
+    });
+    await Promise.all(dead);
+
+    // With only two slots, this is the assertion that matters: the live request
+    // is not queued behind six abandoned ones.
+    await expect(http.get('/live', { cache: false })).resolves.toBeDefined();
+    expect(live).toHaveLength(1);
+  });
+});
+
+describe('HttpService timeout', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.useRealTimers();
+  });
+
+  it('does not retry a timeout by default, and reports it as a timeout not a cancellation', async () => {
+    pinJitter();
+    const { fetch, calls } = hangingFetch();
+    globalThis.fetch = fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 3,
+      retryDelay: 1,
+      requestTimeout: 20,
+    });
+
+    await expect(http.get('/slow', { cache: false })).rejects.toMatchObject({
+      code: ErrorCodes.TIMEOUT,
+      timeout: true,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    // One attempt, not four. Four behind a short timeout is how a single slow
+    // endpoint used to cost tens of seconds of wall clock.
+    expect(calls()).toBe(1);
+  });
+
+  it('retries a timeout when the caller opts in', async () => {
+    const { fetch, calls } = hangingFetch();
+    globalThis.fetch = fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 2,
+      retryDelay: 1,
+      requestTimeout: 20,
+    });
+
+    await expect(
+      http.get('/slow', { cache: false, retryOnTimeout: true }),
+    ).rejects.toMatchObject({ code: ErrorCodes.TIMEOUT });
+
+    expect(calls()).toBe(3);
+  });
+
+  it('bounds total wall clock with a deadline, even with retries on', async () => {
+    pinJitter();
+    const { fetch } = hangingFetch();
+    globalThis.fetch = fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 5,
+      retryDelay: 100,
+      requestTimeout: 20,
+    });
+
+    const started = Date.now();
+    await expect(
+      http.get('/slow', { cache: false, retryOnTimeout: true, deadline: 150 }),
+    ).rejects.toBeDefined();
+
+    // `timeout` bounds an attempt; `deadline` bounds the call. Without it the
+    // total is attempts x timeout + backoff, which no call site computes.
+    expect(Date.now() - started).toBeLessThan(400);
+  });
+
+  it('still retries a 5xx — the fix must not disable retry wholesale', async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      return jsonResponse({ error: 'boom' }, 503);
+    }) as typeof globalThis.fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 2,
+      retryDelay: 1,
+    });
+
+    await expect(http.get('/flaky', { cache: false })).rejects.toBeDefined();
+    expect(calls).toBe(3);
+  });
+
+  it('still refuses to retry a 4xx', async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      return jsonResponse({ error: 'nope' }, 404);
+    }) as typeof globalThis.fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 3,
+      retryDelay: 1,
+    });
+
+    await expect(http.get('/missing', { cache: false })).rejects.toBeDefined();
+    expect(calls).toBe(1);
+  });
+
+  it('arms no timer past a request that threw before returning', async () => {
+    globalThis.fetch = (async () => jsonResponse({ error: 'nope' }, 404)) as typeof globalThis.fetch;
+    jest.useFakeTimers({ doNotFake: ['nextTick'] });
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: false,
+      requestTimeout: 30_000,
+    });
+
+    await expect(http.get('/missing', { cache: false })).rejects.toBeDefined();
+    // `clearTimeout` used to sit on the success path only, so any throw between
+    // the fetch and the return left a 30s timer armed.
+    expect(jest.getTimerCount()).toBe(0);
+    jest.useRealTimers();
+  });
+});

package/src/mixins/OxyServices.user.ts

@@ -202,8 +202,18 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
 
     /**
      * Search user profiles
+     *
+     * Takes an `AbortSignal` because people search is typed into: without one
+     * every keystroke started a search that ran to completion and had its
+     * result discarded, while holding one of the request queue's slots. It was
+     * the only search lane in Mention that could not be cancelled, purely
+     * because this signature had no way to say so.
      */
-    async searchProfiles(query: string, pagination?: PaginationParams): Promise<SearchProfilesResponse> {
+    async searchProfiles(
+      query: string,
+      pagination?: PaginationParams,
+      options?: { signal?: AbortSignal }
+    ): Promise<SearchProfilesResponse> {
       try {
         const response = await this.makeRequest<SearchProfilesResponse>(
           'GET',
@@ -212,6 +222,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
           {
             cache: true,
             cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+            signal: options?.signal,
           }
         );
 

package/src/server/__tests__/traffic.test.ts

@@ -1,6 +1,61 @@
 import { createEcosystemTraffic } from '../traffic';
 
-jest.mock('../../OxyServices', () => ({ OxyServices: jest.fn(() => ({})) }));
+/**
+ * Every client the publisher builds, so a test can ask what it was handed.
+ *
+ * Named `mock*` because ts-jest hoists `jest.mock` above the imports and only
+ * lets a factory close over a binding with that prefix.
+ */
+const mockClients: Array<{ configureServiceAuth: jest.Mock; getServiceToken: jest.Mock }> = [];
+
+jest.mock('../../OxyServices', () => ({
+  OxyServices: jest.fn(() => {
+    const client = {
+      configureServiceAuth: jest.fn(),
+      getServiceToken: jest.fn(async () => 'token-from-workload'),
+    };
+    mockClients.push(client);
+    return client;
+  }),
+}));
+
+function lastClient() {
+  const client = mockClients[mockClients.length - 1];
+  if (!client) throw new Error('No OxyServices was built.');
+  return client;
+}
+
+/** Accepts every publish and remembers the headers, so nothing reaches a network. */
+function recordingFetch(sent: RequestInit[]) {
+  return jest.fn(async (_input, init) => {
+    sent.push(init as RequestInit);
+    return new Response(null, { status: 204 });
+  }) as unknown as typeof fetch;
+}
+
+function authorizations(sent: RequestInit[]): string[] {
+  return sent.map(init => (init.headers as Record<string, string>).Authorization);
+}
+
+/**
+ * A process with nothing configured and nothing to attest: a laptop.
+ *
+ * Emptied by assignment rather than `delete`, which Biome refuses on a property
+ * access — and `= undefined` would be worse than either, because Node stores the
+ * STRING "undefined" and every check here would read it as a configured value.
+ */
+function clearCredentialEnvironment() {
+  process.env.OXY_ACTIVITY_API_KEY = '';
+  process.env.OXY_ACTIVITY_API_SECRET = '';
+  process.env.OXY_SERVICE_API_KEY = '';
+  process.env.OXY_SERVICE_API_SECRET = '';
+  process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '';
+  process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI = '';
+}
+
+beforeEach(() => {
+  mockClients.length = 0;
+});
 
 it('publishes independently of viewers and waits for registration before removing a stopped instance', async () => {
   const originalFetch = globalThis.fetch;
@@ -47,3 +102,79 @@ it('rejects a partial activity credential instead of mixing it with service cred
     process.env = previous;
   }
 });
+
+/**
+ * Who may publish ecosystem activity, and who is still refused.
+ *
+ * ADR 0026 made "no api key, no secret" a legitimate shape for a first-party
+ * service: it attests its ECS task role instead. This constructor used to throw
+ * on exactly that shape, so the migration it asks for — delete two variables
+ * from a task definition — killed the process at boot, the circuit breaker
+ * rolled the deploy back, and the operator was told the service was stable.
+ */
+describe('ecosystem activity credentials', () => {
+  const previous = { ...process.env };
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    process.env = { ...previous };
+    globalThis.fetch = originalFetch;
+  });
+
+  it('uses a service key pair when the process holds one', async () => {
+    clearCredentialEnvironment();
+    process.env.OXY_SERVICE_API_KEY = 'service-key';
+    process.env.OXY_SERVICE_API_SECRET = 'service-secret';
+    const sent: RequestInit[] = [];
+    globalThis.fetch = recordingFetch(sent);
+
+    const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2' });
+    await traffic.stop();
+
+    expect(lastClient().configureServiceAuth).toHaveBeenCalledWith('service-key', 'service-secret');
+    expect(lastClient().getServiceToken).toHaveBeenCalled();
+  });
+
+  it('lets an explicit credential win over the environment', async () => {
+    clearCredentialEnvironment();
+    process.env.OXY_SERVICE_API_KEY = 'service-key';
+    process.env.OXY_SERVICE_API_SECRET = 'service-secret';
+    const sent: RequestInit[] = [];
+    globalThis.fetch = recordingFetch(sent);
+
+    const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2', credential: async () => 'explicit-token' });
+    await traffic.stop();
+
+    expect(authorizations(sent)).not.toContain('Bearer token-from-workload');
+    expect(authorizations(sent)).toContain('Bearer explicit-token');
+    expect(lastClient().getServiceToken).not.toHaveBeenCalled();
+  });
+
+  it('refuses a process with no credential and nothing to attest', () => {
+    clearCredentialEnvironment();
+
+    // A laptop or a CI box: the container credentials endpoint is not going to
+    // appear later, so saying so at boot beats failing on the first heartbeat.
+    expect(() => createEcosystemTraffic({ service: 'homiio', region: 'us-west-2' })).toThrow(
+      /needs one of: an OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair, an OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET pair, or a workload identity/
+    );
+  });
+
+  it('publishes with no key pair at all when the process can attest its workload identity', async () => {
+    clearCredentialEnvironment();
+    // The variable ECS sets on every task, and nothing else does. Stubbed, so
+    // `canAttestWorkloadIdentity()` answers yes without a credentials endpoint.
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '/v2/credentials/abc';
+    const sent: RequestInit[] = [];
+    globalThis.fetch = recordingFetch(sent);
+
+    const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2' });
+    await traffic.stop();
+
+    // Unconfigured on purpose: that is what sends `getServiceToken()` down the
+    // workload path instead of handing it half a credential.
+    expect(lastClient().configureServiceAuth).not.toHaveBeenCalled();
+    expect(lastClient().getServiceToken).toHaveBeenCalled();
+    expect(authorizations(sent)).toContain('Bearer token-from-workload');
+  });
+});

package/src/server/traffic.ts

@@ -3,6 +3,12 @@ import { observeTrafficSocket, observeTrafficWebSocket, type TrafficWebSocket, t
 import { randomUUID } from 'node:crypto';
 import type { RequestHandler } from 'express';
 import { OxyServices } from '../OxyServices';
+// Static, unlike the lazy import in `mixins/OxyServices.auth.ts`: that module is
+// reachable from the root barrel, which ships to React Native, so pulling
+// `node:crypto` in eagerly there would cost every mobile bundle. This file is
+// server-only and the server barrel already exports `./workloadIdentity`, so
+// there is nothing here for a phone to load.
+import { canAttestWorkloadIdentity } from './workloadIdentity';
 import { createTrafficCollector, instrumentTrafficFetch, trafficMiddleware, type TrafficFlow, type ServiceEndpoint, resolveOxyServiceEndpoint, infrastructureLocation } from '@oxy.so/telemetry/collector';
 
 export interface EcosystemTrafficOptions {
@@ -36,8 +42,32 @@ export function createEcosystemTraffic(options: EcosystemTrafficOptions): {
   }
   const apiKey = activityKey || process.env.OXY_SERVICE_API_KEY;
   const apiSecret = activitySecret || process.env.OXY_SERVICE_API_SECRET;
-  if (!options.credential && (!apiKey || !apiSecret)) throw new Error('Ecosystem activity requires OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET');
+  /**
+   * Having no key pair is a legitimate configuration now — but only where this
+   * process can prove what it IS (ADR 0026).
+   *
+   * This used to throw on a missing pair, full stop. Every service in the fleet
+   * boots with `OXY_ECOSYSTEM_ACTIVITY_ENABLED=true`, so deleting
+   * `OXY_SERVICE_API_KEY` and `OXY_SERVICE_API_SECRET` from a task definition —
+   * which is the entire migration ADR 0026 asks for — killed the process at
+   * boot. The ECS circuit breaker then rolled the deploy back and reported the
+   * service stable, so the operator saw a rollback with nothing naming its
+   * cause. That is what one line cost, multiplied by fourteen services holding
+   * a secret they no longer need.
+   *
+   * What is still refused: nothing to authenticate with AND nothing to attest.
+   * That is a laptop or a CI box, where the container credentials endpoint is
+   * not going to turn up later, and the honest answer is to say so at boot
+   * rather than to fail on the first heartbeat.
+   */
+  if (!options.credential && (!apiKey || !apiSecret) && !canAttestWorkloadIdentity()) {
+    throw new Error(
+      'Ecosystem activity needs one of: an OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair, an OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET pair, or a workload identity this process can attest (ADR 0026).',
+    );
+  }
   const oxy = new OxyServices({ baseURL });
+  // Left unconfigured when there is no pair on purpose: `getServiceToken()`
+  // attests instead of being handed half a credential to fail on.
   if (apiKey && apiSecret) oxy.configureServiceAuth(apiKey, apiSecret);
   const credential = options.credential ?? (() => oxy.getServiceToken());
   const fetcher = globalThis.fetch.bind(globalThis);

package/src/utils/__tests__/asyncUtils.test.ts

@@ -1,5 +1,5 @@
 import { retryAsync } from '../asyncUtils';
-import { handleHttpError } from '../errorUtils';
+import { createCancelledError, ErrorCodes, handleHttpError } from '../errorUtils';
 
 /**
  * Regression coverage for the 1.11.11 retry storm:
@@ -185,3 +185,95 @@ describe('handleHttpError preserves HTTP status for retry predicates', () => {
     expect(result.code).toBe('INTERNAL_ERROR');
   });
 });
+
+describe('retryAsync refuses to retry a cancellation', () => {
+  it('stops after one attempt on a cancellation, whatever the retry budget', async () => {
+    const operation = jest.fn(async () => { throw createCancelledError(); });
+
+    await expect(retryAsync(operation, { maxRetries: 3, baseDelay: 1 })).rejects.toMatchObject({
+      code: ErrorCodes.CANCELLED,
+    });
+    // This is the defect in one assertion: a cancellation carries no HTTP
+    // status, `status: 0` is not 4xx, so the status-only predicate passed it
+    // into the retry loop and the SDK re-issued abandoned requests.
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+
+  it('refuses a cancellation even when a custom shouldRetry says yes', async () => {
+    const operation = jest.fn(async () => { throw createCancelledError(); });
+
+    await expect(
+      retryAsync(operation, { maxRetries: 3, baseDelay: 1, shouldRetry: () => true }),
+    ).rejects.toBeDefined();
+    // A custom predicate decides which FAILURES deserve another attempt. It has
+    // no business overriding an explicit instruction to stop.
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats a bare AbortError as a cancellation', async () => {
+    const operation = jest.fn(async () => {
+      throw new DOMException('The operation was aborted.', 'AbortError');
+    });
+
+    await expect(retryAsync(operation, { maxRetries: 3, baseDelay: 1 })).rejects.toBeDefined();
+    // An unclassified abort is assumed to be a cancellation: refusing to retry
+    // something abandoned costs nothing, retrying it is the bug.
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('retryAsync timeout policy', () => {
+  afterEach(() => { jest.restoreAllMocks(); });
+
+  const timeoutError = (): Error => {
+    const error = new Error('timed out') as Error & { code?: string; timeout?: boolean; status?: number };
+    error.code = ErrorCodes.TIMEOUT;
+    error.timeout = true;
+    error.status = 0;
+    return error;
+  };
+
+  it('does not retry a timeout by default', async () => {
+    const operation = jest.fn(async () => { throw timeoutError(); });
+
+    await expect(retryAsync(operation, { maxRetries: 3, baseDelay: 1 })).rejects.toBeDefined();
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries a timeout when asked to', async () => {
+    const operation = jest.fn(async () => { throw timeoutError(); });
+
+    await expect(
+      retryAsync(operation, { maxRetries: 2, baseDelay: 1, retryOnTimeout: true }),
+    ).rejects.toBeDefined();
+    expect(operation).toHaveBeenCalledTimes(3);
+  });
+
+  it('stops at the deadline rather than at the attempt budget', async () => {
+    // Jitter pinned so the backoff is exactly baseDelay * 2**attempt; otherwise
+    // this measures Math.random() rather than the deadline.
+    jest.spyOn(Math, 'random').mockReturnValue(0);
+    const operation = jest.fn(async () => { throw new Error('5xx-ish'); });
+
+    const started = Date.now();
+    await expect(
+      retryAsync(operation, { maxRetries: 10, baseDelay: 50, deadline: Date.now() + 120 }),
+    ).rejects.toBeDefined();
+
+    // The point of a deadline: the wall clock a caller feels is bounded by a
+    // budget it stated, not by arithmetic over attempts x timeout + backoff.
+    expect(Date.now() - started).toBeLessThan(400);
+    expect(operation.mock.calls.length).toBeLessThan(11);
+  });
+});
+
+describe('retryAsync keeps its positional signature working', () => {
+  it('accepts the legacy (operation, maxRetries, baseDelay, shouldRetry) call', async () => {
+    const operation = jest.fn(async () => { throw new Error('transient'); });
+
+    await expect(retryAsync(operation, 2, 1)).rejects.toThrow('transient');
+    // In-tree callers pass positionally, so the options object had to be an
+    // overload rather than a replacement.
+    expect(operation).toHaveBeenCalledTimes(3);
+  });
+});