@distilled.cloud/core 0.16.2 → 0.16.3

package/src/client.ts

@@ -25,11 +25,13 @@
  * const result = yield* fn({ organization: "my-org" });
  * ```
  */
-import * as Duration from "effect/Duration";
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import { pipe } from "effect/Function";
+import * as Option from "effect/Option";
 import { pipeArguments } from "effect/Pipeable";
 import { MinimumLogLevel } from "effect/References";
-import * as Schedule from "effect/Schedule";
+import * as Ref from "effect/Ref";
 import * as Schema from "effect/Schema";
 import * as AST from "effect/SchemaAST";
 import * as Stream from "effect/Stream";
@@ -45,7 +47,7 @@ import {
   type PaginatedTrait,
   type PaginationStrategy,
 } from "./pagination.ts";
-import * as Category from "./category.ts";
+import { makeDefault, type Policy as RetryPolicy } from "./retry.ts";
 import * as Traits from "./traits.ts";
 import { getPath } from "./traits.ts";
 
@@ -143,11 +145,21 @@ export interface ClientConfig<Creds> {
    *  Should return Effect.fail(error) for known errors,
    *  or Effect.fail(fallbackError) for unknown errors.
    *  The optional `errors` parameter provides per-operation typed error classes.
+   *  The optional `headers` parameter is the response header bag (lowercase
+   *  keys) — for retryable status codes, pass `retryAfter: parseRetryAfterForStatus(status, headers)`
+   *  from `@distilled.cloud/core/retry-after` when a standard `Retry-After` /
+   *  `RateLimit` hint is present; omit `retryAfter` when there is no hint (the
+   *  default retry policy still uses exponential backoff). The status-gated
+   *  helper avoids attaching stale `retryAfter` to non-retryable classes
+   *  (BadRequest/401/404/etc.). The maximum honored hint is capped (default
+   *  60s) — override with \`DISTILLED_SERVER_RETRY_HINT_CAP_MS\` or provide
+   *  \`ServerRetryHintCapMs\` via \`Layer\` from \`@distilled.cloud/core/retry\`.
    */
   matchError: (
     status: number,
     body: unknown,
     errors?: readonly ApiErrorClass[],
+    headers?: Record<string, string | undefined>,
   ) => Effect.Effect<never, unknown>;
 
   /** Parse error class for schema decode failures */
@@ -169,6 +181,20 @@ export interface ClientConfig<Creds> {
     pathTemplate: string;
     parts: Traits.RequestParts;
   }) => Traits.RequestParts;
+
+  /**
+   * The SDK's `Retry` Context.Service tag. Each per-SDK client wires its
+   * own tag here so callers can install a blanket policy at the layer
+   * level (e.g. `myEffect.pipe(Cloudflare.Retry.transient)`) and have
+   * every API call below it pick it up — same pattern as
+   * `packages/aws/src/client/api.ts`.
+   *
+   * `makeAPI` reads the policy via `Effect.serviceOption(retry)` on every
+   * call and falls back to `Retry.makeDefault` (transient/throttling/server
+   * with capped exponential backoff + jitter, 5 attempts) when no policy
+   * is provided.
+   */
+  retry: Context.Key<any, RetryPolicy>;
 }
 
 /**
@@ -408,19 +434,6 @@ export const makeAPI = <Creds>(config: ClientConfig<Creds>) => {
 
       const method = httpTrait.method;
 
-      // Capped exponential backoff bounded to 8 attempts so a
-      // pathologically rate-limited endpoint can't hang a test run.
-      // Effect 4's `Schedule.exponential(base, factor)` already produces
-      // delays of base, base*factor, base*factor^2, ...; combined with
-      // `Schedule.both(Schedule.recurs(8))` to cap retries. We don't
-      // currently honour Retry-After (would require a per-attempt Ref);
-      // the exponential ramp is conservative enough for the rate limits
-      // we hit in practice.
-      const throttlingRetrySchedule = Schedule.both(
-        Schedule.exponential(Duration.seconds(1), 2),
-        Schedule.recurs(8),
-      );
-
       const spanName = `${method} ${httpTrait.path}`;
 
       const innerFn = (input: Input): Effect.Effect<any, any, any> =>
@@ -603,6 +616,7 @@ export const makeAPI = <Creds>(config: ClientConfig<Creds>) => {
               response.status,
               errorBody,
               opConfig.errors,
+              response.headers,
             );
           }
 
@@ -651,6 +665,7 @@ export const makeAPI = <Creds>(config: ClientConfig<Creds>) => {
                 response.status,
                 envelope,
                 opConfig.errors,
+                response.headers,
               );
             }
             responseBody = envelope?.data ?? null;
@@ -697,18 +712,39 @@ export const makeAPI = <Creds>(config: ClientConfig<Creds>) => {
           );
         });
 
-      // Auto-retry whenever the SDK's matchError returns a typed error
-      // tagged with the throttling category (e.g. `TooManyRequests`,
-      // or any SDK-specific subclass marked with `withThrottlingError`
-      // / `withRetryable({ throttling: true })`). After retries are
-      // exhausted the original typed error propagates to the caller as
-      // usual.
+      // Auto-retry every operation using the SDK's per-client `Retry`
+      // Context.Service. The policy is read with `Effect.serviceOption`
+      // and falls back to `Retry.makeDefault` (transient/throttling/server
+      // errors with capped exponential backoff + jitter, 5 attempts) when
+      // no policy has been provided in context. This mirrors the AWS
+      // pattern in `packages/aws/src/client/api.ts` and lets callers
+      // install a blanket policy at the layer level instead of wrapping
+      // every call site with `Effect.retry(...)`.
+      const retryTag = config.retry;
       const fn = (input: Input): Effect.Effect<any, any, any> => {
-        const withRetry = innerFn(input).pipe(
-          Effect.retry({
-            schedule: throttlingRetrySchedule,
-            while: (e) => Category.isThrottling(e),
-          }),
+        const withRetry = Effect.gen(function* () {
+          const lastError = yield* Ref.make<unknown>(undefined);
+          const policy = (yield* Effect.serviceOption(retryTag)).pipe(
+            Option.map((value) =>
+              typeof value === "function" ? value(lastError) : value,
+            ),
+            Option.getOrElse(() => makeDefault(lastError)),
+          );
+
+          return yield* pipe(
+            innerFn(input),
+            Effect.tapError((error) => Ref.set(lastError, error)),
+            policy.while
+              ? (eff) =>
+                  Effect.retry(eff, {
+                    while: policy.while,
+                    schedule: policy.schedule,
+                  })
+              : (eff) => eff,
+          );
+        });
+
+        const withSpan = withRetry.pipe(
           Effect.withSpan(spanName, {
             attributes: {
               "http.method": method,
@@ -717,8 +753,8 @@ export const makeAPI = <Creds>(config: ClientConfig<Creds>) => {
           }),
         );
         return distilledDebugEnv
-          ? Effect.provideService(withRetry, MinimumLogLevel, "Debug")
-          : withRetry;
+          ? Effect.provideService(withSpan, MinimumLogLevel, "Debug")
+          : withSpan;
       };
 
       const Proto = {

package/src/errors.ts

@@ -5,9 +5,27 @@
  * using the category system. This module provides base error types and utilities
  * that are used across all SDKs.
  */
+import * as Duration from "effect/Duration";
 import * as Schema from "effect/Schema";
 import * as Category from "./category.ts";
 
+// ============================================================================
+// Shared Schema Helpers
+// ============================================================================
+
+/**
+ * Opaque schema for an Effect `Duration.Duration` value.
+ *
+ * Used on retryable errors to carry a server-provided wait hint (e.g. parsed
+ * from `Retry-After` or the IETF `Ratelimit` header). Core does not encode/decode
+ * this field over the wire — it is constructed at runtime by `matchError` from
+ * whatever the service actually returns (delay-seconds, HTTP-date, epoch, etc.)
+ * and consumed at runtime by the retry policy.
+ */
+export const DurationSchema = Schema.declare<Duration.Duration>(
+  Duration.isDuration,
+);
+
 // ============================================================================
 // Common HTTP Status Error Classes
 // ============================================================================
@@ -63,7 +81,10 @@ export class UnprocessableEntity extends Schema.TaggedErrorClass<UnprocessableEn
  */
 export class TooManyRequests extends Schema.TaggedErrorClass<TooManyRequests>()(
   "TooManyRequests",
-  { message: Schema.String },
+  {
+    message: Schema.String,
+    retryAfter: Schema.optional(DurationSchema),
+  },
 ).pipe(
   Category.withThrottlingError,
   Category.withRetryable({ throttling: true }),
@@ -74,6 +95,7 @@ export class TooManyRequests extends Schema.TaggedErrorClass<TooManyRequests>()(
  */
 export class Locked extends Schema.TaggedErrorClass<Locked>()("Locked", {
   message: Schema.String,
+  retryAfter: Schema.optional(DurationSchema),
 }).pipe(Category.withLockedError, Category.withRetryable()) {}
 
 /**
@@ -81,7 +103,10 @@ export class Locked extends Schema.TaggedErrorClass<Locked>()("Locked", {
  */
 export class InternalServerError extends Schema.TaggedErrorClass<InternalServerError>()(
   "InternalServerError",
-  { message: Schema.String },
+  {
+    message: Schema.String,
+    retryAfter: Schema.optional(DurationSchema),
+  },
 ).pipe(Category.withServerError, Category.withRetryable()) {}
 
 /**
@@ -89,7 +114,10 @@ export class InternalServerError extends Schema.TaggedErrorClass<InternalServerE
  */
 export class BadGateway extends Schema.TaggedErrorClass<BadGateway>()(
   "BadGateway",
-  { message: Schema.String },
+  {
+    message: Schema.String,
+    retryAfter: Schema.optional(DurationSchema),
+  },
 ).pipe(Category.withServerError, Category.withRetryable()) {}
 
 /**
@@ -97,7 +125,10 @@ export class BadGateway extends Schema.TaggedErrorClass<BadGateway>()(
  */
 export class ServiceUnavailable extends Schema.TaggedErrorClass<ServiceUnavailable>()(
   "ServiceUnavailable",
-  { message: Schema.String },
+  {
+    message: Schema.String,
+    retryAfter: Schema.optional(DurationSchema),
+  },
 ).pipe(Category.withServerError, Category.withRetryable()) {}
 
 /**
@@ -105,7 +136,10 @@ export class ServiceUnavailable extends Schema.TaggedErrorClass<ServiceUnavailab
  */
 export class GatewayTimeout extends Schema.TaggedErrorClass<GatewayTimeout>()(
   "GatewayTimeout",
-  { message: Schema.String },
+  {
+    message: Schema.String,
+    retryAfter: Schema.optional(DurationSchema),
+  },
 ).pipe(Category.withServerError, Category.withRetryable()) {}
 
 /**
@@ -144,6 +178,18 @@ export const HTTP_STATUS_MAP = {
  */
 export const DEFAULT_ERROR_STATUSES = new Set([401, 429, 500, 502, 503, 504]);
 
+/**
+ * HTTP status codes whose corresponding error class in {@link HTTP_STATUS_MAP}
+ * declares a `retryAfter` field. The retry policy honors `error.retryAfter`
+ * with precedence over the default backoff for these.
+ *
+ * `matchError` implementations should only pass `retryAfter` into the
+ * constructor when the status is in this set; passing it on non-retryable
+ * classes (BadRequest/Unauthorized/etc.) would silently retain it as a
+ * stale field on the instance and pollute serialized output.
+ */
+export const RETRYABLE_HTTP_STATUSES = new Set([423, 429, 500, 502, 503, 504]);
+
 /**
  * All common API error classes.
  */

package/src/retry-after.ts

@@ -0,0 +1,131 @@
+/**
+ * Server-provided retry hint parsing.
+ *
+ * Standardizes parsing of:
+ *   - `Retry-After` (RFC 7231 §7.1.3): `delay-seconds` (integer) or `HTTP-date`.
+ *   - `RateLimit` (IETF draft-ietf-httpapi-ratelimit-headers): structured
+ *     dictionary `r=<remaining>, t=<seconds-until-reset>`.
+ *
+ * Each SDK's `matchError` calls these helpers and attaches the resulting
+ * `Duration` to retryable errors via the optional `retryAfter` field, where
+ * the retry policy will honor it with precedence over the default backoff.
+ *
+ * Services that use bespoke headers or body fields are expected to do their
+ * own parsing in the SDK's `matchError`, optionally falling back to these
+ * helpers for the standard cases.
+ */
+import * as Duration from "effect/Duration";
+import { RETRYABLE_HTTP_STATUSES } from "./errors.ts";
+
+/**
+ * Header bag — case-insensitive lookup is the caller's responsibility.
+ *
+ * The helpers in this module read lowercase keys (`retry-after`, `ratelimit`)
+ * because most HTTP clients normalize headers to lowercase. If your client
+ * preserves case, normalize before passing in.
+ */
+export type Headers = Record<string, string | undefined> | undefined;
+
+/**
+ * Parse the standard `Retry-After` HTTP header per RFC 7231 §7.1.3.
+ *
+ * Accepts either a non-negative integer number of seconds (the common case)
+ * or an HTTP-date. HTTP-dates in the past produce a zero duration.
+ *
+ * Returns `undefined` when the header is missing or unparseable.
+ */
+export const parseRetryAfter = (
+  headers: Headers,
+): Duration.Duration | undefined => {
+  const raw = headers?.["retry-after"];
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return undefined;
+
+  // delay-seconds: 1*DIGIT (non-negative decimal integer per RFC).
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+      return Duration.seconds(seconds);
+    }
+  }
+
+  // Reject anything that *looks* numeric but isn't a valid delay-seconds.
+  // Without this, `Date.parse("-5")` happens to return 0 on some engines and
+  // would silently yield a zero-duration instead of the expected undefined.
+  if (/^[-+]?\d+(?:\.\d+)?$/.test(trimmed)) return undefined;
+
+  // HTTP-date: try Date.parse, which handles RFC 1123 / RFC 850 / asctime.
+  const ts = Date.parse(trimmed);
+  if (!Number.isNaN(ts)) {
+    const ms = Math.max(0, ts - Date.now());
+    return Duration.millis(ms);
+  }
+
+  return undefined;
+};
+
+/**
+ * Parse the IETF `RateLimit` structured header.
+ *
+ * Examples:
+ *   `RateLimit: limit=100, remaining=0, reset=30`           (older draft)
+ *   `RateLimit: "default";r=0;t=30`                          (newer draft)
+ *   `RateLimit: r=0, t=30`                                   (compact form)
+ *
+ * Returns the `t` (seconds until reset) value as a Duration, but only when
+ * `r` (remaining quota) is present and equals `0` — i.e., we're actually
+ * rate-limited right now. Returns `undefined` otherwise.
+ */
+export const parseRatelimit = (
+  headers: Headers,
+): Duration.Duration | undefined => {
+  const raw = headers?.["ratelimit"];
+  if (!raw) return undefined;
+
+  let remaining: number | undefined;
+  let reset: number | undefined;
+
+  // Tokenize on commas and semicolons; tolerate `key=value` and `key =value`.
+  for (const piece of raw.split(/[,;]/)) {
+    const eq = piece.indexOf("=");
+    if (eq < 0) continue;
+    const key = piece.slice(0, eq).trim().toLowerCase();
+    const value = piece.slice(eq + 1).trim();
+    const num = Number(value);
+    if (!Number.isFinite(num)) continue;
+
+    if (key === "r" || key === "remaining") remaining = num;
+    else if (key === "t" || key === "reset") reset = num;
+  }
+
+  if (remaining !== undefined && remaining > 0) return undefined;
+  if (reset === undefined || reset < 0) return undefined;
+  return Duration.seconds(reset);
+};
+
+/**
+ * Convenience: try `Retry-After` first, then `RateLimit`. Returns the first
+ * successful parse, or `undefined` if neither header yields a usable value.
+ */
+export const parseServerRetryHint = (
+  headers: Headers,
+): Duration.Duration | undefined =>
+  parseRetryAfter(headers) ?? parseRatelimit(headers);
+
+/**
+ * Status-gated variant of {@link parseServerRetryHint}. Returns `undefined`
+ * unless `status` is one whose error class actually declares a `retryAfter`
+ * field (see `RETRYABLE_HTTP_STATUSES`). Use this in `matchError` when you
+ * dispatch off a generic `HTTP_STATUS_MAP` lookup that includes both
+ * retryable (429/5xx/423) and non-retryable (4xx) classes — it prevents
+ * stale `retryAfter` properties from being attached to errors like
+ * `BadRequest` or `NotFound` (which would otherwise leak into JSON output).
+ */
+export const parseRetryAfterForStatus = (
+  status: number,
+  headers: Headers,
+): Duration.Duration | undefined => {
+  if (!RETRYABLE_HTTP_STATUSES.has(status)) return undefined;
+  return parseServerRetryHint(headers);
+};

package/src/retry.ts

@@ -2,24 +2,16 @@
  * Retry Policy System
  *
  * Provides configurable retry policies for API operations.
- * Each SDK creates its own Retry service tag but uses these shared utilities
- * for building retry schedules and policies.
- *
- * @example
- * ```ts
- * import * as Retry from "@distilled.cloud/core/retry";
- *
- * // Use the default retry policy
- * myEffect.pipe(Retry.policy(myRetryService, Retry.makeDefault()))
- *
- * // Disable retries
- * myEffect.pipe(Retry.none(myRetryService))
- * ```
+ * Each SDK creates its own `Retry` Context.Service tag (via
+ * `makeRetryService`) and threads it into `makeAPI({ retry: <SDK>.Retry })`
+ * so that callers can install a blanket retry policy at the layer level
+ * for that SDK without wrapping every call with `Effect.retry`.
  */
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import { pipe } from "effect/Function";
 import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
 import * as Schedule from "effect/Schedule";
 import * as Context from "effect/Context";
@@ -60,36 +52,19 @@ export type Policy = Options | Factory;
 
 /**
  * Create a typed Retry service class for an SDK.
- * Each SDK should create its own Retry service using this factory.
+ * Each SDK creates its own Retry service using this factory; the SDK's
+ * client wraps `makeAPI` with `retry: <SDK>.Retry` so the policy applies
+ * to every API call below it.
  *
  * @example
  * ```ts
- * // In planetscale-sdk/src/retry.ts
+ * // packages/<sdk>/src/retry.ts
  * export class Retry extends makeRetryService("PlanetScaleRetry") {}
  * ```
  */
 export const makeRetryService = (name: string) =>
   Context.Service<any, Policy>()(name);
 
-/**
- * Provides a custom retry policy for API calls.
- */
-export const policy =
-  (Service: any, optionsOrFactory: Policy) =>
-  <A, E, R>(effect: Effect.Effect<A, E, R>) =>
-    Effect.provide(effect, Layer.succeed(Service, optionsOrFactory) as any);
-
-/**
- * Disables all automatic retries.
- */
-export const none =
-  (Service: any) =>
-  <A, E, R>(effect: Effect.Effect<A, E, R>) =>
-    Effect.provide(
-      effect,
-      Layer.succeed(Service, { while: () => false }) as any,
-    );
-
 // ============================================================================
 // Retry Schedule Utilities
 // ============================================================================
@@ -112,6 +87,110 @@ export const capped = (max: Duration.Duration) =>
     ),
   );
 
+// ============================================================================
+// Server Hint Helpers
+// ============================================================================
+
+/**
+ * Default cap (milliseconds) on how long we'll honor a server-provided
+ * `Retry-After` / `RateLimit` hint. A misbehaving server can otherwise park
+ * us forever.
+ */
+export const DEFAULT_SERVER_RETRY_HINT_CAP_MS = 60_000;
+
+const ENV_SERVER_RETRY_HINT_CAP_MS = "DISTILLED_SERVER_RETRY_HINT_CAP_MS";
+
+/**
+ * Optional override for the server-hint cap, in milliseconds. When provided
+ * via `Layer.succeed(ServerRetryHintCapMs, n)`, that value wins over the
+ * environment.
+ *
+ * @example
+ * ```ts
+ * Effect.retry(op, policy).pipe(
+ *   Effect.provide(serverRetryHintCapLayer(120_000)),
+ * )
+ * ```
+ */
+export const ServerRetryHintCapMs = Context.Service<number>(
+  "@distilled.cloud/core/ServerRetryHintCapMs",
+);
+
+/**
+ * Layer that pins the server `retryAfter` cap to a fixed value (milliseconds).
+ */
+export const serverRetryHintCapLayer = (capMs: number) =>
+  Layer.succeed(ServerRetryHintCapMs, capMs);
+
+/**
+ * Effective cap when neither {@link ServerRetryHintCapMs} nor
+ * `DISTILLED_SERVER_RETRY_HINT_CAP_MS` is set: {@link DEFAULT_SERVER_RETRY_HINT_CAP_MS}.
+ *
+ * Reads `process.env.DISTILLED_SERVER_RETRY_HINT_CAP_MS` when present (must be
+ * a non-negative finite integer; invalid values are ignored). Undefined
+ * `process` (some edge runtimes) falls back to the default.
+ */
+export const readServerRetryHintCapMsFromEnv = (): number => {
+  if (typeof process === "undefined" || process.env === undefined) {
+    return DEFAULT_SERVER_RETRY_HINT_CAP_MS;
+  }
+  const raw = process.env[ENV_SERVER_RETRY_HINT_CAP_MS];
+  if (raw === undefined || raw === "") return DEFAULT_SERVER_RETRY_HINT_CAP_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_SERVER_RETRY_HINT_CAP_MS;
+  return Math.trunc(n);
+};
+
+const resolveServerRetryHintCapMs = (): Effect.Effect<number, never, never> =>
+  Effect.gen(function* () {
+    const fromLayer = yield* Effect.serviceOption(ServerRetryHintCapMs);
+    return Option.match(fromLayer, {
+      onNone: () => readServerRetryHintCapMsFromEnv(),
+      onSome: (n) =>
+        Number.isFinite(n) && n >= 0
+          ? Math.trunc(n)
+          : readServerRetryHintCapMsFromEnv(),
+    });
+  });
+
+/**
+ * Extract a server-provided retry hint (in milliseconds) from an error's
+ * optional `retryAfter` field, capped by the effective server-hint cap
+ * (see {@link ServerRetryHintCapMs} and {@link readServerRetryHintCapMsFromEnv}).
+ *
+ * Returns `undefined` when the error doesn't carry a hint.
+ */
+const serverHintMillis = (
+  error: unknown,
+  capMs: number,
+): number | undefined => {
+  const hint = (error as { retryAfter?: unknown } | null | undefined)
+    ?.retryAfter;
+  if (!Duration.isDuration(hint)) return undefined;
+  return Math.min(Duration.toMillis(hint), capMs);
+};
+
+/**
+ * Schedule modifier that honors `error.retryAfter` (set by the SDK's
+ * `matchError` from `Retry-After` / `RateLimit` headers) with precedence
+ * over the input delay. Falls back to the original delay when no hint is
+ * present.
+ */
+const honorServerHint = (
+  lastError: Ref.Ref<unknown>,
+  baseline?: (duration: Duration.Duration, error: unknown) => Duration.Duration,
+) =>
+  Schedule.modifyDelay(
+    Effect.fnUntraced(function* (duration: Duration.Duration) {
+      const capMs = yield* resolveServerRetryHintCapMs();
+      const error = yield* Ref.get(lastError);
+      const hint = serverHintMillis(error, capMs);
+      if (hint !== undefined) return hint;
+      const adjusted = baseline ? baseline(duration, error) : duration;
+      return Duration.toMillis(adjusted);
+    }),
+  );
+
 // ============================================================================
 // Default Retry Policies
 // ============================================================================
@@ -121,7 +200,10 @@ export const capped = (max: Duration.Duration) =>
  *
  * This policy:
  * - Retries transient errors (throttling, server, network, locked errors)
- * - Uses exponential backoff starting at 100ms with a factor of 2
+ * - Honors `error.retryAfter` (server-provided hint) with precedence, capped
+ *   by {@link DEFAULT_SERVER_RETRY_HINT_CAP_MS} by default; override with
+ *   `DISTILLED_SERVER_RETRY_HINT_CAP_MS` or {@link ServerRetryHintCapMs}
+ * - Otherwise uses exponential backoff starting at 100ms with a factor of 2
  * - Ensures at least 500ms delay for throttling errors
  * - Limits to 5 retry attempts
  * - Applies jitter to avoid thundering herd
@@ -130,24 +212,37 @@ export const makeDefault: Factory = (lastError) => ({
   while: (error) => isTransientError(error),
   schedule: pipe(
     Schedule.exponential(100, 2),
-    Schedule.modifyDelay(
-      Effect.fnUntraced(function* (duration) {
-        const error = yield* Ref.get(lastError);
-        if (isThrottling(error)) {
-          if (Duration.toMillis(duration) < 500) {
-            return Duration.toMillis(Duration.millis(500));
-          }
-        }
-        return Duration.toMillis(duration);
-      }),
-    ),
+    honorServerHint(lastError, (duration, error) => {
+      if (isThrottling(error) && Duration.toMillis(duration) < 500) {
+        return Duration.millis(500);
+      }
+      return duration;
+    }),
     Schedule.both(Schedule.recurs(5)),
     jittered,
   ),
 });
 
+/**
+ * Factory for the throttling-only retry policy. Honors server hints when
+ * present so callers using `<SDK>.Retry.throttling` get correct backoff.
+ */
+export const throttlingFactory: Factory = (lastError) => ({
+  while: (error) => isThrottling(error),
+  schedule: pipe(
+    Schedule.exponential(1000, 2),
+    honorServerHint(lastError),
+    capped(Duration.seconds(5)),
+    jittered,
+  ),
+});
+
 /**
  * Retry options that retries all throttling errors indefinitely.
+ *
+ * Note: prefer {@link throttlingFactory} when you want server-hint honoring.
+ * This static `Options` form does not have access to `lastError` and so
+ * cannot read `error.retryAfter`.
  */
 export const throttlingOptions: Options = {
   while: (error) => isThrottling(error),
@@ -158,6 +253,20 @@ export const throttlingOptions: Options = {
   ),
 };
 
+/**
+ * Factory for the transient retry policy. Honors server hints when present
+ * so callers using `<SDK>.Retry.transient` get correct backoff.
+ */
+export const transientFactory: Factory = (lastError) => ({
+  while: isTransientError,
+  schedule: pipe(
+    Schedule.exponential(1000, 2),
+    honorServerHint(lastError),
+    capped(Duration.seconds(5)),
+    jittered,
+  ),
+});
+
 /**
  * Retry options that retries all transient errors indefinitely.
  *
@@ -166,6 +275,8 @@ export const throttlingOptions: Options = {
  * 2. Server errors
  * 3. Network errors
  * 4. Locked errors (423)
+ *
+ * Note: prefer {@link transientFactory} when you want server-hint honoring.
  */
 export const transientOptions: Options = {
   while: isTransientError,