@luckystack/core 0.10.2 → 0.12.0

package/docs/config-registry.md

@@ -1,348 +1,5 @@
-# Config Registry
+# Config registry
 
-> Deep specs for project / deploy / services / avatar / paths config slots. Source: `packages/core/src/`.
+The project, deployment and services registries decouple reusable framework packages from consumer files. Register during boot, read at call time; avoid capturing a configuration snapshot at import time. Explicit registration checks allow security-critical boot paths to reject missing setup rather than silently using permissive assumptions. See `../src/projectConfig.ts`, `../src/deployConfigRegistry.ts`, `../src/servicesConfigRegistry.ts` and `../../server/src/verifyBootstrap.ts`.
 
-## Overview
-
-The config registries are the single source of truth for runtime project configuration. They follow a uniform pattern:
-
-1. A consumer's boot entry calls `registerXConfig({...})` once before any framework code reads a value.
-2. Framework code reads at call time via `getXConfig()` (never at module load) so the registration timing is flexible.
-3. Boolean `isXConfigRegistered()` helpers exist for code paths that must fail closed when the consumer forgot to register.
-
-Four independent slots live in this topic:
-
-- **Project config** — runtime tunables (rate limits, session policy, HTTP, auth, sockets, paths). Deep-merged over `DEFAULT_PROJECT_CONFIG` so consumers only supply the keys they want to override.
-- **Deploy config** — multi-env topology consumed by `@luckystack/router` (resources, environments, routing, development).
-- **Services config** — service + preset definitions consumed by the router / preset loader.
-- **Avatar config** — disk formats + cache header for `serveAvatar`.
-
-Path getters (`getSrcDir`, `getGeneratedApiDocsPath`, …) resolve project-relative paths against `ROOT_DIR` (auto-detected workspace root) and read `getProjectConfig().paths.*` at call time.
-
-## API Reference — Project Config
-
-### `registerProjectConfig(config: ProjectConfigInput): void`
-
-**Signature:**
-```typescript
-export const registerProjectConfig = (config: ProjectConfigInput): void
-```
-
-**Parameters:**
-| Name | Type | Required | Description |
-|---|---|---|---|
-| `config` | `ProjectConfigInput` (deep-partial of `ProjectConfig`) | yes | Only the keys to override. Missing keys fall back to `DEFAULT_PROJECT_CONFIG`. |
-
-**Returns:** `void`
-
-**Behavior:**
-- Deep-merges `config` over `DEFAULT_PROJECT_CONFIG` (plain-object branches recurse; primitives + arrays are replaced wholesale).
-- Sets the registration flag so `isProjectConfigRegistered()` returns true.
-- Replaces (last-write-wins) on repeated calls — the latest call is the active config.
-
-**Errors / Edge cases:**
-- `undefined` keys in the override are skipped (treated as "no override").
-- Arrays are NOT merged element-wise — passing `cors.allowedOrigins: ['x']` replaces the default `[]` array.
-- Calling after framework hot paths already ran is allowed but the values only take effect on subsequent reads (everything reads call-time).
-
-**Example:**
-```typescript
-import { registerProjectConfig } from '@luckystack/core';
-
-registerProjectConfig({
-  defaultLanguage: 'en',
-  session: { expiryDays: 30 },
-  http: {
-    cors: {
-      allowedOrigins: ['https://app.example.com'],
-      allowLocalhost: false,
-    },
-  },
-});
-```
-
-### `getProjectConfig(): ProjectConfig`
-
-**Signature:**
-```typescript
-export const getProjectConfig = (): ProjectConfig
-```
-
-**Returns:** The active fully-merged `ProjectConfig`.
-
-**Behavior:**
-- Returns the currently merged config object (reference-stable until the next `registerProjectConfig`).
-- Returns `DEFAULT_PROJECT_CONFIG` when nothing was registered yet.
-
-**Example:**
-```typescript
-import { getProjectConfig } from '@luckystack/core';
-
-const { http, rateLimiting } = getProjectConfig();
-const cookieName = http.sessionCookieName;
-```
-
-### `getProjectName(): string`
-
-**Signature:**
-```typescript
-export const getProjectName = (): string
-```
-
-**Returns:** The active project namespace (used as Redis key prefix for session, password reset, rate limits, OAuth state, etc.).
-
-**Behavior:** Resolves in this order (first non-empty wins):
-1. `projectConfig.session.projectName`
-2. `process.env.PROJECT_NAME`
-3. literal `'luckystack'`
-
-**Example:**
-```typescript
-import { getProjectName } from '@luckystack/core';
-
-const key = `${getProjectName()}-session:${token}`;
-```
-
-### `isProjectConfigRegistered(): boolean`
-
-**Signature:**
-```typescript
-export const isProjectConfigRegistered = (): boolean
-```
-
-**Returns:** `true` only after `registerProjectConfig` has been called at least once.
-
-**Behavior:**
-- Pure boot-time guard — does not throw.
-- Framework packages use this for "did the installer forget to register?" warnings without crashing tests/CLI contexts.
-
-### `DEFAULT_PROJECT_CONFIG: ProjectConfig`
-
-Exported so consumers can spread + override structurally:
-
-```typescript
-import { DEFAULT_PROJECT_CONFIG, registerProjectConfig } from '@luckystack/core';
-
-registerProjectConfig({
-  ...DEFAULT_PROJECT_CONFIG,
-  defaultLanguage: 'nl',
-});
-```
-
-Notable defaults (verbatim from `projectConfig.ts`):
-
-| Key | Default |
-|---|---|
-| `rateLimiting.enabled` | `true` |
-| `rateLimiting.store` | `'memory'` |
-| `rateLimiting.defaultApiLimit` | `60` |
-| `rateLimiting.defaultIpLimit` | `100` |
-| `rateLimiting.windowMs` | `60_000` |
-| `session.expiryDays` | `7` |
-| `session.perUser` | `'single'` |
-| `session.onConflict` | `'revokeOld'` |
-| `session.notifyOldDeviceOnRevoke` | `true` |
-| `http.sessionCookieName` | `'token'` |
-| `http.sessionCookieSameSite` | `'Strict'` |
-| `http.requestBodyMaxBytes` | `1048576` |
-| `http.healthEndpoint` | `'/_health'` |
-| `http.liveEndpoint` | `'/livez'` |
-| `http.readyEndpoint` | `'/readyz'` |
-| `http.cors.credentials` | `true` |
-| `http.cors.allowedOrigins` | `[]` |
-| `http.cors.allowLocalhost` | `false` |
-| `auth.bcryptRounds` | `10` |
-| `auth.providerAccountStrategy` | `'per-provider'` |
-| `auth.forgotPassword` | `'disabled'` |
-| `auth.passwordResetTtlSeconds` | `3600` |
-| `socket.maxHttpBufferSize` | `5 * 1024 * 1024` |
-| `socket.pingTimeout` | `20_000` |
-| `socket.pingInterval` | `25_000` |
-| `sync.fanoutYieldEvery` | `100` |
-| `sync.fanoutYieldMs` | `1` |
-| `offlineQueue.maxSize` | `200` |
-| `offlineQueue.maxAgeMs` | `3_600_000` |
-| `offlineQueue.dropPolicy` | `'drop-oldest'` |
-| `dev.hotReloadDebounceMs` | `120` |
-| `defaultLanguage` | `'en'` |
-| `defaultTheme` | `'light'` |
-
-## API Reference — Deploy Config
-
-### `registerDeployConfig(config: DeployConfigShape): DeployConfigShape`
-
-**Signature:**
-```typescript
-export const registerDeployConfig = (config: DeployConfigShape): DeployConfigShape
-```
-
-**Parameters:**
-| Name | Type | Required | Description |
-|---|---|---|---|
-| `config` | `DeployConfigShape` | yes | Deploy topology object — `{ resources, environments?, routing?, development? }`. |
-
-**Returns:** The stored config (same reference passed in).
-
-**Behavior:**
-- Stores the provided config wholesale (no deep-merge, unlike `registerProjectConfig`).
-- Sets `isDeployConfigRegistered()` to `true`.
-
-**Example:**
-```typescript
-import { registerDeployConfig } from '@luckystack/core';
-
-registerDeployConfig({
-  resources: {
-    redis: { type: 'redis', urlEnvKey: 'REDIS_URL', synchronizedEnvKeys: ['SESSION_SECRET'] },
-    mongo: { type: 'mongo', urlEnvKey: 'MONGO_URL' },
-  },
-  environments: {
-    production: { redis: 'redis', mongo: 'mongo', bindings: {} },
-  },
-  routing: { strictBootHandshake: true },
-});
-```
-
-### `getDeployConfig(): DeployConfigShape`
-
-Returns the registered deploy config, or `{ resources: {} }` when nothing was registered. Never throws.
-
-### `isDeployConfigRegistered(): boolean`
-
-Non-throwing guard. Used by router / boot probes that need a real registration before behaving differently from the empty default.
-
-## API Reference — Services Config
-
-### `registerServicesConfig(config: ServicesConfigShape): ServicesConfigShape`
-
-**Signature:**
-```typescript
-export const registerServicesConfig = (config: ServicesConfigShape): ServicesConfigShape
-```
-
-**Parameters:**
-| Name | Type | Required | Description |
-|---|---|---|---|
-| `config` | `ServicesConfigShape` | yes | `{ services, presets }` — services define folder sources, presets bundle multiple services into one artifact. |
-
-**Returns:** The stored config.
-
-**Behavior:**
-- Stores the config (last-write-wins).
-- Side-effect pattern: the consumer's `services.config.ts` is expected to call this on module import.
-
-### `getServicesConfig(): ServicesConfigShape`
-
-**Throws** `Error` when no services config has been registered. Message includes guidance to import `services.config.ts` as a side-effect.
-
-### `isServicesConfigRegistered(): boolean`
-
-Non-throwing guard for code that wants to fall back instead of crashing.
-
-## API Reference — Avatar Config
-
-### `registerAvatarConfig(config: AvatarConfigInput): void`
-
-**Signature:**
-```typescript
-export const registerAvatarConfig = (config: AvatarConfigInput): void
-```
-
-**Parameters:**
-| Name | Type | Required | Description |
-|---|---|---|---|
-| `config.formats` | `{ extension: string; contentType: string }[]` | no | Disk formats checked in order; first existing file wins. |
-| `config.cacheControl` | `string` | no | `Cache-Control` header. Default `'public, max-age=86400'`. |
-
-**Behavior:**
-- Empty `formats` array is treated as "use default" (keeps the built-in `[{ extension: 'webp', contentType: 'image/webp' }]`).
-- Missing `cacheControl` keeps the default.
-
-**Example:**
-```typescript
-import { registerAvatarConfig } from '@luckystack/core';
-
-registerAvatarConfig({
-  formats: [
-    { extension: 'webp', contentType: 'image/webp' },
-    { extension: 'png',  contentType: 'image/png'  },
-  ],
-  cacheControl: 'public, max-age=604800',
-});
-```
-
-### `getAvatarConfig(): AvatarConfig`
-
-Returns the active avatar config (defaults applied).
-
-### `DEFAULT_AVATAR_CONFIG: AvatarConfig`
-
-```typescript
-{
-  formats: [{ extension: 'webp', contentType: 'image/webp' }],
-  cacheControl: 'public, max-age=86400',
-}
-```
-
-## API Reference — Paths
-
-`paths.ts` exports lazy getters that resolve `projectConfig.paths.*` against `ROOT_DIR`. Read at call time so a late `registerProjectConfig({ paths: {...} })` still wins.
-
-| Function | Returns | Reads from |
-|---|---|---|
-| `getSrcDir()` | absolute path | `paths.srcDir` |
-| `getServerDir()` | absolute path | `paths.serverDir` |
-| `getSharedDir()` | absolute path | `paths.sharedDir` |
-| `getUploadsDir()` | absolute path | `paths.uploadsDir` |
-| `getPublicDir()` | absolute path | `paths.publicDir` |
-| `getServerFunctionsDir()` | absolute path | `paths.serverFunctionsDir` |
-| `getGeneratedSocketTypesPath()` | absolute path | `paths.generatedSocketTypes` |
-| `getGeneratedApiSchemasPath()` | absolute path | `paths.generatedApiSchemas` |
-| `getGeneratedApiDocsPath()` | absolute path | `paths.generatedApiDocs` |
-| `resolveFromRoot(...segments: string[])` | absolute path | `ROOT_DIR` + joined segments |
-
-`ROOT_DIR` is auto-detected by walking up from `process.cwd()` (then `__dirname`) and stopping at the first directory containing `package.json` plus either `tsconfig.json` or `tsconfig.server.json`. Falls back to `process.cwd()` when no marker is found.
-
-Deprecated module-level constants exist for backwards compatibility (`SRC_DIR`, `SERVER_DIR`, `SHARED_DIR`, `UPLOADS_DIR`, `PUBLIC_DIR`, `SERVER_FUNCTIONS_DIR`, `GENERATED_SOCKET_TYPES_PATH`, `GENERATED_API_SCHEMAS_PATH`, `GENERATED_API_DOCS_PATH`). These resolve at module load and ignore later `registerProjectConfig` overrides — prefer the getters for new code.
-
-## Config keys (top-level `ProjectConfig`)
-
-| Key | Type | Default | Description |
-|---|---|---|---|
-| `app.publicUrl` | `string` | `''` | Absolute origin of the deployment; consumed by OAuth callbacks and transactional email links. |
-| `logging.*` | flags | all `false` | Dev-only logging toggles. |
-| `rateLimiting.enabled` | `boolean` | `true` | Kill-switch — when `false`, every check short-circuits to allowed. |
-| `rateLimiting.store` | `'memory' \| 'redis'` | `'memory'` | Backend for the default strategy. |
-| `rateLimiting.windowMs` | `number` | `60000` | Default sliding window. |
-| `session.basedToken` | `boolean` | `false` | Internal project-config slot: `true` uses tab-scoped sessionStorage + bearer/handshake auth; `false` uses an HttpOnly cookie + CSRF. The scaffold's public `config.sessionBasedToken` field maps here during registration. |
-| `session.expiryDays` | `number` | `7` | Session TTL. |
-| `session.perUser` | `'single' \| 'multiple'` | `'single'` | Whether a single user may be logged in on multiple devices/browsers concurrently. |
-| `session.maxConcurrentPerUser` | `number \| null` | `null` | Cap when `perUser === 'multiple'`. |
-| `session.onConflict` | `'revokeOld' \| 'rejectNew'` | `'revokeOld'` | Policy when the cap is hit. |
-| `session.projectName` | `string` | `''` | Explicit Redis prefix; empty means fall back to `PROJECT_NAME` env. |
-| `http.sessionCookieName` | `string` | `'token'` | Cookie name read by `extractTokenFromSocket` / `extractTokenFromRequest`. |
-| `http.requestBodyMaxBytes` | `number` | `1048576` | Hard cap enforced by `getParams`. |
-| `http.healthEndpoint` | `string` | `'/_health'` | Router boot-handshake endpoint. |
-| `http.cors.allowedOrigins` | `string[] \| (origin: string) => boolean` | `[]` | Static allowlist or sync resolver. |
-| `http.cors.allowLocalhost` | `boolean` | `false` | Convenience flag for dev. |
-| `auth.bcryptRounds` | `number` | `10` | Hash cost factor. |
-| `auth.passwordPolicy.*` | rules | various | Credentials policy. |
-| `auth.forgotPassword` | `'framework' \| 'custom' \| 'disabled'` | `'disabled'` | Reset-flow ownership. |
-| `socket.maxHttpBufferSize` | `number` | `5MB` | Per-message ceiling. |
-| `sync.fanoutYieldEvery` | `number` | `100` | Recipients between event-loop yields. |
-| `offlineQueue.dropPolicy` | `'drop-oldest' \| 'drop-newest' \| 'reject'` | `'drop-oldest'` | Default eviction when full. |
-| `dev.hotReloadDebounceMs` | `number` | `120` | File-watcher debounce. |
-| `paths.*` | paths | see defaults table | Project filesystem layout. |
-| `defaultLanguage` | `string` | `'en'` | Initial language for new sessions. |
-| `socketActivityBroadcaster` | `boolean` | `false` | Enable presence broadcasts. |
-| `socketStatusIndicator` | `boolean` | `false` | Show the floating socket-status badge. |
-| `loginRedirectUrl` | `string` | `'/'` | Post-login destination. |
-
-See `packages/core/src/projectConfig.ts` for the full type definitions of `LoggingConfig`, `RateLimitingConfig`, `SessionConfig`, `HttpConfig`, `CorsConfig`, `SecurityHeadersConfig`, `AuthConfig`, `PasswordPolicyConfig`, `SocketConfig`, `SyncConfig`, `SyncStreamThrottleConfig`, `OfflineQueueConfig`, `DevConfig`, and `PathsConfig`.
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Architecture: `docs/ARCHITECTURE_PACKAGING.md`, `docs/ARCHITECTURE_ROUTING.md`
-- README: `packages/core/README.md`
-- Source: `packages/core/src/projectConfig.ts`, `deployConfigRegistry.ts`, `servicesConfigRegistry.ts`, `avatarConfig.ts`, `paths.ts`
+Cookie versus bearer session mode is a security choice, not a formatting choice. Switching modes affects CSRF, token extraction and persistence; audit those boundaries before changing it (`../src/extractToken.ts`, `../../server/src/httpRoutes/csrfMiddleware.ts`). Types and defaults belong to `../src/projectConfig.ts`, never a second hand-maintained table here.

package/docs/csrf-config.md

@@ -1,88 +1,5 @@
-# CSRF Config
+# CSRF configuration
 
-> Customise the framework's CSRF cookie name, header name, token length and cookie options without forking `@luckystack/server`. Source: `packages/core/src/csrfConfig.ts`.
+CSRF protects cookie-mode writes because browsers attach cookies without an explicit action from JavaScript. It does not replace the HTTP origin policy or authorization. Token-mode requests explicitly supply bearer credentials and follow a different boundary. See `../src/csrfConfig.ts`, `../src/csrf.ts`, `../../server/src/httpRoutes/csrfMiddleware.ts` and `../../server/docs/security-defaults.md`.
 
-## Overview
-
-LuckyStack has two cookie-mode CSRF branches. With `@luckystack/login`, the login package mints a per-session token and the server compares the configured request header with the session record. Without login, `GET /auth/csrf` issues a JavaScript-readable cookie and the server timing-safely compares that double-submit cookie with the header. Token/sessionStorage mode skips CSRF because the browser does not ambiently attach the bearer token. Use `registerCsrfConfig({ ... })` for external gateway conventions or a stronger token-length policy.
-
-| Setting | Default | Where it is consumed |
-|---|---|---|
-| `cookieName` | `'csrf-token'` | Login-absent double-submit issue and validation. |
-| `headerName` | `'x-csrf-token'` | Middleware reads `req.headers[headerName]`; `httpFetch` attaches it on writes. |
-| `tokenLength` | `32` (bytes) | Session-bound and login-absent token minting (`randomBytes(tokenLength).toString('hex')`). |
-| `cookieOptions.sameSite` | `'lax'` | Login-absent double-submit cookie. |
-| `cookieOptions.secure` | unset | Follows `SECURE=true` unless explicitly overridden. |
-| `cookieOptions.httpOnly` | `false` | Compatibility default. May be `true`: the client reads the token from the same-origin JSON response, not from `document.cookie`. |
-| `cookieOptions.path` | `'/'` | Double-submit cookie path. |
-| `cookieOptions.maxAgeMs` | `86_400_000` (1 day) | Double-submit cookie lifetime. |
-
-## API Reference
-
-### `registerCsrfConfig(input: Partial<CsrfConfig>): void`
-
-**Signature:**
-```typescript
-export interface CsrfConfig {
-  cookieName: string;
-  headerName: string;
-  tokenLength: number;
-  cookieOptions: CsrfCookieOptions;
-}
-export const registerCsrfConfig = (input: Partial<CsrfConfig>): void
-```
-
-**Behavior:** Shallow-merges `input` over the current config. `cookieOptions` is deep-merged so a partial override of `sameSite` does not clobber `path` / `maxAgeMs`. Last-write-wins.
-
-**Example — rename the header for an external gateway:**
-```typescript
-import { registerCsrfConfig } from '@luckystack/core';
-
-registerCsrfConfig({
-  headerName: 'x-xsrf-token',
-});
-```
-
-**Example — FIPS-grade token length + strict same-site:**
-```typescript
-import { registerCsrfConfig } from '@luckystack/core';
-
-registerCsrfConfig({
-  tokenLength: 64,
-  cookieOptions: { sameSite: 'strict' },
-});
-```
-
-### `getCsrfConfig(): CsrfConfig`
-
-Read the active config at call time. Framework code uses this — never read at module load.
-
-### `DEFAULT_CSRF_CONFIG: CsrfConfig`
-
-Exported so consumers can spread + override structurally:
-
-```typescript
-import { DEFAULT_CSRF_CONFIG, registerCsrfConfig } from '@luckystack/core';
-
-registerCsrfConfig({
-  ...DEFAULT_CSRF_CONFIG,
-  headerName: 'x-app-csrf',
-});
-```
-
-### `resetCsrfConfigForTests(): void`
-
-Test-only helper. Restore defaults between scenarios. Not part of the runtime contract.
-
-## What this does NOT change
-
-- The validation branch itself (session-bound comparison with login; timing-safe cookie/header comparison without login).
-- Token-mode session behaviour — token-mode sessions skip CSRF entirely (cross-origin requests don't auto-attach `sessionStorage`).
-- The framework's HTTP route paths (`GET /auth/csrf` is still the issuing endpoint).
-- The `csrfMismatch` hook fan-out — payload shape and timing are unchanged.
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Source: `packages/core/src/csrfConfig.ts`, `packages/core/src/csrf.ts`, `packages/server/src/httpRoutes/csrfMiddleware.ts`, `packages/login/src/session.ts`
-- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`, `packages/server/docs/security-defaults.md`
+Changing token/header or cookie policy must keep the issuer, browser helper and verifier in agreement. Do not exempt a state-changing route merely to avoid obtaining a token; a signed webhook exemption must authenticate independently. Consult `../src/csrfConfig.ts` for names and defaults.

package/docs/error-tracker-registry.md

@@ -1,194 +1,5 @@
-# Error Tracker Registry
+# Error tracker registry
 
-> Deep specs for the backend-agnostic error tracker registry + legacy Sentry slot. Source: `packages/core/src/errorTrackerRegistry.ts`, `errorTrackerIdentity.ts`, `sentrySetup.ts`. Bijgewerkt: 2026-07-16.
+A registry keeps framework request paths independent of any single observability backend. Capture fans out to adapters, but an adapter failure must not break an application request. Spans remain a single execution scope rather than nesting spans across all adapters. See `../src/errorTrackerRegistry.ts` and `../../error-tracking/src/adapter.ts`.
 
-## Overview
-
-The error tracker registry is the seam between framework code (which never imports a specific observability backend) and adapters for Sentry / Datadog / PostHog / etc. The slot lives in `@luckystack/core`; adapter implementations ship in `@luckystack/error-tracking`. Multiple adapters can be active at once via `registerErrorTrackers([...])` — every event fans out to all of them, and per-adapter errors are swallowed so one buggy tracker can't break the chain.
-
-The legacy `initSharedSentry(instance)` + `captureException` / `captureMessage` / `setSentryUser` / `startSpan` API predates the multi-adapter registry. It is kept for backwards compatibility and dual-fans events through both the legacy slot AND any adapters registered with the new API, so a project can migrate incrementally.
-
-`startSpanAcrossTrackers` deliberately invokes only the first adapter that supports `startSpan` — spans don't fan out cleanly because they're nested execution scopes.
-
-The fan-out registry and per-request identity scope are separate modules. The registry
-is browser-safe because `@luckystack/core/client` reaches it through its lazy capture
-path. `errorTrackerIdentity.ts` is server-only and owns `node:async_hooks`; API/sync
-handlers and server adapters reach those identity exports through the main core barrel.
-The core package build walks the emitted `dist/client.js` chunk graph and fails if any
-Node builtin becomes reachable, because source-level import checks cannot see tsup's
-cross-entry chunk coalescing.
-
-## Types
-
-```typescript
-export interface ErrorTrackerContext {
-  [key: string]: unknown;
-}
-
-export interface ErrorTrackerUser {
-  id?: string;
-  email?: string;
-  username?: string;
-  [key: string]: unknown;
-}
-
-export interface ErrorTrackerEvent {
-  forwarded: boolean;
-  kind: 'exception' | 'message';
-  payload: Record<string, unknown>;
-}
-
-export type SpanResult<T> = T;
-
-export interface ErrorTracker {
-  name: string;
-  captureException: (error: unknown, context?: ErrorTrackerContext) => void;
-  captureMessage: (
-    message: string,
-    level: 'info' | 'warning' | 'error' | 'fatal',
-    context?: ErrorTrackerContext,
-  ) => void;
-  setUser: (user: ErrorTrackerUser | null) => void;
-  setContext?: (key: string, context: ErrorTrackerContext | null) => void;
-  startSpan?: <T>(name: string, op: string, fn: () => T) => T;
-  recordMetric?: (name: string, value: number, tags?: Record<string, string>) => void;
-  beforeSend?: (event: ErrorTrackerEvent) => ErrorTrackerEvent | null;
-}
-```
-
-`SpanResult<T>` is an alias for `T` — the conditional unwrap collapsed in both branches and `tsup`'s dts emit choked on the widening. Kept as an exported alias so adapter authors can still annotate intent.
-
-## API Reference — Multi-Adapter Registry
-
-### `registerErrorTracker(tracker: ErrorTracker): void`
-
-**Behavior:** Replaces the active list with `[tracker]`. Use this for single-tracker setups.
-
-### `registerErrorTrackers(trackers: ErrorTracker[]): void`
-
-**Behavior:** Replaces the active list with a copy of the input array (`[...trackers]`). Use for multi-backend setups (Sentry + Datadog, etc.).
-
-### `getActiveErrorTrackers(): ErrorTracker[]`
-
-Returns the current array (the internal reference — treat as read-only).
-
-### `captureExceptionAcrossTrackers(error, context?): void`
-
-**Behavior:** For each active tracker, calls `tracker.captureException(error, context)` inside a per-tracker `try / catch` that silently swallows failures.
-
-### `captureMessageAcrossTrackers(message, level, context?): void`
-
-Same fan-out shape as `captureExceptionAcrossTrackers` for messages.
-
-### `setErrorTrackerUser(user: ErrorTrackerUser | null): void`
-
-Calls `tracker.setUser(user)` on every active tracker (errors swallowed).
-
-### `recordMetricAcrossTrackers(name, value, tags?): void`
-
-**Behavior:** Skips trackers that don't define `recordMetric`. Errors are swallowed.
-
-### `startSpanAcrossTrackers<T>(name, op, fn): T`
-
-**Behavior:**
-- Finds the first tracker with a `startSpan` method.
-- If found, returns `tracker.startSpan(name, op, fn)` cast to `T`.
-- If none exist, returns `fn()` directly (no instrumentation).
-
-**Why not fan-out:** Spans are nested execution scopes — invoking multiple `startSpan` implementations would nest each other and produce confusing traces.
-
-### Example — register multiple adapters
-
-```typescript
-import { registerErrorTrackers, type ErrorTracker } from '@luckystack/core';
-
-const sentryAdapter: ErrorTracker = { /* ... */ };
-const datadogAdapter: ErrorTracker = { /* ... */ };
-
-registerErrorTrackers([sentryAdapter, datadogAdapter]);
-```
-
-## API Reference — Per-request identity
-
-`runWithErrorTrackerIdentityScope(fn)` opens an empty AsyncLocalStorage scope before
-session lookup. `setCurrentErrorTrackerIdentity(user)` fills the mutable box once the
-session is known; `getCurrentErrorTrackerIdentity()` lets adapters read it without a
-process-global user. `runWithErrorTrackerIdentity(user, fn)` is the convenience form
-when the user is already known. Outside a scope, reads return `null` and writes are
-no-ops.
-
-These functions are server-only even though they are exported from the main core
-barrel. They are intentionally absent from `@luckystack/core/client`.
-
-## API Reference — Legacy Sentry Slot
-
-### `initSharedSentry(instance: SentryInstance): void`
-
-**Signature:**
-```typescript
-interface SentryInstance {
-  captureException: (exception: unknown, ...args: unknown[]) => string;
-  captureMessage: (message: string, ...args: unknown[]) => string;
-  setUser: (user: unknown) => void;
-  setContext: (key: string, context: unknown) => void;
-  startInactiveSpan?: (context: unknown) => unknown;
-}
-
-export const initSharedSentry = (instance: SentryInstance): void
-```
-
-**Behavior:** Stores the Sentry SDK instance in a module-level slot. New code should `registerErrorTracker(...)` from `@luckystack/error-tracking` instead.
-
-### `captureException(error, context?): void`
-
-**Behavior:**
-- When the legacy Sentry slot is populated, calls `sentry.captureException(error, { extra: context })` (or no second arg when no context).
-- ALSO calls `captureExceptionAcrossTrackers(error, context)` so any modern adapters receive the same event.
-
-**Concurrency note:** Context is passed inline via the hint-shaped second argument so contexts don't leak across concurrent captures. The previous implementation used `sentry.setContext('additional', context)` which was process-global and leaked under concurrent captures.
-
-### `captureMessage(message, level?, context?): void`
-
-**Behavior:** Mirror of `captureException` for messages. Level defaults to `'info'`.
-
-### `setSentryUser(user): void`
-
-Calls `sentry?.setUser(user)` and fans out via `setErrorTrackerUser(user)`.
-
-### `startSpan(name, op): unknown`
-
-**Behavior:**
-- If `sentry?.startInactiveSpan` exists, returns `sentry.startInactiveSpan({ name, op })`.
-- Otherwise falls back to `startSpanAcrossTrackers(name, op, () => undefined)` — useful when the project uses an adapter-only setup that supports spans.
-
-## Edge cases
-
-- All multi-adapter fan-out paths swallow per-tracker errors. There is no way to surface them — by design, since framework hot paths (`tryCatch`, hook dispatch) must never crash because of a misbehaving tracker.
-- `registerErrorTracker` and `registerErrorTrackers` replace the active list — call once at boot. There is no `unregister` API.
-- `beforeSend` and `forwarded` on `ErrorTrackerEvent` are advisory for adapter authors. Core does not call `beforeSend` itself; the adapter implementation is expected to honor it.
-
-## Example — minimal custom adapter
-
-```typescript
-import { registerErrorTracker, type ErrorTracker } from '@luckystack/core';
-
-const stdoutAdapter: ErrorTracker = {
-  name: 'stdout',
-  captureException: (error, context) => {
-    console.error('exception:', error, context);
-  },
-  captureMessage: (message, level, context) => {
-    console.log(`[${level}] ${message}`, context);
-  },
-  setUser: () => { /* no-op */ },
-};
-
-registerErrorTracker(stdoutAdapter);
-```
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`
-- README: `packages/core/README.md`, `packages/error-tracking/README.md`
-- Source: `packages/core/src/errorTrackerRegistry.ts`, `sentrySetup.ts`
+Request identity is scoped so concurrent requests cannot attribute errors to the wrong user; do not store it in a global mutable user slot. Sanitize context before it reaches adapters, including nested sensitive fields. The server-side scope must not enter browser bundles. See `../src/errorTrackerIdentity.ts`, `../src/redactedLogKeys.ts`, `../src/sentrySetup.ts`.