@luckystack/core 0.1.0

package/docs/hooks.md

@@ -0,0 +1,298 @@
+# Hooks
+
+> Deep specs for the async + sync hook registries, the canonical core-owned payload shapes, `processUpload`, and the response normalizer family. Source: `packages/core/src/hooks/`, `processUpload.ts`, `responseNormalizer.ts`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+LuckyStack ships two hook registries:
+
+- **Async hook registry** (`registerHook` / `dispatchHook`) — used by lifecycle events that can tolerate await (`preApiExecute`, `postApiRespond`, `corsRejected`, etc.). Handlers can return a `HookStopSignal` to abort the framework's main flow.
+- **Sync mutator registry** (`registerSyncHook` / `dispatchSyncHook`) — used by hot-path mutators that must remain synchronous (`preErrorNormalize`, `postErrorNormalize`). Handlers mutate the payload object in place; there is no stop signal.
+
+Both registries swallow handler exceptions: errors are routed to `getLogger().error` + `captureException` so a misbehaving handler can never crash the framework. Multiple handlers per hook are supported and invoked in registration order.
+
+Feature packages extend `HookPayloads` via TypeScript module augmentation. The augmentation file must be in a tsconfig `include` path AND side-effect imported from the package barrel (`import './hookPayloads';`) so TS merges the declarations.
+
+`processUpload` is included in this topic because it's the public API that ties the `onUploadStart` / `onUploadComplete` hook contract together for consumer upload routes.
+
+## Lifecycle flow (api request)
+
+```
+client emits apiRequest
+   ├─> preHttpRequest          (async — read-only meta)
+   ├─> preApiValidate          (async — can stop)
+   ├─> [framework validation]
+   ├─> postApiValidate         (async — read-only)
+   ├─> preApiExecute           (async — can stop)
+   ├─> [handler.main()]
+   ├─> postApiExecute          (async — read-only + durationMs)
+   ├─> preApiRespond           (async — mutate response in place)
+   ├─> transformApiResponse    (async — mutate response in place)
+   └─> postApiRespond          (async — read-only, after wire-send)
+
+On error:
+   ├─> preErrorNormalize       (sync mutator)
+   ├─> [responseNormalizer]
+   ├─> postErrorNormalize      (sync mutator)
+   └─> apiError                (async — observability)
+```
+
+The sync flow has its own analogues (`preSyncAuthorize`, `preSyncFanout`, `postSyncFanout`, `preSyncStream`, `postSyncStream`, `syncError`).
+
+## Types
+
+```typescript
+export interface HookSessionShape {
+  id: string;
+  token: string;
+  email?: string | null;
+  name?: string | null;
+  avatar?: string | null;
+  avatarFallback?: string | null;
+  admin?: boolean | null;
+  language?: string | null;
+  roomCodes?: string[];
+}
+
+export interface HookStopSignal {
+  stop: true;
+  errorCode: string;
+  httpStatus?: number;
+}
+
+export type HookResult = undefined | HookStopSignal;
+export type HookHandler<TPayload> = (payload: TPayload) => Promise<HookResult> | HookResult;
+export type SyncHookHandler<TPayload> = (payload: TPayload) => void;
+
+export type DispatchResult =
+  | { stopped: false }
+  | { stopped: true; signal: HookStopSignal };
+
+export type HookName = keyof HookPayloads;
+export type SyncHookName = keyof SyncHookPayloads;
+```
+
+`HookSessionShape` is defined in core (not imported from login) so the core hook layer stays free of feature-package deps. Any concrete `BaseSessionLayout` / project `SessionLayout` is structurally assignable.
+
+## API Reference — Async Hooks
+
+### `registerHook<TName>(name, handler): void`
+
+**Signature:**
+```typescript
+export const registerHook = <TName extends HookName>(
+  name: TName,
+  handler: HookHandler<HookPayloads[TName]>,
+): void
+```
+
+**Behavior:** Appends the handler to the (string-keyed) list of handlers for `name`. Multiple registrations are allowed; order is preserved.
+
+### `dispatchHook<TName>(name, payload): Promise<DispatchResult>`
+
+**Signature:**
+```typescript
+export const dispatchHook = async <TName extends HookName>(
+  name: TName,
+  payload: HookPayloads[TName],
+): Promise<DispatchResult>
+```
+
+**Behavior (in order):**
+1. Reads the handler list for `name` (empty array if none).
+2. For each handler:
+   - Awaits `handler(payload)` inside a try/catch.
+   - On thrown error → logs `hook: handler for "<name>" threw` via `getLogger().error` + `captureException(error, { hook: name })`. Continues with the next handler.
+   - On returned `HookStopSignal` (any non-undefined return value) → returns `{ stopped: true, signal: result }` immediately. Remaining handlers do NOT run.
+3. After all handlers complete without a stop → returns `{ stopped: false }`.
+
+**Mutation contract:** Handlers receive the same payload object reference. For payloads that explicitly support mutation (`PreApiRespondPayload.response`, `transformApiResponse`), mutating in place is the documented mechanism to replace the outgoing response without a stop signal.
+
+### `clearAllHooks(): void`
+
+Test-only. Clears both the async and sync hook registries. Never call from production paths — framework-internal hooks (presence cleanup, etc.) would be wiped.
+
+## API Reference — Sync Hooks
+
+### `registerSyncHook<TName>(name, handler): void`
+
+**Behavior:** Same shape as `registerHook` but appends to the sync map.
+
+### `dispatchSyncHook<TName>(name, payload): void`
+
+**Behavior:**
+- Invokes every handler synchronously.
+- Per-handler try/catch isolates failures (same logger + `captureException` path as async).
+- Cannot stop the flow. Handlers mutate `payload` in place.
+
+**When to use sync:** Only when the call site is on a hot path that genuinely cannot afford to `await`. The current usage is `normalizeErrorResponse` because it's invoked from many places in a single request (api error path, sync error path, transport boundaries).
+
+## Core-owned payload shapes
+
+### API lifecycle
+
+| Hook | Payload (key fields) |
+|---|---|
+| `preHttpRequest` | `method`, `url`, `requestId`, `origin`, `headers` (sanitized — no auth/cookie). |
+| `preApiValidate` | `routeName`, `data`, `user`. |
+| `postApiValidate` | extends `preApiValidate` + `validation: { status: 'success' } \| { status: 'error', message }`. |
+| `preApiExecute` | `routeName`, `data`, `user`. |
+| `postApiExecute` | `routeName`, `data`, `user`, `result`, `error`, `durationMs`. |
+| `preApiRespond` | `routeName`, `user`, `response: ApiResponseEnvelope` (mutable). |
+| `transformApiResponse` | Same shape — separate hook so plugins can compose without ordering with `preApiRespond`. |
+| `postApiRespond` | `routeName`, `user`, `response` (immutable after wire-send). |
+
+### Sync lifecycle
+
+| Hook | Payload (key fields) |
+|---|---|
+| `preSyncAuthorize` | `routeName`, `data` (raw), `user`, `receiver`. |
+| `preSyncFanout` | `routeName`, `data`, `user`, `receiver`, `serverOutput`. |
+| `postSyncFanout` | extends `preSyncFanout` + `recipientCount`. |
+| `preSyncStream` | `routeName`, `chunk`, `recipient`. |
+| `postSyncStream` | extends `preSyncStream` + `chunkIndex`. |
+
+### Error / security signals
+
+| Hook | Payload (key fields) |
+|---|---|
+| `apiError` | `route`, `method?`, `requestId?`, `user?`, `error`. |
+| `syncError` | Same shape. |
+| `rateLimitExceeded` | `scope`, `key` (sanitized), `limit`, `windowMs`, `count`, `route?`, `ip?`, `userId?`. |
+| `corsRejected` | `origin`, `normalizedOrigin`, `allowedOrigins`, `allowLocalhost`, `route?`. |
+| `csrfMismatch` | `route`, `method?`, `requestId?`, `userId?`, `providedToken: boolean`. |
+
+### Session refresh
+
+| Hook | Payload (key fields) |
+|---|---|
+| `preSessionRefresh` | `token`, `userId`, `oldTtl`, `newTtl`. |
+| `postSessionRefresh` | extends + `applied: boolean`. |
+
+### Uploads
+
+| Hook | Payload (key fields) |
+|---|---|
+| `onUploadStart` | `userId`, `contentType`, `sizeBytes`, `uploadKind`. Can return `HookStopSignal` (e.g. content moderation reject). |
+| `onUploadComplete` | `userId`, `fileName`, `sizeBytes`, `uploadKind`. Read-only — fires after disk write. |
+
+### Sync mutator hooks
+
+| Hook | Payload (key fields) |
+|---|---|
+| `preErrorNormalize` | `response: ErrorResponseInput` (mutable), `preferredLocale?`, `userLanguage?`, `fallbackHttpStatus?`. |
+| `postErrorNormalize` | `normalized: NormalizedErrorResponse` (mutable), `preferredLocale?`, `userLanguage?`. |
+
+## API Reference — processUpload
+
+### `processUpload(input: ProcessUploadInput): Promise<ProcessUploadResult>`
+
+**Signature:**
+```typescript
+export interface ProcessUploadInput {
+  userId: string;
+  contentType: string;
+  buffer: Buffer;
+  uploadKind?: string;       // default 'avatar'
+  fileName: string;
+  encodeAndSave: (buffer: Buffer) => Promise<number>;
+}
+
+export type ProcessUploadResult =
+  | { status: 'success'; sizeBytes: number }
+  | { status: 'rejected'; errorCode: string }
+  | { status: 'error'; reason: string; cause?: unknown };
+```
+
+**Behavior (in order):**
+1. Resolves `uploadKind` (defaults to `'avatar'`).
+2. Dispatches `onUploadStart` with `{ userId, contentType, sizeBytes: buffer.byteLength, uploadKind }`. If a handler returned a stop signal → returns `{ status: 'rejected', errorCode: signal.errorCode }`.
+3. Runs `input.encodeAndSave(buffer)` inside `tryCatch`. On error → returns `{ status: 'error', reason: error.message || 'encode-failed', cause: error }`.
+4. Dispatches `onUploadComplete` with `{ userId, fileName, sizeBytes: finalSize ?? buffer.byteLength, uploadKind }`.
+5. Returns `{ status: 'success', sizeBytes }`.
+
+**Why a callback (not built-in encoder):** core stays free of heavy native deps (sharp, ffmpeg, S3 SDKs). The consumer plugs in whichever encoder it needs and core only brackets the call with the hook contract.
+
+**Example:** see `src/settings/_api/updateUser_v1.ts` for the canonical avatar usage.
+
+## API Reference — Response normalizer family
+
+### Types
+```typescript
+export interface ErrorParam {
+  key: string;
+  value: string | number | boolean;
+}
+
+export interface ErrorResponseInput {
+  status?: unknown;
+  errorCode?: unknown;
+  errorParams?: unknown;
+  httpStatus?: unknown;
+}
+
+export interface NormalizedErrorResponse {
+  status: 'error';
+  message: string;
+  errorCode: string;
+  errorParams?: ErrorParam[];
+  httpStatus?: number;
+}
+
+export const INVALID_ERROR_RESPONSE_CODE = 'error.invalidResponse';
+```
+
+### `isErrorParamArray(value: unknown): value is ErrorParam[]`
+
+Type guard. Returns `true` when `value` is an array and every element has a string `key` plus a `string | number | boolean` `value`.
+
+### `normalizeErrorResponseCore({ response, fallbackHttpStatus?, fallbackErrorCode?, resolveMessage? })`
+
+**Behavior:**
+- Extracts `errorParams` (defaults to `undefined` when not an `ErrorParam[]`).
+- Reads `errorCode` (trimmed string). Falls back to `fallbackErrorCode` then `INVALID_ERROR_RESPONSE_CODE`.
+- Reads `httpStatus` only when `typeof === 'number'`; otherwise uses `fallbackHttpStatus`.
+- Calls `resolveMessage?.({ errorCode, errorParams })` when provided; otherwise uses the raw `errorCode` as `message`.
+- Returns `{ status: 'error', message, errorCode, errorParams?, httpStatus? }`.
+
+### `defaultHttpStatusForResponse({ status, explicitHttpStatus?, fallbackErrorStatus = 400 })`
+
+Returns `explicitHttpStatus` when numeric, else `200` for `'success'` and `fallbackErrorStatus` for `'error'`.
+
+The localized `normalizeErrorResponse` wrapper (in `localizedNormalizer.ts`) layers i18n + the `preErrorNormalize` / `postErrorNormalize` sync hooks on top of `normalizeErrorResponseCore` — see source for the full surface.
+
+## Extending HookPayloads (feature packages)
+
+```typescript
+// packages/<feature>/src/hookPayloads.ts
+import type { HookSessionShape } from '@luckystack/core';
+
+declare module '@luckystack/core' {
+  interface HookPayloads {
+    myFeatureHook: { userId: string; data: { foo: number } };
+  }
+}
+
+export {};
+```
+
+Then side-effect import from the package barrel so the augmentation is reachable:
+
+```typescript
+// packages/<feature>/src/index.ts
+import './hookPayloads';
+export { /* ... */ };
+```
+
+## Edge cases
+
+- A handler that returns `undefined` continues the chain; ANY non-`undefined` return value is treated as a stop signal (the type is `undefined | HookStopSignal`, so returning a plain string would be a type error in TS but a stop in JS — keep the typed signature).
+- `clearAllHooks` clears BOTH registries; if you only need to drop async handlers, register fresh sync ones afterwards.
+- `dispatchSyncHook` ignores handler return values entirely — mutate `payload` in place.
+
+## Related
+
+- Function INDEX: `packages/core/CLAUDE.md`
+- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`, `docs/ARCHITECTURE_API.md`, `docs/ARCHITECTURE_SYNC.md`
+- README: `packages/core/README.md`
+- Source: `packages/core/src/hooks/registry.ts`, `hooks/types.ts`, `processUpload.ts`, `responseNormalizer.ts`

package/docs/rate-limit-strategy.md

@@ -0,0 +1,170 @@
+# Rate Limit Strategy
+
+> Deep specs for the pluggable rate-limit dispatcher and built-in memory/Redis strategy. Source: `packages/core/src/rateLimiter.ts`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+Rate limiting in LuckyStack is a thin dispatcher backed by a swappable strategy. Framework code calls `checkRateLimit({ key, limit, windowMs })`; the active `RateLimitStrategy` decides how to count. The default strategy implements in-memory counters with optional Redis backing for multi-instance deployments and silently degrades to memory mode on Redis failure (with a one-shot warn log).
+
+Consumers can plug in their own backend (token-bucket, sliding-window, per-user tier limits, Cloudflare KV, no-op) by implementing the four `RateLimitStrategy` methods and calling `registerRateLimitStrategy(strategy)` at boot.
+
+The dispatcher also runs an internal cleanup timer that drops expired in-memory entries every `rateLimiting.cleanupIntervalMs`. The timer is `unref`'d so it never holds the process open.
+
+## Types
+
+```typescript
+export interface CheckRateLimitParams {
+  key: string;
+  limit: number;
+  windowMs?: number; // default 60_000
+}
+
+export interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  resetIn: number; // seconds until reset
+}
+
+export interface RateLimitStrategy {
+  name: string;
+  check(params: CheckRateLimitParams): Promise<RateLimitResult>;
+  getStatus(key: string, limit: number): Promise<RateLimitResult>;
+  clear(key: string): Promise<void>;
+  clearAll(): Promise<void>;
+}
+```
+
+## API Reference — Dispatcher
+
+### `checkRateLimit(params: CheckRateLimitParams): Promise<RateLimitResult>`
+
+**Behavior:** Delegates to `getRateLimitStrategy().check(params)`. Increments the counter as a side effect when allowed.
+
+**Example:**
+```typescript
+import { checkRateLimit } from '@luckystack/core';
+
+const { allowed, remaining, resetIn } = await checkRateLimit({
+  key: `user:${userId}:api:getData`,
+  limit: 60,
+});
+
+if (!allowed) {
+  return { status: 'error', errorCode: 'rateLimit.exceeded', httpStatus: 429 };
+}
+```
+
+### `getRateLimitStatus(key, limit): Promise<RateLimitResult>`
+
+**Behavior:** Read-only — does NOT increment. Useful for `X-RateLimit-Remaining` response headers.
+
+### `clearRateLimit(key): Promise<void>`
+
+Resets a single key. Useful for admin overrides or post-test cleanup.
+
+### `clearAllRateLimits(): Promise<void>`
+
+Wipes every key under the active strategy's namespace. Useful for tests / server restart.
+
+### `registerRateLimitStrategy(strategy: RateLimitStrategy): void`
+
+**Behavior:**
+- Replaces the active strategy (last-write-wins).
+- Logs `[RateLimiter] active strategy → <name>` at debug level.
+- Common use cases: token-bucket, sliding-window, per-tier user limits, edge-KV, no-op (tests).
+
+### `getRateLimitStrategy(): RateLimitStrategy`
+
+Returns the currently active strategy. Defaults to `defaultRateLimitStrategy`.
+
+## API Reference — Built-in Default Strategy
+
+### `defaultRateLimitStrategy: RateLimitStrategy`
+
+`name === 'default-memory-redis'`. Reads `projectConfig.rateLimiting.{enabled,store,redisKeyPrefix,windowMs}` at call time.
+
+#### `check(params)` flow
+
+1. If `rateLimiting.enabled === false` → returns `{ allowed: true, remaining: limit, resetIn: 0 }` without touching counters.
+2. If `rateLimiting.store === 'redis'`:
+   - Runs a Lua `INCR` + `PEXPIRE` script atomically against `<projectName>:<redisKeyPrefix>:<key>`.
+   - Returns `{ allowed: count <= limit, remaining: max(0, limit - count), resetIn: ceil(ttl / 1000) }` when the script returns a valid pair.
+   - On any Redis error, logs a one-shot warn `[RateLimiter] Redis mode unavailable, falling back to in-memory mode` and falls through to the memory path.
+3. Memory path:
+   - First request in the window → create entry, return `allowed: true, remaining: limit - 1`.
+   - Subsequent requests → increment, return `{ allowed: count <= limit, remaining: max(0, limit - count), resetIn: ceil((resetAt - now) / 1000) }`.
+
+#### `getStatus(key, limit)` flow
+
+Same dual-path shape but does NOT increment. The Redis path uses `MULTI` (`GET` + `PTTL`) to read current count + remaining TTL.
+
+#### `clear(key)` flow
+
+- Redis mode: `DEL <prefix>:<key>` (wrapped in `tryCatch`).
+- Always: deletes the in-memory entry as well.
+
+#### `clearAll()` flow
+
+- Redis mode: `SCAN` with `MATCH <prefix>:*`, `DEL` matched keys, repeat until cursor returns to `'0'`.
+- Always: clears the in-memory map.
+
+### Lua script (atomic increment)
+
+```lua
+local current = redis.call('INCR', KEYS[1])
+if current == 1 then
+  redis.call('PEXPIRE', KEYS[1], ARGV[1])
+end
+local ttl = redis.call('PTTL', KEYS[1])
+return { current, ttl }
+```
+
+### Cleanup timer
+
+A self-rescheduling `setTimeout(unref)` deletes expired in-memory entries every `rateLimiting.cleanupIntervalMs`. Re-reads the config each tick so a late `registerProjectConfig` is picked up. Logs `[RateLimiter] Cleaned N expired entries` at debug level when any are removed.
+
+## Edge cases
+
+- Negative or non-finite `windowMs` is normalized to `projectConfig.rateLimiting.windowMs`.
+- Concurrent strategy switches are allowed but the cleanup timer keeps running against the in-memory map regardless of the active strategy — fine because the map is only touched by the default strategy.
+- The default Redis script + scan path swallow errors via `tryCatch`; a network blip degrades to memory mode instead of throwing.
+- The disabled mode (`rateLimiting.enabled = false`) still calls `getStatus` happily — useful for showing meaningful headers in dev.
+
+## Hooks dispatched
+
+Rate limiting itself does not dispatch hooks from core. The api/sync packages dispatch `rateLimitExceeded` when their handlers translate a `RateLimitResult` rejection into the response envelope.
+
+## Config keys consumed
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `rateLimiting.enabled` | `boolean` | `true` | Global kill-switch. |
+| `rateLimiting.store` | `'memory' \| 'redis'` | `'memory'` | Backend. |
+| `rateLimiting.redisKeyPrefix` | `string` | `'rate-limit'` | Prefixed with `<projectName>:`. |
+| `rateLimiting.defaultApiLimit` | `number \| false` | `60` | Default per-route cap (consumed by api package). |
+| `rateLimiting.defaultIpLimit` | `number \| false` | `100` | Default per-IP cap. |
+| `rateLimiting.windowMs` | `number` | `60_000` | Sliding window. |
+| `rateLimiting.cleanupIntervalMs` | `number` | `60_000` | Memory eviction cadence. |
+
+## Example — register a no-op strategy for tests
+
+```typescript
+import { registerRateLimitStrategy, type RateLimitStrategy } from '@luckystack/core';
+
+const noopStrategy: RateLimitStrategy = {
+  name: 'noop',
+  check: async ({ limit }) => ({ allowed: true, remaining: limit, resetIn: 0 }),
+  getStatus: async (_key, limit) => ({ allowed: true, remaining: limit, resetIn: 0 }),
+  clear: async () => undefined,
+  clearAll: async () => undefined,
+};
+
+registerRateLimitStrategy(noopStrategy);
+```
+
+## Related
+
+- Function INDEX: `packages/core/CLAUDE.md`
+- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`, `docs/ARCHITECTURE_API.md`
+- README: `packages/core/README.md`
+- Source: `packages/core/src/rateLimiter.ts`

package/docs/redis-adapter.md

@@ -0,0 +1,111 @@
+# Redis Adapter
+
+> Deep specs for the Redis client proxy, connection options helper, and the Socket.io cross-instance adapter. Source: `packages/core/src/redis.ts`, `socketRedisAdapter.ts`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+Core ships a single Redis client that the entire framework shares for session storage, rate limiting, OAuth state, password-reset tokens, boot UUIDs, and the Socket.io pub/sub adapter. The `redis` export is a `Proxy` that defers resolution to call time so a consumer can `registerRedisClient(customClient)` after this module is imported and still win.
+
+`attachSocketRedisAdapter(io)` wires `@socket.io/redis-adapter` with two duplicated pub/sub connections so room broadcasts span multiple Node processes — without it, `io.to(room).emit(...)` only reaches clients connected to the same instance.
+
+`getRedisConnectionOptions()` exposes the same `{ host, port, username?, password? }` shape that the framework's default ioredis client uses. `@luckystack/router` reuses it for short-lived cross-env probes so a config rename never drifts between writer and reader.
+
+## API Reference
+
+### `redis: RedisClient` (proxy)
+
+**Signature:**
+```typescript
+export const redis: RedisClient
+export default redis
+```
+
+**Behavior:**
+- Every method/property access is forwarded to whatever `getRedisClient()` currently returns.
+- When the consumer has called `registerRedisClient(...)`, that client wins.
+- Otherwise the proxy lazily constructs a default ioredis instance from `env.REDIS_HOST` / `env.REDIS_PORT` (plus optional `REDIS_USERNAME` / `REDIS_PASSWORD`) on first access.
+- The default client installs a `connect` listener that logs `"Connected to Redis"` via `getLogger().info` and an `error` listener that routes to `getLogger().error`.
+- The default client uses an exponential `retryStrategy(times => Math.min(times * 50, 2000))`.
+
+**Edge cases:**
+- Method results are auto-bound to the underlying client to keep `this` correct for chained calls (`redis.multi().get(...).exec()` works).
+- The `has` trap checks against the live client so `'eval' in redis` reports whatever the registered client supports.
+
+**Example:**
+```typescript
+import { redis } from '@luckystack/core';
+
+await redis.set(`${prefix}:foo`, 'bar', 'EX', 60);
+const value = await redis.get(`${prefix}:foo`);
+```
+
+### `getRedisConnectionOptions(): RedisConnectionOptions`
+
+**Signature:**
+```typescript
+export interface RedisConnectionOptions {
+  host: string;
+  port: number;
+  username?: string;
+  password?: string;
+}
+
+export const getRedisConnectionOptions = (): RedisConnectionOptions
+```
+
+**Behavior:**
+- Reads `env.REDIS_HOST` and parses `env.REDIS_PORT` to a number.
+- Includes `username` only when `process.env.REDIS_USERNAME` is non-empty.
+- Includes `password` only when `process.env.REDIS_PASSWORD` is non-empty.
+- Read at call time so dotenv timing doesn't capture stale values.
+
+**Example:**
+```typescript
+import Redis from 'ioredis';
+import { getRedisConnectionOptions } from '@luckystack/core';
+
+// router-side: open a short-lived probe with the same params
+const probe = new Redis({ ...getRedisConnectionOptions(), lazyConnect: true });
+```
+
+### `attachSocketRedisAdapter(io: SocketIOServer): void`
+
+**Signature:**
+```typescript
+export const attachSocketRedisAdapter = (io: SocketIOServer): void
+```
+
+**Behavior (in order):**
+1. Calls `redis.duplicate()` twice to obtain dedicated pub + sub clients (ioredis blocks non-pub/sub commands on a connection in subscribe mode, so duplicating is required).
+2. Installs `error` listeners on both clients that log to `console.error` with the `[socket-redis-adapter]` prefix.
+3. Calls `io.adapter(createAdapter(pubClient, subClient))` to wire `@socket.io/redis-adapter`.
+
+**Edge cases:**
+- Calling this after `io` has already accepted connections is allowed but races with in-flight broadcasts — wire it before `io.listen` / connection handlers in the boot sequence.
+- The duplicated clients inherit the active registered client (or the default).
+
+**Example:**
+```typescript
+import { Server } from 'socket.io';
+import { attachSocketRedisAdapter, setIoInstance } from '@luckystack/core';
+
+const io = new Server(httpServer, { /* ... */ });
+attachSocketRedisAdapter(io);
+setIoInstance(io);
+```
+
+## Config keys consumed
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `REDIS_HOST` | `'127.0.0.1'` | Default client + `getRedisConnectionOptions`. |
+| `REDIS_PORT` | `'6379'` | Same. |
+| `REDIS_USERNAME` | (unset) | Optional ioredis auth. |
+| `REDIS_PASSWORD` | (unset) | Optional ioredis auth. |
+
+## Related
+
+- Function INDEX: `packages/core/CLAUDE.md`
+- Architecture: `docs/ARCHITECTURE_SOCKET.md`, `docs/HOSTING.md`
+- README: `packages/core/README.md`
+- Source: `packages/core/src/redis.ts`, `socketRedisAdapter.ts`, `clients.ts`