@luckystack/server 0.10.2 → 0.11.0

package/docs/request-pipeline.md

@@ -1,198 +1,5 @@
-# Request Pipeline
+# Request pipeline
 
-> Deep specs. Bron: `packages/server/src/httpHandler.ts`, `packages/server/src/loadSocket.ts`, `packages/server/src/sse.ts`.
+Apply the origin policy and security headers before dispatching HTTP routes; apply cookie-mode CSRF protection before executing state-changing handlers. A missing browser origin on a write must not become a Host-derived same-origin assumption. Keep HTTP and Socket.io policies explicit rather than assuming the HTTP handler protects socket handshakes. Source: `../src/httpHandler.ts`, `../src/loadSocket.ts`, `../src/httpRoutes/csrfMiddleware.ts`.
 
-## Overview
-
-`handleHttpRequest` is the orchestrator that every HTTP request flows through. Its job is fixed and intentionally narrow: enforce origin policy, set headers, parse session + CSRF, run pre-request hook, decide method validity, parse params, then walk two ordered handler tables. Each handler in those tables (see `http-routes.md`) is single-purpose and returns `boolean`.
-
-Top-level flow:
-
-1. Build session-cookie option string (`HttpOnly; SameSite; Path; Max-Age; Secure?`).
-2. `enforceOriginPolicy(req, res)` — origin/referer gate. Read-only methods without origin pass; state-changing methods without origin are 403.
-3. `setSecurityHeaders(req, res, origin)` — framework defaults + consumer builder (see `security-defaults.md`).
-4. Resolve `requestId` from `x-request-id` (echoed back) or `randomUUID()`. Set `X-Request-Id` response header.
-5. Dispatch `preHttpRequest` hook with a sanitized header subset. A `HookStopSignal` returns `JSON.stringify({ status: 'error', errorCode })` at `signal.httpStatus ?? 403`.
-6. `OPTIONS` -> `204` and return.
-7. Method allowlist: `GET / POST / PUT / DELETE`. Anything else -> `404` plain text.
-8. Extract session token via `extractTokenFromRequest`. Sliding-cookie refresh when the cookie + session both exist.
-9. `enforceCsrfOnStateChangingRequest(...)` — see `security-defaults.md`.
-10. Dispatch `PRE_PARAMS_ROUTES` (`csrf`, `favicon`, `livez`, `readyz`, `_health`, `_test/reset`) — fast paths that should not consume the body.
-11. `parseRequestParams(...)` — `await getParams({ method, req, res, queryString })`. Streams the body when applicable; bails out if `res.writableEnded`.
-12. Dispatch `POST_PARAMS_ROUTES` (`uploads`, `auth/api`, `auth/callback`, `api`, `sync`, `customRoutes`, `staticAndSpaFallback`).
-
-Socket.io runs on a parallel lifecycle — attached to the same `http.Server` via `loadSocket(httpServer, { maxHttpBufferSize })` but with its own event-driven dispatch.
-
-## API Reference
-
-### `handleHttpRequest(req, res, options): Promise<void>`
-
-**Signature:**
-
-```typescript
-export const handleHttpRequest = async (
-  req: IncomingMessage,
-  res: ServerResponse,
-  options: CreateLuckyStackServerOptions,
-): Promise<void>;
-```
-
-**Parameters:**
-
-| Field | Type | Purpose |
-| --- | --- | --- |
-| `req` | `IncomingMessage` | Raw Node request. |
-| `res` | `ServerResponse` | Raw Node response. |
-| `options` | `CreateLuckyStackServerOptions` | Forwarded to the route handler context (used by `staticAndSpaFallback` / `customRoutes`). |
-
-**Returns:** `Promise<void>`. The handler resolves once it has ended the response (or short-circuited).
-
-**Behavior (execution order):**
-
-- Read `projectConfig` once and snapshot `shouldLogDev`, `sessionCookieName`, `sessionCookieOptions`.
-- `enforceOriginPolicy`: state-changing requests without `Origin` / `Referer` are rejected with `403 'Forbidden'`. A present-but-disallowed origin is also `403`. Read-only methods without origin pass to keep health probes and asset fetches working.
-- `setSecurityHeaders`: see `security-defaults.md`. Consumer builder runs after defaults; errors fall through to defaults.
-- Compute `requestId`. Honor `x-request-id` (idempotent for retrying proxies); otherwise mint a `randomUUID()`. Echo as `X-Request-Id` response header.
-- Build a sanitized `safeHeaders` map (drops `authorization`, `cookie`, `set-cookie`, `x-csrf-token`).
-- Dispatch `preHttpRequest` hook. On `result.stopped`: respond with `signal.httpStatus ?? 403` and `application/json { status: 'error', errorCode: signal.errorCode }`.
-- `OPTIONS` -> `writeHead(204)` + `end()`.
-- Reject methods outside `GET / POST / PUT / DELETE` with `404 text/plain`.
-- Split `req.url` into `[routePath, queryString]`.
-- `extractTokenFromRequest(req)` — pulls token from cookie or `Authorization`.
-- `refreshSessionCookieIfPresent` — sliding expiration in cookie mode. Re-emits `Set-Cookie` with refreshed `Max-Age` when the session exists.
-- `enforceCsrfOnStateChangingRequest` — returns `true` when it has ended the response; the request loop bails.
-- `dispatchRoutes(PRE_PARAMS_ROUTES, { ...baseCtx, params: {} })` — first handler to return `true` (or end `res`) wins; otherwise the chain falls through.
-- `parseRequestParams` — pulls body when method needs one. If `res.writableEnded` (because the body parser ended with an error), bail out.
-- `dispatchRoutes(POST_PARAMS_ROUTES, { ...baseCtx, params })`.
-
-**Errors / Edge cases:**
-
-- The orchestrator itself never wraps the table in `tryCatch`. Per-route handlers wrap their work; `customRoutes` handlers are caught and reported as `500 server.customRouteFailed`.
-- Handler order is fixed; mutating it requires editing `PRE_PARAMS_ROUTES` / `POST_PARAMS_ROUTES`.
-- A handler that ends `res` but returns `false` still terminates dispatch — `dispatchRoutes` checks `res.writableEnded` after each call.
-
----
-
-### `dispatchRoutes(handlers, ctx): Promise<boolean>`
-
-**Signature:**
-
-```typescript
-const dispatchRoutes = async (
-  handlers: HttpRouteHandler[],
-  ctx: HttpRouteContext,
-): Promise<boolean>;
-```
-
-**Behavior:**
-
-- Iterates `handlers` in array order.
-- After each call, if `handled === true` OR `ctx.res.writableEnded` -> return `true` (stop).
-- Otherwise continue. Return `false` if none handled.
-
-**Edge case:** a handler that writes a partial response without ending (`res.write(...)`) without setting `writableEnded` still falls through unless it returns `true`. Always end the response or return `true`.
-
----
-
-### `loadSocket(httpServer, options?): SocketIOServer`
-
-**Signature:**
-
-```typescript
-export interface LoadSocketOptions {
-  maxHttpBufferSize?: number;
-}
-
-export const loadSocket = (
-  httpServer: HttpServer,
-  options: LoadSocketOptions = {},
-): SocketIOServer;
-```
-
-**Parameters:**
-
-| Field | Type | Default | Purpose |
-| --- | --- | --- | --- |
-| `httpServer` | `http.Server` | required | The HTTP server returned by `createLuckyStackServer`. Socket.io upgrades on it. |
-| `options.maxHttpBufferSize` | `number` | `projectConfig.socket.maxHttpBufferSize` | Forwarded to Socket.io. |
-
-**Returns:** the `SocketIOServer` instance. Also registered globally via `setIoInstance(io)` so framework code (presence, broadcast helpers) can reach it without a parameter.
-
-**Behavior:**
-
-- Construct `SocketIOServer` with:
-  - CORS: methods `GET / POST / PUT / DELETE / OPTIONS`, origin callback delegates to `allowedOrigin`, `credentials: true`. Empty origin is allowed (Socket.io polling without an origin header).
-  - `maxHttpBufferSize`, `pingTimeout`, `pingInterval` from `projectConfig.socket`.
-- `setIoInstance(io)` and `attachSocketRedisAdapter(io)` — required for room broadcasts to fan out across instances.
-- `io.on('connect', ...)` per-socket lifecycle:
-  - Extract token, cache `activityBroadcasterEnabled` + `locationProviderEnabled` flags + `preferredLocale`.
-  - When token present: `socketConnected({ token, io })` (presence).
-  - Dispatch `onSocketConnect` hook with `{ socketId, token, ip }`.
-  - Wire event handlers (delegates):
-    - `apiRequest` -> `handleApiRequest({ msg, socket, token })` from `@luckystack/api`.
-    - `sync` -> `handleSyncRequest({ msg, socket, token })` from `@luckystack/sync`.
-    - `joinRoom` -> validate, `getSession(token)`, dispatch `preRoomJoin` (may stop), `socket.join(group)`, persist `roomCodes` via `saveSession`, emit `buildJoinRoomResponseEventName(responseIndex)`, dispatch `postRoomJoin`. Serialized per-token via `withSessionLock`.
-    - `leaveRoom` -> symmetric to `joinRoom`. Dispatches `preRoomLeave` / `postRoomLeave`.
-    - `getJoinedRooms` -> emits visible rooms (filters out `socket.id` and the token room).
-    - `disconnect` -> dispatch `onSocketDisconnect`, then either `socketDisconnecting` (if presence is enabled) or a dev log line.
-    - `updateLocation` -> when location provider is enabled, mutate session location, dispatch `onLocationUpdate`. Coordinates with `socketLeaveRoom` from presence.
-  - When `activityBroadcasterEnabled && token`: `initActivityBroadcaster({ socket, token })`.
-  - When token present: `socket.join(token)` — every authenticated socket joins its own token room so server-side code can target a user by token.
-
-**Errors / Edge cases:**
-
-- `withSessionLock(token, fn)` serializes per-token mutations to prevent read-modify-write races on `session.roomCodes`. The lock's `then(fn, fn)` ensures a failed prior call doesn't block the next caller.
-- Legacy session shapes that still carry `code` / `codes` are stripped on save via `sanitizeSessionRoomKeys`.
-- Room validation: empty / non-string `group` -> emit `room.invalid` error frame.
-- `responseIndex` is required for join/leave/getJoinedRooms; non-number values silently no-op (the client never gets a response — Socket.io's response indexing is purely opt-in).
-
-## SSE streaming inside the pipeline
-
-`/api/*` and `/sync/*` opt into SSE via `shouldUseHttpStream({ acceptHeader, queryString })`. When enabled:
-
-- `initSseResponse(res)` writes `200 text/event-stream` + `Cache-Control: no-cache, no-transform` + `Connection: keep-alive` + `X-Accel-Buffering: no`. Optional `projectConfig.http.stream.connectedComment` is sent as the initial keepalive comment.
-- The route handler passes a `stream` callback to its delegate. The delegate emits per-event payloads; the handler forwards each as `event: stream\ndata: <json>\n\n`.
-- On completion, emit `event: final` with the result envelope. On error, `event: error`. Then `res.end()`.
-- `req.on('close', ...)` flips a `streamClosed` flag so post-disconnect writes are suppressed.
-
-## Hooks dispatched
-
-| Hook | Payload | When |
-| --- | --- | --- |
-| `preHttpRequest` | `{ method, url, requestId, origin, headers }` | Before route dispatch. May stop with `HookStopSignal` to short-circuit. `headers` omits sensitive entries. |
-| `csrfMismatch` | `{ route, method, requestId, userId, providedToken: boolean }` | Cookie-mode CSRF check rejects a write. Token VALUE is never in payload. |
-| `apiError` / `syncError` | `{ route, method, requestId, error }` | Outer error path of `/api/*` / `/sync/*` handlers (see `http-routes.md`). |
-| `rateLimitExceeded` | `{ scope, key, limit, windowMs, count, route, ip }` | Credentials login. |
-| `onSocketConnect` / `onSocketDisconnect` | `OnSocketConnectPayload` / `OnSocketDisconnectPayload` | Socket lifecycle (see `create-server.md`). |
-| `preRoomJoin` / `postRoomJoin` | `PreRoomJoinPayload` / `PostRoomJoinPayload` | Room-join lifecycle inside `loadSocket`. `pre*` may stop. |
-| `preRoomLeave` / `postRoomLeave` | `PreRoomLeavePayload` / `PostRoomLeavePayload` | Room-leave lifecycle inside `loadSocket`. `pre*` may stop. |
-| `onLocationUpdate` | `OnLocationUpdatePayload` | When the presence layer reports a path change. |
-
-## Config keys consumed
-
-| Source | Key | Effect |
-| --- | --- | --- |
-| env | `SECURE` | `'true'` -> session cookies get the `Secure;` flag. |
-| config | `projectConfig.logging.devLogs` | Gates per-request debug logs (sanitized params + method/route). |
-| config | `projectConfig.http.cors.*` / `securityHeaders.*` | Response headers (see `security-defaults.md`). |
-| config | `projectConfig.http.sessionCookieName` / `sessionCookiePath` / `sessionCookieSameSite` | Session cookie shape. |
-| config | `projectConfig.session.expiryDays` / `basedToken` | Cookie `Max-Age` + CSRF middleware activation predicate. |
-| config | `projectConfig.http.stream.queryParam` / `enabledValue` / `connectedComment` | SSE opt-in + keepalive. |
-| config | `projectConfig.socket.maxHttpBufferSize` / `pingTimeout` / `pingInterval` | Socket.io transport options. |
-| config | `projectConfig.socketActivityBroadcaster` / `locationProviderEnabled` | Gate presence-related socket handlers. |
-
-## Error fall-through
-
-- The outer `handleHttpRequest` does NOT wrap the table in a global `tryCatch`. Each handler is responsible for its own errors.
-- `handleApiRoute` / `handleSyncRoute` wrap their body and emit `500 *.invalidRequestFormat` after dispatching `apiError` / `syncError`.
-- `handleCustomRoutes` wraps each handler and emits `500 server.customRouteFailed` on throw.
-- Throws from inside a `dispatchHook` handler propagate per `@luckystack/core`'s `dispatchHook` semantics — generally they are caught and logged inside the hook system.
-
-## Related
-
-- Function INDEX: `packages/server/CLAUDE.md`
-- HTTP routes: `packages/server/docs/http-routes.md`
-- Security defaults: `packages/server/docs/security-defaults.md`
-- Create server: `packages/server/docs/create-server.md`
-- Architecture: `docs/ARCHITECTURE_API.md`, `docs/ARCHITECTURE_SOCKET.md`, `docs/ARCHITECTURE_SYNC.md`, `docs/ARCHITECTURE_SESSION.md`
-- README: `packages/server/README.md`
+Per-route error formatting must not change authorization outcomes. Streaming must preserve failure signalling after partial delivery; see `../src/sse.ts` and `../../sync/docs/streaming.md`. For route selection consult `../src/httpRoutes/` rather than a hand-maintained execution tour.

package/docs/runtime-maps.md

@@ -1,209 +1,5 @@
-# Runtime Maps Loader
+# Runtime maps
 
-> Deep specs. Bron: `packages/server/src/runtimeMapsLoader.ts`.
+Generated route maps are loaded in production so boot does not depend on a development watcher or scan. Bundles must not silently overwrite another bundle's API or sync route: conflicting ownership is a deployment error. Repeated equivalent shared functions are intentionally deduplicated because scoped builds can carry the same registry. Source: `../src/runtimeMapsLoader.ts`, `../src/verifyBootstrap.ts`.
 
-## Overview
-
-A `RuntimeMapsProvider` (defined in `@luckystack/core`) is the runtime source of truth for which `apis`, `syncs`, and `functions` exist in the running process. Without one, every `/api/*` and `/sync/*` request silently resolves to `notFound`.
-
-`@luckystack/server` ships two helpers so consumers no longer need to hand-roll their own `server/prod/runtimeMaps.ts`:
-
-- `createProdRuntimeMapsProvider(options)` — builds and returns the provider without registering.
-- `registerProdRuntimeMapsProvider(options)` — convenience wrapper: builds AND calls `registerRuntimeMapsProvider(provider)`. Most consumers want this.
-
-In production, the provider loads generated maps via the consumer-supplied `loadGenerated(preset)` callback. In dev it transparently delegates to `@luckystack/devkit`'s in-memory discovery (`devApis` / `devSyncs` / `devFunctions`), which is populated by the devkit watchers.
-
-Why does the consumer supply `loadGenerated`? Dynamic-import path resolution in ESM is module-scoped — the framework cannot resolve a relative path on the consumer's behalf. Passing a function that calls `import(\`./prod/generatedApis.${preset}\`)` lets the consumer-side module own resolution.
-
-Preset list resolution (in `resolvePresets`):
-
-1. `options.preset` if it is a non-empty string -> `[preset]`.
-2. `options.preset` if it is a non-empty array -> dedup via `Array.from(new Set(...))`.
-3. `getParsedBundles()` from `argv.ts` when non-empty.
-4. Final fallback: `['default']`.
-
-Multiple presets are loaded in parallel, normalized to `{ apisObject, syncObject, functionsObject }`, then shallow-merged into a single view. API/sync key collisions throw at boot — services must own exactly one preset (see `docs/ARCHITECTURE_PACKAGING.md` §10). Because phase-1 generation intentionally repeats the complete function registry in every preset, equivalent function entries deduplicate; a repeated function key with different exports still throws.
-
-## API Reference
-
-### `createProdRuntimeMapsProvider(options: ProdRuntimeMapsLoaderOptions): RuntimeMapsProvider`
-
-**Signature:**
-
-```typescript
-export interface ProdRuntimeMapsLoaderOptions {
-  loadGenerated: (preset: string) => Promise<unknown>;
-  preset?: string | string[];
-}
-
-export const createProdRuntimeMapsProvider = (
-  options: ProdRuntimeMapsLoaderOptions,
-): RuntimeMapsProvider;
-```
-
-**Parameters:**
-
-| Field | Type | Default | Purpose |
-| --- | --- | --- | --- |
-| `loadGenerated` | `(preset: string) => Promise<unknown>` | required | Dynamic-import callback that resolves the generated maps module for a given preset. The resolved module must have shape `{ apis, syncs, functions }` (what `scripts/generateServerRequests.ts` emits). Called once per preset per process lifetime; the result is cached. |
-| `preset` | `string \| string[]` | argv -> `['default']` | Override for the preset list. String -> single-entry array; array -> deduplicated. Skips the argv lookup. |
-
-**Returns:** a `RuntimeMapsProvider`:
-
-```typescript
-interface RuntimeMapsProvider {
-  getRuntimeApiMaps: () => Promise<{ apisObject: Record<string, unknown>; functionsObject: Record<string, unknown> }>;
-  getRuntimeSyncMaps: () => Promise<{ syncObject: Record<string, unknown>; functionsObject: Record<string, unknown> }>;
-}
-```
-
-**Behavior:**
-
-- Builds two getters (`getRuntimeApiMaps`, `getRuntimeSyncMaps`) that switch on `process.env.NODE_ENV === 'production'`:
-  - **Production:** lazy-loads + caches the prod maps via `loadProdRuntimeMaps`. Subsequent calls await the same `prodMapsPromise`.
-  - **Dev:** lazy-imports `@luckystack/devkit` and returns `{ devApis, devSyncs, devFunctions }`. Devkit is excluded from production bundles so this dynamic import is never reached when `NODE_ENV === 'production'`.
-- `loadProdRuntimeMaps`:
-  1. Resolve presets via `resolvePresets(options)`.
-  2. Concurrently `loadGenerated(preset)` for each preset; failures resolve to `null` (caught with `.catch(() => null)`).
-  3. For each loaded module, run `normalizeGeneratedModule` (defends against missing or malformed export shape: anything other than an object becomes `{}`).
-  4. Merge `apis`, `syncs`, `functions` into the combined view with `mergeInto`, tracking origin per key in three `Map<string, string>`s. Equivalent repeated function entries are retained once.
-  5. Skipped presets emit `console.warn('[luckystack:runtimeMaps] preset "<name>" failed to load — skipping. ...')`.
-  6. If no presets loaded successfully, emit `console.warn('[luckystack:runtimeMaps] no presets resolved (tried: ...). Every api/sync request will return notFound until at least one generated module loads.')` and return empty maps.
-- The dev branch caches the devkit module promise so repeated calls share one resolved module.
-
-**Errors / Edge cases:**
-
-- API/sync collisions, and repeated function keys whose exported values differ, throw synchronously inside `loadProdRuntimeMaps`:
-
-  ```
-  [luckystack:runtimeMaps] <kind> key collision: "<key>" present in both preset "<previous>" and preset "<current>". Services must belong to exactly one preset (see docs/ARCHITECTURE_PACKAGING.md §10).
-  ```
-
-- Failed `import()` (e.g. preset module not built) is swallowed and logged as a warning; the provider continues with whatever did load.
-- A preset module whose default export is not an object normalizes to `{}` for all three maps — no throw, just empty.
-- The dev branch dynamic-imports `'@luckystack/devkit'` even when only one of the two getters is invoked; the module promise is cached.
-
-**Example:**
-
-```typescript
-import { createProdRuntimeMapsProvider, registerRuntimeMapsProvider } from '@luckystack/server';
-
-const provider = createProdRuntimeMapsProvider({
-  loadGenerated: (preset) => import(`./prod/generatedApis.${preset}`),
-  preset: 'billing',
-});
-registerRuntimeMapsProvider(provider);
-```
-
----
-
-### `registerProdRuntimeMapsProvider(options: ProdRuntimeMapsLoaderOptions): RuntimeMapsProvider`
-
-**Signature:**
-
-```typescript
-export const registerProdRuntimeMapsProvider = (
-  options: ProdRuntimeMapsLoaderOptions,
-): RuntimeMapsProvider;
-```
-
-**Parameters:** identical to `createProdRuntimeMapsProvider`.
-
-**Returns:** the same `RuntimeMapsProvider` instance that was registered.
-
-**Behavior:**
-
-- Internally:
-  ```typescript
-  const provider = createProdRuntimeMapsProvider(options);
-  registerRuntimeMapsProvider(provider);
-  return provider;
-  ```
-- Calling twice replaces the active provider (last-write-wins) — `registerRuntimeMapsProvider` is the registry function.
-
-**Errors / Edge cases:** same as `createProdRuntimeMapsProvider`. `registerRuntimeMapsProvider` itself does not throw on duplicate calls.
-
-**Example — direct use:**
-
-```typescript
-import { registerProdRuntimeMapsProvider } from '@luckystack/server';
-
-registerProdRuntimeMapsProvider({
-  loadGenerated: (preset) => import(`./prod/generatedApis.${preset}`),
-});
-```
-
-**Example — via `createLuckyStackServer.loadGeneratedMaps`:** when the option is supplied, `createLuckyStackServer` calls `registerProdRuntimeMapsProvider` for you before `verifyBootstrap` runs.
-
-```typescript
-import { createLuckyStackServer } from '@luckystack/server';
-
-const server = await createLuckyStackServer({
-  serveFile,
-  serveFavicon,
-  loadGeneratedMaps: (preset) => import(`./prod/generatedApis.${preset}`),
-  runtimeMapsPreset: ['billing', 'vehicles'],
-});
-await server.listen();
-```
-
-## Expected module shape
-
-`loadGenerated(preset)` must resolve to a module that has these named exports:
-
-```typescript
-export const apis: Record<string, ApiRouteEntry>;
-export const syncs: Record<string, SyncRouteEntry>;
-export const functions: Record<string, FunctionEntry>;
-```
-
-This matches what `scripts/generateServerRequests.ts` emits. Missing exports default to `{}` — useful when a preset has no syncs or functions.
-
-## Merge semantics
-
-`mergeInto(target, source, kind, fromPreset, keyOrigin)`:
-
-- Iterate every key in `source`.
-- If an API or sync key already belongs to a different preset -> throw the collision error.
-- If a function key already exists, compare both wrapper records: they must expose the same keys and every exported value must be identical through `Object.is`. Equivalent entries are skipped; different implementations throw.
-- Otherwise record the origin and shallow-assign `target[key] = source[key]`.
-
-Three independent origin maps are used so an api named `users/get` and a sync named `users/get` do not collide. ADR 0042 governs the shared-function exception.
-
-## Failure modes
-
-| Situation | Behavior |
-| --- | --- |
-| `loadGenerated(preset)` rejects | Warn (`preset "<name>" failed to load — skipping`); continue with other presets. |
-| All presets failed | Warn (`no presets resolved (tried: ...)`); return empty maps; every request returns `notFound`. |
-| Preset module has wrong shape | Normalize to `{}`. Same effect: requests for those routes return `notFound`. |
-| API/sync key collision across presets | Throw at boot — services must own exactly one preset. |
-| Equivalent repeated function entry | Deduplicate — phase-1 scoped builds intentionally carry the complete registry. |
-| Repeated function key with different exports | Throw at boot — generated artifacts disagree. |
-| Provider is never registered at all | `verifyBootstrap` hard-fails in production, loud-warns in dev. |
-
-## Dev vs prod branch
-
-| Environment | Source of maps |
-| --- | --- |
-| `NODE_ENV === 'production'` | `loadGenerated(preset)` for each resolved preset; cached `prodMapsPromise`. |
-| Anything else | Dynamic import of `'@luckystack/devkit'` -> `{ devApis, devSyncs, devFunctions }`. Devkit watchers keep these maps live. |
-
-The dynamic import to `'@luckystack/devkit'` is intentionally written as `import('@luckystack/devkit')` and not statically referenced, so bundlers tree-shake it out of production builds.
-
-## Config keys
-
-| Source | Key | Effect |
-| --- | --- | --- |
-| env | `NODE_ENV` | Switches dev (devkit) vs prod (`loadGenerated`) branch. |
-| argv | `<bundles>` | Preset list when `options.preset` is omitted. |
-| options | `options.preset` | Overrides argv-derived preset list. |
-| options | `options.loadGenerated` | Required prod loader callback. |
-
-## Related
-
-- Function INDEX: `packages/server/CLAUDE.md`
-- Argv parsing: `packages/server/docs/argv-parsing.md`
-- Create server: `packages/server/docs/create-server.md`
-- Architecture: `docs/ARCHITECTURE_PACKAGING.md` (§10 preset bundles + multi-service builds)
-- README: `packages/server/README.md`
+Failing to register a production provider must be visible at boot, not discovered as a missing route by the first user. Runtime map selection does not authorize a caller; each handler still applies its own access policy. See `./argv-parsing.md`, `../../api/docs/auth-flow.md`, `../../sync/docs/room-fanout.md`.