actly 1.1.5 → 1.2.0

package/README.md

@@ -1,25 +1,18 @@
 # 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 execution. Retry, timeout, dedupe, cache — composable, zero-throw, with `AbortSignal` cancellation, jittered backoff, observability hooks, and a typed error taxonomy.
 
 ```bash
 npm install actly
 ```
 
-> Requires Node 18+. Ships ESM + CJS. Zero dependencies.
+> Requires Node 20+. Ships ESM + CJS. Zero runtime dependencies. Tree-shakeable.
 
 ---
 
-## The problem
+## What it does
 
-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.
-
----
-
-## Quick start
+`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.
 
 ```ts
 import { act } from 'actly'
@@ -37,573 +30,378 @@ const result = await act(
 )
 
 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.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)
 } else {
-  console.error(result.error)  // unknown — never throws
+  console.error(result.error)    // typed — see Error taxonomy
 }
 ```
 
-`act` always resolves. It never rejects. You check `.ok` and move on.
-
-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
+## Compared to Cockatiel
 
-```ts
-act<T>(key: string, fn: ActFn<T>, options?: ActOptions): Promise<ActResult<T>>
-```
+Both are typed, zero-dependency resilience libraries for Node/TypeScript. The core difference is scope and composition model.
 
-| Argument | Type | Description |
+| | actly | Cockatiel |
 |---|---|---|
-| `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. |
+| 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 |
 
-### Result shape
+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`.
 
-```ts
-type ActResult<T> =
-  | { ok: true;  value: T; source: 'fresh' | 'cache'; attempts: number }
-  | { ok: false; error: unknown;                       attempts: number }
-```
-
-`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)
-
----
+### Measured overhead: actly vs Cockatiel
 
-## Policies
+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`.
 
-All policies are optional and compose freely. The execution order is **fixed**:
+Representative run (Node 20, single machine, trivial no-op `fn`, 20,000 iterations per case — see `bench/compare-cockatiel.mjs` for full methodology):
 
-```
-totalTimeout → cache → dedupe → retry → timeout
-```
+| 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 |
 
-### Retry
+**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.
 
-```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')
-  },
-})
-```
+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.
 
-`result.attempts` tells you how many tries it took.
+---
 
-#### Jitter (default: `'full'`)
+## API
 
-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]`.
+### `act(key, fn, options?)`
 
-| Strategy | Formula |
-|---|---|
-| `'none'` | `delay` |
-| `'full'` | `random() * delay` |
-| `'equal'` | `delay/2 + random() * delay/2` |
-| `'decorrelated'` | `base + random() * (delay - base)` |
+Wraps `fn` with reliability policies. Returns `Promise<ActResult<T>>`.
 
-#### Selective retry with `shouldRetry`
+| 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. |
 
-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.
+**Returns:** `Promise<ActResult<T>>` — always resolves, never rejects.
 
 ```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
-    },
-  },
-})
-```
-
-`shouldRetry(error, attempt)` receives the error and the 1-based attempt number. Return `false` to surface the error immediately.
+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
+}
 
-> **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.
+interface ActFailure {
+  ok: false
+  error: unknown        // typed — see Error taxonomy
+  attempts: number
+  traceId?: string
+  durationMs?: number
+}
+```
 
----
+### `invalidate(key)`
 
-### Timeout
+Removes the cached value for `key` from the default module-level store. Returns `true` if a cache entry was removed.
 
-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).
+Does **not** cancel in-flight dedupe entries — those settle on their own.
 
 ```ts
-import { act, TimeoutError } from 'actly'
-
-const result = await act('geo:lookup', async (signal) => lookupCoords(ip, signal), {
-  timeout: { ms: 3_000 },
-})
-
-if (!result.ok && result.error instanceof TimeoutError) {
-  console.log(`timed out after ${result.error.ms}ms`)
-}
+await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
+// ... user updates their profile ...
+invalidate('user:42')  // next call re-fetches
 ```
 
-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.
-
----
-
-### 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.
+### `withStore(store)`
 
-**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.
+Creates a scoped `act` function bound to an explicit store. Use for SSR request isolation, multi-tenant scenarios, or test isolation.
 
 ```ts
-import { act, TimeoutError, TotalTimeoutError } from 'actly'
+import { withStore, InMemoryStore } 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
-})
+const store = new InMemoryStore({ maxSize: 1000, autoCleanup: true })
+const act = withStore(store)
 
-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`)
-  }
+try {
+  await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
+  act.invalidate('user:42')
+} finally {
+  store.destroy()
 }
 ```
 
-`TotalTimeoutError` and `TimeoutError` are separate classes — `instanceof` distinguishes which deadline fired.
+For sync stores, `invalidate` returns `boolean`. For async stores, returns `Promise<boolean>`.
 
----
+### `execute(input)`
 
-### Dedupe
+Low-level execution engine for building custom policy chains. Accepts `{ key, fn, policies, store, meta, signal, observability }`. Most callers should use `act()` instead.
 
-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.
+### `InMemoryStore`
+
+Reference `SyncStateStore` implementation. Bounded LRU with TTL, background cleanup, O(1) operations.
 
 ```ts
-const result = await act('config:load', async (signal) => loadRemoteConfig(signal), {
-  dedupe: true,
+import { InMemoryStore } from 'actly'
+
+const store = new InMemoryStore({
+  maxSize: 10_000,          // default Infinity
+  autoCleanup: true,        // default false
+  cleanupIntervalMs: 30_000 // default 30s
 })
 ```
 
-`dedupe: { enabled: true }` is also valid — object form for forward compatibility.
-
-#### v1.1.5 fixes
-
-- **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.
-
 ---
 
-### Cache
-
-Stores successful results for `ttl` milliseconds. Failures are never cached. A cache hit short-circuits everything — dedupe, retry, and timeout are all skipped.
-
-```ts
-const result = await act('flags:all', async (signal) => fetchFeatureFlags(signal), {
-  cache: { ttl: 60_000 },
-})
-
-console.log(result.source) // 'fresh' on miss, 'cache' on hit
-console.log(result.attempts) // 1 on miss, 0 on hit (v1.1.5 fix)
-```
-
-#### v1.1.5 fixes
+## Options
 
-- **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.
+### `retry`
 
-#### Invalidation
+Retry `fn` on failure.
 
 ```ts
-import { act, invalidate } from 'actly'
-
-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
+{
+  retry: {
+    attempts: 3,                    // total attempts including first call (≥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
+  }
+}
 ```
 
-For scoped stores (see `withStore` below), use the scoped `invalidate`:
+**Delay computation order:** backoff grows → maxDelay caps → jitter randomizes.
 
-```ts
-const scopedAct = withStore(myStore)
-scopedAct.invalidate('user:42')  // sync store: returns boolean
-                                // async store: returns Promise<boolean>
-```
+**Default `shouldRetry`:** retries on every error except `AbortError` (caller/timeout cancellation). Override to skip non-recoverable errors (HTTP 4xx, auth failures).
 
----
+**`attempts: 1` is a no-op** — the retry policy is skipped (pure overhead if included).
+
+### `timeout`
 
-### Combining policies
+Per-attempt deadline. Each retry gets a fresh clock.
 
 ```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
-})
+{ timeout: { ms: 5_000 } }  // ms > 0, ≤100_000_000
 ```
 
----
+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).
 
-## Cancellation: `options.signal`
+### `totalTimeout`
 
-`act()` accepts an `AbortSignal` for caller-driven cancellation:
+Hard wall-clock budget over the entire operation — including all retry attempts, delays, and per-attempt timeouts.
 
 ```ts
-const controller = new AbortController()
-const promise = act('search:big', async (signal) => runBigQuery(q, signal), {
-  signal: controller.signal,
-  timeout: { ms: 30_000 },
-})
-
-// User clicks "Cancel":
-controller.abort(new Error('user-cancelled'))
-
-const r = await promise
-// r.ok === false, r.error.message === 'user-cancelled'
+{ totalTimeout: { ms: 12_000 } }
 ```
 
-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.
-
-The signal propagates through the entire chain: `totalTimeout`, `retry` (interrupts delay sleeps), and `timeout` all observe it. No more attempts fire after abort.
+Use with `timeout` to express: "each attempt may take at most X ms, but the whole operation must finish within Y ms."
 
----
+### `dedupe`
 
-## Options reference
+Collapse concurrent calls with the same key into one in-flight Promise.
 
 ```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
+dedupe: true
+// or
+dedupe: { enabled: true, inflightTtl: 30_000 }
 ```
 
-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`.
+`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.
 
----
+**Joiner isolation:** if the originator's caller aborts, joiners are NOT affected. Each joiner races the in-flight promise against their own signal.
 
-## Exported values
+**Requires sync store.** `execute()` throws at chain-build time if an async store is used with dedupe.
 
-```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'
-```
+### `cache`
 
----
-
-## Exported types
+Store successful results for a TTL.
 
 ```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'
+{ cache: { ttl: 60_000 } }  // ttl > 0, ≤86_400_000
 ```
 
----
+**Failures are never cached.** Only successful values are stored.
 
-## Custom store
+**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.
 
-By default `act` uses a module-level `InMemoryStore`. For SSR request isolation, multi-tenant scenarios, or test control, use `withStore()`:
+**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.
 
-### `withStore(store)`
+### `signal`
 
-Returns a scoped `act` function bound to the provided store, with an `invalidate(key)` method and a `store` reference attached.
+Caller-provided `AbortSignal` for external cancellation.
 
 ```ts
-import { withStore, InMemoryStore } from 'actly'
-
-// Basic
-const store = new InMemoryStore()
-const act = withStore(store)
+const controller = new AbortController()
+setTimeout(() => controller.abort(new Error('user-cancelled')), 5_000)
 
-// 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)
+await act('user:42', async (signal) => fetch(url, { signal }), {
+  signal: controller.signal,
 })
-const serverAct = withStore(serverStore)
+```
 
-try {
-  await serverAct('user:42', async (signal) => fetchUser(42, signal), {
-    cache: { ttl: 60_000 },
-  })
+### `observability`
 
-  // ... user updates their profile ...
-  serverAct.invalidate('user:42')  // next call re-fetches
+Event hooks for metrics, logging, and tracing. Zero overhead when not registered.
 
-  // Access the underlying store if needed:
-  console.log(serverAct.store.size())
-} finally {
-  serverStore.destroy()  // stop the cleanup timer
+```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'),
+  }
 }
 ```
 
-For sync stores, `invalidate` returns `boolean` synchronously.
-For async stores, `invalidate` returns `Promise<boolean>`.
+**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.
 
-### `execute()` directly
+### `traceId`
 
-For full control (custom policy chains, custom meta, custom signal composition), call `execute()` directly:
+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`.
 
-```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,
-})
+---
 
-console.log(meta.attempts)  // final attempt count
-```
+## Error taxonomy
 
-### InMemoryStore options
+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).
 
 ```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,
-})
+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'
 ```
 
-`InMemoryStore` satisfies `SyncStateStore`. Call `destroy()` to stop the background timer and prevent leaks.
-
-### Async store (v1.1+)
+**`ValidationError` throws synchronously** — it's not wrapped in `ActFailure` because the caller's code is broken, not the runtime.
 
-For external cache backends (Redis, Upstash, etc.), implement `AsyncStateStore`:
+**`RetryExhaustedError`** carries `attempts`, `lastError`, and `errors[]` for debugging retry patterns.
 
 ```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> { /* ... */ }
+if (!result.ok && result.error instanceof RetryExhaustedError) {
+  console.log(`failed after ${result.error.attempts} attempts`)
+  console.log(`last error:`, result.error.lastError)
 }
 ```
 
-`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).
+**Cross-realm safety:** prefer `err.code === 'ACTLY_TIMEOUT'` over `err instanceof TimeoutError` when errors cross process/worker boundaries.
 
 ---
 
-## Store interfaces
+## Stores
 
-```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
-}
+### Sync vs Async
+
+`SyncStateStore` — all operations complete synchronously. Required for `dedupePolicy` (the read-then-write that makes deduplication work must happen in a single synchronous frame).
+
+`AsyncStateStore` — all operations return Promises. Compatible with `cachePolicy` only.
 
-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>
+```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> { /* ... */ },
 }
 ```
 
-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`.
+### Default store
 
----
+`act()` without `withStore()` uses a module-level default `InMemoryStore` bounded at 10,000 entries with 60-second background cleanup.
 
-## Zero-throw contract
+**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.
 
-`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.
+### `InMemoryStore` internals
 
-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.
+- **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.
 
 ---
 
-## Philosophy
+## Policy order
 
-One function. One return type. No exceptions in userland.
+Policies are applied in a fixed order, outermost to innermost:
 
-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.)
+```
+totalTimeout → cache → dedupe → retry → timeout → fn
+```
 
-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.
+- `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.
 
-Cancellation is cooperative: pass the `signal` through. `act()` will return promptly regardless (via internal race), but only you can stop `fn` from leaking resources.
+Policies with no effect (e.g. `retry.attempts: 1`) are skipped.
 
 ---
 
-## Changelog
-
-### v1.1.5 — 2026-06-25
-
-**Critical correctness fixes**
-
-- **`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.)*
-
-**Public API additions (fixes A-1, A-2, m-8)**
+## Limits
 
-- **`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).
+All numeric inputs are bounded to prevent memory/CPU/timer exhaustion:
 
-**New options**
+| 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 |
 
-- **`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).
-
-**Behaviour changes (non-breaking)**
-
-- **`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.
-
-**Internal improvements**
-
-- **`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.)*
-
-**Non-breaking changes**
-
-- `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.
+Exceeding a limit throws `RangeError`. If you need more, you likely have a bug.
 
 ---
 
-### v1.1.0 — 2026-06-01
+## Migration
 
-- `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.
+### From v1.1.x to v1.2.0
 
----
+**Node 20+ required** (was 18+). Node 18 reached EOL April 2025.
+
+**`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.
 
-### v1.0.1
+**`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.
 
-- Initial stable release.
-- `act()`, `retry`, `timeout`, `totalTimeout`, `dedupe`, `cache`.
-- `TimeoutError` exported for `instanceof` checks.
-- Zero dependencies. ESM + CJS. Node 18+.
+**`ActResult` has new optional fields**: `traceId?`, `durationMs?`. Existing code that reads only `ok`, `value`, `error`, `source`, `attempts` is unaffected.
 
 ---