Implement a bounded retry policy

Implement the retry policy and reproduce the fixture decisions. Explain how it fits into a deadline-aware executor, how SDK retries are accounted for, and what changes after a partial streamed response or an uncertain write.

The teaching policy permits at most three total attempts. It retries only explicitly classified transient failures when replay is safe. It uses capped exponential backoff with full jitter and respects a normalized retry-after delay as a minimum wait.

Before scheduling a retry, it requires enough remaining time for the delay plus a configured minimum useful attempt window. This check does not guarantee that the next request will finish. The runtime must still enforce the actual deadline.

The provider's raw Retry-After value may be a duration or date depending on the protocol. Parsing and validation happen before this pure policy function receives a nonnegative delay in milliseconds.

The policy is a pure function. The caller passes the failure classification, the number of attempts already made (including the one that just failed), the time left before the task deadline, and a random value for jitter. Nothing inside it sleeps, reads a clock, or generates randomness, so every decision is reproducible.

type Failure = {
  transient: boolean;
  safeToRetry: boolean;
  retryAfterMs?: number;
};
type Policy = {
  maxAttempts: number;
  baseDelayMs: number;
  maxDelayMs: number;
  minimumAttemptMs: number;
};
type Decision =
  | { retry: true; delayMs: number }
  | { retry: false; reason: "unsafe" | "permanent" | "attempts" | "deadline" };

// Throws on a negative or non-finite duration, an attempt count that is not a
// positive integer, a random value outside [0, 1), or a zero minimumAttemptMs.
// Then stops, in order, for unsafe replay, permanent failure, and used-up attempts.
// Otherwise:
//   ceiling = min(maxDelayMs, baseDelayMs * 2 ** (completedAttempts - 1))
//   delayMs = max(floor(random * ceiling), retryAfterMs ?? 0)
// and stops for "deadline" when delayMs + minimumAttemptMs > remainingMs.
declare function decideRetry(
  failure: Failure,
  completedAttempts: number,
  remainingMs: number,
  random: number,
  policy: Policy
): Decision;

const policy: Policy = {
  maxAttempts: 3, baseDelayMs: 200, maxDelayMs: 1000, minimumAttemptMs: 300
};