actly 1.1.5 → 1.3.0

package/README.md

@@ -1,611 +1,517 @@
 # actly
 
-**Reliability primitive for async functions.**
-Retry. Timeout. Dedupe. Cache. Composable, typed, zero-throw — with proper `AbortSignal` cancellation, single-flight cache, LRU store, and jittered backoff.
+A typed reliability kernel for async TypeScript. Retry, timeout, circuit breaker, bulkhead, rate limit, dedupe, cache, hedge, fallback, and graceful shutdown, all composed through one `act()` call that never rejects.
 
 ```bash
 npm install actly
 ```
 
-> Requires Node 18+. Ships ESM + CJS. Zero dependencies.
+Node 20+. ESM + CJS. Zero runtime deps. 57 KB tarball, 243 KB JS runtime (335 KB installed with type defs). 12 policies in one `act()` call.
 
----
-
-## The problem
-
-Every async call can fail. Networks blip. Services time out. The same UI mounts three times and fires the same fetch in parallel. You need retry logic, but not for 4xx errors. You need timeouts, but not the kind that let retry loops run forever.
-
-These patterns are solved the same way every time. `actly` solves them once.
-
----
+> **Bundle note:** This is ~4× larger than [Cockatiel](https://github.com/vjkramer/cockatiel) (63 KB JS) because actly ships cache, dedupe, rate limit, hedge, audit log, multi-tenant isolation, drain, watchdog, and health check in the same package. If you only need retry/timeout/circuit-breaker/bulkhead/fallback and bundle size is critical, use Cockatiel. If you want the broader policy surface in one call, the size delta is the cost.
 
 ## Quick start
 
 ```ts
 import { act } from 'actly'
 
-const result = await act(
-  'user:42',
-  async (signal) => fetch(`/api/users/42`, { signal }),
-  {
-    retry:        { attempts: 3, delayMs: 200, backoff: 'exponential' },
-    timeout:      { ms: 5_000 },
-    totalTimeout: { ms: 12_000 },
-    dedupe:       true,
-    cache:        { ttl: 60_000 },
-  },
-)
+const r = await act('user:42', async (signal) => {
+  const res = await fetch('/api/users/42', { signal })
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  return res.json()
+}, {
+  retry: { attempts: 3, delayMs: 200, backoff: 'exponential' },
+  timeout: { ms: 5_000 },
+  totalTimeout: { ms: 12_000 },
+  cache: { ttl: 60_000 },
+})
 
-if (result.ok) {
-  console.log(result.value)    // T
-  console.log(result.source)   // 'fresh' | 'cache'
-  console.log(result.attempts) // number (0 on cache hit)
+if (r.ok) {
+  console.log(r.value, r.source, r.attempts, r.durationMs)
 } else {
-  console.error(result.error)  // unknown — never throws
+  console.error(r.error)
 }
 ```
 
-`act` always resolves. It never rejects. You check `.ok` and move on.
+`act()` always resolves. You branch on `r.ok` instead of try/catch around `await`. Failures are typed (see [Errors](#errors)) so you can switch on `r.error.code` for telemetry.
+
+## Features
+
+- **Retry** with exponential/linear/constant backoff, four jitter modes, custom `backoffFn` with per-call state, and `shouldRetryResult` for retrying on returned values (HTTP 500 without throwing)
+- **Per-attempt timeout** with `race` (aggressive) or `cooperative` (gentle) strategies
+- **Total timeout** spanning the whole retry loop, not just one attempt
+- **Circuit breaker** with `consecutive` or `count` (sliding-window ratio) strategies, half-open probe, idle reset
+- **Bulkhead** with bounded queue, queue timeout, backpressure event
+- **Rate limit** (sliding window, per key)
+- **Cache** with stampede protection (single-flight on sync stores), TTL, LRU eviction
+- **Dedupe** (single-flight) with generation-safe cleanup and joiner isolation
+- **Hedge** with cancel-loser semantics, `outside-retry` (one hedge per call) or `inside-retry` (one per attempt) placement
+- **Fallback** value or function
+- **AbortSignal** cancellation everywhere, with cross-realm duck-typed signal support
+- **Observability** hooks (10 event types) wrapped in `safeCall` so a buggy hook never crashes the main path
+- **Health check**, **watchdog** for hung calls, **graceful drain** for shutdown
+- **Multi-tenant** store isolation with LRU eviction
+- **Pluggable state store** (built-in `InMemoryStore`; bring your own for Redis, DynamoDB, etc.)
+- **`@usePolicy`** method decorator
+- Typed error taxonomy with stable `.code` strings for cross-realm handling
 
-The `signal` passed to `fn` is your escape hatch: wire it through to `fetch`, `AbortController`, database drivers, or any primitive that accepts one. If a timeout fires (per-attempt or total), or the caller aborts via `options.signal`, `fn`'s signal aborts and the operation rejects promptly — no leaked resources, no hung retry loops.
+## API
 
----
+### `act(key, fn, options?)`
 
-## API
+Wraps `fn` with reliability policies. Returns `Promise<ActResult<T>>`, always resolves.
 
 ```ts
-act<T>(key: string, fn: ActFn<T>, options?: ActOptions): Promise<ActResult<T>>
-```
-
-| Argument | Type | Description |
-|---|---|---|
-| `key` | `string` | Stable, unique identifier. Scopes dedupe and cache state. Must be non-empty and must not start with reserved prefixes (`dedupe:`, `cache:`, `__inflight:`). |
-| `fn` | `(signal: AbortSignal) => Promise<T> \| T` | The async function to execute. Receives an `AbortSignal` for cooperative cancellation. Backwards compatible: `() => Promise<T>` is accepted (the signal is simply ignored). |
-| `options` | `ActOptions` | All optional. See policies below. |
+interface ActSuccess<T> {
+  ok: true
+  value: T
+  source: 'fresh' | 'cache'
+  attempts: number       // 1-based; 0 on cache hit
+  traceId?: string
+  durationMs?: number
+}
 
-### Result shape
+interface ActFailure {
+  ok: false
+  error: unknown         // see Errors
+  attempts: number
+  traceId?: string
+  durationMs?: number
+}
 
-```ts
-type ActResult<T> =
-  | { ok: true;  value: T; source: 'fresh' | 'cache'; attempts: number }
-  | { ok: false; error: unknown;                       attempts: number }
+type ActResult<T> = ActSuccess<T> | ActFailure
 ```
 
-`attempts` semantics:
-- Fresh success on first try: `1`
-- Fresh success after N retries: `N`
-- Cache hit: `0` (no work was performed)
-- Dedupe joiner: mirrors the originator's attempt count (v1.1.5 fix — see changelog)
+`key` scopes dedupe and cache. Validated for prototype pollution, control chars, CRLF, length (1024 max), and reserved prefixes (`dedupe:`, `cache:`, `inflight:`, `tenant:`).
 
----
+### `invalidate(key)`
 
-## Policies
+Removes the cached value for `key` from the default store. Returns `true` if a cache entry was removed.
 
-All policies are optional and compose freely. The execution order is **fixed**:
-
-```
-totalTimeout → cache → dedupe → retry → timeout
+```ts
+await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
+invalidate('user:42')  // next call re-fetches
 ```
 
-### Retry
+### `withStore(store)`
+
+Returns a scoped `act` bound to an explicit store. Use for SSR request isolation, multi-tenant scenarios, or tests.
 
 ```ts
-const result = await act('payments:charge', async (signal) => chargeCard(payload, signal), {
-  retry: {
-    attempts: 3,            // total attempts (including first). Must be integer >= 1.
-    delayMs:  200,          // base delay between attempts (ms)
-    backoff:  'exponential',// 'none' | 'linear' | 'exponential'
-    maxDelay: 30_000,       // cap (ms) — prevents 8.5-minute waits on long exponential chains
-    jitter:   'full',       // 'none' | 'full' | 'equal' | 'decorrelated' (default: 'full')
-  },
-})
-```
+import { withStore, InMemoryStore } from 'actly'
 
-`result.attempts` tells you how many tries it took.
+const store = new InMemoryStore({ maxSize: 1000, autoCleanup: true })
+const act = withStore(store)
 
-#### Jitter (default: `'full'`)
+try {
+  await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
+  act.invalidate('user:42')
+} finally {
+  store.destroy()
+}
+```
 
-Jitter prevents thundering-herd retry storms when many callers fail simultaneously. Without jitter, all callers retry on the same tick after an upstream outage recovers. The default `'full'` jitter randomises each delay to `[0, computed]`.
+The scoped `act` has the same signature as the default `act`, plus an `invalidate(key)` method, a `store` property, and a `scope` property (the internal scope string for `createHealthCheck`).
 
-| Strategy | Formula |
-|---|---|
-| `'none'` | `delay` |
-| `'full'` | `random() * delay` |
-| `'equal'` | `delay/2 + random() * delay/2` |
-| `'decorrelated'` | `base + random() * (delay - base)` |
+### `execute(input)`
 
-#### Selective retry with `shouldRetry`
+Low-level execution engine for custom policy chains. Accepts `{ key, fn, policies, store, meta, signal, observability }`. Most callers should use `act()`.
 
-By default, `actly` retries on every error EXCEPT `AbortError` (which indicates the caller or a timeout cancelled the operation — retrying would just abort again). Use `shouldRetry` to skip retrying other permanent errors — a `404` will never recover, a `503` might.
+### `noopPolicy()`
+
+Passthrough policy. No retry, no timeout, no state. Useful for testing and conditional chains.
 
 ```ts
-const result = await act('api:resource', async (signal) => fetchResource(id, signal), {
-  retry: {
-    attempts: 4,
-    delayMs:  150,
-    backoff:  'exponential',
-    shouldRetry: (err, attempt) => {
-      if (err instanceof HttpError && err.status < 500) return false
-      return true
-    },
-  },
-})
+const retry = isProd
+  ? retryPolicy({ attempts: 3 })
+  : noopPolicy()
 ```
 
-`shouldRetry(error, attempt)` receives the error and the 1-based attempt number. Return `false` to surface the error immediately.
+### `usePolicy(options)`
 
-> **v1.1.5 change:** `shouldRetry` is now called on EVERY failure, including the final attempt. This preserves the predicate's contract for observers / metrics. The return value is only consulted when there are remaining attempts.
+Method decorator. Wraps a class method with `act()`. Preserves `this` and the method `name`.
 
----
+```ts
+import { usePolicy } from 'actly'
+
+class UserService {
+  @usePolicy({ retry: { attempts: 3, delayMs: 100 }, timeout: { ms: 5000 } })
+  async fetchUser(signal: AbortSignal, id: string): Promise<User> {
+    const res = await fetch(`/api/users/${id}`, { signal })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    return res.json()
+  }
+}
+```
 
-### Timeout
+### `createHealthCheck(store, options?)`
 
-Per-attempt deadline. Each retry gets a fresh clock. Implemented via `AbortController` + race — `act()` returns promptly even if `fn` ignores the signal (the underlying work may continue in the background, but the caller is unblocked).
+Returns a function that produces a `HealthStatus` snapshot.
 
 ```ts
-import { act, TimeoutError } from 'actly'
+import { createHealthCheck, InMemoryStore } from 'actly'
 
-const result = await act('geo:lookup', async (signal) => lookupCoords(ip, signal), {
-  timeout: { ms: 3_000 },
+const store = new InMemoryStore()
+const health = createHealthCheck(store, {
+  scope: 'default',
+  probeIntervalMs: 30_000,  // optional: warn on stuck inflight calls
 })
 
-if (!result.ok && result.error instanceof TimeoutError) {
-  console.log(`timed out after ${result.error.ms}ms`)
-}
+const status = health()
+// { storeSize, pendingInflight, uptimeMs, lastError?, lastSuccessAt? }
 ```
 
-For cooperative cancellation, pass `signal` through to your async primitive (`fetch`, `AbortController`, etc.). `actly` will abort the signal when the deadline fires — `fn` rejects immediately, no background leak.
-
----
+### `drain(timeoutMs, scope?)` and `drainAll(timeoutMs)`
 
-### Total timeout
-
-Hard budget over the **entire** operation — all attempts, delays, and per-attempt timeouts combined. The per-attempt `timeout` resets on retry; `totalTimeout` does not.
-
-**v1.1.5 fix:** When `totalTimeout` fires, the inner retry loop is cancelled — no more attempts fire, no more delays are slept. Previous versions would continue running `fn` in the background after `TotalTimeoutError` was returned to the caller.
+Wait for in-flight `act()` calls to settle. `drainAll` drains all scopes in parallel.
 
 ```ts
-import { act, TimeoutError, TotalTimeoutError } from 'actly'
-
-const result = await act('search:query', async (signal) => runQuery(q, signal), {
-  retry:        { attempts: 5, delayMs: 100, backoff: 'linear' },
-  timeout:      { ms: 2_000 },  // per attempt
-  totalTimeout: { ms: 8_000 },  // whole operation
+process.on('SIGTERM', async () => {
+  const ok = await drainAll(10_000)
+  process.exit(ok ? 0 : 1)
 })
-
-if (!result.ok) {
-  if (result.error instanceof TotalTimeoutError) {
-    console.log(`budget exhausted after ${result.error.ms}ms`)
-  } else if (result.error instanceof TimeoutError) {
-    console.log(`last attempt timed out after ${result.error.ms}ms`)
-  }
-}
 ```
 
-`TotalTimeoutError` and `TimeoutError` are separate classes — `instanceof` distinguishes which deadline fired.
-
----
+### `enableWatchdog(thresholdMs?, hooks?)`
 
-### Dedupe
-
-Concurrent calls with the same key collapse into one in-flight Promise. The first caller executes; the rest wait and receive the same result. After settlement, the next call starts fresh.
+Opt-in background watchdog. Fires `onWatchdog` when an in-flight call exceeds `thresholdMs` (default 60s). Catches hung `fn` calls that ignore the signal and have no timeout configured.
 
 ```ts
-const result = await act('config:load', async (signal) => loadRemoteConfig(signal), {
-  dedupe: true,
+enableWatchdog(30_000, {
+  onWatchdog: (e) => logger.warn({ elapsedMs: e.elapsedMs }, 'hung act() call'),
 })
 ```
 
-`dedupe: { enabled: true }` is also valid — object form for forward compatibility.
+### `createTenantStore(options)` and `createAsyncTenantStore(factory)`
 
-#### v1.1.5 fixes
+Per-tenant store isolation. Each tenant gets its own store instance (not a shared store with key prefixes). LRU-evicts idle tenants when `maxTenants` is reached.
 
-- **Shared `attempts`**: joiners now mirror the originator's attempt count. If the originator retried twice before succeeding, all joiners report `attempts: 3` (was `1` in v1.0 — a misleading default).
-- **Abort safety**: joiners race the in-flight promise against their own `AbortSignal`. If a joiner's signal aborts (e.g. their `totalTimeout` fires), they reject immediately — they don't block on a hung originator.
-- **In-flight TTL** (optional): `dedupe: { enabled: true, inflightTtl: 30_000 }` removes the store entry after 30s if the originator never settles, so subsequent callers can start fresh. Pair with `timeout` / `totalTimeout` for proper cancellation in production.
+```ts
+import { createTenantStore } from 'actly'
 
----
+const tenants = createTenantStore({ maxSize: 1000, autoCleanup: true, maxTenants: 10_000 })
+const tenant1Act = tenants.get('tenant-1')
+await tenant1Act('user:42', async () => fetchUser(42))
+tenants.evict('tenant-1')  // destroys the store, releases resources
+```
 
-### Cache
+### `InMemoryStore`
 
-Stores successful results for `ttl` milliseconds. Failures are never cached. A cache hit short-circuits everything — dedupe, retry, and timeout are all skipped.
+Reference `SyncStateStore`. Bounded LRU with TTL, background sweep, O(1) operations. Default `maxSize` is 10,000 (bounded). Pass `Infinity` explicitly for unbounded storage.
 
 ```ts
-const result = await act('flags:all', async (signal) => fetchFeatureFlags(signal), {
-  cache: { ttl: 60_000 },
+const store = new InMemoryStore({
+  maxSize: 10_000,              // default 10_000; pass Infinity for unbounded
+  autoCleanup: true,            // default false
+  cleanupIntervalMs: 30_000,    // default 30s
+  memoryPressureCleanup: true,  // react to Node 22+ 'memory' events
 })
 
-console.log(result.source) // 'fresh' on miss, 'cache' on hit
-console.log(result.attempts) // 1 on miss, 0 on hit (v1.1.5 fix)
+store.destroy()  // stops timer, clears map, removes listeners. Idempotent.
 ```
 
-#### v1.1.5 fixes
-
-- **Single-flight (cache stampede prevention)**: on a sync store, concurrent cache misses for the same key now collapse into a single `fn` invocation. Previously, 10 concurrent callers would all run `fn` (10x redundant work). Now they share one in-flight Promise.
-- **`attempts: 0` on cache hit**: cache hits now report `attempts: 0` (was `1` in v1.0), consistent with the documented meaning ("number of attempts made before success").
-- **Fail-open writes**: if `store.set()` throws (e.g. Redis transient error), the value is still returned to the caller. Caching is an optimisation, not a correctness requirement.
+The store registers a `FinalizationRegistry` so the cleanup timer is cleared even if you forget `destroy()`. Still call `destroy()` explicitly when you can; GC timing is not deterministic.
 
-#### Invalidation
+## Options
 
-```ts
-import { act, invalidate } from 'actly'
+All fields optional. Compose any combination.
 
-await act('user:42', async (signal) => fetchUser(42, signal), { cache: { ttl: 60_000 } })
-// ... user updates their profile ...
-invalidate('user:42')  // returns true if a cache entry was removed
-await act('user:42', ...)  // re-fetches
-```
-
-For scoped stores (see `withStore` below), use the scoped `invalidate`:
+### `retry`
 
 ```ts
-const scopedAct = withStore(myStore)
-scopedAct.invalidate('user:42')  // sync store: returns boolean
-                                // async store: returns Promise<boolean>
+{
+  retry: {
+    attempts: 3,                    // total attempts including first (1-100)
+    delayMs: 200,                   // base delay (0-300_000)
+    backoff: 'exponential',         // 'none' | 'linear' | 'exponential' (default 'none')
+    maxDelay: 30_000,               // cap on computed delay (default Infinity)
+    jitter: 'full',                 // 'none' | 'full' | 'equal' | 'decorrelated' (default 'full')
+    shouldRetry: (error, attempt) => true,
+    shouldRetryResult: (value, attempt) => true,  // retry on returned values (HTTP 500)
+    backoffFn: (attempt, error, state) => 1000,   // custom backoff, overrides backoff+jitter
+    dangerouslyUnref: false,        // unref sleep timer (CLI/scripts/tests)
+  }
+}
 ```
 
----
-
-### Combining policies
+`shouldRetryResult` retries on returned values that are semantic failures. The common pattern: `fetch` returns a 500 without throwing.
 
 ```ts
-const result = await act('product:detail', async (signal) => fetchProduct(id, signal), {
-  totalTimeout: { ms: 10_000 },  // outermost wall
-  cache:        { ttl: 30_000 }, // short-circuits on hit
-  dedupe:       true,            // collapses concurrent calls
-  retry:        { attempts: 3, delayMs: 100, backoff: 'linear' },
-  timeout:      { ms: 3_000 },   // per attempt
-  signal:       userSignal,      // caller-provided cancellation
+await act('fetch-api', async (signal) => fetch('/api', { signal }), {
+  retry: {
+    attempts: 3,
+    shouldRetryResult: (res) => res.ok && res.status < 500,
+  },
 })
 ```
 
----
-
-## Cancellation: `options.signal`
-
-`act()` accepts an `AbortSignal` for caller-driven cancellation:
+`backoffFn` carries per-call state. Useful for honoring `Retry-After`.
 
 ```ts
-const controller = new AbortController()
-const promise = act('search:big', async (signal) => runBigQuery(q, signal), {
-  signal: controller.signal,
-  timeout: { ms: 30_000 },
+await act('fetch-retry-after', async (signal) => {
+  const res = await fetch('/api', { signal })
+  if (!res.ok) {
+    const ra = parseInt(res.headers.get('retry-after') ?? '0', 10)
+    if (ra > 0) state.retryAfter = ra * 1000
+    throw new Error(`HTTP ${res.status}`)
+  }
+  return res
+}, {
+  retry: {
+    attempts: 5,
+    backoffFn: (_attempt, _err, state) => state.retryAfter ?? 1000,
+  },
 })
-
-// User clicks "Cancel":
-controller.abort(new Error('user-cancelled'))
-
-const r = await promise
-// r.ok === false, r.error.message === 'user-cancelled'
 ```
 
-When `signal` aborts:
-- If the operation hasn't started, `act()` returns immediately with `attempts: 0` and the signal's `reason` as the error.
-- If it's in progress, `fn`'s inner signal aborts (cooperative). `fn` should propagate the signal to its primitives (`fetch`, `AbortController`, etc.) for proper cleanup.
-- If it has already settled, the result is returned as normal.
+Default `shouldRetry` skips `AbortError`, `ACTLY_TIMEOUT`, and `ACTLY_TOTAL_TIMEOUT` so a slow endpoint with `timeout: 1000, retry: { attempts: 5 }` fails at 1s, not 5s. Override with `shouldRetry: () => true` to retry on everything.
 
-The signal propagates through the entire chain: `totalTimeout`, `retry` (interrupts delay sleeps), and `timeout` all observe it. No more attempts fire after abort.
+`attempts: 1` is a no-op; the retry policy is skipped.
 
----
+### `timeout`
 
-## Options reference
+Per-attempt deadline. Each retry gets a fresh clock.
 
 ```ts
-interface ActOptions {
-  retry?:        RetryOptions
-  timeout?:      TimeoutOptions      // per-attempt
-  totalTimeout?: TimeoutOptions      // entire operation
-  dedupe?:       boolean | DedupeOptions
-  cache?:        CacheOptions
-  signal?:       AbortSignal         // caller-provided cancellation
-}
-
-interface RetryOptions {
-  attempts:     number               // integer >= 1
-  delayMs?:     number               // non-negative finite
-  backoff?:     'none' | 'linear' | 'exponential'
-  maxDelay?:    number               // cap, default Infinity
-  jitter?:      'none' | 'full' | 'equal' | 'decorrelated'  // default 'full'
-  shouldRetry?: (error: unknown, attempt: number) => boolean
-}
-
-interface TimeoutOptions  { ms: number }   // positive finite
-interface DedupeOptions   {
-  enabled: boolean
-  inflightTtl?: number   // safety-net TTL for in-flight entry, default Infinity
-}
-interface CacheOptions    { ttl: number }  // positive finite
+{ timeout: { ms: 5_000, strategy: 'race' } }
 ```
 
-All options are validated upfront. Invalid input (negative `attempts`, non-positive `ms`, empty `key`, etc.) throws `RangeError` or `TypeError` — these are programmer errors, not runtime failures, so they surface as thrown exceptions rather than `ActFailure`.
+`strategy: 'race'` (default) races `fn(signal)` against the abort event and returns promptly at `ms` whether `fn` cooperates or not.
+
+`strategy: 'cooperative'` aborts the signal but waits for `fn` to settle. Gentler on downstreams that don't cooperate with `AbortSignal` (they get to clean up), but can run past `ms` if `fn` is slow to reject after the abort.
 
----
+### `totalTimeout`
 
-## Exported values
+Hard wall-clock budget over the whole operation, including retries, delays, and per-attempt timeouts.
 
 ```ts
-import {
-  // Primary API
-  act,                       // execute with reliability policies
-  invalidate,                // clear cache for a key on the default store
-  withStore,                 // create a scoped act() with explicit store
-
-  // Execution engine (for custom policy chains)
-  execute,                   // run a policy chain with explicit store + signal
-  REQUIRES_SYNC_STORE,       // symbol stamped on dedupe policy
-
-  // Stores
-  InMemoryStore,             // sync store with LRU + maxSize + autoCleanup
-  isSyncStore,               // type guard
-  isAsyncStore,              // type guard
-
-  // Error classes
-  TimeoutError,              // per-attempt deadline (.ms)
-  TotalTimeoutError,         // total budget exhausted (.ms)
-} from 'actly'
+{ totalTimeout: { ms: 12_000 } }
 ```
 
----
+### `dedupe`
 
-## Exported types
+Collapses concurrent calls with the same key into one in-flight Promise.
 
 ```ts
-import type {
-  ActResult, ActSuccess, ActFailure, ActSource,
-  ActOptions, ActFn,
-  RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions,
-  // Policy internals (for custom policy authors)
-  PolicyApplier, PolicyContext, RunMeta,
-  // Store interfaces
-  SyncStateStore,
-  AsyncStateStore,
-  AnyStateStore,
-  InMemoryStoreOptions,
-  // v1.0 alias — still valid, zero migration needed
-  StateStore,
-  // withStore result types
-  ScopedActSync,
-  ScopedActAsync,
-} from 'actly'
+dedupe: true
+// or
+dedupe: { enabled: true, inflightTtl: 30_000 }
 ```
 
----
+`inflightTtl` (default 5 minutes) is a safety-net TTL for the in-flight entry. If the originator's Promise doesn't settle within this window, the entry is removed so subsequent callers can start fresh. Pass `Infinity` explicitly for the old "wait forever" behavior.
 
-## Custom store
+Joiner isolation: if the originator's caller aborts, joiners are not affected. Each joiner races the in-flight Promise against their own signal.
 
-By default `act` uses a module-level `InMemoryStore`. For SSR request isolation, multi-tenant scenarios, or test control, use `withStore()`:
+Requires a sync store. `execute()` throws at chain-build time if an async store is used with dedupe.
 
-### `withStore(store)`
+### `cache`
 
-Returns a scoped `act` function bound to the provided store, with an `invalidate(key)` method and a `store` reference attached.
+Stores successful results for a TTL.
 
 ```ts
-import { withStore, InMemoryStore } from 'actly'
+{ cache: { ttl: 60_000 } }  // 0 < ttl <= 86_400_000
+```
 
-// Basic
-const store = new InMemoryStore()
-const act = withStore(store)
+Failures are never cached. Only successful values.
 
-// With LRU + background cleanup (long-lived server store)
-const serverStore = new InMemoryStore({
-  maxSize: 10_000,           // evict least-recently-used when exceeded
-  autoCleanup: true,
-  cleanupIntervalMs: 60_000, // sweep every 60s (default: 30s)
-})
-const serverAct = withStore(serverStore)
+Single-flight (cache stampede protection): on sync stores, concurrent cache misses join one in-flight Promise. On async stores, stampedes are a known limitation.
 
-try {
-  await serverAct('user:42', async (signal) => fetchUser(42, signal), {
-    cache: { ttl: 60_000 },
-  })
+`store.set()` failures (e.g. Redis transient error) are swallowed; the value is still returned to the caller.
 
-  // ... user updates their profile ...
-  serverAct.invalidate('user:42')  // next call re-fetches
+### `circuitBreaker`
 
-  // Access the underlying store if needed:
-  console.log(serverAct.store.size())
-} finally {
-  serverStore.destroy()  // stop the cleanup timer
+Opens after threshold failures, rejects immediately while open, allows one probe call after cooldown.
+
+```ts
+{
+  circuitBreaker: {
+    threshold: 5,             // consecutive failures before opening
+    cooldownMs: 30_000,       // how long to stay open
+    resetTimeoutMs: 600_000,  // optional: reset failure count after idle (default Infinity)
+    strategy: 'consecutive',  // 'consecutive' (default) | 'count'
+    // For strategy: 'count':
+    countSize: 100,            // window size
+    countThreshold: 0.5,       // failure rate to trip (0-1)
+    countMinimumCalls: 100,    // min calls before tripping
+  }
 }
 ```
 
-For sync stores, `invalidate` returns `boolean` synchronously.
-For async stores, `invalidate` returns `Promise<boolean>`.
-
-### `execute()` directly
+`consecutive` opens after N failures in a row. Resets on any success. Good for "downstream is fully down."
 
-For full control (custom policy chains, custom meta, custom signal composition), call `execute()` directly:
+`count` is a sliding-window ratio breaker. Trips when the failure rate in the last `countSize` calls exceeds `countThreshold`. Use for "downstream is degraded" (e.g. trip when >30% of last 100 calls fail).
 
-```ts
-import { execute, InMemoryStore, retryPolicy, timeoutPolicy } from 'actly'
-
-const store = new InMemoryStore()
-const meta = { attempts: 1, source: 'fresh' as const }
-
-const value = await execute({
-  key: 'custom:chain',
-  fn: async (signal) => fetchThing(signal),
-  policies: [
-    retryPolicy({ attempts: 3, delayMs: 100 }),
-    timeoutPolicy({ ms: 5_000 }),
-  ],
-  store,
-  meta,
-  signal: new AbortController().signal,
-})
+Half-open probe: probe failure re-opens immediately. Probe success resets the window (count strategy) or the failure counter (consecutive).
 
-console.log(meta.attempts)  // final attempt count
-```
+### `bulkhead`
 
-### InMemoryStore options
+Caps in-flight concurrency per key.
 
 ```ts
-new InMemoryStore({
-  // Periodically sweep expired entries. Default: false (lazy eviction on access).
-  autoCleanup?: boolean,
-  cleanupIntervalMs?: number,  // default 30_000
-
-  // Bounded cache with LRU eviction. Default: Infinity (unbounded).
-  // On set(), if size would exceed maxSize, the least-recently-used entry
-  // is evicted before the new one is inserted.
-  maxSize?: number,
-})
+{
+  bulkhead: {
+    maxConcurrent: 10,
+    maxQueueSize: 100,         // default Infinity
+    queueTimeoutMs: 5_000,     // default Infinity
+  }
+}
 ```
 
-`InMemoryStore` satisfies `SyncStateStore`. Call `destroy()` to stop the background timer and prevent leaks.
+When `maxConcurrent` is reached, new callers queue. When the queue is full or `queueTimeoutMs` elapses, callers get `BulkheadOverflowError`. `onBackpressure` observability hook fires when queue utilization crosses 80%.
 
-### Async store (v1.1+)
+### `rateLimit`
 
-For external cache backends (Redis, Upstash, etc.), implement `AsyncStateStore`:
+Sliding window rate limit per key.
 
 ```ts
-import type { AsyncStateStore } from 'actly'
-
-class RedisStore implements AsyncStateStore {
-  readonly _sync = false as const
-
-  async get<T>(key: string): Promise<T | undefined> { /* ... */ }
-  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> { /* ... */ }
-  async delete(key: string): Promise<void> { /* ... */ }
-  async has(key: string): Promise<boolean> { /* ... */ }
-  async clear(): Promise<void> { /* ... */ }
-  async size(): Promise<number> { /* ... */ }
-}
+{ rateLimit: { maxCalls: 100, windowMs: 60_000 } }
 ```
 
-`AsyncStateStore` is compatible with `cache` only. Using it with `dedupe` is a TypeScript error and a runtime error — `execute()` throws at chain-build time. Dedupe requires synchronous store access (the read-then-write that makes deduplication work must happen in a single tick; an async `await` between `get()` and `set()` would let two concurrent callers both see a miss).
-
----
+### `hedge`
 
-## Store interfaces
+Sends a second call after `delayMs`, races them, cancels the loser.
 
 ```ts
-interface SyncStateStore {
-  readonly _sync: true
-  get<T>(key: string): T | undefined
-  set<T>(key: string, value: T, ttlMs?: number): void
-  delete(key: string): void
-  has(key: string): boolean
-  clear(): void
-  size(): number
-}
-
-interface AsyncStateStore {
-  readonly _sync: false
-  get<T>(key: string): Promise<T | undefined>
-  set<T>(key: string, value: T, ttlMs?: number): Promise<void>
-  delete(key: string): Promise<void>
-  has(key: string): Promise<boolean>
-  clear(): Promise<void>
-  size(): Promise<number>
+{
+  hedge: {
+    delayMs: 100,                  // > 0, <= 300_000
+    keepLoser: false,              // default false; true = don't cancel
+    placement: 'outside-retry',    // 'outside-retry' (default) | 'inside-retry'
+  }
 }
 ```
 
-The `_sync` discriminant is read at runtime by `execute()` to enforce the dedupe constraint. Set it as a `readonly` literal — `true as const` or `false as const`.
+`outside-retry` (default) wraps the whole execute chain. One hedge per `act()` call regardless of retry count. `inside-retry` wraps `fn` directly, so each retry attempt can spawn its own hedge (multiplies downstream load; rarely what you want).
 
----
+When one settles, the loser is aborted via its `AbortController`. If `fn` cooperates with the signal (passes it to `fetch`, DB drivers, etc.) the underlying work is cancelled. The winner's controller is not aborted, so downstream side-effects (streaming bodies, cursor cleanup) run to completion.
 
-## Zero-throw contract
+### `fallback`
 
-`act()` always resolves. Under any condition — network error, thrown exception, timeout, total budget exhaustion, caller abort — the result is an `ActFailure`, not a rejected promise. This contract holds across all versions.
+Returns a value (or function result) instead of the failure when `fn` fails.
 
-The only exceptions are programmer errors (invalid options, invalid keys) — these throw synchronously so bugs surface at development time rather than degrading silently in production.
+```ts
+{ fallback: { value: 'default' } }
+// or
+{ fallback: { value: () => computeFallback() } }
+```
 
----
+If the fallback function itself throws, the original `fn` error is surfaced. The fallback error is logged via `console.warn` in non-production and emitted via `onFinalFailure` so you can detect a broken fallback.
 
-## Philosophy
+### `observability`
 
-One function. One return type. No exceptions in userland.
+Hooks fire on lifecycle events. Wrapped in `safeCall` so a buggy hook never crashes the main path.
+
+```ts
+{
+  observability: {
+    onAttempt: (e) => ...,        // before each attempt
+    onRetry: (e) => ...,          // before each retry delay
+    onCacheHit: (e) => ...,
+    onCacheMiss: (e) => ...,
+    onDedupeJoin: (e) => ...,
+    onTimeout: (e) => ...,
+    onFinalSuccess: (e) => ...,
+    onFinalFailure: (e) => ...,
+    onBackpressure: (e) => ...,
+    onWatchdog: (e) => ...,
+  }
+}
+```
 
-The key is your responsibility. Make it stable and specific. `user:42` is good. `fetch` is not. (Empty keys and reserved prefixes are rejected — see validation.)
+Each event carries `key`, `traceId`, `timestamp`. Pass `traceId` explicitly or let actly generate a UUID.
 
-Policies are composable but intentionally constrained. There is no builder API, no middleware system, no hooks. If you need something `act` doesn't do, write a wrapper around it — that's the right boundary.
+### `audit`
 
-Cancellation is cooperative: pass the `signal` through. `act()` will return promptly regardless (via internal race), but only you can stop `fn` from leaking resources.
+Single hook for structured logging of every call result.
 
----
+```ts
+{
+  audit: {
+    log: (entry: AuditEntry) => {
+      // { key, traceId, timestamp, durationMs, ok, attempts, failedBy?, error? }
+      logger.info(entry)
+    },
+  }
+}
+```
 
-## Changelog
+### `signal`
 
-### v1.1.5 — 2026-06-25
+Caller-supplied `AbortSignal`. Linked to the root controller. Aborting it cancels the entire operation.
 
-**Critical correctness fixes**
+## Errors
 
-- **`totalTimeout` now cancels the inner retry loop.** Previously, when `totalTimeout` fired, `act()` returned `TotalTimeoutError` to the caller but the inner `retryPolicy` continued firing attempts and sleeping delays in the background — leaking resources for the full retry budget. Now, the abort propagates through the chain: no more attempts fire, delay sleeps reject immediately. *(Fixes C-1.)*
-- **`timeout` (per-attempt) cancels `fn` via `AbortSignal`.** `fn` now receives a signal that aborts when the per-attempt deadline fires. If `fn` cooperates (passes signal to `fetch`, `AbortController`, etc.), the underlying work is cancelled properly. `act()` returns promptly even if `fn` ignores the signal (via internal race). *(Fixes C-2.)*
-- **Dedupe joiners can abort independently.** Previously, if the originator's `fn` hung, all joiners blocked forever waiting for the in-flight promise. Now, joiners race the in-flight promise against their own `AbortSignal` — they reject immediately when their signal aborts, without waiting for the originator. *(Fixes C-3.)*
-- **Cache stampede prevention (single-flight).** Concurrent cache misses for the same key on a sync store now collapse into a single `fn` invocation. Previously, 10 concurrent callers would all run `fn` (10x redundant work). Now they share one in-flight Promise via an internal `__inflight:cache:<key>` slot. *(Fixes C-4.)*
-- **Dedupe joiners mirror originator's `attempts`.** Previously, joiners reported `attempts: 1` regardless of how many retries the originator performed. Now, joiners copy the originator's final `attempts` and `source` from a shared `RunMeta` reference. *(Fixes C-5.)*
-- **Cache hit reports `attempts: 0`.** Previously, cache hits reported `attempts: 1`, inconsistent with the documented meaning ("number of attempts made before success"). Now: `0` on hit, `1+` on miss. *(Fixes C-6.)*
+All actly-thrown errors extend `ActlyError` and carry a stable `.code` string. Use the code (not `instanceof`) for cross-realm handling. `isActlyError(e)` is a realm-safe predicate.
 
-**Public API additions (fixes A-1, A-2, m-8)**
+| Class | code | Meaning |
+|---|---|---|
+| `ActlyAbortError` | `ACTLY_ABORT` | caller signal, per-attempt timeout, or total timeout aborted |
+| `TimeoutError` | `ACTLY_TIMEOUT` | per-attempt deadline fired |
+| `TotalTimeoutError` | `ACTLY_TOTAL_TIMEOUT` | operation-wide budget exhausted |
+| `RetryExhaustedError` | `ACTLY_RETRY_EXHAUSTED` | all retry attempts failed |
+| `ValidationError` | `ACTLY_VALIDATION` | programmer error (invalid options) |
+| `CircuitBreakerOpenError` | `ACTLY_CIRCUIT_OPEN` | breaker is open |
+| `BulkheadOverflowError` | `ACTLY_BULKHEAD_FULL` | bulkhead queue full or timed out |
+| `RateLimitError` | `ACTLY_RATE_LIMIT` | rate limit exceeded |
+| `ResourceExhaustedError` | `ACTLY_RESOURCE_EXHAUSTED` | process-wide inflight budget exceeded |
+| `HedgeTimeoutError` | `ACTLY_HEDGE_TIMEOUT` | hedge deadline fired before primary settled |
 
-- **`execute()` is now exported.** Call it directly with a custom policy chain, store, meta, and signal for full control (SSR isolation, multi-tenant scenarios, custom policy composition).
-- **`isSyncStore()` / `isAsyncStore()` are now exported.** Type guards for `AnyStateStore`, useful when building custom policy chains or store adapters.
-- **`invalidate(key)`** clears cache entries on the default store. Returns `boolean` (true if an entry was removed).
-- **`withStore(store)`** returns a scoped `act` function bound to an explicit store, with `invalidate(key)` and `store` attached. Overloads for sync (`invalidate: boolean`) vs async (`invalidate: Promise<boolean>`) stores.
-- **`REQUIRES_SYNC_STORE` symbol** is now exported for consumers building custom policy chains that need to declare sync-store requirements.
-- **`ScopedActSync` / `ScopedActAsync` types** exported for typed `withStore` results.
-- **`PolicyApplier`, `PolicyContext`, `RunMeta`, `AnyStateStore`** are now exported as public types (previously internal).
+`ActlyError.toJSON({ redact?: true })` returns a plain object with `name`, `code`, `message`, `key`, `stack`, plus subclass-specific fields (`attempts`, `ms`, `current`, `limit`, etc.). Pass `redact: true` to HTML-escape and length-cap the message for log shipping.
 
-**New options**
+## Compared to Cockatiel
 
-- **`options.signal: AbortSignal`** — caller-provided cancellation signal. Propagates through the entire chain: `totalTimeout`, `retry` (interrupts delay sleeps), and `timeout` all observe it. `fn` receives the composite signal.
-- **`RetryOptions.maxDelay`** — cap on computed delay. Prevents 8.5-minute waits on long exponential chains (`delayMs: 1000, attempts: 10, exponential` → 256s between attempts 9 and 10 without a cap).
-- **`RetryOptions.jitter`** — jitter strategy: `'none' | 'full' | 'equal' | 'decorrelated'`. Default: `'full'` (random in `[0, delay]`). Prevents thundering-herd retry storms.
-- **`DedupeOptions.inflightTtl`** — safety-net TTL for the in-flight entry. If the originator never settles, subsequent callers can start fresh after the TTL expires.
-- **`InMemoryStoreOptions.maxSize`** — bounded cache with LRU eviction. On `set()`, if size would exceed `maxSize`, the least-recently-used entry is evicted before the new one is inserted. Default: `Infinity` (unbounded).
+Both are typed, zero-dependency resilience libraries for Node/TypeScript. Both use native `AbortSignal` for cancellation. The core difference is scope *and* size.
 
-**Behaviour changes (non-breaking)**
+| | actly | Cockatiel |
+|---|---|---|
+| Policies | retry, timeout, totalTimeout, circuitBreaker, bulkhead, rateLimit, cache, dedupe, hedge, fallback, noop, decorator | retry, timeout, circuitBreaker, bulkhead, fallback, noop |
+| Cross-call state | Yes (keyed store: cache, dedupe, breaker counter, rate limit) | No (policies are stateless per-instance) |
+| Multi-tenant isolation | Yes (`createTenantStore`) | No |
+| Audit log / health / drain / watchdog | Built-in | External |
+| Tarball size | 57 KB | ~30 KB |
+| JS runtime (installed) | 243 KB | 63 KB (~4× smaller) |
+| Per-call overhead (retry configured) | ~2.4 µs | ~0.35 µs (~7× faster) |
+| Runtime deps | 0 | 0 |
 
-- **`shouldRetry` is now called on every failure, including the final attempt.** Previously, it was skipped on the last attempt. The return value is still only consulted when there are remaining attempts — but observers / metrics now see every failure. *(Fixes M-2.)*
-- **Default `shouldRetry` skips abort errors.** Previously, the default retried on every error. Now it skips `AbortError` (which indicates cancellation — retrying would just abort again, wasting delay budget). User-supplied `shouldRetry` overrides this entirely.
-- **Input validation throws on invalid options.** Empty keys, reserved prefixes (`dedupe:`, `cache:`, `__inflight:`), non-integer `attempts`, non-positive `ms`/`ttl`, non-finite delays — all throw `RangeError` or `TypeError` synchronously, rather than degrading silently. *(Fixes M-3, M-4.)*
-- **`RetryOptions.attempts: 1` is a documented no-op.** The retry policy is not added to the chain when `attempts <= 1` (would be pure overhead). This was already the behaviour; it's now explicitly documented.
+Where they overlap (retry, timeout, circuit breaker, bulkhead), semantics are comparable. actly uses a keyed state store (`Map` get/set per call) to support cross-call features (circuit breaker failure counts, cache, dedupe) that Cockatiel doesn't have. That indirection costs a few microseconds per call and the extra code adds bundle weight.
 
-**Internal improvements**
+For wrapping network or database calls (what both libraries are for), the per-call overhead difference is noise — a single intra-region AWS RTT is ~1,000 µs, so a 2 µs delta is 0.2% of one network hop. But for in-process cache layers or routers at 100k+ calls/sec, the overhead and bundle size matter; pick Cockatiel there.
 
-- **`ActFn<T>` signature changed to `(signal: AbortSignal) => Promise<T> | T`.** Backwards compatible: `() => Promise<T>` is assignable (signal arg is ignored). New code can opt-in to cooperative cancellation.
-- **`cachePolicy` fails open on `store.set()` errors.** If the cache write throws (e.g. Redis transient error), the value is still returned to the caller. Caching is an optimisation, not a correctness requirement. *(Fixes M-6.)*
-- **`InMemoryStore.size()` is now side-effect free** with respect to LRU order. Previously, it called `has()` (which delegated to `get()`), refreshing LRU positions. Now it scans without touching order. *(Fixes m-1.)*
-- **`InMemoryStore` implements LRU** via `Map` insertion-order semantics: `delete` + `set` on every access moves the key to the most-recent position. *(Fixes P-3.)*
-- **`retryPolicy` checks `parentSignal.aborted` before each attempt and before each delay sleep.** When `totalTimeout` or caller signal aborts, the retry loop bails immediately — no more attempts, no more delays. Delay sleeps use a signal-aware `sleep()` helper that rejects early on abort.
-- **`package.json` `engines.node` set to `>=18`** (was missing — README claimed Node 18+ but it wasn't enforced). *(Fixes D-7.)*
-- **`package.json` `sideEffects: false`** for tree-shaking. *(Fixes D-8.)*
-- **`package.json` `exports` field:** `types` condition is now first (was last) — required for correct TypeScript resolution in some bundlers. *(Fixes A-3.)*
-- **`tsconfig` updated:** target ES2022, `lib: ["ES2022"]`, `types: ["node"]`. Removed `DOM` lib (was unnecessary for a Node-targeted library). *(Fixes D-9, D-11, D-12.)*
-- **`tsconfig.cjs.json` `moduleResolution: "Node"`** (was `"Bundler"` — incompatible with `module: "CommonJS"`). *(Fixes D-9.)*
-- **Test suite added.** 64 tests covering: API surface, zero-throw contract, input validation, retry (jitter, maxDelay, shouldRetry on final attempt, abort-skip), timeout (cooperative + race fallback), totalTimeout (cancellation, delay interrupt), dedupe (collapse, shared meta, abort safety, hung originator), cache (single-flight, attempts=0, fail-open, TTL), invalidate, withStore (sync + async, isolation, scoped invalidate), InMemoryStore (LRU, maxSize, TTL, size() purity, destroy), AbortSignal integration, execute() public API. *(Fixes D-1.)*
+Pick actly when you want cache/dedupe/rate-limit/hedge/audit/multi-tenant in the same call and can absorb the bundle cost. Pick Cockatiel when you only need retry/timeout/circuit-breaker/bulkhead/fallback and want the leanest per-call cost and smallest install footprint.
 
-**Non-breaking changes**
+## Performance
 
-- `StateStore` preserved as type alias for `SyncStateStore` — all v1.0 code compiles without changes.
-- All new exports are purely additive.
-- `ActFn<T>` signature widened to accept `(signal) => ...` — existing `() => Promise<T>` is assignable.
-- `withStore()` is a new function — no impact on existing `act()` callers.
+Numbers from `npm run bench` on a 2023 MacBook Pro with Node 22. 20,000 iterations, 500 warmup. Live sandbox re-run (Node 24) confirms the same shape.
 
----
+| Configuration | ops/sec | µs/op | Notes |
+|---|---|---|---|
+| Fast path (zero options) | ~680,000 | ~1.5 | Just `act(key, fn)`, no policies applied |
+| Cache hit | ~700,000 | ~1.4 | Single-flight in-memory store |
+| Retry only (attempts=3) | ~415,000 | ~2.4 | Same as the Quick Start example |
+| Circuit breaker (closed) | ~720,000 | ~1.4 | Happy path, breaker not tripped |
+| Bulkhead (maxConcurrent=10) | ~313,000 | ~3.2 | Under cap, no queuing |
+| Composed (retry+timeout+breaker) | ~84,000 | ~11.9 | The realistic case |
 
-### v1.1.0 — 2026-06-01
+**Cockatiel comparison (same sandbox, same workload):**
 
-- `AsyncStateStore` interface for plug-in async backends (Redis, Upstash, Cloudflare KV).
-- `SyncStateStore` canonical name; `StateStore` preserved as alias.
-- `InMemoryStore` public export with `InMemoryStoreOptions` (`autoCleanup`, `cleanupIntervalMs`).
-- `TotalTimeoutError` class distinct from `TimeoutError`.
-- `totalTimeout` option for hard wall-clock budget.
-- `dedupe: true` shorthand.
-- `isSyncStore()` / `isAsyncStore()` type guards.
+| Configuration | actly ops/sec | Cockatiel ops/sec | actly overhead |
+|---|---|---|---|
+| Retry | 415,000 | 2,835,000 | 6.8× slower |
+| Timeout | 87,000 | 177,000 | 2.0× slower |
+| Circuit breaker | 722,000 | 2,272,000 | 3.1× slower |
+| Bulkhead | 313,000 | 5,533,000 | 17.7× slower |
+| Composed (3 policies) | 84,000 | 156,000 | 1.9× slower |
 
----
+The composed case is the closest to a real workload. The 1.9× delta is microseconds, not milliseconds — invisible behind a 50ms network call. The bulkhead 17.7× delta is the worst case and matters only for in-process routers; if your `fn` is a no-op or in-memory lookup, the bulkhead machinery dominates total time.
 
-### v1.0.1
+Observability hooks have zero overhead when not configured. When configured, `safeCall` wraps every hook invocation so a buggy hook never propagates into the main path.
 
-- Initial stable release.
-- `act()`, `retry`, `timeout`, `totalTimeout`, `dedupe`, `cache`.
-- `TimeoutError` exported for `instanceof` checks.
-- Zero dependencies. ESM + CJS. Node 18+.
+## Limitations
 
----
+- `dedupe`, `circuitBreaker`, `bulkhead`, and `rateLimit` require a sync store. `cache` works with both sync and async stores.
+- Async stores can't do single-flight for cache misses (no atomic check-and-publish). Use a sync store or accept the stampede risk.
+- `cooperative` timeout strategy can wait past `ms` if `fn` doesn't reject after the abort. Pair with `totalTimeout` for a hard ceiling.
+- `instanceof ActlyError` works only within the same realm (worker_threads, vm contexts break the prototype chain). Use `isActlyError(e)` or switch on `.code` for cross-realm handling.
 
 ## License