@luckystack/sync 0.10.2 → 0.11.0

package/docs/streaming.md

@@ -1,348 +1,5 @@
-# streaming
+# Sync streaming
 
-> Four stream primitives are wired into a sync `_server_v{N}.ts` handler — each picks a different audience and cost profile. `_client_v{N}.ts` adds a fifth, per-recipient, primitive. The `createStreamThrottle` helper coalesces tiny pieces (LLM tokens at 3–10 chars apiece) into bigger chunks so a 1000-token response sends ~30 socket messages instead of 1000.
+Streaming communicates progress, not a replacement for the final request result. An originator-targeted stream, a room broadcast and a selected-recipient stream have different audiences: do not substitute one for another, particularly for private data. Recipient-side streaming is an output concern, not permission to broadcast to other viewers. Source: `../src/_shared/streamEmitters.ts`, `../src/_shared/clientFanout.ts`.
 
-This doc covers the four primitives, the throttle, the recipient side, and the HTTP/SSE fallback.
-
-For the originator-side `onStream` callback see [`./sync-request.md`](./sync-request.md). For recipient stream subscription see [`./callback-registration.md`](./callback-registration.md).
-
----
-
-## 1. The four primitives — decision matrix
-
-```
-                            stream(payload)       Originator's socket only        cheapest
-                            broadcastStream(p)    Every socket in `roomCode`      medium
-_server_v{N}.ts param:      streamTo(tokens, p)   Selected session tokens         medium
-                            (broadcastStream + streamTo fan out across ALL instances via the Redis adapter)
-
-_client_v{N}.ts param:      stream(payload)       Per-recipient (one in the loop) cheapest per-target
-```
-
-### `stream(payload)` (server-only entry, originator-targeted)
-
-Unicast back to the requesting socket only via `socket.emit(buildSyncProgressEventName(responseIndex), payload)`. Cheapest path — no room lookup, no per-recipient iteration. The originator consumes these via `syncRequest({ onStream })`.
-
-Use for **per-user progress that nobody else cares about**: upload progress, search-result narrowing, "downloading models...".
-
-### `broadcastStream(payload)`
-
-Fanout to every socket in `roomCode`, **across all server instances** — always `io.to(roomCode).emit(...)`, which the Socket.io Redis adapter fans out cluster-wide. It does NOT inspect the local room size: the per-process room view only sees sockets on the current instance, so degrading to a per-socket unicast would silently drop members connected to other instances (see the multi-instance note below).
-
-Use for **the entire room sees the same stream**: live AI chat tokens to a group, collab-editor diffs, multiplayer game ticks. Recipients consume via `upsertSyncEventStreamCallback`.
-
-### `streamTo(tokens, payload)`
-
-Selective fanout. `tokens` is one or many session tokens. Every socket joins a room named after its session token at connect time, so `io.to(tokens).emit(...)` reaches every device of every targeted user.
-
-Use for **explicit subscribers**: "stream this only to the admin viewers", "send the heart-rate ticker only to the patient's care team", "user X just asked for a private side-stream from this same sync request".
-
-### `_client_v{N}.ts` `stream(payload)` (per-recipient)
-
-Inside the per-recipient loop of `handleSyncRequest`, each `_client` invocation receives a `stream` callback that emits ONLY to that one recipient. This runs **after** `_server` finishes and after the fanout loop has reached that recipient — chunks emitted here arrive at that recipient after the main `{ serverOutput, clientOutput, ... status: 'success' }` frame from `_server`, ordered.
-
-Use for **per-recipient customization that needs to stream**: "send each viewer their own translated tokens", "throttle per-recipient based on their connection quality".
-
----
-
-## 2. `createStreamThrottle({ flushEveryMs?, flushAtChars?, field? })`
-
-Coalesces small pieces into bigger ones. Designed for LLM token streams where the provider yields 3–10 characters at a time and emitting one socket message per token is wasteful.
-
-```ts
-import { createStreamThrottle } from '@luckystack/sync';
-
-const throttle = createStreamThrottle({
-  flushEveryMs: 50,     // flush at most every 50ms (false = no timer flush)
-  flushAtChars: 32,     // flush once buffered text crosses 32 chars
-  field: 'chunk',       // payload key carrying the buffered text (default 'chunk')
-});
-
-for await (const piece of openaiStream) {
-  throttle.push(piece.text, broadcastStream);
-}
-throttle.flush(broadcastStream);  // emit whatever is left after the loop ends
-```
-
-### Options
-
-| Option | Default | Effect |
-|---|---|---|
-| `flushAtChars` | `32` (from `projectConfig.sync.streamThrottle.flushAtChars`) | Flush once `buffer.length >= flushAtChars`. Lower = more frequent emits = smoother UI but more network traffic. Higher = fewer emits but chunkier UI. |
-| `flushEveryMs` | `50` (from config) | Timer-based flush — wakes up after Nms and emits whatever is buffered. Set to `false` to disable the timer (only flush at char threshold or explicit `flush()`). |
-| `field` | `'chunk'` (from config) | Payload key carrying the buffered text. Override when your stream payload uses a different key (e.g. `'text'`, `'delta'`). |
-
-### Returned handle
-
-```ts
-interface StreamThrottle {
-  push(text: string, emit: (payload: Record<string, unknown>) => void): void;
-  flush(emit: (payload: Record<string, unknown>) => void): void;
-  reset(): void;  // discard buffered text without emitting — for aborts
-}
-```
-
-The `emit` argument is the stream callback of your choice — `stream`, `broadcastStream`, or a partial of `streamTo`. The throttle stays agnostic of audience, which is why you pass `emit` per call instead of binding it at construction time. That lets a single throttle drive different audiences across `push` calls if you ever need it (rare).
-
-### Why the timer is `.unref()`'d
-
-When a `flushEveryMs` timer is scheduled, the throttle calls `timer.unref()` so a pending flush does not keep the Node.js event loop alive. This prevents short scripts and tests from hanging on a 50ms timer after the main work resolves.
-
-### `reset()` for aborts
-
-When the upstream LLM stream aborts (client disconnected mid-generation, generation error), call `throttle.reset()` to drop the buffered text without emitting. Forgetting to call `reset()` or `flush()` leaks the pending timer until it fires (and then emits a no-op). It's safe but noisy in logs.
-
----
-
-## 3. End-to-end LLM token example
-
-```ts
-// src/chat/_sync/sendMessage_server_v1.ts
-import { createStreamThrottle } from '@luckystack/sync';
-import type { SessionLayout, Functions } from '@luckystack/core';
-
-export const auth = { login: true };
-
-export interface SyncParams {
-  clientInput: { prompt: string };
-  user: SessionLayout;
-  functions: Functions;
-  roomCode: string;
-  broadcastStream: (payload?: Record<string, unknown>) => void;
-}
-
-export const main = async ({ clientInput, user, functions, roomCode, broadcastStream }: SyncParams) => {
-  const throttle = createStreamThrottle({ flushEveryMs: 50, flushAtChars: 32 });
-  let full = '';
-
-  // 1. Mark message as in-progress for the room (so other clients show a typing indicator).
-  broadcastStream({ status: 'started', author: user.id });
-
-  // 2. Stream LLM tokens through the throttle.
-  const [error, _] = await functions.tryCatch(async () => {
-    for await (const piece of yourLlmStream(clientInput.prompt)) {
-      full += piece.text;
-      throttle.push(piece.text, broadcastStream);
-    }
-    throttle.flush(broadcastStream);
-  });
-
-  if (error) {
-    throttle.reset();
-    return { status: 'error', errorCode: 'chat.llmFailed' };
-  }
-
-  // 3. Persist the final message and emit a `done` marker.
-  const message = await functions.db.message.create({ data: { authorId: user.id, body: full, roomId: roomCode } });
-  broadcastStream({ status: 'done', messageId: message.id });
-
-  return { status: 'success', messageId: message.id };
-};
-```
-
-Recipients in `roomCode` see (in order):
-
-1. `{ status: 'stream', cb, fullName, status: 'started', author }`
-2. `{ status: 'stream', cb, fullName, chunk: '<32+ chars>' }` × N
-3. `{ status: 'stream', cb, fullName, status: 'done', messageId }`
-4. `{ status: 'success', serverOutput: { messageId }, clientOutput: {}, ... }`
-
-The `status` field on the wire frame is always literal `'stream'` for chunks (set by `buildBroadcastFrame` in `streamEmitters.ts`); the inner `status: 'started' | 'done'` you set on the payload is a domain-level marker carried alongside `cb` and `fullName`.
-
----
-
-## 4. Recipient side — consuming stream chunks
-
-Two consumer surfaces on the client:
-
-### A. `upsertSyncEventStreamCallback({ name, version, callback })`
-
-The room-wide subscriber. Receives every chunk fanned out via `broadcastStream` and every chunk targeted at this socket via `streamTo`. Also receives per-recipient chunks emitted by `_client.stream(payload)`.
-
-```ts
-import { useSyncEvents } from '@luckystack/sync/client';
-
-const { upsertSyncEventStreamCallback } = useSyncEvents();
-
-useEffect(() => {
-  return upsertSyncEventStreamCallback({
-    name: 'chat/sendMessage',
-    version: 'v1',
-    callback: ({ stream }) => {
-      if ('chunk' in stream) appendToken(stream.chunk);
-      else if (stream.status === 'done') commitMessage(stream.messageId);
-    },
-  });
-}, []);
-```
-
-The callback's `stream` parameter is typed via `SyncRouteStreamCallbackForFullName<F, V>` — TS folds together `serverStream` (from `broadcastStream` / `streamTo`) AND `clientStream` (from `_client.stream`) into a single discriminated union. If neither side ever streams, the callback type collapses to `never` and registration is a compile error.
-
-### B. `syncRequest({ onStream })`
-
-The originator-only listener. Subscribes to `buildSyncProgressEventName(responseIndex)` for the duration of one request. Receives ONLY chunks emitted via `stream(payload)` from `_server` (originator-targeted unicast).
-
-```ts
-await syncRequest({
-  name: 'upload/processImage',
-  version: 'v1',
-  data: { fileId },
-  receiver: tokenOfSelf,
-  onStream: ({ percent }) => setProgress(percent),
-});
-```
-
-Crucially, **`onStream` does NOT receive `broadcastStream` / `streamTo` chunks** — those go through `upsertSyncEventStreamCallback`. Use `onStream` for progress and partial results that are only relevant to the sender; use `upsertSyncEventStreamCallback` for everything else.
-
----
-
-## 5. HTTP / SSE fallback
-
-When a client uses the HTTP transport (`handleHttpSyncRequest`), the originator's `stream` callback is wired by `@luckystack/server` to a Server-Sent-Events writer. Each emit becomes one SSE event.
-
-```ts
-// On the server side, hooking up the SSE writer (illustrative — already done by @luckystack/server):
-await handleHttpSyncRequest({
-  name: 'chat/sendMessage/v1',
-  data: req.body,
-  receiver: roomId,
-  token: extractToken(req),
-  requesterIp: req.socket.remoteAddress,
-  xLanguageHeader: req.headers['x-language'],
-  acceptLanguageHeader: req.headers['accept-language'],
-  stream: (payload) => {
-    res.write(`event: stream\ndata: ${JSON.stringify(payload)}\n\n`);
-  },
-});
-```
-
-Public type:
-
-```ts
-export type HttpSyncStreamEvent = Record<string, unknown>;
-```
-
-Important: `broadcastStream` and `streamTo` chunks still flow over **Socket.io** even when the originator uses HTTP — recipients live on sockets regardless of how the request entered the server. Only the originator's `stream(payload)` chunks travel via SSE.
-
----
-
-## 6. Performance notes
-
-### `broadcastStream` is always a cross-instance room emit
-
-```ts
-io.to(receiver).emit(socketEventNames.sync, frame);
-```
-
-`broadcastStream` does NOT inspect local room membership. A previous "if room size <= 1, unicast to the lone socket" optimization was removed: the per-process room view only sees sockets on the LOCAL instance, so in a multi-instance cluster it dropped members connected to other instances. `io.to(room).emit(...)` lets the Redis adapter resolve the real recipients cluster-wide; `streamTo` uses the same `io.to(tokens).emit(...)` path.
-
-### Stream-hook fire-and-forget
-
-`preSyncStream` and `postSyncStream` hooks dispatch via `void dispatchHook(...)` — chunks never `await` the hook. Hook errors are swallowed by the hook dispatcher's own `tryCatch`. This matters because a slow error-tracker breadcrumb (for example) must not delay chunk delivery to the user.
-
-### Chunk-index counter
-
-`postSyncStream` includes `chunkIndex` (1-based) so observers can correlate chunks within a single fanout. The counter is keyed by `(routeName, recipient)` and lives in-memory; it grows for the lifetime of the process but is bounded by the route × recipient cardinality (typically tens of thousands at most).
-
-### Throttle math
-
-For a 1000-token LLM response (~4000 chars), at `flushAtChars: 32` you emit ~125 messages instead of 1000 — an **8× reduction** with no perceptible UI lag. At `flushAtChars: 64` you get ~62 messages, but punctuation/whitespace can cause perceived stuttering. 32 is a good default.
-
----
-
-## 7. Types reference
-
-| Type | Where | Purpose |
-|---|---|---|
-| `CreateStreamThrottleOptions` | `@luckystack/sync` | Throttle constructor options. |
-| `StreamThrottle` | `@luckystack/sync` | The handle returned by `createStreamThrottle`. |
-| `HttpSyncStreamEvent` | `@luckystack/sync` | SSE event shape (alias of `Record<string, unknown>`). |
-| `SyncRequestStreamEvent<T>` | `@luckystack/sync/client` | Payload shape passed to `onStream` (originator). |
-| `SyncRouteStreamEvent<T>` | `@luckystack/sync/client` | Payload shape passed to `upsertSyncEventStreamCallback`. |
-| `StreamPayload` | `@luckystack/core` | Base constraint — `Record<string, unknown>`-compatible. |
-
----
-
-## 8. Cancellation (`abortSignal`) and backpressure (`flushPressure`)
-
-Both helpers are injected into every `_server_v{N}.ts` handler alongside `stream` / `broadcastStream` / `streamTo`. Older handlers that do not destructure them still work — destructuring an extra key from a JS function param is a no-op, so the change is fully backwards compatible.
-
-### `abortSignal: AbortSignal`
-
-Aborts when **either** the originating client emits `syncCancel` (e.g. consumer wrote `syncRequest({ ..., signal })` and called `controller.abort()`) **or** the originator's socket disconnects.
-
-Effects:
-
-- Every emit through the framework's `stream` / `broadcastStream` / `streamTo` callbacks is short-circuited automatically once the signal aborts. Already-on-the-wire chunks are not unsent — there's no way to do that in Socket.io — but no new chunks will be queued.
-- `flushPressure()` resolves immediately when the signal is aborted.
-- The handler itself should check `abortSignal.aborted` inside long-running loops (LLM generation, DB cursor walks, file streaming) and break out — only the *emit* gate is wired automatically; the handler's own CPU work keeps going until you read the flag.
-
-```ts
-export const main = async ({ broadcastStream, abortSignal, flushPressure }: SyncParams) => {
-  for await (const piece of yourLlmStream(prompt)) {
-    if (abortSignal.aborted) break;        // bail on client cancel
-    broadcastStream({ chunk: piece.text });
-  }
-  return { status: 'success' };
-};
-```
-
-On the client side:
-
-```ts
-const controller = new AbortController();
-const promise = syncRequest({
-  name: 'chat/sendMessage',
-  version: 'v1',
-  data: { prompt: '...' },
-  receiver: roomCode,
-  signal: controller.signal,    // ← optional opt-in
-});
-
-// later — user clicked Stop:
-controller.abort();
-// `promise` resolves with { status: 'error', errorCode: 'request.aborted' }.
-```
-
-Same opt-in surface exists for `apiRequest({ signal })`.
-
-### `flushPressure({ thresholdBytes? })`
-
-Awaitable. Resolves when the worst-case Socket.io write buffer across the sockets you're streaming to drops below the threshold (default `1 MB`). Use it between large batches of small chunks so the Node.js write buffer doesn't balloon.
-
-```ts
-export const main = async ({ broadcastStream, flushPressure, abortSignal }: SyncParams) => {
-  let i = 0;
-  for await (const piece of yourLlmStream(prompt)) {
-    if (abortSignal.aborted) break;
-    broadcastStream({ chunk: piece.text });
-    i++;
-    //? Every 64 chunks, pause if the room is backed up. 1 MB default.
-    //? Pass `thresholdBytes` to tighten or loosen the watermark.
-    if (i % 64 === 0) await flushPressure();
-  }
-  return { status: 'success' };
-};
-
-// Tuning the threshold:
-await flushPressure({ thresholdBytes: 256 * 1024 });   // pause if >= 256 KB pending
-```
-
-Notes:
-
-- For `broadcastStream` / `streamTo`, `flushPressure` samples up to the first **32** sockets in the affected room and waits on the worst-case writer. Rooms larger than 32 trade fairness for O(1) cost.
-- For originator-only `stream(payload)`, `flushPressure` polls the originator socket's engine.io write buffer. HTTP/SSE transport has no equivalent — `flushPressure` is a no-op on HTTP, since SSE backpressure is the caller's responsibility (Node's `res.write` returns `false` when full).
-- Polling interval is ~10 ms; no busy-loop, no `drain` event (engine.io doesn't expose one in the public Socket.io API).
-- Resolves immediately if `abortSignal` is aborted.
-
-The same `flushPressure({ thresholdBytes? })` is also injected into `_api/<name>_v{N}.ts` handler params. There it always measures the originator socket only.
-
----
-
-## 9. Related
-
-- Originator API + `onStream`: [`./sync-request.md`](./sync-request.md)
-- Recipient subscription: [`./callback-registration.md`](./callback-registration.md)
-- Handler authoring (where streams come from): [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md)
-- Full architecture: [`/docs/ARCHITECTURE_SYNC.md`](../../../docs/ARCHITECTURE_SYNC.md#streaming)
-- Throttle config: `projectConfig.sync.streamThrottle.*`
+Delivery must tolerate slow connections without blocking unrelated requests; producer throttling and pressure handling protect memory and responsiveness. Stream hooks are observational so slow tracking cannot stall chunks; abort/reset must not flush stale partial content into a later request. The HTTP/SSE fallback needs the same auth/receiver checks even though it has a different originator transport. See `../src/streamThrottle.ts`, `../src/handleHttpSyncRequest.ts`.

package/docs/sync-request.md

@@ -1,284 +1,5 @@
-# sync-request
+# Sync request
 
-> Type-safe fire-and-broadcast call from the browser into a Socket.io room. Resolves with the server result envelope after the originator's ack lands; recipients receive the merged `{ serverOutput, clientOutput }` payload via `upsertSyncEventCallback`. The HTTP/SSE fallback (`handleHttpSyncRequest`) keeps the same pipeline alive when websockets are blocked.
+The caller asks the server to apply a mutation and selects a receiver; the receiver name is not proof of permission. The request must pass authorization before mutation and fanout on both socket and HTTP/SSE transports. A successful acknowledgement reports the server result; it does not guarantee every recipient accepted the event. See `../src/syncRequest.ts`, `../src/handleSyncRequest.ts`, `../src/handleHttpSyncRequest.ts`, `./server-vs-client-handlers.md`.
 
-Documents the **caller-facing transport API**: how `syncRequest` is invoked, the response envelope, and the rare HTTP-fallback path. For handler authoring see [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md); for callback subscription see [`./callback-registration.md`](./callback-registration.md).
-
----
-
-## 1. Function signature
-
-```ts
-import { syncRequest } from '@luckystack/sync/client';
-
-await syncRequest({
-  name,             // typed string literal — see `SyncFullName`
-  version,          // typed string literal — see `VersionsForFullName<name>`
-  data,             // typed via generated `SyncTypeMap` — required iff non-empty
-  receiver,         // room code, or 'all' (NOT recommended in production)
-  ignoreSelf,       // optional, default false
-  onStream,         // optional originator-side stream callback
-  offlineDropPolicy // optional per-request offline-queue policy
-});
-```
-
-The signature is a type-driven discriminated union — under the hood `SyncParamsForFullName<F, V>` branches on `DataRequired<ClientInput>`:
-
-- If the route's `clientInput` type allows `{}`, `data` is optional.
-- If the route's `clientInput` carries any required key (or is a union without `{}`), `data` is required at compile time.
-
-This is enforced through generated `SyncTypeMap` entries — no runtime check fills it in.
-
----
-
-## 2. Argument breakdown
-
-### `name: F extends SyncFullName`
-
-`SyncFullName` is the union of every discovered sync route, computed from `SyncTypeMap`:
-
-- `src/{page}/_sync/{name}_server_v{N}.ts` -> `'{page}/{name}'`
-- `src/_sync/{name}_server_v{N}.ts` (root-level) -> `'system/{name}'`
-
-Always pass the literal string. Any narrowing layer (`as any`, `as SyncFullName`, manual cast helpers) breaks inference and **violates rule 21** in the repository-root `CLAUDE.md` (no `unknown`/`any` casts on typed transports).
-
-### `version: V extends VersionsForFullName<F>`
-
-String-literal version key (`'v1'`, `'v2'`, ...). One version per source file. See [`./version-policy.md`](./version-policy.md) for the deprecation flow when you need to ship a `v2` while `v1` consumers still exist.
-
-### `data: ClientInputForFullName<F, V>`
-
-Whatever `clientInput` your `_server_v{N}.ts` declares. Goes through Zod validation server-side via `validateInputByType` against the schema generated by `@luckystack/devkit`.
-
-Validation lifecycle (server side):
-
-1. Empty / non-object payload -> `sync.invalidRequest`.
-2. Schema generated but payload fails -> `sync.invalidInputType` with `errorParams: [{ key: 'message', value: <readable reason> }]`.
-3. Route has no `inputType` (Zod schema not generated yet) -> validation skipped, dev-only warn-log fires on first miss.
-
-### `receiver: string`
-
-Identifies the fanout target.
-
-- A **room code** (e.g. `'Ag2cg4'`, `'board-123'`, the session token of a specific user). Sockets join rooms via `joinRoom` / `leaveRoom` from `@luckystack/core` (client).
-- The literal `'all'` -> every connected socket on the current instance. Avoid in production: every `getRuntimeSyncMaps()` lookup runs once but the per-recipient loop runs O(N). The framework yields to the event loop every `sync.fanoutYieldEvery` recipients to avoid starving other requests, but burning N sockets per write is still a smell.
-- Empty / non-string -> `sync.missingReceiver`.
-
-Every socket auto-joins a room named after its own session token at connect time. That is how `streamTo(token, ...)` reaches a specific user across all of their devices.
-
-### `ignoreSelf?: boolean` (default `false`)
-
-Skip the originator's own sockets during fanout. See [`./ignore-self.md`](./ignore-self.md) — short version: turn it on when the sender already applied the optimistic change locally and only needs other clients to be told.
-
-### `onStream?: SyncRequestStreamCallback`
-
-Originator-side stream listener. Subscribes to the `buildSyncProgressEventName(responseIndex)` channel for the lifetime of this single request, then unsubscribes the moment the final ack lands. Receives **only originator-targeted** chunks emitted via `stream(payload)` from the `_server` handler (not `broadcastStream` / `streamTo` — those flow through the normal `upsertSyncEventStreamCallback` registry).
-
-Typed via `SyncRequestStreamEvent<ServerStream>` — if the route never streams to the originator, the callback type collapses to `never` and the TS compiler will reject the call site.
-
-### `offlineDropPolicy?: 'reject' | 'drop-oldest' | 'drop-newest'`
-
-Per-request override of `projectConfig.offlineQueue.dropPolicy`. When the socket is offline (disconnected or browser is offline), `syncRequest` does **not** reject — it queues the request in `enqueueSyncRequest` and replays on reconnect. If the queue is full:
-
-- `'reject'` (default) — the request resolves with `errorCode: 'offline.queueFull'`.
-- `'drop-oldest'` — the oldest queued request is evicted; this one joins the queue.
-- `'drop-newest'` — this request is dropped at the door; the queue stays intact.
-
-Per-request override exists so a noisy ephemeral event (`'editor cursor move'`) can pick `'drop-oldest'` while the global default stays `'reject'` for safer mutations.
-
----
-
-## 3. Response envelope
-
-`syncRequest` always resolves (never rejects). The promise type is `SyncRequestResponseForFullName<F, V>`:
-
-```ts
-type SyncRequestResponseForFullName<F, V> =
-  | { status: 'error'; message: string; errorCode: string; errorParams?: SyncErrorParam[]; httpStatus?: number }
-  | { status: 'success'; message: string; result: ServerOutputForFullName<F, V> };
-```
-
-### Success branch
-
-```ts
-{
-  status: 'success',
-  message: string,           // server-provided or `sync ${name} success`
-  result: ServerOutput       // exactly what _server_v{N}.ts returned, minus its `status` field
-}
-```
-
-`result` is typed via `ServerOutputForFullName<F, V>` -> the same shape `_server_v{N}.ts`'s `main(...)` declared. **Never** narrow this with `as any` / `as unknown`; if inference fails the generated type map is wrong (regenerate via `npm run ai:index`).
-
-### Error branch
-
-```ts
-{
-  status: 'error',
-  message: string,           // localized via normalizeErrorResponse
-  errorCode: string,         // see error-states.md for the full catalog
-  errorParams?: [{ key, value }],  // i18n interpolation slots
-  httpStatus?: number        // 401/403/429/500 typically
-}
-```
-
-Localization runs through `normalizeErrorResponse({ response, preferredLocale, userLanguage })` server-side, then again client-side through `normalizeErrorResponseCore`. Order of preference for the locale: `x-language` header -> `accept-language` header -> `user.language` from session.
-
-Full catalog of `errorCode` values in [`./error-states.md`](./error-states.md).
-
----
-
-## 4. Lifecycle (originator side)
-
-```
-syncRequest({ name, version, data, receiver, ... })
-        |
-        v
-1. Validate arguments locally:
-   - name        -> sync.invalidName / routing.invalidServiceRouteName
-   - version     -> sync.invalidVersion
-   - receiver    -> sync.missingReceiver
-2. waitForSocket() — ensures the socket has booted
-   - times out  -> sync.ioUnavailable
-3. canSendNow(socket):
-   - false (offline / disconnected) -> enqueueSyncRequest({...})
-     - queue full + dropPolicy='reject' -> offline.queueFull
-     - otherwise: queued, replays on `connect`
-4. responseIndex = incrementResponseIndex()
-5. Subscribe to buildSyncProgressEventName(responseIndex) if onStream
-6. socket.emit('sync', { name, data, cb, receiver, responseIndex, ignoreSelf })
-7. socket.once(buildSyncResponseEventName(responseIndex)):
-   - status: 'error'   -> normalizeSyncError -> resolve(errorEnvelope)
-   - status: 'success' -> resolve({ status: 'success', message, result })
-   - other             -> sync.invalidServerResponse
-```
-
-The progress listener cleans itself up in the response handler. Even if the request errors out, `onStream` is unsubscribed before the promise resolves.
-
----
-
-## 5. Concrete examples
-
-### A. Mutation broadcast (the 90% case)
-
-```ts
-const response = await syncRequest({
-  name: 'board/moveCard',
-  version: 'v1',
-  data: { cardId, toLane },
-  receiver: roomCode,
-  ignoreSelf: true,   // we already moved it optimistically
-});
-
-if (response.status !== 'success') {
-  notify.error({ key: response.errorCode });
-  return;
-}
-// `response.result` is typed as ServerOutput for board/moveCard v1
-```
-
-### B. Optimistic send with offline tolerance
-
-```ts
-// Cursor moves are spammy and disposable — drop oldest if offline queue fills up.
-await syncRequest({
-  name: 'editor/cursorMove',
-  version: 'v1',
-  data: { x, y },
-  receiver: documentId,
-  offlineDropPolicy: 'drop-oldest',
-});
-```
-
-### C. Stream consumer (originator)
-
-```ts
-let buffer = '';
-const response = await syncRequest({
-  name: 'chat/sendMessage',
-  version: 'v1',
-  data: { prompt },
-  receiver: chatRoomId,
-  onStream: ({ chunk }) => {
-    buffer += chunk;
-    setPreview(buffer);
-  },
-});
-
-if (response.status === 'success') {
-  commitMessage(response.result.messageId, buffer);
-}
-```
-
-For broadcast streams (where everyone in the room — including the sender — sees the chunks) prefer `upsertSyncEventStreamCallback` instead of `onStream`. See [`./streaming.md`](./streaming.md).
-
----
-
-## 6. HTTP / SSE fallback (`handleHttpSyncRequest`)
-
-When the Socket.io transport is unavailable (corporate firewalls, mobile carriers blocking websockets), `@luckystack/server` exposes a POST endpoint that calls `handleHttpSyncRequest` directly. The pipeline is identical to the socket variant except for:
-
-| Stage | Socket transport | HTTP transport |
-|---|---|---|
-| Originator chunks (`stream(payload)`) | `socket.emit(progressEventName, payload)` | `stream?.(payload)` injected callback → SSE writer |
-| Recipients (`broadcastStream`, `streamTo`) | Socket.io fanout | Socket.io fanout (recipients still on sockets) |
-| Auto-instrumented error-tracker span | none | `'sync.request.http'` |
-| Final ack | `socket.emit(buildSyncResponseEventName(responseIndex), envelope)` | HTTP response body (`HttpSyncResponse`) |
-
-Signature:
-
-```ts
-async function handleHttpSyncRequest({
-  name: string;             // 'sync/<page>/<name>/v<N>' or '<page>/<name>/v<N>'
-  cb?: string;              // callback handle used in recipient emits
-  data: Record<string, unknown>;
-  receiver: string;
-  ignoreSelf?: boolean;
-  token: string | null;
-  requesterIp?: string;     // for IP rate-limit bucket
-  xLanguageHeader?: string | string[];
-  acceptLanguageHeader?: string | string[];
-  stream?: (payload: HttpSyncStreamEvent) => void;
-}): Promise<HttpSyncResponse>
-```
-
-`HttpSyncStreamEvent` is an alias of `SyncStreamPayload` (`Record<string, unknown>`). The server side typically wires `stream` to a Server-Sent-Events writer that flushes each chunk as `event: stream\ndata: <json>\n\n`.
-
-The client side ships with no built-in SSE adapter — `syncRequest` always uses Socket.io. Adding an HTTP-fallback client is a project-level decision; the server side already supports it.
-
----
-
-## 7. Interaction with the offline queue
-
-Queue identity:
-
-- Each queued request gets a `queueId = ${Date.now()}-${Math.random()}` on first queue (not on retries).
-- The queue key is the full sync route name (`sync/<page>/<name>/v<N>`) for ordering and (optionally) coalescing in `enqueueSyncRequest`.
-- The `run` closure captures the original arguments — when the socket reconnects, the queued call replays through the same `runRequest(socket)` body that originally enqueued it.
-
-Replay order is FIFO unless `dropPolicy` mutates the queue. A successful replay resolves the original `syncRequest` promise; the caller's `await` simply takes longer.
-
-Failures during replay surface the same way as if the call had run online — the promise resolves with `status: 'error'`, the caller branches on `errorCode`.
-
----
-
-## 8. Types reference
-
-| Type | Purpose | Exported from |
-|---|---|---|
-| `SyncRequestStreamEvent<T>` | Payload shape passed to `onStream` (originator side) | `@luckystack/sync/client` |
-| `SyncRouteStreamEvent<T>` | Payload shape passed to `upsertSyncEventStreamCallback` (any recipient) | `@luckystack/sync/client` |
-| `HttpSyncStreamEvent` | SSE event shape emitted by the HTTP fallback | `@luckystack/sync` |
-| `StreamThrottle` / `CreateStreamThrottleOptions` | Throttle handle + options | `@luckystack/sync` |
-
----
-
-## 9. Related
-
-- Handler authoring: [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md)
-- Stream primitives: [`./streaming.md`](./streaming.md)
-- Subscribing to results: [`./callback-registration.md`](./callback-registration.md)
-- Error catalog: [`./error-states.md`](./error-states.md)
-- Versioning: [`./version-policy.md`](./version-policy.md)
-- Offline queue config: `@luckystack/core` `OfflineQueueConfig` (`projectConfig.offlineQueue`)
-- Architecture deep-dive: [`/docs/ARCHITECTURE_SYNC.md`](../../../docs/ARCHITECTURE_SYNC.md)
+Offline queuing is for transient transport loss, not a bypass of server validation or room membership on replay. Regenerate generated types rather than casting a call around a version mismatch. For request types, envelopes and retry policy consult `../src/syncRequest.ts` and `../../core/src/offlineQueue.ts`.