webhook-delivery-engine 0.0.0-stage → 1.0.0

package/dist/src/app/lifecycle.js

@@ -0,0 +1,138 @@
+/**
+ * Coordinates a clean process exit on SIGINT or SIGTERM.
+ *
+ * Responsibilities (WBS 4.2):
+ * 1. Register one-time SIGINT and SIGTERM handlers via `register()`.
+ * 2. On signal (or direct `shutdown()` call): stop the scheduler so no new
+ *    events are claimed.
+ * 3. Call `DatabaseAdapter.releaseEventLease` for every event that was claimed
+ *    but whose dispatch has not yet started, returning those leases to the
+ *    `pending` state so they are picked up on the next startup.
+ * 4. Remain idempotent — duplicate signals or `shutdown()` calls run the
+ *    shutdown sequence exactly once.
+ *
+ * The lifecycle module does NOT implement the poll loop itself (WBS 4.1), does
+ * NOT dispatch events, and does NOT know about HMAC signing or HTTP transport.
+ *
+ * ### Lease tracking contract
+ *
+ * When the scheduler claims an event and hands it to the worker seam, callers
+ * should immediately call `trackClaimed(event)`. When network dispatch starts,
+ * call `trackDispatch(event.id, work)` to move the event from releasable claims
+ * to work that shutdown must drain. `untrackClaimed` remains available for
+ * callers that only need claim release tracking.
+ */
+export class GracefulShutdown {
+    scheduler;
+    adapter;
+    /**
+     * Events that have been claimed by the scheduler but have not yet started
+     * network dispatch. Keyed by event id for O(1) lookup and removal.
+     */
+    pendingClaims = new Map();
+    /** Dispatches that crossed the network-start boundary and must be drained. */
+    activeDispatches = new Set();
+    /** Whether the shutdown sequence has been started (guards idempotency). */
+    shuttingDown = false;
+    /** Shared completion promise so concurrent stop calls await the same drain. */
+    shutdownPromise = null;
+    /** Whether `register()` has been called (guards duplicate listener registration). */
+    registered = false;
+    /**
+     * Creates a lifecycle coordinator for the given scheduler and adapter.
+     *
+     * @param scheduler - The running poll loop to stop on shutdown.
+     * @param adapter - Adapter used to release unclaimed-dispatch leases.
+     */
+    constructor(scheduler, adapter) {
+        this.scheduler = scheduler;
+        this.adapter = adapter;
+    }
+    /**
+     * Registers one-time SIGINT and SIGTERM listeners on `process`.
+     *
+     * Safe to call multiple times — only one pair of listeners is ever added.
+     * Each signal triggers `shutdown()` which is itself idempotent.
+     */
+    register() {
+        if (this.registered)
+            return;
+        this.registered = true;
+        const handle = () => {
+            void this.shutdown();
+        };
+        process.on('SIGINT', handle);
+        process.on('SIGTERM', handle);
+    }
+    /**
+     * Marks an event as claimed-but-not-dispatched.
+     *
+     * Call this immediately after the scheduler hands an event to the worker
+     * seam so that a concurrent or subsequent `shutdown()` can release its
+     * lease.
+     *
+     * @param event - The claimed event to track.
+     */
+    trackClaimed(event) {
+        this.pendingClaims.set(event.id, event);
+    }
+    /**
+     * Removes an event from the pending-claim tracking set.
+     *
+     * Call this when the worker begins actual network dispatch for an event.
+     * After removal, `shutdown()` will not attempt to release that lease —
+     * the stale-lease recovery mechanism will handle it if the process aborts
+     * mid-dispatch.
+     *
+     * @param eventId - Id of the event whose dispatch has started.
+     */
+    untrackClaimed(eventId) {
+        this.pendingClaims.delete(eventId);
+    }
+    /**
+     * Marks dispatch as started and tracks its completion for shutdown.
+     * The lease is no longer eligible for release once network dispatch begins.
+     */
+    trackDispatch(eventId, dispatch) {
+        this.pendingClaims.delete(eventId);
+        const tracked = dispatch.then(() => undefined, () => undefined);
+        this.activeDispatches.add(tracked);
+        void tracked.then(() => this.activeDispatches.delete(tracked));
+    }
+    /**
+     * Executes the graceful shutdown sequence exactly once.
+     *
+     * 1. Stops the scheduler (no new claims after this point).
+     * 2. Releases the leases of all still-tracked (not-yet-dispatched) events
+     *    by calling `releaseEventLease` for each. Failures for individual events
+     *    are swallowed so that the remaining releases still run; those events
+     *    will be recovered by the stale-lease mechanism on next startup.
+     *
+     * Safe to call multiple times — subsequent calls resolve immediately.
+     *
+     * @returns A promise that resolves when the shutdown sequence completes.
+     */
+    async shutdown() {
+        if (this.shuttingDown)
+            return this.shutdownPromise;
+        this.shuttingDown = true;
+        this.shutdownPromise = this.drainAndRelease();
+        return this.shutdownPromise;
+    }
+    async drainAndRelease() {
+        await this.scheduler.stop();
+        const releasedAt = new Date().toISOString();
+        const releasePromises = Array.from(this.pendingClaims.values()).map((event) => this.adapter
+            .releaseEventLease({
+            eventId: event.id,
+            workerId: event.lockedBy ?? '',
+            releasedAt,
+        })
+            .catch(() => {
+            // Failed releases remain recoverable through stale-lease recovery.
+        }));
+        await Promise.allSettled(releasePromises);
+        this.pendingClaims.clear();
+        await Promise.all(Array.from(this.activeDispatches));
+    }
+}

package/dist/src/config/engine.config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Worker and polling limits used by the engine.
+ *
+ * Every value must be a positive safe integer. `batchSize` must be greater
+ * than zero and should not exceed the adapter's practical claim limit.
+ */
+export interface EngineConcurrency {
+    /** Maximum number of events processed concurrently. */
+    readonly workerCount: number;
+    /** Maximum number of events claimed in one poll cycle. */
+    readonly batchSize: number;
+    /** Milliseconds between scheduler polls when no work is immediately due. */
+    readonly pollIntervalMs: number;
+}
+/**
+ * Bounded exponential retry policy used after retryable delivery failures.
+ *
+ * Delay before jitter is `min(baseDelayMs * 2 ** (attempt - 1), maxDelayMs)`;
+ * full jitter selects a delay from zero through that bound.
+ */
+export interface RetryPolicy {
+    /** Maximum number of dispatch attempts before terminal exhaustion. */
+    readonly maxAttempts: number;
+    /** Initial exponential backoff bound in milliseconds. */
+    readonly baseDelayMs: number;
+    /** Maximum exponential backoff bound in milliseconds. */
+    readonly maxDelayMs: number;
+}
+/**
+ * Immutable runtime configuration required by the delivery engine.
+ *
+ * Configuration providers validate positive safe-integer limits and require
+ * `retry.maxDelayMs >= retry.baseDelayMs` before the engine starts. Documented
+ * SDD v1 defaults are batch size 10, a 10,000 ms request timeout, 5 attempts,
+ * and 1,000/60,000 ms retry bounds; worker count and poll interval remain
+ * provider-selected values.
+ */
+export interface EngineConfig {
+    /** Bounded worker and polling concurrency controls. */
+    readonly concurrency: EngineConcurrency;
+    /** Maximum duration of a single outbound HTTP request in milliseconds. */
+    readonly timeoutLimitMs: number;
+    /** Retry ceiling and bounded exponential backoff settings. */
+    readonly retry: RetryPolicy;
+}

package/dist/src/config/engine.config.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/errors.d.ts

@@ -0,0 +1,4 @@
+/** A caller supplied an invalid opaque event-list cursor. */
+export declare class InvalidPageCursorError extends TypeError {
+    constructor(options?: ErrorOptions);
+}

package/dist/src/core/errors.js

@@ -0,0 +1,7 @@
+/** A caller supplied an invalid opaque event-list cursor. */
+export class InvalidPageCursorError extends TypeError {
+    constructor(options) {
+        super('cursor must be a valid event page cursor.', options);
+        this.name = 'InvalidPageCursorError';
+    }
+}

package/dist/src/core/ports.d.ts

@@ -0,0 +1,217 @@
+import type { AttemptRecord, EventStatus, Timestamp, WebhookEvent } from './types.js';
+/**
+ * The event returned from an idempotent upsert.
+ *
+ * When `inserted` is false, `event` is the existing row identified by the
+ * same `(clientId, idempotencyKey)` pair.
+ */
+export interface EventUpsertResult {
+    /** Newly inserted event or the existing idempotent match. */
+    readonly event: WebhookEvent;
+    /** Whether this call inserted a new event row. */
+    readonly inserted: boolean;
+}
+/**
+ * Parameters for atomically claiming a batch of due events.
+ */
+export interface ClaimDueEventsInput {
+    /** Unique identifier persisted on each claimed lease. */
+    readonly workerId: string;
+    /** UTC reference time used to determine which events are due. */
+    readonly now: Timestamp;
+    /** Maximum number of eligible events to claim. */
+    readonly limit: number;
+}
+/**
+ * Parameters for atomically returning expired processing leases to the retry
+ * queue.
+ *
+ * The adapter calculates the cutoff as
+ * `now - max(timeoutLimitMs + 30000, 90000)` and schedules recovered events
+ * for `now + 10000` milliseconds. A lease exactly at the cutoff is not stale.
+ */
+export interface RecoverStaleLeasesInput {
+    /** UTC reference time used for the cutoff and retry schedule. */
+    readonly now: Timestamp;
+    /** Configured per-request timeout in milliseconds; must be a positive safe integer. */
+    readonly timeoutLimitMs: number;
+}
+/**
+ * Parameters for releasing an unstarted claim during graceful shutdown.
+ *
+ * The adapter only releases a lease owned by `workerId`; it restores the event
+ * to `pending`, clears its lease, and reverses the attempt reservation made
+ * when the event was claimed.
+ */
+export interface ReleaseEventLeaseInput {
+    /** Identifier of the event whose lease is being released. */
+    readonly eventId: string;
+    /** Worker identifier that must still own the event lease. */
+    readonly workerId: string;
+    /** UTC time at which the lease is released. */
+    readonly releasedAt: Timestamp;
+}
+/**
+ * Parameters for atomically appending an attempt and changing its event state.
+ *
+ * The `nextRetryAt` invariant is enforced by the discriminated union: retry
+ * transitions require a timestamp, while terminal transitions require null.
+ */
+export type RecordAttemptAndTransitionInput = {
+    /** Attempt row to append for the event. */
+    readonly attempt: AttemptRecord & {
+        readonly outcome: 'success';
+    };
+    /** Worker that must own the event lease. */
+    readonly workerId: string;
+    /** Successful attempts transition the event to delivered. */
+    readonly nextStatus: 'delivered';
+    /** Successful terminal delivery does not schedule a retry. */
+    readonly nextRetryAt: null;
+    /** UTC time at which the event state change is recorded. */
+    readonly updatedAt: Timestamp;
+} | {
+    /** Attempt row to append for the event. */
+    readonly attempt: AttemptRecord & {
+        readonly outcome: 'retry_scheduled';
+    };
+    /** Worker that must own the event lease. */
+    readonly workerId: string;
+    /** A retryable attempt transitions the event to retry. */
+    readonly nextStatus: 'retry';
+    /** Time at or after which the retry may be claimed. */
+    readonly nextRetryAt: Timestamp;
+    /** UTC time at which the event state change is recorded. */
+    readonly updatedAt: Timestamp;
+} | {
+    /** Attempt row to append for the event. */
+    readonly attempt: AttemptRecord & {
+        readonly outcome: 'exhausted';
+    };
+    /** Worker that must own the event lease. */
+    readonly workerId: string;
+    /** Terminal unsuccessful attempts transition the event to failed. */
+    readonly nextStatus: 'failed';
+    /** Terminal failure does not schedule a retry. */
+    readonly nextRetryAt: null;
+    /** UTC time at which the event state change is recorded. */
+    readonly updatedAt: Timestamp;
+};
+/**
+ * Tenant-scoped event page query with optional status filtering and cursor
+ * pagination.
+ */
+export interface ListEventsInput {
+    /** Tenant that owns all returned rows. */
+    readonly clientId: string;
+    /** Optional lifecycle state to filter by. */
+    readonly status?: EventStatus;
+    /** Maximum number of events to return. */
+    readonly limit: number;
+    /** Opaque cursor from the preceding page, if one exists. */
+    readonly cursor?: string;
+}
+/**
+ * A page of events and the opaque cursor for the next page, when available.
+ */
+export interface EventPage {
+    /** Tenant-scoped events in deterministic creation order. */
+    readonly items: readonly WebhookEvent[];
+    /** Cursor for the next page, or null when the result set is exhausted. */
+    readonly nextCursor: string | null;
+}
+/**
+ * Persistence boundary used by engine modules without depending on a database
+ * driver.
+ *
+ * Implementations must use parameterized statements and preserve the
+ * idempotency, tenant-isolation, lease-ownership, and append-only attempt
+ * invariants described by each operation. Rejected promises represent
+ * persistence failures and must not be converted to successful fallback
+ * values.
+ */
+export interface DatabaseAdapter {
+    /**
+     * Inserts an event or returns the existing event for the same tenant/key
+     * pair without creating a duplicate.
+     *
+     * @param event Complete validated event to insert.
+     * @returns The inserted event or its idempotent existing match.
+     */
+    upsertEvent(event: WebhookEvent): Promise<EventUpsertResult>;
+    /**
+     * Atomically claims up to `limit` due pending/retry events for one worker.
+     *
+     * A successful claim sets `processing`, stamps the lease, and increments the
+     * dispatch attempt counter in the same atomic database operation.
+     *
+     * @param input Claim owner, reference time, and maximum batch size.
+     * @returns The claimed events with their updated lease and attempt state.
+     */
+    claimDueEvents(input: ClaimDueEventsInput): Promise<readonly WebhookEvent[]>;
+    /**
+     * Atomically returns processing events with expired leases to the retry
+     * queue and clears their lease fields.
+     *
+     * @param input UTC reference time and per-request timeout used to derive the
+     * stale cutoff and retry schedule.
+     * @returns The number of leases recovered.
+     */
+    recoverStaleLeases(input: RecoverStaleLeasesInput): Promise<number>;
+    /**
+     * Releases a worker-owned event lease that has not started network dispatch.
+     *
+     * The event returns to `pending` and its claim-reserved attempt count is
+     * reversed; a lease owned by a different worker must remain unchanged.
+     *
+     * @param input Event, expected lease owner, and release timestamp.
+     * @returns Whether the adapter released the matching lease.
+     */
+    releaseEventLease(input: ReleaseEventLeaseInput): Promise<boolean>;
+    /**
+     * Appends the attempt and applies the resulting event transition atomically.
+     *
+     * The adapter must verify lease ownership, ensure the attempt belongs to the
+     * event and is the next 1-based ordinal, match the attempt outcome to the
+     * target event state, append no duplicate audit row, and clear the lease as
+     * part of a successful transition. If the worker no longer owns the lease,
+     * neither the attempt nor transition is written.
+     *
+     * @param input Attempt details, expected lease owner, and resulting state.
+     * @returns Whether the attempt and state transition were committed.
+     */
+    recordAttemptAndTransition(input: RecordAttemptAndTransitionInput): Promise<boolean>;
+    /**
+     * Finds one event while enforcing its tenant boundary.
+     *
+     * @param eventId System-generated event identifier.
+     * @param clientId Configured tenant that must own the event.
+     * @returns The tenant-owned event, or null when not found.
+     */
+    findEventById(eventId: string, clientId: string): Promise<WebhookEvent | null>;
+    /**
+     * Finds an event by its tenant-scoped idempotency key.
+     *
+     * @param clientId Configured tenant that owns the idempotency namespace.
+     * @param idempotencyKey Client-supplied key to find.
+     * @returns The matching tenant-owned event, or null when not found.
+     */
+    findEventByIdempotencyKey(clientId: string, idempotencyKey: string): Promise<WebhookEvent | null>;
+    /**
+     * Lists events with tenant filtering, optional status filtering, and a
+     * bounded cursor page.
+     *
+     * @param input Tenant identity and page constraints.
+     * @returns A deterministic page containing only the requested tenant's rows.
+     */
+    listEvents(input: ListEventsInput): Promise<EventPage>;
+    /**
+     * Reads a tenant-owned event's append-only attempt history in attempt-number
+     * order. Implementations must enforce ownership in the database query.
+     *
+     * @param eventId Identifier of the event whose attempts are requested.
+     * @param clientId Configured tenant that must own the event.
+     * @returns The event's attempts ordered by their 1-based ordinal.
+     */
+    listAttempts(eventId: string, clientId: string): Promise<readonly AttemptRecord[]>;
+}

package/dist/src/core/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * A JSON-compatible scalar value.
+ */
+export type JsonPrimitive = string | number | boolean | null;
+/**
+ * A JSON value whose arrays and object properties are readonly. Numbers must
+ * be finite values to remain valid JSON.
+ */
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * An immutable UTC timestamp encoded as an ISO-8601 string.
+ *
+ * Values crossing a persistence boundary must be normalized to UTC and remain
+ * parseable by the JavaScript `Date` constructor.
+ */
+export type Timestamp = string;
+/**
+ * Lifecycle states persisted for a webhook event.
+ */
+export declare const EVENT_STATUSES: readonly ["pending", "processing", "delivered", "retry", "failed"];
+export type EventStatus = (typeof EVENT_STATUSES)[number];
+/**
+ * Result recorded for a delivery attempt. `exhausted` means the event reached
+ * a terminal unsuccessful state, either through a permanent response or by
+ * reaching the configured retry limit.
+ */
+export declare const ATTEMPT_OUTCOMES: readonly ["success", "retry_scheduled", "exhausted"];
+export type AttemptOutcome = (typeof ATTEMPT_OUTCOMES)[number];
+/**
+ * Durable webhook delivery work together with its immutable input and lease
+ * state.
+ *
+ * `attemptCount` is the number of dispatch attempts started, `nextRetryAt` is
+ * null when no retry is scheduled, and the lease fields are both null unless
+ * the event is being processed. `metadata`, `payload`, and `headers` are
+ * readonly data; engine-owned signing and event-identification headers must
+ * not be overridden by values in `headers`.
+ */
+export interface WebhookEvent {
+    /** System-generated, non-enumerable event identifier. */
+    readonly id: string;
+    /** Client-supplied key, unique within `clientId`. */
+    readonly idempotencyKey: string;
+    /** Host-configured tenant identifier used for all tenant-scoped reads. */
+    readonly clientId: string;
+    /** Fully qualified destination URL validated before persistence. */
+    readonly destinationUrl: string;
+    /** JSON body data delivered to the consumer. */
+    readonly payload: JsonValue;
+    /** Additional immutable JSON context associated with the event. */
+    readonly metadata: Readonly<Record<string, JsonValue>>;
+    /** Event-specific outbound headers, excluding reserved engine-owned names. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Current durable lifecycle state. */
+    readonly status: EventStatus;
+    /** Number of delivery attempts started for this event. */
+    readonly attemptCount: number;
+    /** Time at or after which a retry may be claimed, or null when not scheduled. */
+    readonly nextRetryAt: Timestamp | null;
+    /** Time at which the current processing lease was acquired, if any. */
+    readonly lockedAt: Timestamp | null;
+    /** Identifier of the worker holding the current lease, if any. */
+    readonly lockedBy: string | null;
+    /** Time at which the event was first persisted. */
+    readonly createdAt: Timestamp;
+    /** Time at which the event was most recently changed. */
+    readonly updatedAt: Timestamp;
+}
+/**
+ * Append-only audit data for one outbound delivery attempt.
+ *
+ * The attempt ordinal is 1-based. `statusCode` is null when no HTTP response
+ * was received, `responseSnippet` is null when no response body exists and
+ * must be bounded to at most 1 KB, and `error` contains a non-secret
+ * description when dispatch failed.
+ */
+export interface AttemptRecord {
+    /** Adapter-generated identifier for this audit row. */
+    readonly id: string;
+    /** Identifier of the event that was dispatched. */
+    readonly eventId: string;
+    /** 1-based ordinal matching the event's dispatch attempt counter. */
+    readonly attemptNumber: number;
+    /** UTC time at which this dispatch attempt began. */
+    readonly attemptedAt: Timestamp;
+    /** HTTP response status, or null when transport failed before a response. */
+    readonly statusCode: number | null;
+    /** Secret-free response excerpt bounded to at most 1 KB, if available. */
+    readonly responseSnippet: string | null;
+    /** Non-secret transport or delivery error description, if any. */
+    readonly error: string | null;
+    /** Round-trip duration in milliseconds, or null if it was not measured. */
+    readonly latencyMs: number | null;
+    /** Delivery result used to determine the event's next lifecycle state. */
+    readonly outcome: AttemptOutcome;
+}

package/dist/src/core/types.js

@@ -0,0 +1,10 @@
+/**
+ * Lifecycle states persisted for a webhook event.
+ */
+export const EVENT_STATUSES = ['pending', 'processing', 'delivered', 'retry', 'failed'];
+/**
+ * Result recorded for a delivery attempt. `exhausted` means the event reached
+ * a terminal unsuccessful state, either through a permanent response or by
+ * reaching the configured retry limit.
+ */
+export const ATTEMPT_OUTCOMES = ['success', 'retry_scheduled', 'exhausted'];

package/dist/src/features/delivery/delivery.backoff.d.ts

@@ -0,0 +1,74 @@
+import type { Timestamp } from '../../core/types.js';
+/**
+ * Input for one backoff calculation.
+ */
+export interface BackoffInput {
+    /**
+     * 1-based dispatch attempt number for the event.
+     *
+     * Must be a positive safe integer (≥ 1).
+     */
+    readonly attempt: number;
+    /**
+     * Initial exponential backoff bound in milliseconds.
+     *
+     * The uncapped delay for attempt `n` is `baseDelayMs * 2^(n - 1)`.
+     * Must be a positive safe integer.
+     */
+    readonly baseDelayMs: number;
+    /**
+     * Maximum exponential backoff bound in milliseconds.
+     *
+     * The delay is capped at this value before full jitter is applied.
+     * Must be a positive safe integer ≥ `baseDelayMs`.
+     */
+    readonly maxDelayMs: number;
+    /**
+     * UTC reference time for computing `nextRetryAt`.
+     *
+     * Must be a valid ISO-8601 timestamp string.
+     */
+    readonly now: Timestamp;
+}
+/**
+ * Result of a single backoff calculation.
+ */
+export interface BackoffResult {
+    /**
+     * UTC ISO-8601 timestamp at or after which the event may next be claimed.
+     *
+     * Computed as `now + floor(Math.random() * cap)` where
+     * `cap = min(baseDelayMs * 2^(attempt - 1), maxDelayMs)`.
+     */
+    readonly nextRetryAt: Timestamp;
+}
+/**
+ * Computes the next retry timestamp using bounded exponential backoff with
+ * full jitter.
+ *
+ * ### Algorithm
+ *
+ * ```
+ * cap          = min(baseDelayMs * 2^(attempt - 1), maxDelayMs)
+ * actualDelay  = floor(Math.random() * cap)   // full jitter: uniform [0, cap)
+ * nextRetryAt  = now + actualDelay
+ * ```
+ *
+ * Full jitter prevents thundering-herd on struggling endpoints by spreading
+ * retries uniformly across the entire backoff window rather than clustering
+ * them near the cap (R5, §10 trade-offs).
+ *
+ * `Math.random()` returns values in [0, 1). When the mock returns exactly 1
+ * in tests, `floor(1 * cap)` equals `cap`, which is why the tests that pass
+ * `mockReturnValue(1)` expect the full cap as the delay. In production the
+ * max actual delay is `cap - 1` ms due to `Math.random() < 1`.
+ *
+ * @param input - Attempt number, policy bounds, and UTC reference time.
+ * @returns The ISO-8601 timestamp at or after which the retry may be claimed.
+ * @throws {RangeError} When `attempt` is not a positive safe integer.
+ * @throws {RangeError} When `baseDelayMs` is not a positive safe integer.
+ * @throws {RangeError} When `maxDelayMs < baseDelayMs` or not a positive safe
+ * integer.
+ * @throws {TypeError} When `now` is not a valid ISO-8601 timestamp.
+ */
+export declare function calculateNextRetryAt(input: BackoffInput): BackoffResult;

package/dist/src/features/delivery/delivery.backoff.js

@@ -0,0 +1,56 @@
+/**
+ * Computes the next retry timestamp using bounded exponential backoff with
+ * full jitter.
+ *
+ * ### Algorithm
+ *
+ * ```
+ * cap          = min(baseDelayMs * 2^(attempt - 1), maxDelayMs)
+ * actualDelay  = floor(Math.random() * cap)   // full jitter: uniform [0, cap)
+ * nextRetryAt  = now + actualDelay
+ * ```
+ *
+ * Full jitter prevents thundering-herd on struggling endpoints by spreading
+ * retries uniformly across the entire backoff window rather than clustering
+ * them near the cap (R5, §10 trade-offs).
+ *
+ * `Math.random()` returns values in [0, 1). When the mock returns exactly 1
+ * in tests, `floor(1 * cap)` equals `cap`, which is why the tests that pass
+ * `mockReturnValue(1)` expect the full cap as the delay. In production the
+ * max actual delay is `cap - 1` ms due to `Math.random() < 1`.
+ *
+ * @param input - Attempt number, policy bounds, and UTC reference time.
+ * @returns The ISO-8601 timestamp at or after which the retry may be claimed.
+ * @throws {RangeError} When `attempt` is not a positive safe integer.
+ * @throws {RangeError} When `baseDelayMs` is not a positive safe integer.
+ * @throws {RangeError} When `maxDelayMs < baseDelayMs` or not a positive safe
+ * integer.
+ * @throws {TypeError} When `now` is not a valid ISO-8601 timestamp.
+ */
+export function calculateNextRetryAt(input) {
+    if (!Number.isSafeInteger(input.attempt) || input.attempt < 1) {
+        throw new RangeError('attempt must be a positive safe integer (≥ 1).');
+    }
+    if (!Number.isSafeInteger(input.baseDelayMs) || input.baseDelayMs <= 0) {
+        throw new RangeError('baseDelayMs must be a positive safe integer.');
+    }
+    if (!Number.isSafeInteger(input.maxDelayMs) || input.maxDelayMs <= 0) {
+        throw new RangeError('maxDelayMs must be a positive safe integer.');
+    }
+    if (input.maxDelayMs < input.baseDelayMs) {
+        throw new RangeError('maxDelayMs must be greater than or equal to baseDelayMs.');
+    }
+    const nowMs = Date.parse(input.now);
+    if (!Number.isFinite(nowMs)) {
+        throw new TypeError('now must be a valid ISO-8601 timestamp.');
+    }
+    // Compute the exponential cap, guarding against overflow for large attempts.
+    const exponent = input.attempt - 1;
+    const uncapped = exponent >= 53 ? Number.MAX_SAFE_INTEGER : input.baseDelayMs * Math.pow(2, exponent);
+    const cap = Math.min(uncapped, input.maxDelayMs);
+    // Full jitter: uniform random delay in [0, cap].
+    const actualDelay = Math.floor(Math.random() * (cap + 1));
+    const clampedDelay = Math.min(actualDelay, cap);
+    const nextRetryAt = new Date(nowMs + clampedDelay).toISOString();
+    return { nextRetryAt };
+}