svelte-realtime 0.4.23 → 0.5.0-next.2

package/README.md

@@ -185,6 +185,7 @@ The `ctx` object passed to every server function contains:
 | `ctx.platform` | The adapter platform API |
 | `ctx.publish` | Shorthand for `platform.publish()` |
 | `ctx.cursor` | Cursor from a `loadMore()` call, or `null` |
+| `ctx.requestId` | Correlation id from `platform.requestId` (per WS connection or per HTTP request); honors `X-Request-ID` |
 | `ctx.throttle` | `(topic, event, data, ms)` -- publish at most once per `ms` ms |
 | `ctx.debounce` | `(topic, event, data, ms)` -- publish after `ms` ms of silence |
 | `ctx.signal` | `(userId, event, data)` -- point-to-point message |
@@ -199,9 +200,12 @@ Note: `ctx.user` may contain adapter-injected properties (`__subscriptions`, `re
 **Core**
 - [Getting started](#getting-started)
 - [Merge strategies](#merge-strategies)
+- [Connection state stores](#connection-state-stores)
+- [Svelte 5 store helpers](#svelte-5-store-helpers)
 - [Error handling](#error-handling)
 - [Per-module auth](#per-module-auth)
 - [Dynamic topics](#dynamic-topics)
+- [Topic registry](#topic-registry)
 - [Schema validation](#schema-validation)
 - [Channels](#channels)
 - [SSR hydration](#ssr-hydration)
@@ -212,8 +216,10 @@ Note: `ctx.user` may contain adapter-injected properties (`__subscriptions`, `re
 - [Stream pagination](#stream-pagination)
 - [Undo and redo](#undo-and-redo)
 - [Request deduplication](#request-deduplication)
+- [Idempotency keys](#idempotency-keys)
 - [Offline queue](#offline-queue)
 - [Connection hooks](#connection-hooks)
+- [SvelteKit transport](#sveltekit-transport)
 - [Combine stores](#combine-stores)
 
 **Server features**
@@ -222,6 +228,10 @@ Note: `ctx.user` may contain adapter-injected properties (`__subscriptions`, `re
 - [Stream lifecycle hooks](#stream-lifecycle-hooks)
 - [Access control](#access-control)
 - [Rate limiting](#rate-limiting)
+- [Load shedding](#load-shedding)
+- [Concurrency control](#concurrency-control)
+- [Server-initiated push](#server-initiated-push)
+- [Request correlation](#request-correlation)
 - [Cron scheduling](#cron-scheduling)
 - [Derived streams](#derived-streams)
 - [Effects](#effects)
@@ -361,8 +371,16 @@ Events: `update` (add/update by key), `remove` (remove by key), `set` (replace a
 | `prepend` | `false` | Prepend new items instead of appending (`crud` mode) |
 | `max` | `50` / `0` | Max items to keep. Defaults to 50 for `latest`, 0 (unlimited) for `crud`. Oldest items are dropped when exceeded |
 | `replay` | `false` | Enable seq-based replay for gap-free reconnection |
+| `args` | -- | Standard Schema (Zod / ArkType / Valibot) for stream arguments. Validated before topic resolution -- prevents topic injection via malformed dynamic-topic args |
+| `transform` | -- | `(data) => projection` applied to BOTH initial-load data (per-item for arrays) AND every live publish for this topic. Ship a wide row from the database, emit a narrow shape on the wire |
+| `coalesceBy` | -- | `(data) => key` extractor. Publishes fan out via per-socket `sendCoalesced`; the latest value for each `(topic, key)` pair wins. For high-frequency latest-value streams (prices, cursors, presence). Cannot combine with `volatile` |
+| `volatile` | `false` | Mark messages fire-and-forget. Disables seq stamping for this topic so reconnects with `lastSeenSeq` won't try to backfill. Wire-level drop-on-backpressure is the adapter's default. For typing indicators, telemetry pings, cursors |
+| `staleAfterMs` | -- | Per-topic staleness watchdog. If no events arrive for N ms, the loader re-runs and the result broadcasts as a `refreshed` event. Useful for streams whose source can quietly stop emitting. See [Stream lifecycle hooks](#stream-lifecycle-hooks) |
+| `invalidateOn` | -- | String or array of glob-style topic patterns (e.g. `'todos:*'`). When `ctx.publish` hits a matching topic, the stream's loader reruns and the result broadcasts as a `refreshed` event. See [Stream lifecycle hooks](#stream-lifecycle-hooks) |
+| `onError` | -- | `(err, ctx, topic)` per-stream observer. Fires on loader throws (subscribe / stale-reload / `.load()` SSR). Errors thrown inside are silently swallowed |
+| `classOfService` | -- | Names a class registered via `live.admission()`. New subscribes are shed under matching pressure. See [Load shedding](#load-shedding) |
 | `onSubscribe` | -- | Callback `(ctx, topic)` fired when a client subscribes |
-| `onUnsubscribe` | -- | Callback `(ctx, topic)` fired when a client disconnects |
+| `onUnsubscribe` | -- | Callback `(ctx, topic, remainingSubscribers)` fired when a client disconnects. `remainingSubscribers` counts OTHER WebSockets still on the topic -- use it to tear down upstream feeds at zero |
 | `filter` / `access` | -- | Per-connection publish filter (see [Access control](#access-control)) |
 | `delta` | -- | Delta sync config (see [Delta sync and replay](#delta-sync-and-replay)) |
 | `version` | -- | Schema version (see [Schema evolution](#schema-evolution)) |
@@ -372,6 +390,113 @@ Events: `update` (add/update by key), `remove` (remove by key), `set` (replace a
 
 When the WebSocket reconnects, streams automatically refetch initial data and resubscribe. The store keeps showing stale data during the refetch -- it does not reset to `undefined`.
 
+**Mid-flight RPCs reject with `DISCONNECTED`.** If the WS drops while an RPC or `mutate` is awaiting a response, the corresponding promise rejects with `RpcError('DISCONNECTED')`. Callers that wrap the call in `mutate(asyncOp, change)` get auto-rollback for free: the optimistic-queue entry settles as failed, removing the placeholder from the displayed state. Concurrent in-flight mutates each roll back independently -- if A and B are both pending when the WS drops, both promises reject and both placeholders are removed in one display recompute.
+
+**Catch-up via initial fetch on resubscribe.** Once the WS reconnects, every active stream re-runs its loader and broadcasts the result through the same merge strategy used on first subscribe. Pub/sub events that fired during the disconnect window arrive as part of the fresh fetch (they're materialized in the loader's data source). For tighter "no-frame-loss" guarantees use the `delta` configuration (see [Delta sync and replay](#delta-sync-and-replay)), which fills small gaps via the per-topic seq-numbered replay buffer and falls back to delta sync for larger gaps.
+
+**Triggering reconnect.** The next RPC call after the WS drops triggers the adapter's reconnect logic. Most apps don't need to do anything special -- the user clicks something, the RPC fires, the adapter reconnects, the call lands. If you want to display a reconnecting banner, watch the `status` store from `svelte-adapter-uws/client` for the `'reconnecting'` -> `'open'` transition.
+
+---
+
+## Connection state stores
+
+Four reactive stores re-export from `svelte-realtime/client` for rendering connection state without app-side WebSocket plumbing.
+
+```svelte
+<script>
+  import { status, failure, quiescent, health } from 'svelte-realtime/client';
+</script>
+
+{#if $health === 'degraded'}
+  <Banner severity="warn">Real-time updates paused, reconnecting...</Banner>
+{:else if $failure?.class === 'TERMINAL'}
+  <Banner severity="error">Session expired. <a href="/login">Sign in again</a></Banner>
+{:else if $failure?.class === 'THROTTLE'}
+  <Banner severity="warn">Server is busy. Reconnecting more slowly...</Banner>
+{:else if $status === 'disconnected'}
+  <Banner severity="info">Reconnecting...</Banner>
+{/if}
+
+{#if !$quiescent}
+  <Spinner />
+{/if}
+```
+
+| Store | Type | Behavior |
+|---|---|---|
+| `status` | `'connecting' \| 'open' \| 'suspended' \| 'disconnected' \| 'failed'` | Connection state machine. `suspended` = tab in background; `failed` = terminal (auth denied or `close()` called) |
+| `failure` | `{ kind, class, code, reason } \| null` | Cause of the most recent non-open transition. `class` is `TERMINAL` (auth) / `EXHAUSTED` (max retries) / `THROTTLE` (4429) / `RETRY` / `AUTH` (HTTP preflight). Cleared on next `'open'`. Not set on intentional `close()` |
+| `quiescent` | `Readable<boolean>` | `true` when every active stream has settled (initial load + all reconnects). Continuous signal -- a `false -> true` transition after a reconnect cycle marks "everything caught up" |
+| `health` | `'healthy' \| 'degraded'` | System-wide health, sourced from `degraded` / `recovered` events on the `__realtime` topic. Stays `'healthy'` until something publishes -- typically the extensions package's pub/sub bus circuit breaker |
+
+`failure` and `quiescent` are pure additions; apps that don't use them pay nothing. `health` lazily subscribes to `__realtime` only on first read; never reading it = no subscription.
+
+Apps that need richer health detail (reason strings, timestamps) can listen to the topic directly:
+
+```js
+import { on } from 'svelte-adapter-uws/client';
+on('__realtime').subscribe((envelope) => { /* full payload */ });
+```
+
+---
+
+## Svelte 5 store helpers
+
+Generated `$live/*` stream stores work out of the box as Svelte 4 `Readable<T>` values via the `$store` auto-subscribe syntax. For Svelte 5 apps, two methods are exposed alongside the existing `subscribe` interface so component code stays terse without reaching for `$derived.by(() => $store ?? [])` boilerplate.
+
+### `store.rune()` -- Svelte 5 reactive object
+
+Returns an object with a single `current` getter, backed by Svelte's `fromStore` from `svelte/store`. Reading `current` inside an effect or component subscribes via Svelte's `createSubscriber` for fine-grained reactivity; reading it outside an effect synchronously returns the latest value.
+
+```svelte
+<script>
+  import { todos } from '$live/todos';
+  const items = todos.rune();
+</script>
+
+<p>{items.current?.length ?? 0} items</p>
+{#each items.current ?? [] as todo}
+  <li>{todo.title}</li>
+{/each}
+```
+
+`rune()` requires Svelte 5 (the `fromStore` export is not available in Svelte 4) and throws a descriptive error if called against an older runtime. Apps still on Svelte 4 use the `$store` auto-subscribe syntax instead.
+
+### `store.map(fn)` -- per-item projection
+
+Returns a mapped store with the same `{ subscribe, rune, map }` shape as the source. Idiomatic alternative to `$derived.by(() => ($stream ?? []).map(...))` and avoids the `$derived(() => ...)` footgun where storing a function reference instead of its return value silently breaks rendering.
+
+```svelte
+<script>
+  import { todos } from '$live/todos';
+  const titles = todos.map(t => t.title);
+  // Or compose with rune() for Svelte 5:
+  const titlesRune = todos.map(t => t.title).rune();
+</script>
+
+{#each $titles as title}<li>{title}</li>{/each}
+```
+
+Semantics match the documented `($stream ?? []).map(fn)` pattern: a `null` or `undefined` source emits `[]`; an array source emits `source.map(fn)`; a non-array source (set-merge stream, paginated wrapper) emits `[]` after a dev-mode `console.warn` pointing at the merge-strategy docs. Subscriptions are lazy: the source is only subscribed while at least one mapped consumer is active. Chains via further `.map()` calls preserve the same shape.
+
+### `empty` -- bundled placeholder store
+
+Every generated `$live/<name>.js` re-exports an `empty` store that holds `undefined`. Use it as the fallback for conditional streams without importing `readable` from `svelte/store`:
+
+```svelte
+<script>
+  import { todos, empty } from '$live/todos';
+  let { user, orgId } = $props();
+  const items = $derived(user ? todos(orgId) : empty);
+</script>
+
+{#each $items ?? [] as todo}
+  <li>{todo.title}</li>
+{/each}
+```
+
+Auto-imported alongside the stream itself; nothing extra to wire.
+
 ---
 
 ## Error handling
@@ -554,6 +679,8 @@ export const _guard = guard(
 
 Use a function instead of a string as the first argument to `live.stream()` for per-entity streams. The client-side stub becomes a factory function -- call it with arguments to get a cached store for that entity.
 
+> **The first argument's shape decides the client export.** If the first argument is a string, the export is a Svelte store and you read it as `$messages`. If the first argument is a function, the export is a factory that returns a store, and you must call it first: `const messages = roomMessages(data.roomId); ... $messages`. Forgetting the call gives `Svelte error: store_invalid_shape -- 'roomMessages' is not a store with a 'subscribe' method` during SSR. If the topic does not depend on arguments, prefer the string form.
+
 ```js
 // src/live/rooms.js
 import { live } from 'svelte-realtime/server';
@@ -590,6 +717,44 @@ Same arguments return the same cached store instance. The cache is cleaned up wh
 
 ---
 
+## Topic registry
+
+Centralize topic strings so the SQL trigger and the stream definition reference one source of truth. `defineTopics(map)` validates the map at boot and exposes `__patterns` for tooling.
+
+```js
+// src/lib/topics.js
+import { defineTopics } from 'svelte-realtime/server';
+
+export const TOPICS = defineTopics({
+  audit: (orgId) => `audit:${orgId}`,
+  security: (orgId) => `security:${orgId}`,
+  systemNotices: 'system:notices'
+});
+
+// Stream definitions reference the registry
+live.stream((ctx, orgId) => TOPICS.audit(orgId), loadAudit, { merge: 'crud' });
+
+// Tooling reads __patterns to derive shapes
+TOPICS.__patterns;
+// => { audit: 'audit:{arg0}', security: 'security:{arg0}', systemNotices: 'system:notices' }
+```
+
+Map values can be strings (static topics) or `(...args) => string` functions (dynamic topics). The helper validates non-empty strings and rejects reserved names (`__patterns`, `__definedTopics`). Pattern derivation calls each function with sentinel placeholders (`{arg0}`, `{arg1}`, ...) and falls back to `'<dynamic>'` if the function throws on placeholders or returns a non-string.
+
+### Build-time registry check
+
+When the Vite plugin sees a `defineTopics({...})` call anywhere under `src/`, it builds a registry of patterns and validates string-literal topics passed to `live.stream(...)` and `live.channel(...)` against it. A literal that does not match any registered pattern triggers a one-shot warning per `(file, topic)` pair:
+
+```
+[svelte-realtime] src/live/feed.js: live.stream topic 'mistyped-topic' is not in
+your TOPICS registry. Either add it to defineTopics({...}) or call TOPICS.<name>(...)
+instead of passing a string literal.
+```
+
+The check covers static-string patterns (`feed: 'feed:notices'`) and arrow-return template literals (`audit: (orgId) => \`audit:${orgId}\``); template interpolations match `.+` so `'audit:org-123'` and `'audit:any-id'` both pass against the `audit` pattern. Function references and other dynamic value shapes are silently skipped at parse time -- the warning only fires for literal topics under a confidently parsed registry. If your project does not call `defineTopics` at all, the check is disabled.
+
+---
+
 ## Schema validation
 
 Use `live.validated(schema, fn)` to validate the first argument against a schema before the function runs. Any [Standard Schema](https://standardschema.dev/)-compatible validator is supported, including Zod, ArkType, Valibot, and others.
@@ -627,6 +792,22 @@ export const addTodo = live.validated(CreateTodo, async (ctx, input) => {
 
 On the client, validated exports work like regular `live()` calls. Validation errors are thrown as `RpcError` with `code: 'VALIDATION'` and an `issues` array.
 
+### Validating stream arguments
+
+Stream arguments validate via the `args` option on `live.stream()`. Validation runs BEFORE topic resolution, so a malformed argument can never reach a dynamic topic function.
+
+```js
+import { z } from 'zod';
+
+export const auditFeed = live.stream(
+  (ctx, orgId) => `audit:${orgId}`,
+  async (ctx, orgId) => loadAudit(orgId),
+  { args: z.tuple([z.string().uuid()]) }
+);
+```
+
+Validation failures reject the subscribe RPC with `{ code: 'VALIDATION', issues }`. Both the WebSocket and `.load()` SSR paths apply the schema. Coerced values from the schema (e.g. Zod transforms) flow through to the loader and the topic function.
+
 ---
 
 ## Channels
@@ -659,6 +840,18 @@ export const cursors = live.channel(
 );
 ```
 
+For high-frequency streams where a missed frame is acceptable (typing indicators, telemetry pings, raw cursor positions you don't need replayed on reconnect), set `volatile: true` on the stream:
+
+```js
+export const cursors = live.stream(
+  (ctx, roomId) => `room:${roomId}:cursors`,
+  loader,
+  { merge: 'cursor', volatile: true }
+);
+```
+
+Two effects: per-event seq stamping is skipped for the topic (so reconnect with `lastSeenSeq` won't try to backfill), and the option declares intent at the call site. Wire-level "drop on backpressure" is the adapter's default behavior already -- uWS auto-skips a subscriber whose outbound buffer is over `maxBackpressure` (default 64 KB). Cannot combine with `coalesceBy` (queue vs drop -- different intents) or `replay` (volatile messages aren't buffered for resume).
+
 ---
 
 ## SSR hydration
@@ -796,6 +989,73 @@ Apply changes to a stream store instantly, then roll back if the server call fai
 | `latest` | any event name | Appends data to the ring buffer. |
 | `set` | any event name | Replaces the entire value. |
 
+### Auto-rollback with `store.mutate()`
+
+`store.mutate(asyncOp, optimisticChange)` wraps the apply-await-rollback pattern. Applies the optimistic change synchronously, awaits the RPC, and on rejection rolls back and re-throws.
+
+```js
+// Event-based: server's confirming event reconciles the placeholder by key
+const todo = await todos.mutate(
+  () => addTodo(text),
+  { event: 'created', data: { id: tempId(), text } }
+);
+
+// Free-form mutator: arbitrary local change, no merge-strategy assumptions
+await todos.mutate(
+  () => removeTodo(id),
+  (current) => current.filter((t) => t.id !== id)
+);
+```
+
+Returns the result of `asyncOp` on success. The free-form mutator receives a shallow copy: top-level array shape changes (push, pop, filter, splice) roll back cleanly; in-place item field mutations (`draft[0].name = 'x'`) do NOT, because the draft and the prior items share item references. Replace whole items instead: `draft[i] = { ...draft[i], name: 'x' }`.
+
+**Concurrent mutates roll back independently.** Pending mutations are tracked in an in-flight queue and the displayed value is recomputed by replaying that queue against the un-overlaid server state after every server event and every settle. If `mutate` A and `mutate` B are both in flight and both fail, the displayed state returns to the latest server state with no phantom traces of either A or B. Server events with a key matching a queue entry's optimistic key absorb the entry, so the typical "client generates UUID, server confirms with same id" flow does not flicker.
+
+### RPC-bound shorthand: `rpc.createOptimistic()`
+
+Every generated RPC stub also exposes a `.createOptimistic(store, callArgs, optimisticChange)` method. It threads `callArgs` into the optimistic-change callback so the call site doesn't have to capture them in a closure:
+
+```js
+import { sendMessage, messages } from '$live/chat';
+
+await sendMessage.createOptimistic(
+  messages,
+  ['Hello!'],
+  (current, args) => [...current, { id: tempId(), text: args[0] }]
+);
+```
+
+`callArgs` is always passed as an array (so multi-argument RPCs work the same as single-argument ones; pass `[arg]` for the single-arg case). The third argument accepts the same two shapes as `store.mutate()`: a `(current, args) => newValue` function or a `{ event, data }` object. Equivalent to:
+
+```js
+store.mutate(() => rpc(...callArgs), wrappedChange);
+```
+
+so behavior on success/rollback/server-confirmation is identical to `store.mutate()`. The shorthand is purely syntactic; reach for `store.mutate()` directly when the asyncOp isn't an RPC (third-party API call, multi-step flow, etc.).
+
+**Curried form** -- bind once, call many times. Pass two arguments instead of three (`store, change`) and `createOptimistic` returns a callable bound to that store + change:
+
+```js
+const optimisticSend = sendMessage.createOptimistic(
+  messages,
+  (current, args) => [...current, { id: tempId(), text: args[0] }]
+);
+await optimisticSend('Hello!');
+await optimisticSend('There!');
+```
+
+**Stream-side spelling** -- the same flow can be expressed from the stream's perspective via `store.createOptimistic(rpc, callArgs, change)`:
+
+```js
+await messages.createOptimistic(
+  sendMessage,
+  ['Hello!'],
+  (current, args) => [...current, { id: tempId(), text: args[0] }]
+);
+```
+
+Identical semantics to the RPC-side spelling; pick whichever reads more naturally for your call site (stream-focused code prefers `store.createOptimistic`; RPC-focused code prefers `rpc.createOptimistic`).
+
 ---
 
 ## Stream pagination
@@ -881,6 +1141,52 @@ const result = await getUser.fresh(userId); // always sends a new request
 
 ---
 
+## Idempotency keys
+
+Microtask deduplication only collapses calls within the same tick. For durable safety against retries that span reconnects, tab reloads, or offline replay, wrap the handler with `live.idempotent(config, fn)`. Identical calls (by key) return the cached result without re-running the handler.
+
+```js
+// Server: server-derived key (Stripe-style)
+import { live } from 'svelte-realtime/server';
+
+export const createOrder = live.idempotent(
+  { keyFrom: (ctx, input) => `order:${ctx.user.id}:${input.clientOrderId}`, ttl: 48 * 3600 },
+  live.validated(OrderSchema, async (ctx, input) => {
+    return db.orders.insert({ userId: ctx.user.id, ...input });
+  })
+);
+```
+
+```js
+// Client: envelope-supplied key (uuid per intent)
+import { createOrder } from '$live/orders';
+
+const intentId = crypto.randomUUID();
+const order = await createOrder.with({ idempotencyKey: intentId })(payload);
+```
+
+Resolution: `keyFrom(ctx, ...args)` if defined, otherwise the client envelope's `idempotencyKey`, otherwise the wrapper is a no-op. Only successful results cache; throwing handlers abort the slot so the next caller re-runs. Default store is in-process and bounded; for multi-instance deployments pass `store: createIdempotencyStore(redis)` from `svelte-adapter-uws-extensions`.
+
+| Option | Default | Description |
+|---|---|---|
+| `keyFrom` | -- | `(ctx, ...args) => string \| null \| undefined`. `null`/`undefined` falls back to the envelope key |
+| `store` | in-process | Any object exposing `acquire(key, ttlSec)` matching the extensions store contract |
+| `ttl` | `172800` (48h) | TTL in seconds. `0` skips the cache write (concurrent waiters re-run after the first finishes) |
+
+`__rpc().with({ ... })` composes options on the same surface:
+
+```js
+// Compose idempotency + per-call timeout
+await createOrder.with({ idempotencyKey: id, timeout: 60_000 })(payload);
+```
+
+| `.with({})` option | Description |
+|---|---|
+| `idempotencyKey` | Carried in the envelope for the server's `live.idempotent` wrapper |
+| `timeout` | Per-call timeout in ms; overrides the global `configure({ timeout })` default. Sleep-detect threshold scales with the override |
+
+---
+
 ## Offline queue
 
 Queue RPC calls when the WebSocket is disconnected and replay them on reconnect.
@@ -1035,6 +1341,36 @@ The client coalesces concurrent connects into a single in-flight preflight, trea
 
 ---
 
+## SvelteKit transport
+
+`realtimeTransport()` from `svelte-realtime/hooks` is a SvelteKit transport-hook preset that auto-registers `RpcError` and `LiveError` serialization across the SSR / client boundary. Without it, typed errors thrown from `+page.server.js` `load()` arrive at `+error.svelte` as plain `Error` instances and lose their `code` field.
+
+```js
+// src/hooks.js  (NOT hooks.server.js -- the shared hook is required)
+import { realtimeTransport } from 'svelte-realtime/hooks';
+
+export const transport = realtimeTransport();
+```
+
+Compose with app-defined types via the optional `extras` parameter (user entries appear after defaults so they win on key conflict):
+
+```js
+// src/hooks.js
+import { realtimeTransport } from 'svelte-realtime/hooks';
+import { Vector } from '$lib/geometry';
+
+export const transport = realtimeTransport({
+  Vector: {
+    encode: (v) => v instanceof Vector && [v.x, v.y],
+    decode: ([x, y]) => new Vector(x, y)
+  }
+});
+```
+
+Wire from `src/hooks.js`, NOT `hooks.server.js`. SvelteKit's transport primitive needs both encode (server-side) and decode (client-side hydration) visible at build time -- the wrong file silently half-works (encode runs but decode never reaches the client). `RpcError`'s optional `issues` field (carried by `live.validated()` failures) survives the round-trip. Validation runs at registration: malformed extras throw immediately so misconfiguration fails fast at app boot.
+
+---
+
 ## Combine stores
 
 Compose multiple stream stores into a single derived store. When any source updates, the combining function re-runs.
@@ -1115,8 +1451,9 @@ export const presence = live.stream('room:lobby', async (ctx) => {
   onSubscribe(ctx, topic) {
     ctx.publish(topic, 'join', { key: ctx.user.id, name: ctx.user.name });
   },
-  onUnsubscribe(ctx, topic) {
+  onUnsubscribe(ctx, topic, remainingSubscribers) {
     ctx.publish(topic, 'leave', { key: ctx.user.id });
+    if (remainingSubscribers === 0) stopUpstreamFeed(topic);
   }
 });
 ```
@@ -1129,11 +1466,64 @@ export { message, close, unsubscribe } from 'svelte-realtime/server';
 
 `onUnsubscribe` fires for both static and dynamic topics. For dynamic topics, the server tracks which stream produced each subscription and fires the correct hook. The `unsubscribe` hook fires as soon as the client drops a topic; `close` only fires for topics still active at disconnect time. There is no double-firing.
 
+The third argument `remainingSubscribers` counts OTHER WebSockets still holding a realtime-stream subscription to the topic after the current one drops. Use it to tear down upstream feeds (CDC connections, polling loops, external pub/sub follows) when the count reaches zero. Existing 2-argument `(ctx, topic) => ...` handlers continue to work; the third arg is silently ignored.
+
+### Staleness watchdog and per-stream `onError`
+
+Streams whose underlying source can quietly stop emitting (CDC drops, polling stalls, upstream cache evicts the key) declare `staleAfterMs` to arm a per-topic watchdog. Every `ctx.publish` to the topic resets the timer; if no events arrive for the configured duration, the realtime layer re-runs the loader and broadcasts the result as a `refreshed` event. The client merges `refreshed` as a full-state replacement across every merge strategy.
+
+```js
+export const auditFeed = live.stream(
+  (ctx, orgId) => `audit:${orgId}`,
+  async (ctx, orgId) => loadAudit(orgId),
+  {
+    merge: 'crud',
+    key: 'id',
+    staleAfterMs: 30_000,
+    onError: (err, ctx, topic) => log.warn({ err, topic }, 'audit stream error')
+  }
+);
+```
+
+Watchdog state is per-topic. Multiple subscribers share one timer; the timer arms on the first subscribe and clears when the last subscriber leaves. The reload uses the first subscriber's `ctx` and `args`, which is correct for shared topics since the loader's output is identical regardless of which subscriber's ctx triggers it.
+
+`onError(err, ctx, topic)` is observer-only. It fires on loader throws across three paths -- the initial subscribe, the staleness-driven reload, and the `.load()` SSR path. Errors thrown inside `onError` are silently swallowed so a buggy logger never breaks the original error path. Apps that want a topic-scoped degraded signal can publish a system event from inside the handler:
+
+```js
+onError: (err, ctx, topic) => {
+  ctx.publish(`__system:${topic}`, 'degraded', { reason: err.message });
+}
+```
+
+### Topic-driven invalidation
+
+For mutations whose effects don't fit the merge-strategy model cleanly (bulk operations, server-side recomputation, cascading writes), declare an `invalidateOn` pattern so any matching `ctx.publish` triggers a loader rerun:
+
+```js
+export const todos = live.stream('todos', loadTodos, {
+  merge: 'crud',
+  invalidateOn: 'todos:*'
+});
+
+// Anywhere in your live functions:
+ctx.publish('todos:bulk-imported', 'created', { count: 42 });
+// -> matches 'todos:*', the todos loader reruns, the result is broadcast
+//    as a 'refreshed' event, and every subscriber gets the new state.
+```
+
+`invalidateOn` accepts a single string or an array of strings. `*` is a wildcard that matches any sequence of one or more characters; other regex specials are escaped. Multiple patterns are OR-ed (any match triggers the reload).
+
+The reload reuses the staleness machinery: it captures the first subscriber's `ctx` + args, applies any configured init `transform`, and publishes a `refreshed` event to the stream's own topic. The client merges `refreshed` as a full-state replacement.
+
+`refreshed` events are themselves excluded from the invalidation check, so a stream whose own topic happens to match its `invalidateOn` pattern (e.g., `'todos*'` matching topic `'todos'`) won't loop. Concurrent triggers while a reload is in flight are deduped via a per-watcher `reloading` flag.
+
+Errors thrown by the loader during an `invalidateOn` reload route through the same `onError(err, ctx, topic)` observer as staleness-driven reloads.
+
 ---
 
 ## Access control
 
-Use the `filter` / `access` option on `live.stream()` to control who can subscribe. The predicate receives `ctx` and is checked once at subscription time. If it returns `false`, the subscription is denied with `{ ok: false, code: 'FORBIDDEN', error: 'Access denied' }` and no data is sent. For per-event filtering, use `pipe.filter()`.
+Use the `filter` / `access` option on `live.stream()` to control who can subscribe. The predicate receives `ctx` and is checked once at subscription time. If it returns `false`, the subscription is denied with `{ ok: false, code: 'FORBIDDEN', error: 'Access denied' }` and no data is sent. For per-event projection or filtering on a live stream, use the `transform` option on `live.stream({ transform })`.
 
 ```js
 import { live } from 'svelte-realtime/server';
@@ -1174,9 +1564,80 @@ export const myOrders = live.stream(
 | `live.access.owner(field?)` | Subscription allowed if `ctx.user[field]` is present (default: `'id'`) |
 | `live.access.team()` | Subscription allowed if `ctx.user.teamId` is present |
 | `live.access.role(map)` | Role-based: `{ admin: true, viewer: (ctx) => ... }` |
+| `live.access.org(opts?)` | Subscription allowed if `args[0]` matches `ctx.user.organization_id`. Configurable via `{ from, orgField }` |
+| `live.access.user(opts?)` | Subscription allowed if `args[0]` matches `ctx.user.user_id`. Configurable via `{ from, userField }` |
 | `live.access.any(...predicates)` | OR: any predicate returning true allows the subscription |
 | `live.access.all(...predicates)` | AND: all predicates must return true |
 
+`live.access.org` and `live.access.user` follow the SQL `[table]_id` convention. Override the field for non-default user shapes:
+
+```js
+// Stream that takes an orgId arg and verifies the caller belongs to that org
+export const auditFeed = live.stream(
+  (ctx, orgId) => `audit:${orgId}`,
+  async (ctx, orgId) => loadAudit(orgId),
+  { access: live.access.org() }
+);
+
+// Custom user-shape (e.g. SvelteKit locals.user with camelCase)
+access: live.access.org({ orgField: 'organizationId' })
+```
+
+### Authentication shorthand on guards
+
+`guard()` accepts an options object alongside the existing variadic-function shape. `{ authenticated: true }` rejects calls with no `ctx.user` as `UNAUTHENTICATED`:
+
+```js
+// src/live/_guard.js
+import { guard } from 'svelte-realtime/server';
+
+// Bare authenticated check
+export const _guard = guard({ authenticated: true });
+
+// Compose with custom predicates
+export const _guard = guard({ authenticated: true }, (ctx) => ctx.user.role === 'admin');
+```
+
+Bare `Error` throws from any guard auto-classify: thrown errors against an anonymous user produce `LiveError('UNAUTHENTICATED')`; thrown errors with a user produce `LiveError('FORBIDDEN')`. Original errors travel on `.cause` for server-side logging. Throw `LiveError(code, message)` explicitly to control the wire-visible code and message verbatim.
+
+### `live.scoped(predicate, fn)`
+
+Wrap an RPC handler with a per-call access predicate that throws `UNAUTHENTICATED` (no user) or `FORBIDDEN` (predicate rejects). Composes with `live.validated`, `live.rateLimit`, etc.
+
+```js
+export const editOrgSettings = live.scoped(
+  live.access.org(),
+  live.validated(SettingsSchema, async (ctx, orgId, patch) => {
+    return db.orgs.update(orgId, patch);
+  })
+);
+```
+
+For streams, use the `access` option directly. `live.scoped` is the RPC equivalent.
+
+### Subscribe-denial codes on stream stores
+
+When a server-side subscribe denial fires (guard rejection, access predicate, rate limit, invalid topic), the typed reason flows through the stream store's `error` slot as an `RpcError` with the canonical code:
+
+```svelte
+<script>
+  import { auditFeed } from '$live/audit';
+  const err = auditFeed.error;
+</script>
+
+{#if $err?.code === 'UNAUTHENTICATED'}
+  <p>Please sign in to view audit history.</p>
+{:else if $err?.code === 'FORBIDDEN'}
+  <p>You don't have access to this organization's audit log.</p>
+{:else if $err?.code === 'RATE_LIMITED'}
+  <p>Too many requests. Please wait a moment.</p>
+{:else if $err}
+  <p>Audit feed unavailable: {$err.message}</p>
+{/if}
+```
+
+Custom denial reasons returned from a server-side `subscribe` hook (e.g. `'KYC_PENDING'`) flow through verbatim as the `code` field. The same denial fans out to every stream subscribed to the topic.
+
 ---
 
 ## Rate limiting
@@ -1193,6 +1654,26 @@ export const sendMessage = live.rateLimit({ points: 5, window: 10000 }, async (c
 });
 ```
 
+### Registry-level rate limiting
+
+For the common case of "a default for everyone, with a few path overrides and a few exemptions" you can configure the registry once at startup with `live.rateLimits()`:
+
+```js
+// hooks.ws.js or any startup module
+import { live } from 'svelte-realtime/server';
+
+live.rateLimits({
+  default: { points: 200, window: 10_000 },
+  overrides: {
+    'chat/sendMessage': { points: 50, window: 10_000 },
+    'orders/create':    { points: 5,  window: 60_000 }
+  },
+  exempt: ['presence/moveCursor', 'cursor/move']
+});
+```
+
+Resolution order per call: `exempt` -> per-handler `live.rateLimit(...)` wrapping (explicit wins over central) -> `overrides[path]` -> `default` -> none. Stream subscribes are not rate-limited by this primitive. Pass `null` to clear the registry.
+
 ### Global rate limiting with Redis
 
 Use the `beforeExecute` hook with the rate limit extension for global per-connection throttling:
@@ -1215,54 +1696,236 @@ export const message = createMessage({
 
 ---
 
-## Prometheus metrics
+## Load shedding
 
-Opt-in instrumentation for RPC calls, stream subscriptions, and cron executions. Zero overhead if not called.
-
-`live.metrics(registry)` is a one-time setup call. The top of `src/hooks.ws.{js,ts}` is a natural place, since it loads once when the server boots. Pair it with the `createMetrics()` registry from `svelte-adapter-uws-extensions/prometheus`:
+Under sustained pressure, drop low-priority traffic before it reaches the handler. `live.admission(config)` registers named pressure rules; `ctx.shed(className)` checks them; the `classOfService` stream option gates new subscribes automatically.
 
 ```js
-// src/hooks.ws.js
 import { live } from 'svelte-realtime/server';
-import { createMetrics } from 'svelte-adapter-uws-extensions/prometheus';
 
-const metrics = createMetrics();
+// Register classes once at startup
+live.admission({
+  classes: {
+    background: ['PUBLISH_RATE', 'SUBSCRIBERS', 'MEMORY'],   // shed under any pressure
+    nonCritical: ['MEMORY'],                                  // shed only on memory pressure
+    realtime: (snapshot) => snapshot.publishRate > 8000      // custom predicate
+  }
+});
 
-live.metrics({
-  counter:   ({ name, help, labelNames }) => metrics.counter(name, help, labelNames),
-  histogram: ({ name, help, labelNames }) => metrics.histogram(name, help, labelNames),
-  gauge:     ({ name, help, labelNames }) => metrics.gauge(name, help, labelNames)
+// Stream gating: new subscribes shed under matching pressure
+export const browseList = live.stream('browse:list', loader, {
+  merge: 'crud',
+  classOfService: 'background'
 });
 
-export { message, close, unsubscribe } from 'svelte-realtime/server';
+// RPC gating: per-call decision
+export const expensiveSearch = live(async (ctx, query) => {
+  if (ctx.shed('background')) {
+    throw new LiveError('OVERLOADED', 'Server is busy, try again shortly');
+  }
+  return search(query);
+});
+```
+
+`platform.pressure.reason` is a precedence-ordered enum (`MEMORY > PUBLISH_RATE > SUBSCRIBERS > NONE`); class rules using a string-array match if the active reason is in the array. Predicate rules receive the full pressure snapshot. Existing subscribers are unaffected -- shedding applies to NEW subscribes and RPC calls only.
+
+`live.admission()` validates rules at registration; unknown reasons throw with a `[svelte-realtime]`-prefixed error so typos fail fast at boot. Pass `null` to clear.
+
+---
+
+## Concurrency control
+
+`live.lock(keyOrConfig, fn)` serializes concurrent RPC calls that resolve to the same key. Composes with `live.validated`, `live.idempotent`, `live.rateLimit`, etc.
+
+```js
+// Per-org leaderboard recompute: one in-flight per org, others wait for the result
+export const recomputeLeaderboard = live.lock(
+  (ctx) => `leaderboard:${ctx.user.organization_id}`,
+  async (ctx) => {
+    const rows = await db.expensive.recompute(ctx.user.organization_id);
+    ctx.publish(`org:${ctx.user.organization_id}:leaderboard`, 'set', rows);
+    return rows;
+  }
+);
+
+// Static key (single global section)
+export const rebuildSearchIndex = live.lock('search-index-rebuild', async (ctx) => {
+  return rebuildIndex();
+});
+
+// Distributed lock via the extensions package
+import { createDistributedLock } from 'svelte-adapter-uws-extensions/redis/lock';
+const distributedLock = createDistributedLock(redis);
+
+export const settleInvoice = live.lock(
+  { key: (ctx, id) => `invoice:${id}`, lock: distributedLock },
+  live.validated(InvoiceIdSchema, async (ctx, id) => settle(id))
+);
 ```
 
-Mount the metrics endpoint on your uWS app (typically in `svelte.config.js` or wherever you build the app):
+Concurrent callers wait in FIFO order for the holder's result. A `null` / `undefined` / empty key bypasses the lock (the handler runs unguarded for that call). Custom lock implementations need a single method: `withLock(key, fn, opts?) -> Promise<result>`.
+
+Default lock is in-process and bounded. For multi-instance deployments, pass `lock: createDistributedLock(redis)` from the extensions package -- any object exposing the `withLock(key, fn, opts?)` contract works.
+
+### Bounded wait with `maxWaitMs`
+
+Pass `maxWaitMs` (in the config-object form) to bound how long a queued caller will wait before giving up. On timeout the wrapper rejects with `LiveError('LOCK_TIMEOUT', ...)` so the client receives a typed error with `.code === 'LOCK_TIMEOUT'` (plus `.key` and `.maxWaitMs` fields for observability).
 
 ```js
-app.get('/metrics', metrics.handler);
+export const settleInvoice = live.lock(
+  { key: (ctx, id) => `invoice:${id}`, maxWaitMs: 5000 },
+  async (ctx, id) => settle(id)
+);
 ```
 
-The six-line shim adapts realtime's options-object call shape to the extensions registry's positional create methods. Once a metric is registered, every increment, observation, and gauge update flows directly to the extensions registry, so the emitted Prometheus output is exactly what `metrics.serialize()` produces.
+The current holder is **not** interrupted when a waiter times out -- only the waiting caller gives up. Subsequent waiters on the same key are unaffected and continue in their original order. This is the right primitive for "fail fast under contention" rather than "cancel work in flight."
+
+For custom lock implementations, the option is forwarded as the third argument: `lockInst.withLock(key, fn, { maxWaitMs })`. The default in-process lock and `createDistributedLock` from the extensions package both honor it.
+
+---
+
+## Server-initiated push
+
+`live.push({ userId }, event, data, options?)` sends a server-initiated request to a connected user and awaits the reply. Routes through a per-instance userId -> WebSocket registry maintained by a small pair of hooks.
+
+```js
+// hooks.ws.js -- wire the registry once
+import { pushHooks } from 'svelte-realtime/server';
 
-### Registered metrics
+export const open = pushHooks.open;
+export const close = pushHooks.close;
+```
+
+```js
+// Anywhere on the server (admin RPC, cron, webhook receiver, etc.)
+import { live } from 'svelte-realtime/server';
+
+const reply = await live.push(
+  { userId: 'u-123' },
+  'confirm-delete',
+  { itemId: 42 },
+  { timeoutMs: 30_000 }
+);
+if (reply.confirmed) await actuallyDelete(42);
+```
+
+```svelte
+<!-- Client: register handlers per event -->
+<script>
+  import { onPush } from 'svelte-realtime/client';
+
+  onPush('confirm-delete', async ({ itemId }) => {
+    return { confirmed: confirm(`Delete item ${itemId}?`) };
+  });
+</script>
+```
 
+The default identifier reads `ws.getUserData()?.user_id ?? ws.getUserData()?.userId`. Override for custom userData shapes:
+
+```js
+import { live } from 'svelte-realtime/server';
+live.configurePush({ identify: (ws) => ws.getUserData()?.account?.id });
+```
+
+Throws `LiveError('NOT_FOUND')` when no connection is registered for the userId. Propagates `Error('request timed out')` from the underlying primitive on the configurable `timeoutMs` (default 5000ms), and `Error('connection closed')` if the WebSocket closes before reply.
+
+Multi-device users see most-recent-connection-wins routing within each instance, and cluster-wide most-recent-wins via the registry's Redis hash when cluster routing is configured (see [Cluster routing](#cluster-routing) below). Older connections still receive topic publishes via their own subscriptions; only push routing flips. Anonymous connections (identify returning null/undefined) are silently skipped at registration so they cannot be push targets.
+
+`onPush(event, handler)` multiplexes multiple events over the adapter's single `onRequest` channel. Returning a value sends it as the reply; throwing rejects the server-side promise. Returns an unsubscribe function.
+
+### Cluster routing
+
+For multi-instance deploys, wire the connection registry from `svelte-adapter-uws-extensions` so a `live.push` originating on any instance reaches the user's owning instance:
+
+```js
+// hooks.ws.js
+import { pushHooks, live } from 'svelte-realtime/server';
+import { createRedisClient } from 'svelte-adapter-uws-extensions/redis';
+import { createConnectionRegistry } from 'svelte-adapter-uws-extensions/redis/registry';
+
+const redis = createRedisClient({ url: process.env.REDIS_URL });
+const registry = createConnectionRegistry(redis, {
+  identify: (ws) => ws.getUserData()?.userId
+});
+
+// Tell live.push to fall back to the registry for cross-instance lookups
+live.configurePush({ remoteRegistry: registry });
+
+// Wire the registry's own connection hooks (NOT pushHooks.* in this mode --
+// the registry tracks ownership in Redis and short-circuits same-instance
+// requests internally).
+export const open = registry.hooks.open;
+export const close = registry.hooks.close;
+```
+
+Lookup order inside `live.push`:
+
+1. **Local registry** -- the per-instance Map populated by `pushHooks.open` / `pushHooks.close`. Resolves directly via `platform.request(ws, ...)` with no I/O.
+2. **Remote registry** -- when configured via `live.configurePush({ remoteRegistry })`, used as a fallback when the userId is not registered locally. The extensions registry looks up the owning instance in Redis and either short-circuits to a local `platform.request` or forwards the envelope on a per-instance push channel and awaits the reply.
+
+Errors with a remote registry come from the registry layer: typically an offline rejection when the user has no active connection cluster-wide, a timeout when routing succeeded but the client did not reply within `timeoutMs`, or a propagated handler error from the receiving instance. The realtime layer does NOT translate these to `LiveError('NOT_FOUND')`; let your caller distinguish and surface them.
+
+You can wire BOTH (`pushHooks.*` + `remoteRegistry`); the local Map wins when an entry is present and the remote registry is consulted only as fallback. In practice pick one of the two patterns -- the registry-only setup is simpler and the registry already does same-instance short-circuit on its own.
+
+Single-instance setups without a registry continue to throw `LiveError('NOT_FOUND')` for unknown userIds, unchanged.
+
+---
+
+## Prometheus metrics
+
+Opt-in instrumentation for RPC calls, stream subscriptions, and cron executions. Zero overhead if not called.
+
+```js
+import { live } from 'svelte-realtime/server';
+import { createMetricsRegistry } from 'svelte-adapter-uws-extensions/prometheus';
+
+const registry = createMetricsRegistry();
+live.metrics(registry);
+```
+
+This registers counters/histograms for:
 - `svelte_realtime_rpc_total` -- RPC call count by path and status
 - `svelte_realtime_rpc_duration_seconds` -- RPC latency by path
 - `svelte_realtime_rpc_errors_total` -- RPC errors by path and code
-- `svelte_realtime_stream_subscriptions` -- active stream subscription gauge
+- `svelte_realtime_stream_subscriptions` -- active stream subscription gauge by topic
 - `svelte_realtime_cron_total` -- cron execution count by path and status
 - `svelte_realtime_cron_errors_total` -- cron errors by path
+- `svelte_realtime_assertion_violations_total` -- production-assertion violations by category (see "Production assertions" below)
+
+---
+
+## Production assertions
 
-### Registry shape
+`svelte-realtime` instruments each internal invariant with `assert(cond, category, context)`. Behavior:
 
-`live.metrics()` accepts any object exposing:
+- **In production**, a violation increments an in-memory per-category counter, fires the Prometheus counter `svelte_realtime_assertion_violations_total{category}` (when `live.metrics(...)` is wired), and logs a single `[realtime/assert] {...}` line at `console.error`. The assert does NOT throw -- a thrown exception inside a publish hot-path microtask or a subscribe callback could leave a half-applied bookkeeping update or a corrupted index. Counter + log give observability without the corruption risk.
+- **In test mode** (`process.env.VITEST` or `NODE_ENV === 'test'`) the assert THROWS so vitest surfaces the failure as a normal test error.
 
-- `counter({ name, help, labelNames }) -> { inc(labels?) }`
-- `histogram({ name, help, labelNames }) -> { observe(labels, valueSeconds) }`
-- `gauge({ name, help }) -> { inc(), dec() }`
+Categories are stable strings prefixed `realtime/<module>.<invariant>` (so the Prometheus label cardinality is bounded and won't collide with the adapter's `extensions_assertion_violations_total`). Today's categories:
+
+| Category                                              | Where                                       |
+| ----------------------------------------------------- | ------------------------------------------- |
+| `realtime/handleRpc.envelope.non-empty`               | RPC frame has non-empty `rpc` and `id`      |
+| `realtime/subscription.bookkeeping.ws-was-tracked`    | Unsubscribe path: ws was in the topic set   |
+| `realtime/push-registry.entry-tracked`                | Close hook: registry entry exists for userId |
+| `realtime/lock.waiter.shape`                          | Dequeued lock waiter has resolve+reject     |
+| `realtime/optimistic.queue.serverValue-iff-nonempty`  | Server-merge path: `_serverValue` set when queue non-empty |
+| `realtime/optimistic.queue.drain-precondition`        | `_drainQueue` called only with empty queue  |
+| `realtime/optimistic.queue.entry.shape`               | Settle path: queue entry has expected fields |
+
+Read the live counter map programmatically:
+
+```js
+import { getAssertionCounters } from 'svelte-realtime/server';
+
+setInterval(() => {
+  for (const [category, count] of getAssertionCounters()) {
+    if (count > 0) console.warn(`assertion ${category}: ${count} violations`);
+  }
+}, 60_000);
+```
 
-If you prefer `prom-client`, wire it the same way: `counter: ({ name, help, labelNames }) => new client.Counter({ name, help, labelNames, registers: [register] })`, and likewise for `Histogram` and `Gauge`.
+The client-side assert helper is exported from `svelte-realtime/client` with the same shape (sans Prometheus wiring -- the browser has no metrics registry; use the in-memory counter or log shipping instead).
 
 ---
 
@@ -1287,6 +1950,57 @@ If `fallback` is omitted and the circuit is open, the call throws `LiveError('SE
 
 ---
 
+## Request correlation
+
+Every live function receives `ctx.requestId` -- a stable identifier for the originating RPC envelope. The id flows in three directions automatically:
+
+- **From clients**: WebSocket clients tag every RPC envelope with a generated id; HTTP request handlers honor `X-Request-ID` headers (and generate one if absent). The adapter writes the resolved id to `platform.requestId`, and the realtime layer copies it to `ctx.requestId` for the duration of that handler.
+- **Through your handlers**: pass it to whatever you do downstream so log lines, traces, and persisted rows all share one key.
+- **Into background work**: the `svelte-adapter-uws-extensions` postgres tasks/jobs APIs persist `request_id` on every row. Pass it explicitly or pipe `ctx.platform` and the helpers extract it for you.
+
+```js
+import { live } from 'svelte-realtime/server';
+import { createTasks } from 'svelte-adapter-uws-extensions/postgres/tasks';
+import { createJobs } from 'svelte-adapter-uws-extensions/postgres/jobs';
+
+const tasks = createTasks({ client: pgClient });
+const jobs = createJobs({ client: pgClient });
+
+export const submitOrder = live(async (ctx, input) => {
+  // Option A: explicit -- works anywhere ctx.requestId is in scope
+  const order = await tasks.run('processOrder', input, {
+    requestId: ctx.requestId
+  });
+
+  // Option B: pipe ctx.platform; the helpers read platform.requestId for you
+  await jobs.enqueue('shipment-notice', { orderId: order.id }, {
+    platform: ctx.platform
+  });
+
+  return order;
+});
+```
+
+Once the rows land, you can join them back to the originating RPC for debugging or audit:
+
+```sql
+-- Trace one user request across the websocket -> task -> job pipeline
+SELECT
+  t.svti_tasks_id, t.name AS task_name, t.status, t.created_at AS task_created,
+  j.svti_jobs_id,  j.queue,             j.attempts,
+  t.request_id
+FROM ws_tasks t
+LEFT JOIN ws_jobs j ON j.request_id = t.request_id
+WHERE t.request_id = $1
+ORDER BY task_created;
+```
+
+The id passes opaquely -- no validation, no length cap from the realtime layer. If you generate ids with a structured prefix (`o-` for orders, `a-` for audits), every downstream record carries that prefix too.
+
+If you also instrument with [Prometheus metrics](#prometheus-metrics), include `requestId` in your log fields rather than as a metric label -- it's high-cardinality and would blow up your label space.
+
+---
+
 ## Cron scheduling
 
 Use `live.cron()` to run server-side functions on a schedule and publish results to a topic.
@@ -1728,6 +2442,32 @@ How it works:
 - If versions differ: server calls `diff(sinceVersion)` and sends only the changes
 - If diff returns `null`: falls back to full refetch
 
+### Three-tier reconnect with `delta.fromSeq`
+
+For seq-based reconnects where the bounded replay buffer cannot satisfy the gap (the client's `lastSeenSeq` is older than the oldest entry in the buffer), `delta.fromSeq(sinceSeq)` is the user-supplied bridge to the durable store. The server falls back to full rehydrate only when `fromSeq` returns `null` / `undefined`.
+
+```js
+export const auditFeed = live.stream(
+  (ctx, orgId) => `audit:${orgId}`,
+  async (ctx, orgId) => loadAudit(orgId, { limit: 200 }),
+  {
+    merge: 'crud',
+    key: 'id',
+    replay: true,
+    delta: {
+      fromSeq: async (sinceSeq) => {
+        const events = await db.auditEvents.where('seq', '>', sinceSeq).orderBy('seq').limit(500);
+        if (events.length === 0) return [];        // nothing missed, no-op
+        if (events.length === 500) return null;     // too many -> fall through to full rehydrate
+        return events;
+      }
+    }
+  }
+);
+```
+
+Resolution order on reconnect-with-seq: replay buffer (bounded, fast) -> `delta.fromSeq(clientSeq)` (this hook) -> full rehydrate via the loader (always safe). Returning `[]` signals "nothing missed" (client no-op). Each event should carry a `seq` field so the client's `_lastSeq` advances; if the events come from a Postgres column with a `seq` per row, the client tracks correctly without extra plumbing.
+
 ### Replay
 
 Enable seq-based replay for gap-free stream reconnection. When a client reconnects, it sends its last known sequence number. If the server has the missed events buffered, it sends only those instead of a full refetch.
@@ -1883,6 +2623,70 @@ Workers are health-checked every 10 seconds. If a worker fails to respond within
 
 ---
 
+## Capacity model
+
+Every internal Map / Set / array with caller-driven growth is bounded by default. Numbers are deliberately generous -- far above any healthy single-instance workload -- so they catch obvious bugs (subscribe-leak, register-without-deregister) without biting real apps.
+
+Each cap is one of three saturation behaviors:
+
+- **REJECT** -- caller gets an explicit error or a documented silent skip.
+- **WARN-ONLY** -- logs once per category; structure keeps growing because eviction would corrupt routing.
+- **FIFO-evict** -- drops oldest insertion-order entries; safe for dedup state where re-warn or duplicate is acceptable.
+
+| Cap                                  | Default     | Behavior     | Notes                                                               |
+| ------------------------------------ | ----------- | ------------ | ------------------------------------------------------------------- |
+| `MAX_PUSH_REGISTRY`                  | 10,000,000  | WARN+skip    | Per-userId connection registry for `live.push({ userId })`.         |
+| `TOPIC_WS_COUNTS_WARN_THRESHOLD`     | 1,000,000   | WARN-only    | Per-topic subscriber index. Eviction would corrupt routing.         |
+| `SILENT_TOPIC_WARN_DEDUP_MAX`        | 1,000,000   | FIFO-evict   | Dev-mode silent-topic warning dedup set.                            |
+| `PUBLISH_RATE_WARN_DEDUP_MAX`        | 1,000,000   | FIFO-evict   | Dev-mode publish-rate warning dedup set.                            |
+| `MAX_OPTIMISTIC_QUEUE_DEPTH`         | 1,000       | REJECT       | Per-stream in-flight `mutate()` queue depth.                        |
+| Rate-limit identities                | 5,000       | REJECT       | Per-function `live.rateLimit()` buckets after stale-sweep.          |
+| Throttle/debounce timers             | 5,000       | direct       | At cap, publishes immediately instead of dropping.                  |
+| Idempotency results                  | 10,000      | FIFO-evict   | In-process `live.idempotent()` store; evicts oldest 10%.            |
+| Presence refs                        | 10,000      | evict+drop   | Suspended entries evicted first; full -> join dropped silently.     |
+| Per-stream history                   | 50          | FIFO         | `store.history` undo/redo ring; configurable via `enableHistory`.   |
+| Per-stream devtools events           | 20          | FIFO         | Recent-events ring shown in `__devtools`.                           |
+
+The first five are exported as named constants from `svelte-realtime/server` and `svelte-realtime/client` so apps writing tools or dashboards can read them programmatically. The remaining caps are internal; their values are documented here for capacity planning.
+
+### MAX_PUSH_REGISTRY (10,000,000)
+
+Per-process Map of userId -> { ws, platform } populated by `pushHooks.open` and drained by `pushHooks.close`. When the registry reaches the cap, new userIds are not registered (the connection still works, it just can't be the target of `live.push({ userId })` until existing entries clear). A one-shot warning surfaces the saturation. Hitting this typically means push registrations are not being released on disconnect -- check `hooks.ws.js` wires `pushHooks.close`.
+
+### TOPIC_WS_COUNTS_WARN_THRESHOLD (1,000,000)
+
+Per-process Map<topic, Set<ws>> tracking which sockets hold an active stream subscription per topic. Used by the realtime layer to pass `remainingSubscribers` to `__onUnsubscribe`. Eviction would corrupt subscribe / unsubscribe routing, so this is WARN-ONLY: the map keeps growing past the threshold, but a one-shot warning surfaces. Hitting this typically means runaway dynamic-topic generation (per-request topic strings); prefer aggregating into stable topic names.
+
+### SILENT_TOPIC_WARN_DEDUP_MAX (1,000,000)
+
+Dev-mode set of topics that have already fired the silent-topic warning. FIFO-evicts at the cap (dropping the oldest topic just lets it re-warn on its next over-threshold subscribe). Dev-only; production code paths are constant-folded out.
+
+### PUBLISH_RATE_WARN_DEDUP_MAX (1,000,000)
+
+Dev-mode set of topics that have already fired the high-frequency publish-rate warning. FIFO-evicts at the cap (dropping the oldest topic just lets it re-warn on its next sample tick). Dev-only.
+
+### MAX_OPTIMISTIC_QUEUE_DEPTH (1,000)
+
+Per-stream upper bound on concurrent in-flight `store.mutate(asyncOp, change)` calls. When the queue depth equals the cap, the next `mutate()` rejects with `MAX_OPTIMISTIC_QUEUE_DEPTH=1000`. Hitting this means either the server is unresponsive (mutates are not settling), the call site is firing mutates faster than the server can confirm, or a bulk operation is being submitted as N individual mutates instead of one batch. For bulk actions over 1000 items, prefer `batch()` or a single bulk-RPC handler. The cap protects the worst-case display-recompute cost during slow-server scenarios; recompute walks the full queue on every server event so cost grows linearly.
+
+### Rate-limit identities (5,000)
+
+Per-function rate limiting (`live.rateLimit()`) tracks sliding-window buckets in memory. When the bucket map reaches the cap, stale buckets are swept first. If still full, new identities are rejected with a `RATE_LIMITED` error. Existing identities are unaffected.
+
+### Throttle/debounce timers (5,000)
+
+Active per-key throttle and debounce entries (`ctx.throttle()` / `ctx.debounce()`). At capacity, new entries bypass the timer and publish immediately so data is never silently dropped.
+
+### Presence refs (10,000)
+
+The server tracks presence join/leave refcounts in memory. When the map reaches the cap, suspended entries (those with a pending leave timer) are evicted first. If the map is still full after eviction, the join is dropped silently.
+
+### Idempotency results (10,000)
+
+In-process `live.idempotent()` store. At capacity, evicts the oldest 10% of entries to make room. The TTL set per-call also prunes expired entries every 30 seconds.
+
+---
+
 ## Production limits
 
 ### maxPayloadLength (default: 16KB)
@@ -1901,18 +2705,6 @@ The adapter's `sendQueued()` drops the oldest item when the queue exceeds 1000 m
 
 A single `batch()` call is limited to 50 RPC calls. The client rejects before sending if the limit is exceeded, and the server enforces the same limit as a safety net. Split into multiple `batch()` calls if you need more.
 
-### Presence refs (max 10,000)
-
-The server tracks presence join/leave refcounts in memory. When the map reaches 10,000 entries, suspended entries (those with a pending leave timer) are evicted first. If the map is still full after eviction, the join is dropped silently.
-
-### Rate-limit identities (max 5,000)
-
-Per-function rate limiting (`live.rateLimit()`) tracks sliding-window buckets in memory. When the bucket map reaches 5,000 entries, stale buckets are swept first. If still full, new identities are rejected with a `RATE_LIMITED` error. Existing identities are unaffected.
-
-### Throttle/debounce timers (max 5,000)
-
-The server tracks active throttle and debounce entries globally. When at capacity, new entries bypass the timer and publish immediately so data is never silently dropped.
-
 ### Topic length (max 256 characters)
 
 The adapter rejects topic names longer than 256 characters or containing control characters (byte value < 32). This applies to subscribe, unsubscribe, and batch-subscribe messages.
@@ -1954,6 +2746,59 @@ onError((path, error) => {
 
 > `onCronError` still works but is deprecated -- use `onError` instead.
 
+### Dev-mode publish rate warning
+
+In development, the framework samples `platform.pressure.topPublishers` at a configurable interval and logs a one-shot warning per topic when message rate crosses a threshold. Suggests `coalesceBy` and `volatile: true` mitigations and suppresses automatically when the topic is already configured with either.
+
+```js
+import { live } from 'svelte-realtime/server';
+
+// Defaults: enabled, threshold 200 events/sec, intervalMs 5000
+live.publishRateWarning({ threshold: 500, intervalMs: 10_000 });
+
+// Disable entirely
+live.publishRateWarning(false);
+```
+
+Production builds constant-fold the activation branch to dead code -- zero overhead. The sampler runs once per platform on the first ctx-helpers cache miss; per-publish cost is unchanged. Topics already in `_topicCoalesce` or `_topicVolatile` are skipped (the user has already addressed them).
+
+### Dev-mode silent-topic warning
+
+In development, the framework arms a one-shot timer when a stream first subscribes to a topic. If no events arrive within `thresholdMs` (default `30000`), it logs a warning naming the topic and the common causes:
+
+```
+[svelte-realtime] Topic 'audit:org-1' has subscribers but no events arrived within 30000ms.
+  Common causes:
+    - missing pg_notify trigger on the underlying table
+    - no ctx.publish() call in the relevant handler
+    - intentionally low-traffic topic (extend threshold or suppress)
+  Configure: live.silentTopicWarning({ thresholdMs: 60000 })
+  Suppress:  live.silentTopicWarning({ suppress: ['audit:org-1'] })
+  Disable:   live.silentTopicWarning(false)
+  See: https://svti.me/silent-topic
+```
+
+```js
+import { live } from 'svelte-realtime/server';
+
+// Lower the bar (default 30s)
+live.silentTopicWarning({ thresholdMs: 5000 });
+
+// Suppress per-topic for known-quiet streams (admin views, scheduled reports)
+live.silentTopicWarning({ suppress: ['admin:audit', 'cron:reports'] });
+
+// Disable globally
+live.silentTopicWarning(false);
+```
+
+Topics starting with `__` (system topics: `__realtime`, `__signal:*`, `__custom`) are always skipped automatically; you don't need to add them to `suppress`. Each topic warns at most once per process; the warning never fires for a topic that has been live, and re-subscribing after a warn does not re-fire. Hard-gated to development -- production builds constant-fold the activation branch to dead code, so apps not in dev mode pay zero cost regardless of configuration.
+
+The watchdog reuses the same lifecycle hooks as the staleness watchdog (`staleAfterMs`): arms on first sub for the topic, observed on every publish, disarms on last unsub. Apps using both features share the per-topic timer machinery without paying twice.
+
+### Per-stream `onError` for loader observability
+
+For streams whose loader can fail, add `onError(err, ctx, topic)` to the stream options. See [Stream lifecycle hooks](#stream-lifecycle-hooks) for the full pattern. Per-stream observers fire alongside the global `onError` setter, not instead of it.
+
 ---
 
 ## Custom message handling
@@ -2005,6 +2850,32 @@ This applies to all handler types -- `live()`, `live.stream()`, `live.cron()`, `
 
 In dev mode, the Vite plugin injects an in-browser overlay that shows active streams, RPC history, and connection status. Toggle with `Ctrl+Shift+L`.
 
+The Streams tab lists every store currently mounted on the page. For each one it shows:
+
+| Field | Meaning |
+|---|---|
+| topic | The wire topic the store is subscribed to (or `?` while loading). |
+| merge | The store's merge strategy (`crud`, `latest`, `set`, `presence`, `cursor`). |
+| subs | Active subscriber count; the entry disappears when this hits zero. |
+| last | Event name of the most recent pub/sub frame and its relative age (`12s ago`). |
+| err | Error code + message if the stream is in the error state; cleared on recovery. |
+
+**Click any stream row to expand a per-stream payload preview** -- the most recent 20 envelopes, time + event name + JSON data. Toggle Pretty / Raw via the header buttons (Raw shows full JSON up to ~500 chars; Pretty truncates at ~200 with overflow indicator). Pause stops capturing new events without affecting the live `last:` timestamp; Clear events drops every stream's ring buffer in one click. Pretty/Raw + Pause states persist across reloads via `localStorage`.
+
+**Privacy.** Captured payloads are walked once at write time with key-based redaction. The default redact list covers `password`, `token`, `apiKey` / `api_key`, `secret`, `authorization`, `cookie`, `sessionid` / `session_id`, `csrf` / `csrftoken`. Override or extend at runtime:
+
+```js
+import { __devtools } from 'svelte-realtime/client';
+if (__devtools) {
+  __devtools.redactKeys.add('paymentMethod');
+  __devtools.redactKeys.add('ssn');
+}
+```
+
+Match is case-insensitive and exact-key (no substring fuzz). Redacted values render as `'[REDACTED]'`. Recursion is capped at depth 5 (deeper structures show `'[depth-cap]'`) and arrays at 50 items so a malformed-large payload doesn't pin a graph in memory.
+
+The RPC tab shows pending calls (with elapsed time) and a 50-entry ring buffer of recent results (ok/err, duration). The Connection tab summarizes the same counters.
+
 The overlay is stripped from production builds. Disable it in dev with:
 
 ```js
@@ -2075,6 +2946,82 @@ describe('chat module', () => {
 | `events` | All pub/sub events received |
 | `hasMore` | Whether more pages are available |
 | `waitFor(predicate, timeout?)` | Wait for a value matching a predicate |
+| `simulatePublish(event, data)` | Publish a server-side event to this stream's topic. Equivalent to `env.platform.publish(stream.topic, event, data)`, but discoverable on the stream return where the test is already focused. Throws if the topic is not yet known (await the initial subscribe first). |
+
+### Chaos harness
+
+`createTestEnv({ chaos: { dropRate, seed } })` enables fault injection on `platform.publish` so tests can verify resilience to message drops without spinning a real cluster.
+
+```js
+import { createTestEnv } from 'svelte-realtime/test';
+
+// 50% drop rate, deterministic via seed
+const env = createTestEnv({
+  chaos: { dropRate: 0.5, seed: 'rep-1234' }
+});
+
+env.register('chat', chat);
+const client = env.connect({ id: 'u1' });
+const stream = client.subscribe('chat/messages');
+
+// Publish 100 events; ~50 of them get dropped.
+for (let i = 0; i < 100; i++) {
+  env.platform.publish('chat-messages', 'created', { id: i });
+}
+// Same seed -> same drop sequence across runs, so failures replay.
+```
+
+Runtime control via `env.chaos`:
+
+| Method/property | Description |
+|---|---|
+| `env.chaos.set({ dropRate?, seed? })` | Apply (or replace) chaos config mid-test. |
+| `env.chaos.disable()` | Equivalent to `set(null)`. |
+| `env.chaos.config` | Current `{ dropRate, seed }` or `null`. |
+| `env.chaos.dropped` | Running count of `platform.publish` drops. |
+| `env.chaos.resetCounter()` | Zero the counter without changing config. |
+
+Currently models the `drop-outbound` scenario only -- `platform.publish` events to subscribers are dropped at the platform layer. RPC replies (`platform.send`) are exempt because timing them out would just hang test code; the chaos harness is for testing pub/sub resilience, not RPC retry behavior.
+
+### Direct ctx unit tests
+
+`createTestContext({ user })` builds a `ctx`-shaped object suitable for direct unit tests of guards and predicates -- helper methods are no-ops, the user / cursor / requestId can be overridden. Use this when the function under test takes `ctx` and synchronously returns a value; reach for `createTestEnv()` only when you need full publish/subscribe round-trips.
+
+```js
+import { createTestContext } from 'svelte-realtime/test';
+
+const adminOnly = (ctx) => ctx.user?.role === 'admin';
+
+expect(adminOnly(createTestContext({ user: { role: 'admin' } }))).toBe(true);
+expect(adminOnly(createTestContext({ user: { role: 'viewer' } }))).toBe(false);
+expect(adminOnly(createTestContext())).toBe(false);
+```
+
+The returned shape mirrors the production `_buildCtx`: `user`, `ws`, `platform`, `publish`, `cursor`, `throttle`, `debounce`, `signal`, `batch`, `shed`, `requestId`. Helpers default to no-op stubs (`publish` returns `true`, `shed` returns `false`, etc.), which is correct for predicates that only read `ctx.user` or `ctx.cursor`.
+
+### Asserting guard rejections
+
+`expectGuardRejects(promise, expectedCode?)` is a small ergonomic wrapper for the common "this call should be denied" pattern. It awaits the promise, asserts it rejected with a `LiveError` of the expected code (default `'FORBIDDEN'`), and returns the error so further assertions can run on it.
+
+```js
+import { createTestEnv, expectGuardRejects } from 'svelte-realtime/test';
+
+const env = createTestEnv();
+env.register('admin', adminModule);
+
+const user = env.connect({ role: 'viewer' });
+
+// Guards that throw FORBIDDEN are the default case
+await expectGuardRejects(user.call('admin/destroyAll'));
+
+// Anonymous calls typically reject with UNAUTHENTICATED
+const anon = env.connect(null);
+await expectGuardRejects(anon.call('admin/destroyAll'), 'UNAUTHENTICATED');
+
+// The rejected error is returned for further assertions
+const err = await expectGuardRejects(user.call('admin/destroyAll'));
+expect(err.message).toMatch(/admin role/);
+```
 
 ---
 
@@ -2097,6 +3044,7 @@ Import from `svelte-realtime/server`.
 | `live.webhook(topic, config)` | HTTP webhook-to-stream bridge |
 | `live.gate(predicate, fn)` | Conditional stream activation |
 | `live.rateLimit(config, fn)` | Per-function sliding window rate limiter |
+| `live.rateLimits(config)` | Registry-level rate limits with `default` / `overrides` / `exempt` |
 | `live.middleware(fn)` | Global middleware (runs before guards) |
 | `live.access.*` | Subscribe-time access control helpers |
 | `guard(...fns)` | Per-module auth middleware |