@luckystack/sync 0.10.1 → 0.11.0

package/docs/error-states.md

@@ -1,258 +1,18 @@
-# error-states
+# Sync 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 registered error-tracker capture behavior.
+A request failure, a local connection failure and a single recipient's failure are different outcomes. The originator acknowledgement reports server-handler success or failure, not the result of each recipient's filter; one rejected recipient must not prevent delivery to authorized peers. See `../src/handleSyncRequest.ts`, `../src/handleHttpSyncRequest.ts`, `../src/_shared/clientFanout.ts`.
 
-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).
+Localize recipient errors using that recipient's locale, not the sender's. Do not expose raw exceptions or sensitive tokens in errors or logs. Offline queue overflow is a delivery failure, not a license to replay a mutation without rechecking authorization. For current envelopes and reason codes consult `../src/_shared/errorBuilders.ts` and `../src/syncRequest.ts`.
 
----
+## Which errors mean "nothing was saved"
 
-## 1. Error envelope shape
+Receiver policy and recipient resolution run before the `_server` handler on both transports (ADR 0063). A rejection at that point is a pre-commit rejection: nothing was persisted and a retry is safe. That covers a refused receiver (`sync.receiverNotAllowed`, `sync.notRoomMember`), an empty room (`sync.noReceiversFound`) and a failed cross-instance recipient lookup. The order exists because the framework cannot undo a handler's side effects; when the lookup ran after the handler, a caller was told `error` about a change that had been saved, retried, and applied it twice.
 
-Every sync error — whether produced client-side before sending or server-side at any stage — collapses to the same shape after `normalizeErrorResponse`:
+- `sync.noReceiversFound` means "not saved, nobody was listening" — not "saved, nobody was listening". UI written against the older reading is wrong.
+- An empty room is an error on every transport, including routed HTTP (ADR 0058). A silent success hid wrong room names, sockets that never re-joined after a reconnect and formatter mismatches; the error is the only runtime signal for that class of bug.
+- A recipient-lookup failure reuses `sync.serverExecutionFailed`, the same code a throwing handler produces. Only the lookup case is guaranteed pre-commit, so the code alone does not prove nothing was saved. A lookup that times out usually means an instance on the same adapter channel did not answer, for example an environment sharing another environment's Redis; see `../../../docs/ARCHITECTURE_MULTI_INSTANCE.md`.
+- `sync.notRoomMember` is tested from a different source per transport (ADR 0059). See `./room-fanout.md`.
 
-```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
-}
-```
+## Locale coverage
 
-`message` is **always** the localized string for `errorCode` (with `errorParams` interpolated). The framework itself ships no message catalog: the `sync.*` keys live in the scaffold's `src/_locales/*.json`, and `translate()` returns the raw key when a key is missing — so a code that is not in your locale files surfaces as `sync.someCode` in the UI rather than as a sentence. The canonical list of every `sync.*` code the framework can emit (both transports plus the server's HTTP sync route, e.g. `sync.disabled`, `sync.methodNotAllowed`, `sync.requestTimeout`) is exported as `SYNC_ERROR_CODES` (with the type `SyncErrorCode`) from both `@luckystack/sync` and `@luckystack/sync/client`. Write a parity test of your locale files against that array instead of retyping the tables below — the framework's own test keeps the scaffold locales in parity the same way. Project-defined codes use whatever the project 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.receiverNotAllowed` | `receiver: 'all'` requested while `sync.allowClientReceiverAll` is `false` | `403` | — |
-| `sync.notRoomMember` | `sync.requireRoomMembership` is on and the requester is not a member of `receiver` — socket: physical membership of the originating socket; HTTP: logical membership from the session's `roomCodes` (+ its own token-room); an anonymous HTTP caller fails closed. See `/docs/ARCHITECTURE_SYNC.md` → "Room membership is transport-specific" | `403` | — |
-| `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` | The cross-instance recipient list for `receiver` is empty. Both transports since 0.10.0 (the HTTP path used to answer `success` with zero recipients). Recipients are resolved BEFORE `_server` runs, so nothing has been persisted — a retry is safe | `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, plus the receiver-policy codes `sync.receiverNotAllowed` / `sync.notRoomMember` -> `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 `'ip'` (per-route bucket, identified by token or by IP)
-
-```ts
-{
-  scope: 'user' | 'ip',
-  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' — marks this a per-route bucket
-  userId: string | undefined,
-  ip: string | undefined, // set when anonymous (no token), else undefined
-}
-```
-
-`scope: 'user'` when the request carried a session token; `scope: 'ip'` when it was anonymous (the per-route bucket is then IP-keyed). The `route` field stays set in both cases to distinguish this per-route bucket from the global `:sync:all` IP bucket below (parity with the API handler).
-
-### 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. Error-tracker 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 -> a breadcrumb/event for the registered tracker(s): `{ handler: 'handleSyncRequest', sync: <route>, stage: 'server', userId, receiver, transport: 'socket' | 'http' }`.
-- `_client` thrown errors -> a breadcrumb/event for the registered tracker(s): `{ 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 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`; it fans out to the registered tracker(s).
-
----
-
-## 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` | Registered error-tracker capture |
-| Domain logic rejected | `<route-supplied errorCode>` | The `_server` or `_client` file's return path |
-| Receiver rejected before `_server` ran (403) | `sync.receiverNotAllowed`, `sync.notRoomMember` | `projectConfig.sync.allowClientReceiverAll` / `requireRoomMembership`; on `routed-http` membership is the session's `roomCodes`, not the socket — `/docs/ARCHITECTURE_SYNC.md` |
-| Empty room (both transports; before `_server` ran, nothing persisted) | `sync.noReceiversFound` | `receiver` argument; whether any socket actually (re)joined the room — [`./room-fanout.md`](./room-fanout.md) §8 |
-| Recipient lookup failed (both transports; before `_server` ran, nothing persisted) | `sync.serverExecutionFailed` | The Redis adapter's `fetchSockets()` timed out: an instance on the same adapter key + Redis did not answer — `/docs/ARCHITECTURE_MULTI_INSTANCE.md` pitfalls (shared Redis across environments) |
-| 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`
-- Canonical code list for locale parity tests: `SYNC_ERROR_CODES` / `SyncErrorCode` (`@luckystack/sync` and `@luckystack/sync/client`)
-- Locale extraction: `@luckystack/core` `extractLanguageFromHeader`, `normalizeErrorResponse`
-- Project config: `projectConfig.rateLimiting`, `projectConfig.offlineQueue`, `projectConfig.logging`
+The framework ships no message catalog. The `sync.*` keys live in the project's locale files, and a missing key appears in the UI as the raw code. The authoritative list of every `sync.*` code either transport can emit is `SYNC_ERROR_CODES` (`../src/_shared/errorCodes.ts`, exported from both the server and `/client` entries). Keep locale files complete with a parity test against that list rather than a hand-copied table.

package/docs/ignore-self.md

@@ -1,162 +1,5 @@
-# ignore-self
+# Ignoring the sender in fanout
 
-> `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.
+Optimistic interfaces have already applied their own change. Suppressing the echoed broadcast avoids needless re-rendering or flicker, but must not suppress the originator's direct acknowledgement: that response carries the server-authoritative result and lets the request complete. The sender can still be in the target room; ignore-self concerns the event audience, not authorization. Source: `../src/_shared/clientFanout.ts`, `../src/syncRequest.ts`.
 
-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)
+Multiple tabs or devices may share an identity, so distinguish originator socket from other recipients rather than interpreting this option as 'exclude this user from all delivery'. Stream audience rules are separate: see `./streaming.md`.