@luckystack/core 0.1.0

package/docs/config-registry.md

@@ -0,0 +1,350 @@
+# Config Registry
+
+> Deep specs for project / deploy / services / avatar / paths config slots. Source: `packages/core/src/`. Bijgewerkt: 2026-05-20.
+
+## 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.perBrowser` | `'single'` |
+| `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` | When `true`, tokens are stored in sessionStorage + handshake auth instead of cookies. |
+| `session.expiryDays` | `number` | `7` | Session TTL. |
+| `session.perBrowser` | `'single' \| 'multiple'` | `'single'` | Whether a single browser may hold multiple parallel logins. |
+| `session.perUser` | `'single' \| 'multiple'` | `'single'` | Whether a single user may be logged in on multiple devices 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`

package/docs/csrf-config.md

@@ -0,0 +1,88 @@
+# CSRF Config
+
+> Customise the framework's CSRF cookie name, header name, token length and cookie options without forking `@luckystack/server`. Source: `packages/core/src/csrfConfig.ts`. Bijgewerkt: 2026-05-21.
+
+## Overview
+
+LuckyStack's CSRF defense is double-submit: on first session write, the login package mints a per-session token; the server reads it from the session record on every state-changing request and compares it against the value the browser sends in a request header. Consumers who need to integrate with an external framework expectation (legacy `x-xsrf-token`, a custom auth gateway that rewrites cookies, FIPS-grade token length) override the defaults via `registerCsrfConfig({ ... })`.
+
+| Setting | Default | Where it is consumed |
+|---|---|---|
+| `cookieName` | `'csrf-token'` | Reserved for future cookie-issued tokens (current double-submit uses session record). |
+| `headerName` | `'x-csrf-token'` | Server: `csrfMiddleware.ts` reads `req.headers[headerName]`. Client: `httpFetch` attaches `headerName` on state-changing requests. |
+| `tokenLength` | `32` (bytes) | Session mint in `packages/login/src/session.ts` (`randomBytes(tokenLength).toString('hex')`). |
+| `cookieOptions.sameSite` | `'lax'` | Cookie attributes if/when the framework migrates to cookie-issued tokens. |
+| `cookieOptions.secure` | `true` | Same. |
+| `cookieOptions.httpOnly` | `false` | MUST be false for CSRF cookies — clients need to read the value. |
+| `cookieOptions.path` | `'/'` | Same. |
+| `cookieOptions.maxAgeMs` | `86_400_000` (1 day) | Same. |
+
+## 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 double-submit comparison logic itself (`csrfSession.csrfToken === provided`).
+- 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`

package/docs/error-tracker-registry.md

@@ -0,0 +1,174 @@
+# Error Tracker Registry
+
+> Deep specs for the backend-agnostic error tracker registry + legacy Sentry slot. Source: `packages/core/src/errorTrackerRegistry.ts`, `sentrySetup.ts`. Bijgewerkt: 2026-05-20.
+
+## 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.
+
+## 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 — 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`