actly 1.1.0 → 1.1.5

package/README.md

@@ -1,7 +1,7 @@
 # actly
 
-**Reliability primitive for async functions.**  
-Retry. Timeout. Dedupe. Cache. Composable, typed, zero-throw.
+**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.
 
 ```bash
 npm install actly
@@ -24,12 +24,22 @@ These patterns are solved the same way every time. `actly` solves them once.
 ```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.attempts) // number (0 on cache hit)
 } else {
   console.error(result.error)  // unknown — never throws
 }
@@ -37,18 +47,20 @@ if (result.ok) {
 
 `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
 
 ```ts
-act<T>(key: string, fn: () => Promise<T>, options?: ActOptions): Promise<ActResult<T>>
+act<T>(key: string, fn: ActFn<T>, options?: ActOptions): Promise<ActResult<T>>
 ```
 
 | Argument | Type | Description |
 |---|---|---|
-| `key` | `string` | Stable, unique identifier. Scopes dedupe and cache state. |
-| `fn` | `() => Promise<T>` | The async function to execute. |
+| `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. |
 
 ### Result shape
@@ -59,6 +71,12 @@ type ActResult<T> =
   | { 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)
+
 ---
 
 ## Policies
@@ -72,23 +90,36 @@ totalTimeout → cache → dedupe → retry → timeout
 ### Retry
 
 ```ts
-const result = await act('payments:charge', () => chargeCard(payload), {
+const result = await act('payments:charge', async (signal) => chargeCard(payload, signal), {
   retry: {
-    attempts: 3,            // total attempts (including first)
+    attempts: 3,            // total attempts (including first). Must be integer >= 1.
     delayMs:  200,          // base delay between attempts (ms)
-    backoff:  'exponential' // 'none' | 'linear' | 'exponential'
+    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')
   },
 })
 ```
 
 `result.attempts` tells you how many tries it took.
 
+#### Jitter (default: `'full'`)
+
+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]`.
+
+| Strategy | Formula |
+|---|---|
+| `'none'` | `delay` |
+| `'full'` | `random() * delay` |
+| `'equal'` | `delay/2 + random() * delay/2` |
+| `'decorrelated'` | `base + random() * (delay - base)` |
+
 #### Selective retry with `shouldRetry`
 
-By default, every error triggers a retry. Use `shouldRetry` to skip retrying permanent errors — a `404` will never recover, a `503` might.
+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.
 
 ```ts
-const result = await act('api:resource', () => fetchResource(id), {
+const result = await act('api:resource', async (signal) => fetchResource(id, signal), {
   retry: {
     attempts: 4,
     delayMs:  150,
@@ -101,18 +132,20 @@ const result = await act('api:resource', () => fetchResource(id), {
 })
 ```
 
-`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.
+`shouldRetry(error, attempt)` receives the error and the 1-based attempt number. Return `false` to surface the error immediately.
+
+> **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.
 
 ---
 
 ### Timeout
 
-Per-attempt deadline. Each retry gets a fresh clock.
+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).
 
 ```ts
 import { act, TimeoutError } from 'actly'
 
-const result = await act('geo:lookup', () => lookupCoords(ip), {
+const result = await act('geo:lookup', async (signal) => lookupCoords(ip, signal), {
   timeout: { ms: 3_000 },
 })
 
@@ -121,16 +154,20 @@ if (!result.ok && result.error instanceof TimeoutError) {
 }
 ```
 
+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.
 
+**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.
+
 ```ts
 import { act, TimeoutError, TotalTimeoutError } from 'actly'
 
-const result = await act('search:query', () => runQuery(q), {
+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
@@ -154,14 +191,18 @@ if (!result.ok) {
 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.
 
 ```ts
-const result = await act('config:load', () => loadRemoteConfig(), {
+const result = await act('config:load', async (signal) => loadRemoteConfig(signal), {
   dedupe: true,
 })
 ```
 
 `dedupe: { enabled: true }` is also valid — object form for forward compatibility.
 
-> **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.
+#### 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.
 
 ---
 
@@ -170,11 +211,37 @@ const result = await act('config:load', () => loadRemoteConfig(), {
 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', () => fetchFeatureFlags(), {
+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
+
+- **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.
+
+#### Invalidation
+
+```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
+```
+
+For scoped stores (see `withStore` below), use the scoped `invalidate`:
+
+```ts
+const scopedAct = withStore(myStore)
+scopedAct.invalidate('user:42')  // sync store: returns boolean
+                                // async store: returns Promise<boolean>
 ```
 
 ---
@@ -182,15 +249,43 @@ console.log(result.source) // 'fresh' on miss, 'cache' on hit
 ### Combining policies
 
 ```ts
-const result = await act('product:detail', () => fetchProduct(id), {
+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
+})
+```
+
+---
+
+## Cancellation: `options.signal`
+
+`act()` accepts an `AbortSignal` for caller-driven cancellation:
+
+```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'
 ```
 
+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.
+
 ---
 
 ## Options reference
@@ -202,28 +297,49 @@ interface ActOptions {
   totalTimeout?: TimeoutOptions      // entire operation
   dedupe?:       boolean | DedupeOptions
   cache?:        CacheOptions
+  signal?:       AbortSignal         // caller-provided cancellation
 }
 
 interface RetryOptions {
-  attempts:     number
-  delayMs?:     number
+  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 }
-interface DedupeOptions   { enabled: boolean }
-interface CacheOptions    { ttl: number }
+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
 ```
 
+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`.
+
 ---
 
 ## Exported values
 
 ```ts
 import {
-  act,                       // primary function
-  InMemoryStore,             // isolated store for SSR / tests
+  // 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'
@@ -238,12 +354,18 @@ import type {
   ActResult, ActSuccess, ActFailure, ActSource,
   ActOptions, ActFn,
   RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions,
-  // v1.1 — store interfaces
+  // 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'
 ```
 
@@ -251,25 +373,86 @@ import type {
 
 ## Custom store
 
-By default `act` uses a module-level `InMemoryStore`. For SSR request isolation or test control, instantiate your own:
+By default `act` uses a module-level `InMemoryStore`. For SSR request isolation, multi-tenant scenarios, or test control, use `withStore()`:
+
+### `withStore(store)`
+
+Returns a scoped `act` function bound to the provided store, with an `invalidate(key)` method and a `store` reference attached.
 
 ```ts
-import { InMemoryStore } from 'actly'
+import { withStore, InMemoryStore } from 'actly'
 
 // Basic
 const store = new InMemoryStore()
+const act = withStore(store)
 
-// With background cleanup (useful for long-lived server-side stores)
-const store = new InMemoryStore({
+// With LRU + background cleanup (long-lived server store)
+const serverStore = new InMemoryStore({
+  maxSize: 10_000,           // evict least-recently-used when exceeded
   autoCleanup: true,
   cleanupIntervalMs: 60_000, // sweep every 60s (default: 30s)
 })
+const serverAct = withStore(serverStore)
+
+try {
+  await serverAct('user:42', async (signal) => fetchUser(42, signal), {
+    cache: { ttl: 60_000 },
+  })
+
+  // ... user updates their profile ...
+  serverAct.invalidate('user:42')  // next call re-fetches
+
+  // Access the underlying store if needed:
+  console.log(serverAct.store.size())
+} finally {
+  serverStore.destroy()  // stop the cleanup timer
+}
+```
+
+For sync stores, `invalidate` returns `boolean` synchronously.
+For async stores, `invalidate` returns `Promise<boolean>`.
+
+### `execute()` directly
+
+For full control (custom policy chains, custom meta, custom signal composition), call `execute()` directly:
+
+```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
+```
+
+### InMemoryStore options
 
-// Always call destroy() when done to prevent timer leaks
-store.destroy()
+```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,
+})
 ```
 
-`InMemoryStore` satisfies `SyncStateStore`. Use it with `execute()` directly for full control.
+`InMemoryStore` satisfies `SyncStateStore`. Call `destroy()` to stop the background timer and prevent leaks.
 
 ### Async store (v1.1+)
 
@@ -290,7 +473,7 @@ class RedisStore implements AsyncStateStore {
 }
 ```
 
-> `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.
+`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).
 
 ---
 
@@ -318,13 +501,15 @@ interface AsyncStateStore {
 }
 ```
 
-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`.
+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`.
 
 ---
 
 ## Zero-throw contract
 
-`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.
+`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.
+
+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.
 
 ---
 
@@ -332,37 +517,84 @@ The `_sync` discriminant is read at runtime by the executor to enforce the dedup
 
 One function. One return type. No exceptions in userland.
 
-The key is your responsibility. Make it stable and specific. `user:42` is good. `fetch` is not.
+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.)
 
 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.
 
+Cancellation is cooperative: pass the `signal` through. `act()` will return promptly regardless (via internal race), but only you can stop `fn` from leaking resources.
+
 ---
 
 ## Changelog
 
-### v1.1.0 — 2026-06-01
+### 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.)*
 
-**New features**
+**Public API additions (fixes A-1, A-2, m-8)**
 
-- **`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.
+- **`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).
+
+**New options**
+
+- **`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**
 
-- 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.
+- **`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.
+
+---
+
+### v1.1.0 — 2026-06-01
+
+- `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.
 
 ---