actly 1.2.0 → 1.3.0

package/README.md

@@ -1,137 +1,101 @@
 # actly
 
-A typed reliability kernel for async execution. Retry, timeout, dedupe, cache — composable, zero-throw, with `AbortSignal` cancellation, jittered backoff, observability hooks, and a typed error taxonomy.
+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 20+. Ships ESM + CJS. Zero runtime dependencies. Tree-shakeable.
+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.
 
----
+> **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.
 
-## What it does
-
-`act()` wraps an async function with configurable reliability policies. It always resolves with a result object — never rejects. You check `.ok` to branch on success or failure.
+## 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)
-  console.log(result.durationMs) // number (wall-clock ms)
+if (r.ok) {
+  console.log(r.value, r.source, r.attempts, r.durationMs)
 } else {
-  console.error(result.error)    // typed — see Error taxonomy
+  console.error(r.error)
 }
 ```
 
----
-
-## Compared to Cockatiel
-
-Both are typed, zero-dependency resilience libraries for Node/TypeScript. The core difference is scope and composition model.
-
-| | actly | Cockatiel |
-|---|---|---|
-| Retry (backoff + jitter) | ✅ exponential/linear/constant, 4 jitter modes | ✅ exponential, `ExponentialBackoff` |
-| Timeout (per-attempt) | ✅ | ✅ |
-| Total/wall-clock timeout | ✅ `totalTimeout` spans the whole retry loop | — (compose manually) |
-| Circuit breaker | ✅ half-open single-probe | ✅ |
-| Bulkhead | ✅ with optional queue + queue timeout | ✅ |
-| Rate limit | ✅ sliding window | — |
-| Cache (with single-flight) | ✅ built in, stampede-proof | — |
-| Request dedupe (single-flight) | ✅ generation-safe, joiner-isolated | — |
-| Hedged requests | ✅ | — |
-| Fallback | — (compose at call site) | ✅ |
-| Composition model | one `act()` call, declarative options object | explicit `wrap()` chaining of policy objects |
-| Cancellation | native `AbortSignal`, propagated through every policy | `CancellationToken` (custom, pre-dates broad `AbortSignal` adoption) |
-| Observability | opt-in hooks, zero-cost when unused | events per policy object |
-| State store | pluggable (`InMemoryStore` built in; bring your own for Redis etc.) | in-process only |
-
-Where the two overlap (retry, timeout, circuit breaker, bulkhead), the semantics are comparable and both are well-suited to production use. actly additionally folds cache, dedupe, rate limiting, and hedging into the same policy chain and result type, so a single `act()` call can express what would otherwise require composing several Cockatiel policies plus your own caching/dedupe layer. Cockatiel's `fallback` policy has no direct equivalent in actly — compose it at the call site by catching the returned `ActResult` and substituting a default when `!result.ok`.
-
-### Measured overhead: actly vs Cockatiel
-
-Feature parity is only half the story — here are actual numbers, not marketing claims. Run it yourself: `npm run build && npm install --no-save cockatiel && node bench/compare-cockatiel.mjs`.
-
-Representative run (Node 20, single machine, trivial no-op `fn`, 20,000 iterations per case — see `bench/compare-cockatiel.mjs` for full methodology):
-
-| Policy (happy path) | actly | Cockatiel | Cockatiel is faster by |
-|---|---|---|---|
-| retry (3 attempts configured, succeeds on 1st) | 5.0 µs/op | 0.9 µs/op | ~5.5x |
-| timeout (5s limit, resolves fast) | 13.7 µs/op | 7.1 µs/op | ~1.9x |
-| circuit breaker (closed) | 3.5 µs/op | 0.5 µs/op | ~7.1x |
-| bulkhead (under cap) | 4.2 µs/op | 0.5 µs/op | ~8.0x |
-| retry + timeout + circuitBreaker composed | 14.5 µs/op | 7.9 µs/op | ~1.8x |
-
-**Honest read:** Cockatiel is faster, consistently, on every policy they both implement. Its policies are closures with no external state lookup. actly's policies go through a keyed state store (`Map` get/set per call, even for `InMemoryStore`) to support cross-call features Cockatiel doesn't have — a circuit breaker's failure count has to live somewhere addressable by `key` across separate `act()` calls, not captured in a closure. That indirection costs microseconds per call.
-
-For nearly all real workloads this difference is noise — both add single-digit-to-low-double-digit microseconds against I/O that costs milliseconds. It matters if you're calling a policy millions of times per second in a hot loop with no I/O; it does not matter wrapping network or database calls, which is what both libraries are for. Pick actly when you want cache/dedupe/rate-limit/hedge in the same call and don't want to hand-wire a state layer around Cockatiel; pick Cockatiel when you only need retry/timeout/circuit-breaker/bulkhead/fallback and want the leanest possible per-call cost.
-
----
+`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
 
 ## API
 
 ### `act(key, fn, options?)`
 
-Wraps `fn` with reliability policies. Returns `Promise<ActResult<T>>`.
-
-| Param | Type | Description |
-|-------|------|-------------|
-| `key` | `string` | Stable identifier. Scopes dedupe + cache. Validated for prototype pollution, control chars, CRLF, length (≤1024), reserved prefixes. |
-| `fn` | `(signal: AbortSignal) => Promise<T> \| T` | The async work. Signal aborts on caller cancel, per-attempt timeout, or total timeout. Legacy `() => Promise<T>` accepted (signal ignored). |
-| `options` | `ActOptions` | Policy configuration. All fields optional. |
-
-**Returns:** `Promise<ActResult<T>>` — always resolves, never rejects.
+Wraps `fn` with reliability policies. Returns `Promise<ActResult<T>>`, always resolves.
 
 ```ts
 interface ActSuccess<T> {
   ok: true
   value: T
   source: 'fresh' | 'cache'
-  attempts: number      // 1-based; 0 on cache hit
-  traceId?: string      // present when observability or traceId option set
-  durationMs?: number   // wall-clock ms
+  attempts: number       // 1-based; 0 on cache hit
+  traceId?: string
+  durationMs?: number
 }
 
 interface ActFailure {
   ok: false
-  error: unknown        // typed — see Error taxonomy
+  error: unknown         // see Errors
   attempts: number
   traceId?: string
   durationMs?: number
 }
+
+type ActResult<T> = ActSuccess<T> | ActFailure
 ```
 
-### `invalidate(key)`
+`key` scopes dedupe and cache. Validated for prototype pollution, control chars, CRLF, length (1024 max), and reserved prefixes (`dedupe:`, `cache:`, `inflight:`, `tenant:`).
 
-Removes the cached value for `key` from the default module-level store. Returns `true` if a cache entry was removed.
+### `invalidate(key)`
 
-Does **not** cancel in-flight dedupe entries — those settle on their own.
+Removes the cached value for `key` from the default store. Returns `true` if a cache entry was removed.
 
 ```ts
 await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
-// ... user updates their profile ...
 invalidate('user:42')  // next call re-fetches
 ```
 
 ### `withStore(store)`
 
-Creates a scoped `act` function bound to an explicit store. Use for SSR request isolation, multi-tenant scenarios, or test isolation.
+Returns a scoped `act` bound to an explicit store. Use for SSR request isolation, multi-tenant scenarios, or tests.
 
 ```ts
 import { withStore, InMemoryStore } from 'actly'
@@ -147,76 +111,186 @@ try {
 }
 ```
 
-For sync stores, `invalidate` returns `boolean`. For async stores, returns `Promise<boolean>`.
+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`).
 
 ### `execute(input)`
 
-Low-level execution engine for building custom policy chains. Accepts `{ key, fn, policies, store, meta, signal, observability }`. Most callers should use `act()` instead.
+Low-level execution engine for custom policy chains. Accepts `{ key, fn, policies, store, meta, signal, observability }`. Most callers should use `act()`.
 
-### `InMemoryStore`
+### `noopPolicy()`
 
-Reference `SyncStateStore` implementation. Bounded LRU with TTL, background cleanup, O(1) operations.
+Passthrough policy. No retry, no timeout, no state. Useful for testing and conditional chains.
 
 ```ts
-import { InMemoryStore } from 'actly'
+const retry = isProd
+  ? retryPolicy({ attempts: 3 })
+  : noopPolicy()
+```
+
+### `usePolicy(options)`
+
+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()
+  }
+}
+```
+
+### `createHealthCheck(store, options?)`
 
+Returns a function that produces a `HealthStatus` snapshot.
+
+```ts
+import { createHealthCheck, InMemoryStore } from 'actly'
+
+const store = new InMemoryStore()
+const health = createHealthCheck(store, {
+  scope: 'default',
+  probeIntervalMs: 30_000,  // optional: warn on stuck inflight calls
+})
+
+const status = health()
+// { storeSize, pendingInflight, uptimeMs, lastError?, lastSuccessAt? }
+```
+
+### `drain(timeoutMs, scope?)` and `drainAll(timeoutMs)`
+
+Wait for in-flight `act()` calls to settle. `drainAll` drains all scopes in parallel.
+
+```ts
+process.on('SIGTERM', async () => {
+  const ok = await drainAll(10_000)
+  process.exit(ok ? 0 : 1)
+})
+```
+
+### `enableWatchdog(thresholdMs?, hooks?)`
+
+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
+enableWatchdog(30_000, {
+  onWatchdog: (e) => logger.warn({ elapsedMs: e.elapsedMs }, 'hung act() call'),
+})
+```
+
+### `createTenantStore(options)` and `createAsyncTenantStore(factory)`
+
+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.
+
+```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
+```
+
+### `InMemoryStore`
+
+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 store = new InMemoryStore({
-  maxSize: 10_000,          // default Infinity
-  autoCleanup: true,        // default false
-  cleanupIntervalMs: 30_000 // default 30s
+  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
 })
+
+store.destroy()  // stops timer, clears map, removes listeners. Idempotent.
 ```
 
----
+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.
 
 ## Options
 
-### `retry`
+All fields optional. Compose any combination.
 
-Retry `fn` on failure.
+### `retry`
 
 ```ts
 {
   retry: {
-    attempts: 3,                    // total attempts including first call (≥1, ≤100)
-    delayMs: 200,                   // base delay (≥0, ≤300_000)
+    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  // default: retry all except AbortError
+    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)
   }
 }
 ```
 
-**Delay computation order:** backoff grows → maxDelay caps → jitter randomizes.
+`shouldRetryResult` retries on returned values that are semantic failures. The common pattern: `fetch` returns a 500 without throwing.
 
-**Default `shouldRetry`:** retries on every error except `AbortError` (caller/timeout cancellation). Override to skip non-recoverable errors (HTTP 4xx, auth failures).
+```ts
+await act('fetch-api', async (signal) => fetch('/api', { signal }), {
+  retry: {
+    attempts: 3,
+    shouldRetryResult: (res) => res.ok && res.status < 500,
+  },
+})
+```
 
-**`attempts: 1` is a no-op** — the retry policy is skipped (pure overhead if included).
+`backoffFn` carries per-call state. Useful for honoring `Retry-After`.
+
+```ts
+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,
+  },
+})
+```
+
+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.
+
+`attempts: 1` is a no-op; the retry policy is skipped.
 
 ### `timeout`
 
 Per-attempt deadline. Each retry gets a fresh clock.
 
 ```ts
-{ timeout: { ms: 5_000 } }  // ms > 0, ≤100_000_000
+{ timeout: { ms: 5_000, strategy: 'race' } }
 ```
 
-If `fn` cooperates (passes `signal` to `fetch`, database drivers, etc.), the underlying work is cancelled. If `fn` ignores the signal, `act()` still returns promptly via a race — but the underlying work continues in the background (resource leak).
+`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`
 
-Hard wall-clock budget over the entire operation — including all retry attempts, delays, and per-attempt timeouts.
+Hard wall-clock budget over the whole operation, including retries, delays, and per-attempt timeouts.
 
 ```ts
 { totalTimeout: { ms: 12_000 } }
 ```
 
-Use with `timeout` to express: "each attempt may take at most X ms, but the whole operation must finish within Y ms."
-
 ### `dedupe`
 
-Collapse concurrent calls with the same key into one in-flight Promise.
+Collapses concurrent calls with the same key into one in-flight Promise.
 
 ```ts
 dedupe: true
@@ -224,186 +298,220 @@ dedupe: true
 dedupe: { enabled: true, inflightTtl: 30_000 }
 ```
 
-`inflightTtl` 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. Default: `Infinity` (no safety net). Pair with `timeout` or `totalTimeout` for proper cancellation.
+`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.
 
-**Joiner isolation:** if the originator's caller aborts, joiners are NOT affected. Each joiner races the in-flight promise against their own signal.
+Joiner isolation: if the originator's caller aborts, joiners are not affected. Each joiner races the in-flight Promise against their own signal.
 
-**Requires sync store.** `execute()` throws at chain-build time if an async store is used with dedupe.
+Requires a sync store. `execute()` throws at chain-build time if an async store is used with dedupe.
 
 ### `cache`
 
-Store successful results for a TTL.
+Stores successful results for a TTL.
 
 ```ts
-{ cache: { ttl: 60_000 } }  // ttl > 0, ≤86_400_000
+{ cache: { ttl: 60_000 } }  // 0 < ttl <= 86_400_000
 ```
 
-**Failures are never cached.** Only successful values are stored.
+Failures are never cached. Only successful values.
 
-**Single-flight (cache stampede prevention):** on sync stores, concurrent cache misses join a single in-flight Promise. On async stores, stampedes are a known limitation.
+Single-flight (cache stampede protection): on sync stores, concurrent cache misses join one in-flight Promise. On async stores, stampedes are a known limitation.
 
-**Fail-open writes:** if `store.set()` throws (e.g. Redis transient error), the error is swallowed and the value is returned to the caller. Caching is an optimization, not a correctness requirement.
+`store.set()` failures (e.g. Redis transient error) are swallowed; the value is still returned to the caller.
 
-### `signal`
+### `circuitBreaker`
 
-Caller-provided `AbortSignal` for external cancellation.
+Opens after threshold failures, rejects immediately while open, allows one probe call after cooldown.
 
 ```ts
-const controller = new AbortController()
-setTimeout(() => controller.abort(new Error('user-cancelled')), 5_000)
-
-await act('user:42', async (signal) => fetch(url, { signal }), {
-  signal: controller.signal,
-})
+{
+  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
+  }
+}
 ```
 
-### `observability`
+`consecutive` opens after N failures in a row. Resets on any success. Good for "downstream is fully down."
+
+`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).
+
+Half-open probe: probe failure re-opens immediately. Probe success resets the window (count strategy) or the failure counter (consecutive).
+
+### `bulkhead`
 
-Event hooks for metrics, logging, and tracing. Zero overhead when not registered.
+Caps in-flight concurrency per key.
 
 ```ts
 {
-  observability: {
-    onAttempt:       (e) => metrics.increment('act.attempt', { attempt: e.attempt }),
-    onRetry:         (e) => metrics.increment('act.retry', { attempt: e.attempt }),
-    onCacheHit:      (e) => metrics.increment('act.cache_hit', { ageMs: e.ageMs }),
-    onCacheMiss:     (e) => metrics.increment('act.cache_miss'),
-    onDedupeJoin:    (e) => metrics.increment('act.dedupe_join'),
-    onTimeout:       (e) => metrics.increment('act.timeout', { kind: e.kind }),
-    onFinalSuccess:  (e) => metrics.histogram('act.duration', e.durationMs),
-    onFinalFailure:  (e) => logger.error({ traceId: e.traceId, failedBy: e.failedBy }, 'act failed'),
+  bulkhead: {
+    maxConcurrent: 10,
+    maxQueueSize: 100,         // default Infinity
+    queueTimeoutMs: 5_000,     // default Infinity
   }
 }
 ```
 
-**Zero-cost contract:** when `observability` is `undefined` or an empty hooks object, no event objects are allocated and no function calls are made. Verified by benchmark: empty observability adds ~0.24 µs over fast path.
-
-### `traceId`
-
-Correlation ID for logs/metrics. Auto-generated via `crypto.randomUUID()` on Node 20+. Falls back to timestamp+random string. Surfaces on every event and on `ActResult.traceId`.
-
----
+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%.
 
-## Error taxonomy
+### `rateLimit`
 
-Six error classes. All extend `ActlyError` which extends `Error`. Each carries a stable `.code` string for cross-realm telemetry (e.g. errors serialized over IPC).
+Sliding window rate limit per key.
 
 ```ts
-import {
-  ActlyError,           // abstract base — instanceof ActlyError
-  ActlyAbortError,      // .code = 'ACTLY_ABORT' — caller/signal cancellation
-  TimeoutError,         // .code = 'ACTLY_TIMEOUT' — per-attempt deadline
-  TotalTimeoutError,    // .code = 'ACTLY_TOTAL_TIMEOUT' — operation-wide budget
-  RetryExhaustedError,  // .code = 'ACTLY_RETRY_EXHAUSTED' — all attempts failed
-  ValidationError,      // .code = 'ACTLY_VALIDATION' — programmer error (invalid options)
-} from 'actly'
+{ rateLimit: { maxCalls: 100, windowMs: 60_000 } }
 ```
 
-**`ValidationError` throws synchronously** — it's not wrapped in `ActFailure` because the caller's code is broken, not the runtime.
+### `hedge`
 
-**`RetryExhaustedError`** carries `attempts`, `lastError`, and `errors[]` for debugging retry patterns.
+Sends a second call after `delayMs`, races them, cancels the loser.
 
 ```ts
-if (!result.ok && result.error instanceof RetryExhaustedError) {
-  console.log(`failed after ${result.error.attempts} attempts`)
-  console.log(`last error:`, result.error.lastError)
+{
+  hedge: {
+    delayMs: 100,                  // > 0, <= 300_000
+    keepLoser: false,              // default false; true = don't cancel
+    placement: 'outside-retry',    // 'outside-retry' (default) | 'inside-retry'
+  }
 }
 ```
 
-**Cross-realm safety:** prefer `err.code === 'ACTLY_TIMEOUT'` over `err instanceof TimeoutError` when errors cross process/worker boundaries.
+`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.
 
-## Stores
+### `fallback`
 
-### Sync vs Async
+Returns a value (or function result) instead of the failure when `fn` fails.
 
-`SyncStateStore` — all operations complete synchronously. Required for `dedupePolicy` (the read-then-write that makes deduplication work must happen in a single synchronous frame).
+```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.
+
+### `observability`
 
-`AsyncStateStore` — all operations return Promises. Compatible with `cachePolicy` only.
+Hooks fire on lifecycle events. Wrapped in `safeCall` so a buggy hook never crashes the main path.
 
 ```ts
-import type { SyncStateStore, AsyncStateStore } from 'actly'
-
-// Sync: InMemoryStore is the reference implementation
-const syncStore: SyncStateStore = new InMemoryStore()
-
-// Async: implement the interface for Redis, DynamoDB, etc.
-const asyncStore: AsyncStateStore = {
-  _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> { /* ... */ },
+{
+  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) => ...,
+  }
 }
 ```
 
-### Default store
+Each event carries `key`, `traceId`, `timestamp`. Pass `traceId` explicitly or let actly generate a UUID.
 
-`act()` without `withStore()` uses a module-level default `InMemoryStore` bounded at 10,000 entries with 60-second background cleanup.
+### `audit`
 
-**Multi-tenant warning:** the default store is shared across all callers in the process. For multi-tenant applications, use `withStore()` with per-tenant stores to prevent cross-tenant data leakage.
+Single hook for structured logging of every call result.
 
-### `InMemoryStore` internals
+```ts
+{
+  audit: {
+    log: (entry: AuditEntry) => {
+      // { key, traceId, timestamp, durationMs, ok, attempts, failedBy?, error? }
+      logger.info(entry)
+    },
+  }
+}
+```
 
-- **LRU:** doubly-linked list for O(1) reordering (no `delete + set` Map churn).
-- **TTL:** lazy on `get()`/`has()`, background sweep for unreferenced entries.
-- **`size()`:** O(1) via Map size counter.
-- **`destroy():** stops cleanup timer. Idempotent.
+### `signal`
 
----
+Caller-supplied `AbortSignal`. Linked to the root controller. Aborting it cancels the entire operation.
 
-## Policy order
+## Errors
 
-Policies are applied in a fixed order, outermost to innermost:
+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.
 
-```
-totalTimeout → cache → dedupe → retry → timeout → fn
-```
+| 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 |
+
+`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.
 
-- `totalTimeout` is outermost — if it fires, no inner policy can extend the deadline.
-- `cache` short-circuits everything below it on a hit.
-- `dedupe` collapses concurrent callers before retry fires.
-- `retry` owns the attempt loop.
-- `timeout` is innermost — each attempt gets a fresh clock.
+## Compared to Cockatiel
 
-Policies with no effect (e.g. `retry.attempts: 1`) are skipped.
+Both are typed, zero-dependency resilience libraries for Node/TypeScript. Both use native `AbortSignal` for cancellation. The core difference is scope *and* size.
 
----
+| | 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 |
 
-## Limits
+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.
 
-All numeric inputs are bounded to prevent memory/CPU/timer exhaustion:
+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.
 
-| Limit | Value | Rationale |
-|-------|-------|-----------|
-| `MAX_KEY_LENGTH` | 1024 chars | Prevents multi-MB keys bloating stores |
-| `MAX_RETRY_ATTEMPTS` | 100 | ~100 fn invocations |
-| `MAX_TIMEOUT_MS` | 100,000,000 ms (~27h) | Prevents timer overflow |
-| `MAX_CACHE_TTL` | 86,400,000 ms (24h) | Prevents pathological TTLs |
-| `MAX_RETRY_DELAY_MS` | 300,000 ms (5 min) | Bounds worst-case latency per retry |
-| `MAX_INFLIGHT_TTL` | 86,400,000 ms (24h) | Bounds dedupe inflight window |
-| `DEFAULT_STORE_MAX_SIZE` | 10,000 entries | Bounds default store memory |
+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.
 
-Exceeding a limit throws `RangeError`. If you need more, you likely have a bug.
+## Performance
 
----
+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.
 
-## Migration
+| 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 |
 
-### From v1.1.x to v1.2.0
+**Cockatiel comparison (same sandbox, same workload):**
 
-**Node 20+ required** (was 18+). Node 18 reached EOL April 2025.
+| 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 |
 
-**`retryPolicy` now throws `RetryExhaustedError`** when all attempts fail AND at least one retry happened. Previously, the raw last error was surfaced. The raw error is available on `err.lastError` and `err.errors[]`. If `shouldRetry` returned `false` on the first attempt (no retries), the raw error is still surfaced — no wrapping.
+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.
 
-**`TimeoutError` and `TotalTimeoutError` now extend `ActlyError`** (which extends `Error`). Existing `instanceof Error` and `instanceof TimeoutError` checks continue to work. Optional: switch to `err.code === 'ACTLY_TIMEOUT'` for cross-realm safety.
+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.
 
-**`ActResult` has new optional fields**: `traceId?`, `durationMs?`. Existing code that reads only `ok`, `value`, `error`, `source`, `attempts` is unaffected.
+## 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