@luckystack/sync 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.4] - 2026-08-17
+
+### Changed
+
+- Corrected dependency, generated-typing, error-tracker, and transport-span documentation, including the current root no-cast rule and HTTP-only automatic sync request span.
+
 ## [0.8.1] - 2026-07-27
 
 ### Fixed

package/CLAUDE.md

@@ -106,11 +106,12 @@ None directly. Inherits socket transport config from `@luckystack/server` and Re
 ## Peer dependencies
 
 - **Required**: `@luckystack/core`, `@luckystack/error-tracking`. **`@luckystack/login` is NOT a dependency** (0.2.0 decoupling) — sessions resolve through core's `readSession` / session-provider registry (`handleSyncRequest` imports `readSession` from `@luckystack/core`), with login as the default *provider* (optional package), not a hard runtime dep.
-- **Peer (canonical ranges, 2026-05-07)**:
-  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
-  - `react@^19.2.0` (only the `/client` subpath)
+- **Required peers**:
   - `socket.io@^4.8.0` (server entry)
   - `socket.io-client@^4.8.0` (client entry)
+- **Optional peers**:
+  - `@prisma/client@^6.19.0` (only for the default Prisma-backed session/user provider)
+  - `react@^19.2.0` (only the `/client` subpath)
 - Redis adapter (required for cross-instance fanout) wired by `@luckystack/server`; see `/docs/ARCHITECTURE_SOCKET.md`.
 
 ## Related

package/README.md

@@ -5,7 +5,8 @@
 ## Install
 
 ```bash
-npm install @luckystack/sync @luckystack/core @luckystack/login @luckystack/error-tracking react socket.io socket.io-client
+npm install @luckystack/sync socket.io socket.io-client
+# Optional React client helpers: npm install react
 ```
 
 ## Quickstart
@@ -143,12 +144,9 @@ Client entry (`@luckystack/sync/client`):
 
 ## Dependencies
 
-- Runtime: `@luckystack/core`, `@luckystack/login`, `@luckystack/error-tracking`
-- Peer (canonical ranges, standardized 2026-05-07):
-  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
-  - `react@^19.2.0` (`/client` entry only)
-  - `socket.io@^4.8.0`
-  - `socket.io-client@^4.8.0`
+- Runtime: `@luckystack/core`, `@luckystack/error-tracking` (`@luckystack/login` is an optional session provider, not a runtime dependency)
+- Required peers: `socket.io@^4.8.0`, `socket.io-client@^4.8.0`
+- Optional peers: `@prisma/client@^6.19.0` (only for the default Prisma-backed session/user provider), `react@^19.2.0` (`/client` entry only).
 
 ## License
 

package/docs/callback-registration.md

@@ -66,7 +66,7 @@ upsertSyncEventCallback<F, V>(params: {
 }): () => void  // returns unsubscribe function
 ```
 
-### Typed payloads (rule 16, no casts)
+### Typed payloads (root contract rule 21, no casts)
 
 Both `clientOutput` and `serverOutput` are typed via the generated `SyncTypeMap`. The framework's discriminated unions surface every possible status:
 
@@ -83,7 +83,7 @@ upsertSyncEventCallback({
 });
 ```
 
-Never cast these to `unknown` or `any` (root `CLAUDE.md` rule 16). If inference fails, regenerate the type map (`npm run ai:index`) — that's the source of truth.
+Never cast these to `unknown` or `any` (root `CLAUDE.md` rule 21). If inference fails, run `npm run generateArtifacts`; if generated output is wrong, fix the generator rather than casting around it.
 
 ### Validation rules
 
@@ -199,7 +199,7 @@ Idempotent: if `initSyncRequest` is called again later, the previous handlers ar
 
 ## 6. Why callbacks must never cast `serverOutput` / `clientOutput`
 
-Rule 16 in the repo root `CLAUDE.md`: generated types are mandatory; no `unknown` / `any` casts on typed transports.
+Rule 21 in the repository-root `CLAUDE.md`: generated types are mandatory; no `unknown` / `any` casts on typed transports.
 
 Both `upsertSyncEventCallback` and `upsertSyncEventStreamCallback` give you fully typed payloads via the generated `SyncTypeMap`. The framework's discriminated unions handle the status branching cleanly:
 
@@ -253,5 +253,5 @@ When inference fails:
 - Originator API: [`./sync-request.md`](./sync-request.md)
 - Stream payload shapes: [`./streaming.md`](./streaming.md)
 - Server / client handler contracts (what produces the payloads): [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md)
-- Type-generation contract (rule 16): repo root [`.claude/CLAUDE.md`](../../../.claude/CLAUDE.md)
+- Type-generation contract (rule 21): repository-root [`CLAUDE.md`](../../../CLAUDE.md)
 - `SocketStatusProvider` wiring: `src/_providers/SocketStatusProvider.tsx` (installer side)

package/docs/error-states.md

@@ -1,6 +1,6 @@
 # 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.
+> 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.
 
 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).
 
@@ -167,14 +167,14 @@ Recipients (per-recipient errors during fanout) use **their own** headers, not t
 
 ---
 
-## 9. Sentry capture via `tryCatch`
+## 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 -> 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 }`.
+- `_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):
 
@@ -183,7 +183,7 @@ NOT captured (returned as `status: 'error'` envelopes only):
 - 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`.
+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).
 
 ---
 
@@ -235,7 +235,7 @@ These are dev hints, not production behavior. Toggle both to `false` for product
 | 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 |
+| Handler threw | `sync.serverExecutionFailed` / `sync.clientExecutionFailed` | Registered error-tracker capture |
 | 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` |

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

@@ -56,7 +56,7 @@ Key rules:
 - **Streaming primitives are received as params.** See [`./streaming.md`](./streaming.md) for the audience matrix.
 - **Optional `export const validation`** toggles runtime input validation, exactly like the API handler. `'strict'` (default, or omit the export) validates `clientInput` against the generated Zod schema; `'relaxed'` or `{ input: 'skip' }` skips validation entirely — use it for routes whose payload shape can't be modelled in TypeScript (third-party webhook fan-in, dynamic blobs). Honored identically by both the Socket.io and HTTP/SSE transports.
 - **Optional `export const errorFormatter`** overrides the error envelope for this route only (falls back to the global `registerErrorFormatter`, then the framework default). Both transports honor it.
-- **Never `try/catch` manually.** Wrap async ops in `functions.tryCatch` (or the destructured `tryCatch` from `functions`) — the framework already wraps the whole `main()` in its own `tryCatch` for Sentry capture, but per-operation `tryCatch` lets you surface targeted error codes.
+- **Never `try/catch` manually.** Wrap async ops in `functions.tryCatch` (or the destructured `tryCatch` from `functions`) — the framework already wraps the whole `main()` in its own `tryCatch` for registered error-tracker capture, but per-operation `tryCatch` lets you surface targeted error codes.
 
 ---
 
@@ -146,7 +146,7 @@ incoming msg (Socket.io 'sync' event)
  2. parseTransportRouteName(name)  -> routing.invalidServiceRouteName
  3. validate cb         -> sync.invalidCallback
  4. validate receiver   -> sync.missingReceiver
- 5. getSession(token)   -> setSentryUser(...)
+ 5. getSession(token)   -> propagate identity to registered error trackers
  6. getRuntimeSyncMaps()
     no _server AND no _client  -> sync.notFound
         |

package/docs/streaming.md

@@ -238,7 +238,7 @@ io.to(receiver).emit(socketEventNames.sync, frame);
 
 ### 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 Sentry breadcrumb (for example) must not delay chunk delivery to the user.
+`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
 

package/docs/sync-request.md

@@ -40,7 +40,7 @@ This is enforced through generated `SyncTypeMap` entries — no runtime check fi
 - `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).
+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>`
 
@@ -222,7 +222,7 @@ When the Socket.io transport is unavailable (corporate firewalls, mobile carrier
 |---|---|---|
 | 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'` |
+| Auto-instrumented error-tracker span | none | `'sync.request.http'` |
 | Final ack | `socket.emit(buildSyncResponseEventName(responseIndex), envelope)` | HTTP response body (`HttpSyncResponse`) |
 
 Signature:

package/docs/version-policy.md

@@ -331,7 +331,7 @@ Allowed by the framework (it just maps `v3` to its own entry), but confusing for
 await syncRequest({ name: 'board/moveCard' as any, version: someString as any, ... });
 ```
 
-This violates rule 16 (no `as any` / `as unknown` on typed transports). If you don't know the version statically, the design needs to change — versions are an authoring-time decision, not a runtime one.
+This violates repository contract rule 21 (no `as any` / `as unknown` on typed transports). If you don't know the version statically, the design needs to change — versions are an authoring-time decision, not a runtime one.
 
 ---
 
@@ -359,4 +359,4 @@ This violates rule 16 (no `as any` / `as unknown` on typed transports). If you d
 - Recipient subscription: [`./callback-registration.md`](./callback-registration.md)
 - Error contract (including `sync.invalidInputType` from regenerated Zod schemas): [`./error-states.md`](./error-states.md)
 - Type-map regeneration: `npm run ai:index` (`@luckystack/devkit`)
-- Sync type contract: rule 16 in repo root [`.claude/CLAUDE.md`](../../../.claude/CLAUDE.md)
+- Sync type contract: rule 21 in repository-root [`CLAUDE.md`](../../../CLAUDE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckystack/sync",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -60,8 +60,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@luckystack/core": "^0.8.2",
-    "@luckystack/error-tracking": "^0.8.2"
+    "@luckystack/core": "^0.8.4",
+    "@luckystack/error-tracking": "^0.8.4"
   },
   "peerDependencies": {
     "@prisma/client": "^6.19.0",