actly 1.1.0 → 1.2.0

package/README.md

@@ -1,377 +1,407 @@
 # actly
 
-**Reliability primitive for async functions.**  
-Retry. Timeout. Dedupe. Cache. Composable, typed, zero-throw.
+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'
 
-const result = await act('user:42', () => fetchUser(42))
+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 },
+  },
+)
 
 if (result.ok) {
-  console.log(result.value)    // T
-  console.log(result.source)   // 'fresh' | 'cache'
-  console.log(result.attempts) // number
+  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.
-
 ---
 
-## API
+## Compared to Cockatiel
 
-```ts
-act<T>(key: string, fn: () => Promise<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. |
-| `fn` | `() => Promise<T>` | The async function to execute. |
-| `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 }
-```
+### 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.
 
 ---
 
-## Policies
+## API
 
-All policies are optional and compose freely. The execution order is **fixed**:
+### `act(key, fn, options?)`
 
-```
-totalTimeout → cache → dedupe → retry → timeout
-```
+Wraps `fn` with reliability policies. Returns `Promise<ActResult<T>>`.
 
-### Retry
+| 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.
 
 ```ts
-const result = await act('payments:charge', () => chargeCard(payload), {
-  retry: {
-    attempts: 3,            // total attempts (including first)
-    delayMs:  200,          // base delay between attempts (ms)
-    backoff:  'exponential' // 'none' | 'linear' | 'exponential'
-  },
-})
+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
+}
+
+interface ActFailure {
+  ok: false
+  error: unknown        // typed — see Error taxonomy
+  attempts: number
+  traceId?: string
+  durationMs?: number
+}
 ```
 
-`result.attempts` tells you how many tries it took.
+### `invalidate(key)`
 
-#### Selective retry with `shouldRetry`
+Removes the cached value for `key` from the default module-level store. Returns `true` if a cache entry was removed.
 
-By default, every error triggers a retry. Use `shouldRetry` to skip retrying permanent errors — a `404` will never recover, a `503` might.
+Does **not** cancel in-flight dedupe entries — those settle on their own.
 
 ```ts
-const result = await act('api:resource', () => fetchResource(id), {
-  retry: {
-    attempts: 4,
-    delayMs:  150,
-    backoff:  'exponential',
-    shouldRetry: (err, attempt) => {
-      if (err instanceof HttpError && err.status < 500) return false
-      return true
-    },
-  },
-})
+await act('user:42', () => fetchUser(42), { cache: { ttl: 60_000 } })
+// ... user updates their profile ...
+invalidate('user:42')  // next call re-fetches
 ```
 
-`shouldRetry(error, attempt)` receives the error and the 1-based attempt number. Return `false` to surface the error immediately. Not called on the final attempt — that always surfaces.
+### `withStore(store)`
 
----
-
-### Timeout
-
-Per-attempt deadline. Each retry gets a fresh clock.
+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 } from 'actly'
+import { withStore, InMemoryStore } from 'actly'
 
-const result = await act('geo:lookup', () => lookupCoords(ip), {
-  timeout: { ms: 3_000 },
-})
+const store = new InMemoryStore({ maxSize: 1000, autoCleanup: true })
+const act = withStore(store)
 
-if (!result.ok && result.error instanceof TimeoutError) {
-  console.log(`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()
 }
 ```
 
----
+For sync stores, `invalidate` returns `boolean`. For async stores, returns `Promise<boolean>`.
 
-### Total timeout
+### `execute(input)`
 
-Hard budget over the **entire** operation — all attempts, delays, and per-attempt timeouts combined. The per-attempt `timeout` resets on retry; `totalTimeout` does not.
+Low-level execution engine for building custom policy chains. Accepts `{ key, fn, policies, store, meta, signal, observability }`. Most callers should use `act()` instead.
+
+### `InMemoryStore`
+
+Reference `SyncStateStore` implementation. Bounded LRU with TTL, background cleanup, O(1) operations.
 
 ```ts
-import { act, TimeoutError, TotalTimeoutError } from 'actly'
+import { InMemoryStore } from 'actly'
 
-const result = await act('search:query', () => runQuery(q), {
-  retry:        { attempts: 5, delayMs: 100, backoff: 'linear' },
-  timeout:      { ms: 2_000 },  // per attempt
-  totalTimeout: { ms: 8_000 },  // whole operation
+const store = new InMemoryStore({
+  maxSize: 10_000,          // default Infinity
+  autoCleanup: true,        // default false
+  cleanupIntervalMs: 30_000 // default 30s
 })
-
-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.
-
 ---
 
-### Dedupe
+## Options
+
+### `retry`
 
-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.
+Retry `fn` on failure.
 
 ```ts
-const result = await act('config:load', () => loadRemoteConfig(), {
-  dedupe: true,
-})
+{
+  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
+  }
+}
 ```
 
-`dedupe: { enabled: true }` is also valid — object form for forward compatibility.
+**Delay computation order:** backoff grows → maxDelay caps → jitter randomizes.
 
-> **Note:** Deduped callers (those that joined an in-flight Promise) always receive `attempts: 1` in their result, because the retry counter belongs to the originating call. This is a known trade-off.
+**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).
 
-### Cache
+### `timeout`
 
-Stores successful results for `ttl` milliseconds. Failures are never cached. A cache hit short-circuits everything — dedupe, retry, and timeout are all skipped.
+Per-attempt deadline. Each retry gets a fresh clock.
 
 ```ts
-const result = await act('flags:all', () => fetchFeatureFlags(), {
-  cache: { ttl: 60_000 },
-})
-
-console.log(result.source) // 'fresh' on miss, 'cache' on hit
+{ 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).
+
+### `totalTimeout`
 
-### Combining policies
+Hard wall-clock budget over the entire operation — including all retry attempts, delays, and per-attempt timeouts.
 
 ```ts
-const result = await act('product:detail', () => fetchProduct(id), {
-  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
-})
+{ 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`
 
-## 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
-}
+dedupe: true
+// or
+dedupe: { enabled: true, inflightTtl: 30_000 }
+```
 
-interface RetryOptions {
-  attempts:     number
-  delayMs?:     number
-  backoff?:     'none' | 'linear' | 'exponential'
-  shouldRetry?: (error: unknown, attempt: number) => boolean
-}
+`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.
 
-interface TimeoutOptions  { ms: number }
-interface DedupeOptions   { enabled: boolean }
-interface CacheOptions    { ttl: number }
-```
+**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.
+
+### `cache`
 
-## Exported values
+Store successful results for a TTL.
 
 ```ts
-import {
-  act,                       // primary function
-  InMemoryStore,             // isolated store for SSR / tests
-  TimeoutError,              // per-attempt deadline (.ms)
-  TotalTimeoutError,         // total budget exhausted (.ms)
-} from 'actly'
+{ cache: { ttl: 60_000 } }  // ttl > 0, ≤86_400_000
 ```
 
----
+**Failures are never cached.** Only successful values are stored.
+
+**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.
+
+**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.
+
+### `signal`
 
-## Exported types
+Caller-provided `AbortSignal` for external cancellation.
 
 ```ts
-import type {
-  ActResult, ActSuccess, ActFailure, ActSource,
-  ActOptions, ActFn,
-  RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions,
-  // v1.1 — store interfaces
-  SyncStateStore,
-  AsyncStateStore,
-  InMemoryStoreOptions,
-  // v1.0 alias — still valid, zero migration needed
-  StateStore,
-} from 'actly'
-```
+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,
+})
+```
 
-## Custom store
+### `observability`
 
-By default `act` uses a module-level `InMemoryStore`. For SSR request isolation or test control, instantiate your own:
+Event hooks for metrics, logging, and tracing. Zero overhead when not registered.
 
 ```ts
-import { InMemoryStore } from 'actly'
+{
+  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'),
+  }
+}
+```
 
-// Basic
-const store = new InMemoryStore()
+**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.
 
-// With background cleanup (useful for long-lived server-side stores)
-const store = new InMemoryStore({
-  autoCleanup: true,
-  cleanupIntervalMs: 60_000, // sweep every 60s (default: 30s)
-})
+### `traceId`
 
-// Always call destroy() when done to prevent timer leaks
-store.destroy()
-```
+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`.
 
-`InMemoryStore` satisfies `SyncStateStore`. Use it with `execute()` directly for full control.
+---
 
-### Async store (v1.1+)
+## Error taxonomy
 
-For external cache backends (Redis, Upstash, etc.), implement `AsyncStateStore`:
+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
-import type { AsyncStateStore } from 'actly'
+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'
+```
+
+**`ValidationError` throws synchronously** — it's not wrapped in `ActFailure` because the caller's code is broken, not the runtime.
 
-class RedisStore implements AsyncStateStore {
-  readonly _sync = false as const
+**`RetryExhaustedError`** carries `attempts`, `lastError`, and `errors[]` for debugging retry patterns.
 
-  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> { /* ... */ }
+```ts
+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 — dedupe requires synchronous store access. See `SyncStateStore` docs for the reason.
+**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).
 
-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>
+`AsyncStateStore` — all operations return Promises. Compatible with `cachePolicy` only.
+
+```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 the executor 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 — the result is an `ActFailure`, not a rejected promise. This contract holds across all versions.
+### `InMemoryStore` internals
+
+- **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
+
+Policies are applied in a fixed order, outermost to innermost:
 
-One function. One return type. No exceptions in userland.
+```
+totalTimeout → cache → dedupe → retry → timeout → fn
+```
 
-The key is your responsibility. Make it stable and specific. `user:42` is good. `fetch` is not.
+- `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.
 
-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.
+Policies with no effect (e.g. `retry.attempts: 1`) are skipped.
 
 ---
 
-## Changelog
+## Limits
 
-### v1.1.0 — 2026-06-01
+All numeric inputs are bounded to prevent memory/CPU/timer exhaustion:
 
-**New features**
+| 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 |
 
-- **`AsyncStateStore` interface** — plug in any async key-value backend (Redis, Upstash, Cloudflare KV). Compatible with `cache` policy. Using with `dedupe` is a compile-time and runtime error by design.
-- **`SyncStateStore` interface** — the canonical public name for what was previously the internal store shape. `StateStore` is preserved as an alias with zero breakage for existing code.
-- **`InMemoryStore` is now a public export** — construct isolated stores for SSR request isolation, per-test control, or multi-tenant scenarios. Accepts `InMemoryStoreOptions`.
-- **`InMemoryStoreOptions`** — opt-in `autoCleanup` with configurable `cleanupIntervalMs`. Call `destroy()` to stop the background timer and prevent leaks.
-- **`TotalTimeoutError`** — new error class thrown when `totalTimeout` fires. Distinct from `TimeoutError` (per-attempt) so `instanceof` tells you which deadline fired.
-- **`totalTimeout` option** — hard wall-clock budget over the entire operation including all retry attempts and delays. Use alongside `timeout` to express both per-attempt and total constraints.
-- **`dedupe: true` shorthand** — equivalent to `dedupe: { enabled: true }`. Object form still valid for forward compatibility.
-- **`isSyncStore()` / `isAsyncStore()` type guards** — exported from `actly` for consumers building custom policy chains or store adapters.
+Exceeding a limit throws `RangeError`. If you need more, you likely have a bug.
 
-**Internal improvements**
+---
 
-- Executor validates sync-store requirement at chain-build time — async store + `dedupePolicy` throws immediately with a clear message instead of producing silent correctness failures.
-- `dedupePolicy` tagged with `REQUIRES_SYNC_STORE` symbol — allows executor to detect the constraint without importing the policy module (avoids circular deps).
-- `cachePolicy` now branches sync/async paths — fast synchronous path for `InMemoryStore`, async-await path for external stores.
+## Migration
 
-**Non-breaking changes**
+### From v1.1.x to v1.2.0
 
-- `StateStore` preserved as type alias for `SyncStateStore` — all v1.0 code compiles without changes.
-- All new exports are purely additive.
+**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.
 
 ---