@luckystack/sync 0.10.2 → 0.11.0

package/docs/room-fanout.md

@@ -1,257 +1,21 @@
-# room-fanout
+# Room fanout
 
-> How `handleSyncRequest` resolves the `receiver` string to a set of Socket.io sockets, iterates them, and notifies hook consumers along the way. Covers the `'all'` sentinel, the per-token room convention, event-loop yielding for giant fanouts, the `preSyncFanout` / `postSyncFanout` hooks, and Redis-backed cross-instance fanout.
+A receiver supplied by a client must be authorized before delivery. Server-side policy limits global broadcast and room targeting; membership for socket requests comes from the connection, while HTTP/SSE uses persisted session room membership because it has no originator socket. Do not use recipient-specific handlers as a substitute for this sender gate. See `../src/_shared/receiverAuth.ts`, `../src/handleSyncRequest.ts`, `../src/handleHttpSyncRequest.ts`.
 
-For the originator's `receiver` argument see [`./sync-request.md`](./sync-request.md). For per-recipient handler authoring see [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md).
+The two membership sources are deliberate (ADR 0059). The socket check tests the room the fanout will actually deliver to. HTTP has no originator socket, and resolving the caller's sockets across instances before authorization would add a Redis round-trip to every HTTP sync. Consequence: on routed HTTP, a successful sync does not prove that the caller is in the room or will receive the fanout. A session can still list a room that its socket has not re-joined since a reconnect. Re-joining after a reconnect is the consumer's job.
 
-> **Applies from `@luckystack/sync` 0.10.0.** Earlier versions resolved recipients from this process's own adapter maps, and only the socket transport rejected an empty room. Everything below describes the cross-instance model that replaced that.
+Each authenticated socket's private token room is for session-targeted messages; never expose token room names to unrelated callers. Tenant room formatting must be consistent when joining and fanning out (`../../core/src/roomNameFormatterRegistry.ts`). The `userId` a formatter receives is context only. It is the joiner on join and the sender on fanout. A formatter that builds it into a content room's physical name therefore splits join and send into different rooms, and every broadcast reaches nobody (ADR 0060). Put per-user isolation in the room code itself.
 
----
+## Recipients are resolved across instances, before the handler commits
 
-## 1. How `receiver` resolves to sockets
+Both transports enumerate the room across every instance that shares the adapter, after authorization and before the `_server` handler (ADR 0063). An empty list or a failed lookup is therefore reported before anything is persisted (see `./error-states.md`). The accepted cost: the recipient snapshot is taken one handler execution earlier, so a socket that joins while the handler runs misses that one fanout.
 
-Both transports — `handleSyncRequest` (socket) and `handleHttpSyncRequest` (HTTP/SSE) — resolve recipients the same way, in the same order:
+A recipient on another instance is a full recipient. Its per-recipient handler runs on the instance handling the request, and the result is delivered through the remote socket handle. Correctness does not need sticky sessions.
 
-1. **Format the room.** The `receiver` string goes through the room-name formatter from `@luckystack/core` under the canonical `'broadcast'` purpose, so a non-identity `registerRoomNameFormatter` targets the same physical room the sockets joined (join formats the name too). `'all'` is a sentinel and is never formatted.
-2. **Enumerate across instances — before `_server` runs.** The framework asks Socket.io for the members of that physical room on **every** instance sharing the Redis adapter (`io.in(room).fetchSockets()`), or for every socket everywhere when the receiver is `'all'`. The result is a list of `RemoteSocket`s — never a lookup in this process's local room map. This happens after auth, rate-limit and the authorize hooks but **before** input validation and the `_server` handler, so nothing has been persisted yet when it fails.
-3. **Empty → `sync.noReceiversFound`.** An empty list ends the request with that error on **both** transports, before `_server` runs, before `preSyncFanout` fires and before any recipient is touched. See §8.
-4. `_server` (validate input, execute, persist), then `preSyncFanout`, then the per-recipient loop (§3).
+Never build a fanout target, presence list or room snapshot from the per-instance socket maps (`io.sockets.adapter.rooms`, `adapter.sids` or enumerating `io.sockets.sockets`). Under the Redis adapter they return a partial view that looks complete, with no error, and silently drop the rest of the cluster (ADR 0061). Use `getRoomSockets` (`../../core/src/roomSockets.ts`) or `io.in(room).fetchSockets()`. A lint rule, `no-local-socket-enumeration`, and a guard on `getIoInstance()` that throws outside production both catch this mistake. Deliberate per-instance work opts out explicitly with a stated reason. See `../../core/src/localSocketEnumerationGuard.ts`, `../../core/docs/redis-adapter.md`.
 
-Three consequences worth internalising: a recipient on another instance is a first-class recipient (its `_client` runs, see §7); "does the room exist locally" is never the question — the only question is whether the cross-instance query returned members; and an error from this step is a **pre-commit** rejection — the cross-instance query can fail (an adapter request timeout when an instance on the channel does not answer) and when that happened after `_server` had persisted its mutation the caller was told `error` about a change that had been saved, so a retry applied it twice. The cost of resolving first is a recipient snapshot taken one handler-execution earlier: a socket that joins the room while `_server` runs misses that one fan-out.
+## Per-recipient hook and counts
 
-Whether the sender is *allowed* to target the room at all is a separate, earlier check (`sync.requireRoomMembership`) whose semantics deliberately differ per transport — see [`/docs/ARCHITECTURE_SYNC.md`](../../../docs/ARCHITECTURE_SYNC.md) → "Room membership is transport-specific".
+`preSyncRecipient` acts on one recipient, on both transports and for remote recipients too. A stop skips only that recipient. A stop with an override output delivers a redacted payload instead. Its `recipientUserId` is always null, because resolving a user per socket would cost one session read per recipient on the hot path. A handler that needs the user reads the session by `recipientToken`. Payload shape: `HookPayloads` in `@luckystack/core`.
 
-There is no "broadcast to all but yourself" sentinel — pass `ignoreSelf: true` to skip the originator's own sockets. See [`./ignore-self.md`](./ignore-self.md).
-
----
-
-## 2. Room conventions
-
-Rooms are managed by `@luckystack/core` (client) via `joinRoom(code)` / `leaveRoom(code)`. Conventions in production code:
-
-| Room name | Membership | Used for |
-|---|---|---|
-| `<sessionToken>` (auto-joined) | Every socket of one user | `streamTo(token, payload)` reaches all that user's devices. |
-| `<sharedCode>` (manual join) | Multiple users by app logic | Collab editors, multiplayer rooms, chat. |
-| `'all'` (sentinel, not a real room) | Every connected socket | Global broadcasts. Avoid in production. |
-
-### Why every socket auto-joins a room named after its session token
-
-`@luckystack/server` joins each socket to a room with that socket's session token at connect time. This is what makes `streamTo(['userToken1', 'userToken2'], payload)` work — without it the framework would have to maintain a separate `tokenToSockets` map.
-
-Side effect: if a user is connected from three devices (three sockets, three different `socket.id`s, one session token), `streamTo` reaches all three because they all live in the same per-token room.
-
----
-
-## 3. The fanout loop
-
-After auth, rate-limit, validation, and `_server` execution succeed, `handleSyncRequest` enters the per-recipient loop:
-
-```
-preSyncFanout (stop signal aborts before any recipient is touched)
-        |
-        v
-for each socket in <resolved sockets>:
-    yield every N (configurable)
-    skip if ignoreSelf && token === recipientToken
-    preSyncRecipient (stop without overrideOutput skips this recipient, uncounted;
-                      stop WITH overrideOutput replaces serverOutput for this recipient)
-    recipientCount++
-    if _client exists:
-        run clientHandler
-        emit per-recipient result (success or normalized error)
-    else:
-        emit { serverOutput, clientOutput: {}, status: 'success', cb, fullName }
-        |
-        v
-postSyncFanout({ recipientCount, ...payload })
-```
-
-Per-recipient errors do **not** abort the loop. A single recipient failing `_client` execution receives a `sync.clientExecutionFailed` frame; everyone else still receives their merged payload.
-
----
-
-## 4. Event-loop yielding (`sync.fanoutYieldEvery`, `sync.fanoutYieldMs`)
-
-```ts
-const { fanoutYieldEvery, fanoutYieldMs } = getProjectConfig().sync;
-let tempCount = 1;
-for (const socketEntry of sockets) {
-  tempCount++;
-  if (tempCount % fanoutYieldEvery === 0) {
-    await new Promise(resolve => setTimeout(resolve, fanoutYieldMs));
-  }
-  // ... fanout to this recipient ...
-}
-```
-
-Why: a `receiver: 'all'` fanout against thousands of sockets would otherwise block the event loop for the whole iteration. Yielding every `fanoutYieldEvery` recipients (default: see `projectConfig.sync.fanoutYieldEvery`) for `fanoutYieldMs` (default: a few ms) lets other socket events, API requests, and the heartbeat handlers run.
-
-Tuning:
-
-- **Higher `fanoutYieldEvery` + lower `fanoutYieldMs`** = faster fanout, less responsiveness for other requests.
-- **Lower `fanoutYieldEvery` + higher `fanoutYieldMs`** = smoother for concurrent traffic but slower fanout.
-- For typical room sizes (<100 recipients), the yield never triggers — defaults are tuned for `receiver: 'all'` worst cases.
-
-Both transports yield on the same schedule — the HTTP handler's loop reads the same two config keys. An HTTP-invoked fanout still runs on the event loop of the instance that received the request, so a giant `'all'` fanout would starve it just the same.
-
----
-
-## 5. Hooks dispatched during fanout
-
-### `preSyncFanout`
-
-```ts
-{
-  routeName: string,         // e.g. 'board/moveCard/v1'
-  data: Record<string, unknown>,   // clientInput
-  user: SessionLayout | null,      // sender's session
-  receiver: string,                 // resolved roomCode or 'all'
-  serverOutput: unknown,            // what _server returned (minus status)
-}
-```
-
-Fires **after** `_server` runs successfully and the recipient set is resolved, **before** any recipient receives the payload. Stop signal converts to an originator-side error envelope with the hook's `errorCode` / `httpStatus`. Use for:
-
-- "Don't fanout this mutation to a degraded region while we drain traffic."
-- "Throttle fanout-heavy routes during peak load."
-- "Inject a cross-room replication hop before the room receives the payload."
-
-### `preSyncRecipient`
-
-Fires once per resolved recipient, after the `ignoreSelf` skip and before that one socket receives anything. It carries the route name, the receiver, the recipient's socket id, the recipient's session token (`recipientToken`, `null` for an anonymous socket) and the `serverOutput` about to be sent. Exact shape: `HookPayloads` in `@luckystack/core`.
-
-Semantics that differ from the other fanout hooks:
-
-- A stop signal **without** `overrideOutput` skips just this recipient — the loop continues, and the skipped socket is not counted in `recipientCount`.
-- A stop signal **with** `overrideOutput` still delivers to this recipient, but with the override in place of `serverOutput` — per-recipient redaction without a `_client` file.
-- `recipientUserId` is **always `null`**. There is no resolver option: resolving a user per recipient would cost a session read per socket on the hot path. A handler that needs the user reads the session itself by `recipientToken` (the token is already known in the loop, so it costs nothing to expose).
-
-Fires on both transports and for remote recipients too (§7).
-
-### `postSyncFanout`
-
-```ts
-{
-  routeName: string,
-  data: Record<string, unknown>,
-  user: SessionLayout | null,
-  receiver: string,
-  serverOutput: unknown,
-  recipientCount: number,    // actual number of sockets emitted to (NOT room size)
-}
-```
-
-Fires after the last recipient's emit. Observation-only — there is no stop signal because the fanout has already happened. Use for:
-
-- Audit logs ("this mutation reached N viewers").
-- Metrics (`fanout_size_histogram.observe(recipientCount)`).
-- Cross-region eventual-consistency markers.
-
-### `rateLimitExceeded`
-
-```ts
-// Scope 'user' or 'route' (per-token / per-IP per-route bucket):
-{
-  scope: 'user' | 'route',
-  key: string,            // 'token:<token>:sync:<route>' or 'ip:<ip>:sync:<route>'
-  limit: number,
-  windowMs: number,
-  count: number,
-  route: string,
-  userId: string | undefined,
-}
-
-// Scope 'ip' (global per-IP cross-route bucket):
-{
-  scope: 'ip',
-  key: string,            // 'ip:<ip>:sync:all'
-  limit: number,
-  windowMs: number,
-  count: number,
-  ip: string,
-}
-```
-
-Fires before fanout begins, when either bucket rejects. Used to surface abusive senders and feed automated mitigation.
-
----
-
-## 6. `recipientCount` vs raw room size
-
-`recipientCount` differs from the size of the resolved recipient list in two cases, identically on both transports:
-
-1. **`ignoreSelf: true`** — every socket whose extracted token matches the sender's is skipped. If a user has 3 sockets in the room and triggered the sync themselves, `recipientCount` is `size - 3`.
-2. **`preSyncRecipient` stop without `overrideOutput`** — the recipient is skipped and not counted (§5).
-
-What does **not** reduce it:
-
-- **Sockets disappearing mid-fanout.** The recipient list is a snapshot of `RemoteSocket`s taken once, before the loop. A socket that disconnects between the snapshot and its turn is still iterated: the loop emits to the remote handle, the adapter drops the emit because the target is gone, and the recipient is still counted. There is no per-iteration "does this socket still exist" re-check against a local map — that check would only be answerable for local sockets anyway.
-- **A failing `_client`.** The recipient is counted before `_client` runs, so a recipient that received an error frame counts the same as one that received a success frame.
-
-So `recipientCount` is "how many recipients the loop emitted to", not "how many received the payload" — the second number does not exist on the server side of an adapter. Observers wanting delivery confirmation need a client-side ack of their own.
-
----
-
-## 7. Cross-instance fanout via Redis adapter
-
-Single-instance fanout is built into Socket.io. **Cross-instance fanout requires the Redis adapter**, which `@luckystack/server` attaches on every backend (see [`/docs/ARCHITECTURE_SOCKET.md`](../../../docs/ARCHITECTURE_SOCKET.md)). Two mechanisms ride on it:
-
-- `io.to(room).emit(...)` — used by the streaming emitters — publishes to Redis; every instance delivers to its own members of that room.
-- `io.in(room).fetchSockets()` + `RemoteSocket.emit()` — used by the regular sync fanout — enumerates the room across all instances and delivers to each member individually.
-
-**The per-recipient `_client` handler runs for remote recipients too.** The fanout loop iterates the cross-instance list, runs `_client` on the instance that is handling the request (it has the route code, the `serverOutput`, and the recipient's handshake headers and token), and delivers the result through the recipient's `RemoteSocket`. No sticky sessions are needed for correctness; spreading one room's members across instances is fine. The cost model (one Redis round-trip per fanout plus one emit per remote recipient) is in [`/docs/ARCHITECTURE_MULTI_INSTANCE.md`](../../../docs/ARCHITECTURE_MULTI_INSTANCE.md).
-
-> **Warning — `io.sockets.adapter.rooms`, `io.sockets.adapter.sids` and enumerating `io.sockets.sockets` are per-instance maps.** They answer "who is connected to *this process*", which under the Redis adapter is a partial view that looks complete: no error, just missing members. A helper that builds a room snapshot, a presence list or a broadcast target from them works on one instance and silently drops the rest of the cluster on two. Use instead:
->
-> - `getRoomSockets(room, { userId? })` from `@luckystack/core` — routes the room through the formatter under `'broadcast'` and returns the cross-instance `RemoteSocket[]` (`'all'` = every socket everywhere). It throws when no Socket.io server is registered, because a silent empty list is exactly the failure this exists to prevent.
-> - `io.in(room).fetchSockets()` / `io.to(room).emit()` directly when you already hold the physical room name.
->
-> Three guards catch the mistake before production does: the ESLint rule `luckystack/no-local-socket-enumeration` in `@luckystack/core/eslint` flags the patterns statically; outside production `getIoInstance()` returns a guarded view that **throws** on those accessors (`sockets.sockets.get(id)` stays allowed); and `getIoInstance({ raw: true })` is the explicit opt-in for deliberate per-instance work — a sweep cleaning up its own connections, or sampling this process's backpressure. In production the raw instance is always returned, so the guard costs nothing on the hot path.
-
-`recipientCount` in `postSyncFanout` counts recipients on every instance, not just local ones.
-
----
-
-## 8. `sync.noReceiversFound`
-
-Triggered on **both transports** when the cross-instance recipient list (§1) comes back empty. Before 0.10.0 only the socket transport rejected this; the HTTP/SSE path returned `success` with zero recipients, so an HTTP caller could not tell "delivered" from "nobody there". Typical causes:
-
-- The room name was misspelled.
-- Every member already disconnected before the request reached the fanout step.
-- A bug had the client `joinRoom`-ing under a different name than the sender's `receiver` argument.
-- A room-name formatter that folds the caller's `userId` into the physical name — join and fanout then land in different physical rooms (see the formatter contract in `packages/core/docs/socket-bootstrap.md`).
-- On `routed-http`: the caller's session still lists the room in `roomCodes` (so the membership check passed) but no socket has re-joined it — see the membership section in [`/docs/ARCHITECTURE_SYNC.md`](../../../docs/ARCHITECTURE_SYNC.md).
-- `receiver: 'all'` while no sockets are connected at all (development edge case).
-
-Surfaced to the originator as:
-
-```ts
-{ status: 'error', errorCode: 'sync.noReceiversFound', message: '<localized>', httpStatus: 404 }
-```
-
-Default `httpStatus` mapping for this code comes from `defaultHttpStatusForResponse` in `@luckystack/core`.
-
-This is not necessarily a bug — sending to an empty room is legal if the sender doesn't yet know the room is empty. Recipients are resolved **before** `_server` runs (§1), so on this error nothing has been persisted: the mutation did NOT happen, and a retry once someone is listening is safe. (Earlier versions ran the check after `_server`, so the UI had to read this error as "saved, but nobody was listening"; that reading is now wrong.)
-
----
-
-## 9. Sanity-check checklist
-
-- Are sockets joining the right room? `socket.rooms` on the recipient side lists every room they're in (including the auto-joined `<sessionToken>` room and `<socket.id>` self-room).
-- Is the Redis adapter wired in production? `getIoInstance().of('/').adapter` should be `RedisAdapter`, not `Adapter`.
-- Are giant fanouts hot in the profiler? Bump `fanoutYieldEvery` higher OR move to per-token rooms instead of `receiver: 'all'`.
-- Is `recipientCount` consistently below room size? Probably `ignoreSelf: true` + multi-tab usage. Expected; not a bug.
-
----
-
-## 10. Related
-
-- Originator API: [`./sync-request.md`](./sync-request.md)
-- Handler authoring: [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md)
-- Skip-self semantics: [`./ignore-self.md`](./ignore-self.md)
-- Streaming fanout: [`./streaming.md`](./streaming.md)
-- Error catalog (including `sync.noReceiversFound`): [`./error-states.md`](./error-states.md)
-- Socket.io + Redis adapter: [`/docs/ARCHITECTURE_SOCKET.md`](../../../docs/ARCHITECTURE_SOCKET.md)
-- Hook payload shapes: `@luckystack/core` `HookPayloads`
-- Config: `projectConfig.sync.fanoutYieldEvery`, `projectConfig.sync.fanoutYieldMs`
+`recipientCount` counts the recipients the loop emitted to, not the ones that received the payload. A socket that disconnected after the snapshot and a recipient whose handler failed are still counted. Only `ignoreSelf` and a skipping `preSyncRecipient` stop lower the count. Across an adapter, the server has no delivery confirmation, so an observer that needs one must add a client-side acknowledgement. Fanout yields to the event loop on both transports, because a fanout started over HTTP still runs on the receiving instance's event loop.

package/docs/server-vs-client-handlers.md

@@ -1,325 +1,9 @@
-# server-vs-client-handlers
+# Server versus recipient sync handlers
 
-> A sync route is **two files**: a mandatory `_server_v{N}.ts` that runs **once per request** to validate and produce `serverOutput`, and an **optional** `_client_v{N}.ts` that runs **once per recipient socket** for per-target filtering, per-client auth, or producing a custom `clientOutput`. This doc covers the contract of both files and the rules for when to skip the `_client` file entirely.
+The server handler owns the request's shared validation, mutation and originator result. An optional per-recipient handler exists only when a viewer needs different output, such as filtering private fields or adapting presentation. Do not add an empty recipient handler: it adds work without changing the audience. Source: `../src/handleSyncRequest.ts`, `../src/handleHttpSyncRequest.ts`, `../src/_shared/clientFanout.ts`.
 
-For the originator-side call signature see [`./sync-request.md`](./sync-request.md). For fanout mechanics see [`./room-fanout.md`](./room-fanout.md).
+**Security invariant:** the sender's authority to target a room must be checked before the shared mutation or fanout (`../src/_shared/receiverAuth.ts`). A recipient handler is not an originator auth gate, and one recipient's failure does not roll back the mutation or stop other deliveries. Assume shared server output can reach every permitted recipient; keep secrets out of it unless the server-side audience is constrained. Resolve recipient-specific identity from that recipient's session, not the sender's. The originator acknowledgement reports the server result independently of recipient delivery.
 
----
+**Ordering invariant:** recipients are resolved, across instances, before the server handler runs, on both transports (ADR 0063). The framework cannot undo a handler's side effects, so any failure it can find before the mutation must be reported before the mutation. An empty room or a failed recipient lookup therefore never reaches the server handler. Consequence for handler authors: the audience is fixed before your handler runs, and a socket that joins the room during your handler misses that fanout.
 
-## 1. The two-file model
-
-Given the file-based router (see `/docs/ARCHITECTURE_ROUTING.md`):
-
-```
-src/board/_sync/moveCard_server_v1.ts   <- REQUIRED: validates + produces serverOutput (runs once)
-src/board/_sync/moveCard_client_v1.ts   <- OPTIONAL: per-recipient logic (runs once per socket in the room)
-```
-
-Route name: `board/moveCard` at version `v1`. The framework loads both files via `getRuntimeSyncMaps()` and keys them as `board/moveCard/v1_server` and `board/moveCard/v1_client`.
-
-A route is valid if **at least one** of the two files exists. If neither exists, `handleSyncRequest` rejects with `sync.notFound`.
-
----
-
-## 2. `_server_v{N}.ts` contract — runs ONCE per request
-
-```ts
-import type { SessionLayout, Functions } from '@luckystack/core';
-import type { AuthProps } from '@luckystack/login';
-
-export const auth: AuthProps = { login: true };
-
-export interface SyncParams {
-  clientInput: { /* validated against generated Zod schema */ };
-  user: SessionLayout | null;       // null only when auth.login === false
-  functions: Functions;              // tryCatch, db, redis, notify, ...
-  roomCode: string;                  // the `receiver` from syncRequest
-  stream: (payload?: Record<string, unknown>) => void;        // originator only
-  broadcastStream: (payload?: Record<string, unknown>) => void; // entire room
-  streamTo: (tokens: string | string[], payload?: Record<string, unknown>) => void;
-}
-
-export const main = async ({ clientInput, user, functions, roomCode, broadcastStream }: SyncParams) => {
-  // 1. Mutate persistent state.
-  await functions.db.card.update({ where: { id: clientInput.cardId }, data: { laneId: clientInput.toLane } });
-
-  // 2. Optionally stream progress / tokens / diffs (broadcastStream goes to everyone in roomCode).
-  // 3. Return the success envelope. Everything except `status` becomes `serverOutput` for the recipients.
-  return { status: 'success', cardId: clientInput.cardId, movedBy: user!.id };
-};
-```
-
-Key rules:
-
-- **`auth: AuthProps` is mandatory.** Drives the framework's auth gate (`auth.login` -> require session, `auth.additional` -> run `validateRequest` predicates). See `@luckystack/login` `AuthProps`.
-- **Return must include `status: 'success' | 'error'`.** Anything else collapses to `sync.invalidServerResponse`. The rest of the object is forwarded as `serverOutput` (after stripping `status`).
-- **Streaming primitives are received as params.** See [`./streaming.md`](./streaming.md) for the audience matrix.
-- **Optional `export const validation`** toggles runtime input validation, exactly like the API handler. `'strict'` (default, or omit the export) validates `clientInput` against the generated Zod schema; `'relaxed'` or `{ input: 'skip' }` skips validation entirely — use it for routes whose payload shape can't be modelled in TypeScript (third-party webhook fan-in, dynamic blobs). Honored identically by both the Socket.io and HTTP/SSE transports.
-- **Optional `export const errorFormatter`** overrides the error envelope for this route only (falls back to the global `registerErrorFormatter`, then the framework default). Both transports honor it.
-- **Never `try/catch` manually.** Wrap async ops in `functions.tryCatch` (or the destructured `tryCatch` from `functions`) — the framework already wraps the whole `main()` in its own `tryCatch` for registered error-tracker capture, but per-operation `tryCatch` lets you surface targeted error codes.
-
----
-
-## 3. `_client_v{N}.ts` contract — runs ONCE per recipient socket
-
-```ts
-import type { Functions } from '@luckystack/core';
-
-export interface SyncClientParams {
-  clientInput: { /* same shape as _server */ };
-  token: string | null;             // recipient's session token (NOT the sender's)
-  functions: Functions;
-  serverOutput: unknown;             // exactly what _server returned (minus `status`)
-  roomCode: string;
-  stream: (payload?: Record<string, unknown>) => void;  // per-recipient stream
-}
-
-export const main = async ({ clientInput, token, functions, serverOutput, roomCode }: SyncClientParams) => {
-  // 1. Optionally fetch this recipient's session — DO NOT receive `user`, only `token`.
-  //    The framework deliberately does not pre-resolve sessions per recipient because
-  //    most clients do not need them. Resolving N sessions for a 50-user room is wasteful.
-  const recipient = await functions.session.getSession(token);
-  if (!recipient) return { status: 'success' };  // anonymous viewer — leave as-is
-
-  // 2. Filter / brand / translate based on the recipient.
-  if (recipient.role === 'guest' && serverOutput.privateNotes) {
-    return { status: 'success', visibleNotes: null };  // strip the private field
-  }
-
-  // 3. Return a `clientOutput` envelope. Same status rules as _server.
-  return { status: 'success', visibleNotes: serverOutput.privateNotes };
-};
-```
-
-Key rules:
-
-- **No `user` param.** Receives `token` instead. Call `functions.session.getSession(token)` only when you actually need the session — most `_client` files don't.
-- **Cannot validate or reject the request.** Validation already happened in `_server`. `_client` only customizes per-recipient output. Its error path emits `sync.clientExecutionFailed` / `sync.invalidClientResponse` / `sync.clientRejected` to that specific recipient, but does NOT abort the fanout to the others.
-- **No `broadcastStream` / `streamTo`.** A per-recipient handler cannot fanout to other recipients — that contract is server-scope only.
-
----
-
-## 4. When to create `_client_v{N}.ts`
-
-| Goal | Need `_client`? | Why |
-|---|---|---|
-| Mutate state, tell the room what changed | No | `serverOutput` reaches every recipient unchanged. |
-| Hide a field from non-owner viewers | Yes | Per-recipient filter. |
-| Brand the payload (translate strings, swap CDN host, inject feature flags) | Yes | Per-recipient customization. |
-| Per-recipient auth (e.g. "guests get a redacted version") | Yes | Use `token` -> `getSession` -> branch. |
-| Per-recipient stream (different chunks per viewer) | Yes | Only `_client` has the per-target `stream(...)` primitive. |
-| Just return `{ status: 'success' }` | **No — delete the file** | Pure overhead: framework already emits success with `clientOutput: {}` when `_client` is absent. |
-
-### The "empty client" anti-pattern
-
-```ts
-// BAD — adds avoidable per-recipient await + tryCatch + emit overhead for every socket in the room.
-export const main = async () => ({ status: 'success' });
-```
-
-If the file would only return `{ status: 'success' }`, leave it out. The framework's no-client branch emits:
-
-```ts
-{
-  cb,
-  fullName: resolvedName,
-  serverOutput,
-  clientOutput: {},
-  message: `${resolvedName} sync success`,
-  status: 'success',
-}
-```
-
-…directly to each recipient with zero per-recipient handler invocation. That path is materially cheaper, especially when `receiver: 'all'`.
-
-Rule of thumb: a `_client` file exists **only** when it makes a decision the server cannot make once.
-
----
-
-## 5. Full lifecycle of `handleSyncRequest`
-
-```
-incoming msg (Socket.io 'sync' event)
-        |
-        v
- 1. validate msg shape  -> sync.invalidRequest
- 2. parseTransportRouteName(name)  -> routing.invalidServiceRouteName
- 3. validate cb         -> sync.invalidCallback
- 4. validate receiver   -> sync.missingReceiver
- 5. getSession(token)   -> propagate identity to registered error trackers
- 6. getRuntimeSyncMaps()
-    no _server AND no _client  -> sync.notFound
-        |
-        v
- 7. If _server exists:
-        AuthProps gate (auth.login)        -> auth.required
-        validateRequest(auth.additional)   -> auth.forbidden
- 8. dispatchHook('preSyncAuthorize')       -> stop signal becomes error envelope
- 9. applySyncRateLimits()                  -> sync.rateLimitExceeded
-10. Resolve recipients (cross-instance, both transports, BEFORE anything is persisted — see ./room-fanout.md §1):
-        receiver === 'all'  -> every socket on every instance (fetchSockets())
-        otherwise           -> formatRoomName(receiver, 'broadcast') -> io.in(room).fetchSockets()
-        fetchSockets throws -> sync.serverExecutionFailed (adapter request timeout; nothing persisted)
-        empty list          -> sync.noReceiversFound (nothing persisted)
-11. If _server exists:
-        validateInputByType(clientInput)   -> sync.invalidInputType
-        tryCatch(serverMain(...))          -> sync.serverExecutionFailed
-        status !== 'success' | 'error'     -> sync.invalidServerResponse
-        status === 'error'                 -> server's errorCode (normalized)
-        status === 'success'               -> serverOutput = result (minus status)
-12. dispatchHook('preSyncFanout')          -> stop signal becomes error envelope
-13. Per-recipient loop (with periodic event-loop yield):
-        if (ignoreSelf && token === recipientToken) continue
-        recipientCount++
-        if (_client exists):
-            tryCatch(clientHandler(...))   -> sync.clientExecutionFailed to that recipient
-            status='error'                 -> normalized error to that recipient
-            status='success'               -> emit { serverOutput, clientOutput, ... }
-        else:
-            emit { serverOutput, clientOutput: {}, ... }
-14. dispatchHook('postSyncFanout', { recipientCount })
-15. ack originator: emit(buildSyncResponseEventName(responseIndex), { status, result: serverOutput })
-```
-
-Per-recipient failures inside step 13 do **not** abort the fanout — every other recipient still receives the merged payload. The originator's ack always reflects the `_server` outcome, never the per-recipient outcomes.
-
----
-
-## 6. Failure-mode matrix
-
-| Stage | Trigger | Error code | Visibility |
-|---|---|---|---|
-| Msg shape | Non-object `msg` | `sync.invalidRequest` | originator ack |
-| Routing | Bad `name` shape | `routing.invalidServiceRouteName` | originator ack |
-| Routing | No `cb` | `sync.invalidCallback` | originator ack |
-| Routing | No receiver | `sync.missingReceiver` | originator ack |
-| Route lookup | No `_server` AND no `_client` | `sync.notFound` | originator ack |
-| Auth | `auth.login` + no session | `auth.required` | originator ack |
-| Auth | `validateRequest` reject | `auth.forbidden` (or specific predicate code) | originator ack |
-| Auth | `preSyncAuthorize` stop | hook's `errorCode` | originator ack |
-| Rate limit | Per-route or per-IP bucket | `sync.rateLimitExceeded` | originator ack |
-| Validation | Zod fail | `sync.invalidInputType` | originator ack |
-| Server execution | Thrown | `sync.serverExecutionFailed` | originator ack |
-| Server return | `status: 'error'` from `_server` | route-supplied `errorCode` | originator ack |
-| Server return | Anything other than `success`/`error` | `sync.invalidServerResponse` | originator ack |
-| Recipients (before `_server`) | No sockets in room | `sync.noReceiversFound` | originator ack |
-| Recipients (before `_server`) | `fetchSockets()` threw (adapter request timeout) | `sync.serverExecutionFailed` | originator ack |
-| Fanout | `preSyncFanout` stop | hook's `errorCode` | originator ack |
-| Per-recipient | `_client` thrown | `sync.clientExecutionFailed` | that recipient only |
-| Per-recipient | `_client` returned `status: 'error'` | route code or `sync.clientRejected` | that recipient only |
-| Per-recipient | `_client` returned non-success | `sync.invalidClientResponse` | that recipient only |
-
-Full catalog including HTTP-status mapping in [`./error-states.md`](./error-states.md).
-
----
-
-## 7. Example A — server-only sync (no `_client`)
-
-```ts
-// src/notifications/_sync/markRead_server_v1.ts
-export const auth = { login: true };
-
-export interface SyncParams {
-  clientInput: { notificationId: string };
-  user: SessionLayout;
-  functions: Functions;
-  roomCode: string;
-}
-
-export const main = async ({ clientInput, user, functions }: SyncParams) => {
-  await functions.db.notification.update({
-    where: { id: clientInput.notificationId, userId: user.id },
-    data: { readAt: new Date() },
-  });
-  return { status: 'success', notificationId: clientInput.notificationId };
-};
-```
-
-No `_client` file. Every recipient in `roomCode` receives `{ serverOutput: { notificationId }, clientOutput: {} }`.
-
----
-
-## 8. Example B — server + client per-recipient filter
-
-```ts
-// src/board/_sync/showCard_server_v1.ts
-export const auth = { login: true };
-
-export const main = async ({ clientInput, functions }: SyncParams) => {
-  const card = await functions.db.card.findUnique({ where: { id: clientInput.cardId } });
-  if (!card) return { status: 'error', errorCode: 'board.cardNotFound' };
-  return { status: 'success', card };
-};
-```
-
-```ts
-// src/board/_sync/showCard_client_v1.ts — strip privateNotes from non-owners
-export const main = async ({ token, serverOutput, functions }: SyncClientParams) => {
-  const recipient = await functions.session.getSession(token);
-  if (!recipient) return { status: 'success', card: { ...serverOutput.card, privateNotes: null } };
-
-  if (recipient.id !== serverOutput.card.ownerId) {
-    return { status: 'success', card: { ...serverOutput.card, privateNotes: null } };
-  }
-  return { status: 'success', card: serverOutput.card };
-};
-```
-
-Recipients see:
-
-- Owner: `{ serverOutput, clientOutput: { card: { privateNotes: '...' } } }`
-- Anyone else: `{ serverOutput, clientOutput: { card: { privateNotes: null } } }`
-
-Note: `serverOutput` is the same payload for every recipient — only `clientOutput` differs. The client-side handler chooses which to render.
-
----
-
-## 9. Example C — server + client custom `clientOutput` (translation)
-
-```ts
-// src/chat/_sync/announce_server_v1.ts
-export const main = async ({ clientInput }: SyncParams) => ({
-  status: 'success',
-  i18nKey: clientInput.i18nKey,
-  params: clientInput.params,
-});
-```
-
-```ts
-// src/chat/_sync/announce_client_v1.ts — pre-translate per recipient locale
-export const main = async ({ token, serverOutput, functions }: SyncClientParams) => {
-  const recipient = await functions.session.getSession(token);
-  const locale = recipient?.language ?? 'en';
-  const text = functions.translator.translate({ key: serverOutput.i18nKey, params: serverOutput.params, locale });
-  return { status: 'success', text };
-};
-```
-
-This is the canonical reason to add `_client`: the translation cost is per-locale, the source key is shared, and centralizing it in `_client` keeps the room mutation single-source.
-
----
-
-## 10. Related hooks
-
-| Hook | Stage | Stop semantics |
-|---|---|---|
-| `preSyncAuthorize` | After `AuthProps` gate, before rate-limit | Stop -> originator error envelope with hook's `errorCode` |
-| `preSyncFanout` | After `_server` runs, before any recipient receives | Stop -> originator error envelope; nobody gets the payload |
-| `postSyncFanout` | After all recipients emitted | Observation-only; receives `recipientCount` |
-| `rateLimitExceeded` | When per-route or per-IP bucket rejects | Observation-only |
-| `preSyncStream` / `postSyncStream` | Per stream chunk emit | Observation-only |
-
-Hook payload shapes live in `@luckystack/core` (`HookPayloads`).
-
----
-
-## 11. Related
-
-- Originator API: [`./sync-request.md`](./sync-request.md)
-- Streaming primitives: [`./streaming.md`](./streaming.md)
-- Room mechanics + fanout hooks: [`./room-fanout.md`](./room-fanout.md)
-- Skip-self semantics: [`./ignore-self.md`](./ignore-self.md)
-- Recipient subscription: [`./callback-registration.md`](./callback-registration.md)
-- Version coexistence: [`./version-policy.md`](./version-policy.md)
-- Full architecture: [`/docs/ARCHITECTURE_SYNC.md`](../../../docs/ARCHITECTURE_SYNC.md)
-- Routing conventions: [`/docs/ARCHITECTURE_ROUTING.md`](../../../docs/ARCHITECTURE_ROUTING.md)
+See `./room-fanout.md` for room trust and `./streaming.md` for stream audiences. Route declarations and generated types own signatures.