@luckystack/sync 0.4.1 → 0.5.0

package/docs/sync-request.md

@@ -1,284 +1,284 @@
-# 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.
-
-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 16** in the 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) |
-| Sentry span | `'sync.request'` | `'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)
+# 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.
+
+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 16** in the 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) |
+| Sentry span | `'sync.request'` | `'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)