@luckystack/sync 0.1.0

package/docs/error-states.md

@@ -0,0 +1,252 @@
+# error-states
+
+> Authoritative catalog of error codes emitted by `syncRequest` (client) and `handleSyncRequest` / `handleHttpSyncRequest` (server). Documents HTTP-status mapping, locale-aware message normalization, `errorParams` interpolation slots, the `rateLimitExceeded` hook payload, and Sentry capture behavior.
+
+For the originator response envelope shape see [`./sync-request.md`](./sync-request.md). For the full lifecycle these errors slot into see [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md).
+
+---
+
+## 1. Error envelope shape
+
+Every sync error — whether produced client-side before sending or server-side at any stage — collapses to the same shape after `normalizeErrorResponse`:
+
+```ts
+{
+  status: 'error',
+  message: string,                 // localized via preferredLocale / userLanguage
+  errorCode: string,               // see catalog below
+  errorParams?: { key, value }[],  // i18n interpolation slots
+  httpStatus?: number,             // inferred via defaultHttpStatusForResponse
+}
+```
+
+`message` is **always** the localized string for `errorCode` (with `errorParams` interpolated). The default i18n catalog ships built-in keys for every framework code; project-defined codes use whatever the project i18n catalog defines.
+
+---
+
+## 2. Client-side error codes
+
+Produced by `syncRequest` BEFORE the message ever hits the wire.
+
+| `errorCode` | Trigger | `httpStatus` (default) | `errorParams` |
+|---|---|---|---|
+| `sync.invalidName` | `name` is missing or not a string | n/a (local) | — |
+| `routing.invalidServiceRouteName` | `name` doesn't match `<page>/<route>` shape | n/a (local) | `[{ key: 'name', value: <input name> }]` |
+| `sync.invalidVersion` | `version` is missing or not a string | n/a (local) | — |
+| `sync.missingReceiver` | `receiver` is missing or empty after trim | n/a (local) | — |
+| `sync.ioUnavailable` | Socket never initialized or `waitForSocket()` timed out | n/a (local) | — |
+| `offline.queueFull` | Socket offline + queue full + `dropPolicy: 'reject'` | n/a (local) | — |
+| `sync.failedRequest` | Catch-all fallback for malformed ack (used in dev notification) | n/a (local) | `[{ key: 'name', ...}, { key: 'message', ...}]` |
+| `sync.invalidServerResponse` | Server ack missing `status: 'success'` and no recognized error code | inherited from server response (if any) | — |
+
+Local errors never travel over the wire — they short-circuit inside `syncRequest`'s promise body and resolve immediately with the error envelope. `httpStatus` doesn't apply (there was no HTTP).
+
+---
+
+## 3. Server-side error codes (originator-visible)
+
+Emitted by `handleSyncRequest` / `handleHttpSyncRequest` to the originator's ack channel (`buildSyncResponseEventName(responseIndex)` for socket, HTTP response body for HTTP).
+
+| `errorCode` | Trigger | `httpStatus` | `errorParams` |
+|---|---|---|---|
+| `sync.invalidRequest` | `msg` is not an object, or `name`/`data` missing or wrong type | `400` | — |
+| `routing.invalidServiceRouteName` | `parseTransportRouteName` failed | `400` | `[{ key: 'name', value: <input name> }]` |
+| `sync.invalidCallback` | `cb` is missing or not a string | `400` | — |
+| `sync.missingReceiver` | `receiver` is empty after trim | `400` | — |
+| `sync.notFound` | Neither `_server_v{N}` nor `_client_v{N}` exists for this route | `404` | — |
+| `auth.required` | `auth.login === true` on `_server` and no session resolved | `401` | — |
+| `auth.forbidden` (or route-specific code from `validateRequest`) | `validateRequest(auth.additional)` rejected | `403` (default; some predicates override) | predicate-defined |
+| `sync.rateLimitExceeded` | Per-route or per-IP rate-limit bucket rejected | `429` | `[{ key: 'seconds', value: <retry in> }]` |
+| `sync.invalidInputType` | `validateInputByType` rejected (Zod schema mismatch) | `400` | `[{ key: 'message', value: <readable reason> }]` |
+| `sync.serverExecutionFailed` | `_server`'s `main(...)` threw (caught by `tryCatch`) | `500` | — |
+| `<route-supplied>` (e.g. `board.cardNotFound`) | `_server` returned `{ status: 'error', errorCode }` | `defaultHttpStatusForResponse` or as-provided | as-provided |
+| `sync.invalidServerResponse` | `_server` returned a value with `status` other than `'success'` / `'error'` | `500` | — |
+| `sync.noReceiversFound` | Resolved sockets is `undefined` or empty | `404` | — |
+| `<hook-supplied>` | `preSyncAuthorize` / `preSyncFanout` stop signal | from hook | from hook |
+
+The `preSyncAuthorize` and `preSyncFanout` hooks can stop with any `errorCode` they choose; the framework normalizes the message via `normalizeErrorResponse` using the originator's locale.
+
+---
+
+## 4. Server-side error codes (per-recipient, fanout step)
+
+Emitted to a **single recipient** when `_client_v{N}.ts` execution fails for them only. These do NOT propagate back to the originator and do NOT abort the fanout loop.
+
+| `errorCode` | Trigger | `httpStatus` | `errorParams` |
+|---|---|---|---|
+| `sync.clientExecutionFailed` | `_client`'s `main(...)` threw (caught by per-recipient `tryCatch`) | `500` | — |
+| `<route-supplied>` (e.g. `chat.translationFailed`) | `_client` returned `{ status: 'error', errorCode }` | as-provided | as-provided |
+| `sync.clientRejected` | `_client` returned `{ status: 'error' }` without an `errorCode` | `500` (default) | — |
+| `sync.invalidClientResponse` | `_client` returned something other than `'success'` / `'error'` | `500` | — |
+
+Recipients see these on their own `socketEventNames.sync` channel as if they were normal sync frames, just with `status: 'error'` set. Subscribers in `upsertSyncEventCallback` that branch on `status` will see the error variant.
+
+---
+
+## 5. HTTP-status mapping
+
+`httpStatus` defaults via `defaultHttpStatusForResponse(errorCode)` in `@luckystack/core`. Default rules (paraphrased — see core for exact source):
+
+- `auth.required` -> `401`
+- `auth.forbidden` and similar role/policy codes -> `403`
+- Validation failures (`*.invalidRequest`, `*.invalidInputType`, `*.invalidName`, `routing.invalidServiceRouteName`) -> `400`
+- Not-found (`*.notFound`, `sync.noReceiversFound`) -> `404`
+- Rate limit (`*.rateLimitExceeded`) -> `429`
+- Execution failures (`*.ExecutionFailed`, `*.invalid*Response`) -> `500`
+
+A hook or route can override the default by returning `httpStatus: <number>` in its stop signal or error payload. Custom codes inherit the fallback `500` unless `defaultHttpStatusForResponse` is extended in core.
+
+---
+
+## 6. `errorParams` localization slots
+
+`errorParams` is an array of `{ key, value }` pairs interpolated into the i18n message template. Framework codes use:
+
+- `sync.rateLimitExceeded` -> `[{ key: 'seconds', value: <number> }]` — the seconds until the next request is allowed. Template: "Rate limited, retry in {{seconds}}s".
+- `sync.invalidInputType` -> `[{ key: 'message', value: <Zod reason> }]` — the Zod error message. Template: "Input validation failed: {{message}}".
+- `sync.failedRequest` (dev notification) -> `[{ key: 'name', ...}, { key: 'message', ...}]`. Template: "Sync {{name}} failed: {{message}}".
+- `routing.invalidServiceRouteName` -> `[{ key: 'name', value: <bad input> }]`. Template: "Invalid service route name: {{name}}".
+
+Project codes can carry whatever slots their templates declare. The normalizer doesn't enforce a schema — it interpolates blindly.
+
+---
+
+## 7. `rateLimitExceeded` hook payload
+
+Fired whenever a rate-limit bucket rejects a sync request. The payload differs by `scope`:
+
+### Scope `'user'` or `'route'` (per-route bucket, identified by token or by IP)
+
+```ts
+{
+  scope: 'user' | 'route',
+  key: string,         // 'token:<token>:sync:<routeName>' or 'ip:<ip>:sync:<routeName>'
+  limit: number,       // projectConfig.rateLimiting.defaultApiLimit
+  windowMs: number,    // projectConfig.rateLimiting.windowMs
+  count: number,       // limit + 1 (the request that tipped over)
+  route: string,       // e.g. 'board/moveCard/v1'
+  userId: string | undefined,
+}
+```
+
+`scope: 'user'` when the request carried a session token; `scope: 'route'` when it was anonymous (only an IP).
+
+### Scope `'ip'` (global per-IP bucket, across all sync routes)
+
+```ts
+{
+  scope: 'ip',
+  key: string,         // 'ip:<ip>:sync:all'
+  limit: number,       // projectConfig.rateLimiting.defaultIpLimit
+  windowMs: number,
+  count: number,
+  ip: string,
+}
+```
+
+The hook is observation-only — there is no stop signal. The fanout has already been aborted by the time the hook fires.
+
+Typical consumer: a mitigation system that bans the offending IP / user after N hook fires within a window.
+
+---
+
+## 8. Locale resolution
+
+Both transports localize error messages through the same chain:
+
+1. **`preferredLocale`** — first non-empty match from headers:
+   - Socket: `socket.handshake.headers['x-language']` -> `socket.handshake.headers['accept-language']`.
+   - HTTP: `xLanguageHeader` argument -> `acceptLanguageHeader` argument.
+2. **`userLanguage`** — `user.language` from the resolved session.
+3. **Fallback** — `projectConfig.defaultLanguage`.
+
+`extractLanguageFromHeader` accepts either a string or `string[]` (Node's headers can be either), trims whitespace, and picks the first listed language. The chain doesn't combine locales — first non-empty wins.
+
+Recipients (per-recipient errors during fanout) use **their own** headers, not the sender's. That's why `handleSyncRequest`'s per-recipient error path re-extracts `tempSocket.handshake.headers` for each recipient.
+
+---
+
+## 9. Sentry capture via `tryCatch`
+
+Every `_server` and `_client` execution is wrapped in `tryCatch(..., undefined, { handler, sync, stage, userId, ... })`. The fourth argument is the breadcrumb context that gets attached when `tryCatch` captures an exception.
+
+Captured automatically:
+
+- `_server` thrown errors -> Sentry breadcrumb: `{ handler: 'handleSyncRequest', sync: <route>, stage: 'server', userId, receiver, transport: 'socket' | 'http' }`.
+- `_client` thrown errors -> Sentry breadcrumb: `{ handler: 'handleSyncRequest', sync: <route>, stage: 'client', sourceUserId, targetToken, receiver, transport }`.
+
+NOT captured (returned as `status: 'error'` envelopes only):
+
+- Validation failures (`sync.invalidInputType`) — these are caller errors, not server bugs.
+- Auth rejects — these are policy outcomes.
+- Rate-limit rejects — these are noise.
+- `_server` / `_client` returning `{ status: 'error' }` voluntarily — the handler made a domain decision; nothing threw.
+
+If you need to also Sentry-capture a voluntary error (e.g. "this code path should never trigger in production"), do it explicitly inside the handler via `@luckystack/error-tracking`'s `captureException`.
+
+---
+
+## 10. Offline queue overflow flow
+
+When the socket is offline AND `dropPolicy: 'reject'` is active:
+
+```
+syncRequest({ ..., offlineDropPolicy: 'reject' })
+  -> canSendNow(socket) === false
+  -> enqueueSyncRequest({ id, key, run, createdAt, dropPolicy: 'reject' })
+  -> queue full
+  -> enqueueSyncRequest returns false
+  -> resolve({
+       status: 'error',
+       errorCode: 'offline.queueFull',
+       message: <localized>,
+       httpStatus: undefined,
+     })
+```
+
+With `dropPolicy: 'drop-oldest'` or `'drop-newest'`, the queue policy handles eviction silently and the caller's promise stays pending until the network comes back (then resolves on replay).
+
+`offline.queueFull` is the only error code that fires when there is no server interaction at all — it's purely a client-side admission of "we cannot promise to deliver this if we accept it".
+
+---
+
+## 11. Dev-only side effects
+
+When `projectConfig.logging.devLogs === true`:
+
+- Local validation failures (`sync.invalidName`, `sync.missingReceiver`, etc.) log via `getLogger().error(...)`.
+- Server returning `{ status: 'error' }` logs the normalized message at `getLogger().error(...)`.
+- Auth rejects, validation rejects, etc., warn-log at `getLogger().warn(...)`.
+
+When `projectConfig.logging.devNotifications === true` AND on the client:
+
+- Most local validation failures call `notify.error({ key: '<errorCode>' })`.
+
+These are dev hints, not production behavior. Toggle both to `false` for production to avoid leaking diagnostic info into user-facing notifications.
+
+---
+
+## 12. Quick lookup by symptom
+
+| Symptom | Most likely code | Where to look |
+|---|---|---|
+| `syncRequest` returns immediately with error | `sync.missingReceiver`, `sync.invalidVersion`, `sync.ioUnavailable` | Client-side validation, §2 |
+| Request reached server but auth rejected | `auth.required`, `auth.forbidden` | `_server`'s `auth` export, [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md) |
+| 429 rate-limit responses | `sync.rateLimitExceeded` | `projectConfig.rateLimiting` |
+| Server-side schema fail | `sync.invalidInputType` | `_server`'s `SyncParams.clientInput` interface + generated Zod schema |
+| Handler threw | `sync.serverExecutionFailed` / `sync.clientExecutionFailed` | Sentry breadcrumb |
+| Domain logic rejected | `<route-supplied errorCode>` | The `_server` or `_client` file's return path |
+| Empty room | `sync.noReceiversFound` | `receiver` argument; check room membership |
+| Offline + caller didn't await | `offline.queueFull` | Bump `offlineQueue.maxSize` or switch `dropPolicy` |
+
+---
+
+## 13. Related
+
+- Originator response envelope: [`./sync-request.md`](./sync-request.md)
+- Pipeline / lifecycle: [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md)
+- Rate limiting hook + buckets: [`./room-fanout.md`](./room-fanout.md) §5
+- Hook payload shapes: `@luckystack/core` `HookPayloads`
+- Status-code mapping source: `@luckystack/core` `defaultHttpStatusForResponse`
+- Locale extraction: `@luckystack/core` `extractLanguageFromHeader`, `normalizeErrorResponse`
+- Project config: `projectConfig.rateLimiting`, `projectConfig.offlineQueue`, `projectConfig.logging`

package/docs/ignore-self.md

@@ -0,0 +1,162 @@
+# ignore-self
+
+> `ignoreSelf: true` on `syncRequest` tells `handleSyncRequest` to skip every recipient socket whose session token matches the sender's. The check is **token-based, not socket-id-based** — multi-tab users skip ALL of their own tabs. The originator's ack response still arrives.
+
+For the full `syncRequest` signature see [`./sync-request.md`](./sync-request.md). For the fanout loop's surrounding mechanics see [`./room-fanout.md`](./room-fanout.md).
+
+---
+
+## 1. What the flag actually does
+
+The originator passes `ignoreSelf: true`. Inside the per-recipient loop:
+
+```ts
+const tempToken = extractTokenFromSocket(tempSocket);
+
+if (ignoreSelf && typeof ignoreSelf === 'boolean' && token === tempToken) {
+  continue;
+}
+
+recipientCount++;
+```
+
+`token` is the sender's session token (resolved from their socket at the top of `handleSyncRequest`). `tempToken` is the recipient's session token (extracted from THAT socket via `extractTokenFromSocket`).
+
+When the two match:
+
+- That recipient is **not** emitted to.
+- That recipient does **not** count toward `recipientCount` (so `postSyncFanout` sees a number that reflects actual sends).
+- The fanout loop continues immediately to the next socket.
+
+The originator still receives:
+
+- The normal ack via `buildSyncResponseEventName(responseIndex)` (the success/error envelope with `serverOutput`).
+- Any chunks emitted via the originator-targeted `stream(payload)` (those flow on the originator's unicast progress channel, not the broadcast room).
+
+What the originator does NOT receive when `ignoreSelf: true`:
+
+- The room frame (the `{ serverOutput, clientOutput, ... status: 'success' }` payload that `upsertSyncEventCallback` consumes).
+- `broadcastStream` and `streamTo` chunks targeted at their own token room.
+
+---
+
+## 2. When to use `ignoreSelf: true`
+
+The canonical case: **optimistic UI**. The sender already applied the local change before calling `syncRequest`, so receiving the broadcast back just causes a no-op re-render (and risks visual flicker if the local optimistic state and the broadcast payload differ subtly).
+
+```ts
+// Local update (optimistic):
+setCards(prev => moveCardLocally(prev, cardId, toLane));
+
+// Tell everyone else:
+await syncRequest({
+  name: 'board/moveCard',
+  version: 'v1',
+  data: { cardId, toLane },
+  receiver: roomCode,
+  ignoreSelf: true,
+});
+```
+
+Other use cases:
+
+- **Drift-tolerant counters / cursor positions / typing indicators** — the sender's state is authoritative locally; rebroadcasting to them is pure waste.
+- **Chat message sends** — the sender already rendered "you said …" in the input box; the broadcast is for everyone else.
+- **Acknowledgment-pattern sends** — the sender awaits the ack to know it persisted; they don't need a separate "your message arrived" frame.
+
+---
+
+## 3. When to leave `ignoreSelf: false` (or omit it)
+
+Default to `false` (or just don't set it) when **the sender needs to receive the server's authoritative version** to reconcile their optimistic guess.
+
+- **Server-assigned IDs** — the optimistic version had a temp UUID, the broadcast payload has the real DB primary key. The sender needs to listen.
+- **Server-computed derived fields** — timestamps (`createdAt`), running totals (`balance`), search scores, anything the client could not have known.
+- **Cross-validation refresh** — the sender wants to confirm "yes, my mutation actually landed in the shape I expected" via the broadcast.
+- **Recipients are different users** — when the sender is NOT a member of the room they're sending to (e.g. an admin pushing an announcement), `ignoreSelf` is irrelevant. Leave it false.
+
+If you're unsure, leave it `false`. Receiving an extra broadcast frame is cheap; **missing one is expensive** because you can't easily detect the absence.
+
+---
+
+## 4. Edge case: multiple sockets per user (tabs, devices)
+
+`ignoreSelf` compares **session tokens**, not socket IDs. If a user has 3 tabs open:
+
+- Tab A initiates `syncRequest({ ignoreSelf: true })`.
+- Tabs A, B, and C are all in the room (they all auto-joined the `<sessionToken>` room AND any shared room they're members of).
+- All three tabs share the same session token.
+
+Result: **all three tabs skip the broadcast**, not just Tab A.
+
+This is usually what you want — when you optimistically update a piece of state in any one tab, the framework's `SessionProvider` typically broadcasts the change to all tabs of the same user via the per-token room separately. But it's worth being aware of: `ignoreSelf` is a per-user filter, not a per-socket filter.
+
+If you ever genuinely want "skip Tab A but notify Tabs B and C", you have to model that explicitly — either with separate logical session tokens per tab (atypical) or by leaving `ignoreSelf: false` and de-duplicating client-side.
+
+---
+
+## 5. Interaction with `recipientCount`
+
+`recipientCount` is what `postSyncFanout` reports. Skipped recipients (whether via `ignoreSelf` or because the socket disappeared mid-fanout) are NOT counted.
+
+Sample timeline:
+
+- Room has 5 sockets, 3 of which belong to the sender's session token.
+- `syncRequest({ ignoreSelf: true })` from one of the sender's sockets.
+- Fanout skips all 3 of the sender's sockets.
+- `recipientCount === 2`.
+- `postSyncFanout` payload: `{ ..., recipientCount: 2 }`.
+
+This makes metrics observe "actual sends", not "room size" — useful for "how many viewers did this update actually reach".
+
+---
+
+## 6. Interaction with streaming
+
+`broadcastStream` and `streamTo` happen **inside** `_server`'s `main()`, BEFORE the fanout loop reaches the skip step. The skip is per-final-emit only.
+
+Implication: a `broadcastStream` call sends chunks to **every socket in the room INCLUDING the sender's own sockets**, regardless of whether the final ack-step fanout will skip them.
+
+If you need to exclude the sender from broadcast streaming too, use `streamTo` with an explicit list that excludes the sender's token:
+
+```ts
+// inside _server_v1.ts main()
+const others = (await functions.session.getRoomMembers(roomCode)).filter(t => t !== user.id);
+streamTo(others, { chunk: piece });
+```
+
+This isn't a common need — typically the sender genuinely does want to see their own LLM tokens stream because they initiated the conversation. But it's available.
+
+---
+
+## 7. Why the originator still gets the ack with `ignoreSelf: true`
+
+The ack response (`buildSyncResponseEventName(responseIndex)`) is the protocol-level "your request succeeded / failed" envelope. It is **never** a fanout payload — it's a direct unicast `socket.emit` to the originator's responseIndex channel, and it carries `serverOutput` so the originator can reconcile their optimistic state with the server's authoritative version.
+
+`ignoreSelf` only affects the **room fanout step**. The ack is wired through a separate channel that bypasses the fanout entirely.
+
+This is critical: the originator's `syncRequest` `await` would never resolve if `ignoreSelf` suppressed the ack. The split between "broadcast payload" and "originator ack" is what makes the optimistic-UI pattern usable.
+
+---
+
+## 8. Quick reference
+
+| Behavior with `ignoreSelf: true` |  |
+|---|---|
+| Sender's tabs skip the broadcast frame | yes |
+| Sender receives ack with `serverOutput` | yes |
+| Sender receives originator-targeted `stream(...)` chunks | yes |
+| Sender receives `broadcastStream(...)` chunks | **yes — broadcastStream runs in `_server` before skip** |
+| Sender receives `streamTo(...)` chunks (when token included) | **yes — same reason** |
+| Other tabs of same user skipped too | yes — token match, not socket-id match |
+| `recipientCount` counts skipped sockets | no |
+| Same flag works on HTTP transport | yes — `handleHttpSyncRequest` has the same skip block |
+
+---
+
+## 9. Related
+
+- Originator API: [`./sync-request.md`](./sync-request.md)
+- Fanout mechanics: [`./room-fanout.md`](./room-fanout.md)
+- Stream audience matrix: [`./streaming.md`](./streaming.md)
+- Server handler params (`user.id` vs sender's token): [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md)

package/docs/room-fanout.md

@@ -0,0 +1,233 @@
+# 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.
+
+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).
+
+---
+
+## 1. How `receiver` resolves to sockets
+
+`handleSyncRequest` branches on `receiver`:
+
+```ts
+const sockets = receiver === 'all'
+  ? ioInstance.sockets.sockets                          // Map<socketId, Socket>
+  : ioInstance.sockets.adapter.rooms.get(receiver);     // Set<socketId> | undefined
+```
+
+- `receiver === 'all'` -> every connected socket on **this instance** (production with Redis adapter: every socket on every instance, see §6).
+- Any other string -> the Socket.io room with that name. If the room does not exist or is empty, `sockets` is `undefined` and the fanout fails with `sync.noReceiversFound`.
+
+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
+    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.
+
+This loop only exists on the socket path (`handleSyncRequest`). The HTTP path (`handleHttpSyncRequest`) does not yield — HTTP requests are inherently isolated per Node.js handler invocation, and the per-instance fanout sits inside a single async block anyway.
+
+---
+
+## 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."
+
+### `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 `sockets.size` in three cases:
+
+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. **Sockets disappearing mid-fanout** — `ioInstance.sockets.sockets.get(socketId)` can return `undefined` between resolving the room set and emitting (the socket disconnected). Those iterations `continue` without bumping `recipientCount`.
+3. **HTTP transport** — the HTTP path's `_client` execution `continue`s without bumping `recipientCount` only for per-recipient failures it could not recover from; the socket path always bumps for handled (success or error) recipients and only skips disappeared sockets.
+
+This is why the hook payload exposes `recipientCount` instead of a raw room size — observers want the count that actually saw the payload.
+
+---
+
+## 7. Cross-instance fanout via Redis adapter
+
+Single-instance fanout is built into Socket.io. **Cross-instance fanout requires the Redis adapter.** Without it, a `broadcastStream` on instance A reaches sockets on instance A only; sockets on instance B (same room name, different Node process) get nothing.
+
+`@luckystack/server` wires the Redis adapter when `REDIS_URL` is set and the Socket.io Redis adapter peer is installed. With it:
+
+- `io.to(roomCode).emit(...)` reaches every socket in the room **across every instance**.
+- `ioInstance.sockets.adapter.rooms.get(roomCode)` still only sees the local instance's members — the Redis adapter handles the cross-instance fanout transparently at the emit layer.
+
+This means `handleSyncRequest`'s **per-recipient `_client` execution only runs against local sockets**. If you need a `_client` handler to execute on every recipient regardless of which instance they're connected to, either:
+
+1. Pin sticky sessions so a given room's sockets all land on the same instance (simplest), OR
+2. Wire your own cross-instance per-recipient runner (rare, advanced).
+
+For the common case (broadcast a single `serverOutput` to everyone in the room), the Redis adapter is sufficient. See [`/docs/ARCHITECTURE_SOCKET.md`](../../../docs/ARCHITECTURE_SOCKET.md) for the adapter setup.
+
+---
+
+## 8. `sync.noReceiversFound`
+
+Triggered when the resolved `sockets` is `undefined` or falsy:
+
+- 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.
+- `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. UI typically treats `sync.noReceiversFound` as "your mutation succeeded server-side (the `_server` already ran and persisted state); just nobody happened to be listening". `_server`'s mutations are NOT rolled back when there are zero recipients.
+
+---
+
+## 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`