@zyno-io/ts-server-foundation 26.712.36

package/docs/content/migrations.md

@@ -0,0 +1,190 @@
+# Migrations
+
+TSF migrations are TypeScript files that compile to JavaScript and run against a `BaseDatabase`. The tooling can generate migrations from entity/schema differences, run pending migrations, reset source migrations to a base migration, and standardize MySQL charset/collation.
+
+## Migration Files
+
+Migration files export a function or a `Migration` object.
+
+```ts
+import { createMigration, sql } from '@zyno-io/ts-server-foundation';
+import type { BaseDatabase } from '@zyno-io/ts-server-foundation';
+
+export default createMigration(async (db: BaseDatabase) => {
+    await db.rawExecute(sql`
+        ALTER TABLE ${sql.identifier('users')}
+        ADD ${sql.identifier('archivedAt')} datetime NULL
+    `);
+});
+```
+
+You can also name a migration explicitly:
+
+```ts
+import { defineMigration } from '@zyno-io/ts-server-foundation';
+
+export const migration = defineMigration('20260630_120000_add_users', async db => {
+    await db.schema.create('users', table => {
+        table.integer('id').primary().autoIncrement();
+        table.string('email', 255);
+    });
+});
+```
+
+## Running Migrations In Code
+
+```ts
+import { loadMigrationsFromDirectory, MigrationRunner } from '@zyno-io/ts-server-foundation';
+
+const migrations = await loadMigrationsFromDirectory('dist/src/migrations');
+const executions = await new MigrationRunner(db).run(migrations);
+```
+
+`MigrationRunner` sorts migrations lexicographically by name, records completed migrations in `_migrations` by default, and skips recorded names on later runs. Each record contains `name`, `executedAt`, and `durationMs`; the returned `MigrationExecution[]` contains the migrations completed by that call.
+
+The constructor accepts a custom tracking-table name and logger. `run()` accepts a `beforeRun` callback:
+
+```ts
+import { MigrationRunner } from '@zyno-io/ts-server-foundation';
+
+const runner = new MigrationRunner(db, 'service_migrations');
+await runner.run(migrations, {
+    beforeRun: async migrationDb => {
+        await migrationDb.rawExecute('SET lock_timeout = 5000');
+    }
+});
+```
+
+`beforeRun` runs on the scoped migration connection before the tracking table is created or read. The runner then creates the tracking table if necessary, reads completed names, and executes pending migrations one at a time. A migration is recorded only after its `up` function succeeds.
+
+The runner scopes a connection but does not automatically wrap each migration in a transaction. If an `up` function fails, it logs the failure, stops immediately, does not record that migration, and does not run later migrations. Use `db.transaction()` inside a migration when the dialect and migration operations support transactional DDL and atomicity is required.
+
+Convenience functions:
+
+- `runMigrations(db, migrations, options?)` creates a default runner.
+- `runMigrationsFromDirectory(db, directory)` loads compiled files and runs them.
+- `loadMigrationsFromDirectory(directory)` only loads and normalizes migration exports.
+
+## CLI
+
+The `tsf-migrate` binary loads a compiled app module, resolves `BaseDatabase` from the app, and runs the selected command.
+
+```bash
+corepack yarn build
+corepack yarn tsf-migrate create --app dist/src/app.js --description add_users
+corepack yarn tsf-migrate run --app dist/src/app.js
+```
+
+Commands:
+
+| Command      | Description                                                                |
+| ------------ | -------------------------------------------------------------------------- |
+| `create`     | Creates a raw SQL migration from entity/database diff.                     |
+| `create:raw` | Alias for `create`.                                                        |
+| `run`        | Runs compiled migrations from the dist migrations directory.               |
+| `reset`      | Removes source migration files and creates a base migration from entities. |
+| `charset`    | Standardizes MySQL database/table charset and collation.                   |
+
+Options:
+
+| Option                               | Description                                            |
+| ------------------------------------ | ------------------------------------------------------ |
+| `--app <path>`                       | Compiled app module. Default `dist/src/app.js`.        |
+| `--description <text>` / `-d <text>` | Migration file description. Default `auto_migration`.  |
+| `--migrations-dir <path>`            | Source migration directory. Default `src/migrations`.  |
+| `--pg-schema <schema>`               | PostgreSQL schema for introspection.                   |
+| `--table <name>`                     | Limit diff generation to one table. Repeatable.        |
+| `--tables <a,b>`                     | Limit diff generation to a comma-separated table list. |
+
+## Diff Generation
+
+`createMigrationPlan(db, options)` compares entity metadata to the live database.
+
+```ts
+import { createMigrationPlan, writeMigrationFile } from '@zyno-io/ts-server-foundation';
+
+const plan = await createMigrationPlan(db, { tableNames: ['users'] });
+
+if (plan.hasChanges) {
+    writeMigrationFile(plan.statements, 'update_users');
+}
+```
+
+The generated plan includes:
+
+- added and removed tables
+- added, removed, modified, and renamed columns
+- primary key changes
+- indexes and unique indexes
+- foreign keys
+- MySQL enum definitions
+- PostgreSQL enum type changes
+- external foreign key drops/adds needed for scoped table changes
+
+Generated statements are dependency ordered. Existing inbound, removed, modified, or temporarily preserved foreign keys are dropped first. Table/column/index/primary-key work follows, and new or restored foreign keys are added after referenced structures exist.
+
+::: warning Review destructive changes
+Diff generation can emit `DROP TABLE`, `DROP COLUMN`, index/constraint drops, enum rewrites, type changes, and nullability changes. Renames are inferred only where the comparator has enough evidence; an intended rename can otherwise appear as a drop plus add. Read every generated migration, verify its table scope and PostgreSQL schema, and add any required data backfill or explicit rename before running it.
+:::
+
+`tableNames`/`--table` narrows entity and database comparison, but changes to referenced tables can still require temporary drops and restores of inbound foreign keys owned by tables outside that scope.
+
+## Schema Builder In Migrations
+
+Use `db.schema.create()` for hand-written table creation.
+
+```ts
+await db.schema.create('api_tokens', table => {
+    table.uuidString('id').primary();
+    table.string('name', 120);
+    table.string('tokenHash', 255).unique();
+    table.time('expiresAfterLocalTime').nullable();
+    table.dateTime('createdAt').defaultRaw('CURRENT_TIMESTAMP');
+});
+```
+
+Available column builders:
+
+`id`, `uuidString`, `uuid`, `string`, `char`, `text`, `tinyText`, `mediumText`, `longText`, `integer`, `tinyint`, `smallint`, `bigint`, `bigInteger`, `float`, `double`, `decimal`, `boolean`, `dateTime`, `timestamp`, `timestamptz`, `time`, `date`, `json`, `jsonb`, `binary`, `blob`, `enum`, and MySQL-only `point`.
+
+MySQL booleans are emitted as `tinyint(1) unsigned`; PostgreSQL booleans are emitted as `boolean`. Generated schema and entity index/foreign-key names are shortened with a stable hash when they exceed the active dialect identifier limit.
+
+Column modifiers include `primary`, `nullable`, `notNull`, `unsigned`, `autoIncrement`, `default`, `defaultRaw`, `onUpdate`, `index`, `unique`, `references`, `change`, `after`, and `first`. Table builders support primary, ordinary/unique/spatial indexes, and single/composite foreign keys. Alter builders also support column, index, foreign-key, and primary-key drops and renames.
+
+See [Database: Schema Builder](./database.md#schema-builder) for the complete database-level and builder API.
+
+## Reset
+
+`resetMigrations(db, options)` removes every `.ts` file from the source migration directory and writes `00000000_000000_base.ts` containing table creation DDL for all registered entities. Non-`.ts` files are left in place. If there are no registered entity tables, it creates the directory if needed but does not write a base migration.
+
+```ts
+import { resetMigrations } from '@zyno-io/ts-server-foundation';
+
+await resetMigrations(db, { migrationsDir: 'src/migrations' });
+```
+
+CLI:
+
+```bash
+corepack yarn tsf-migrate reset --app dist/src/app.js
+```
+
+::: warning
+`reset` permanently deletes the source `.ts` migration files in the selected directory before writing the base file. Commit or back up migrations first, and verify `--migrations-dir` before running it.
+:::
+
+## MySQL Charset
+
+```bash
+corepack yarn tsf-migrate charset utf8mb4 utf8mb4_0900_ai_ci --app dist/src/app.js
+```
+
+The charset command is MySQL/MariaDB-only. PostgreSQL databases are skipped.
+
+## Loading Directories
+
+`loadMigrationsFromDirectory()` accepts a source or dist directory. When a source path under `src/` is passed and compiled files exist under `dist/src/`, it resolves the dist path automatically.
+
+Supported compiled file extensions are `.js`, `.cjs`, and `.mjs`.
+
+A module may export a migration function or `Migration` object as either `default` or `migration`. Function exports use the compiled filename without its extension as the migration name. An invalid module stops directory loading with an error.

package/docs/content/openapi.md

@@ -0,0 +1,134 @@
+# OpenAPI
+
+OpenAPI generation is built from registered HTTP routes and reflected type metadata. The generator reads the same route parameter plan used by the HTTP router, so explicit controller annotations matter.
+
+## Document Identity And Operations
+
+`serializeOpenApiSchema()` defaults `info.title` and `info.version` to the cached package metadata first read from `process.cwd()/package.json`, falling back to `API` and `0.0.0`. Call `resetPackageJsonCache()` after changing the working directory, or override either value explicitly:
+
+```ts
+const document = serializeOpenApiSchema(app, {
+    title: 'Users API',
+    version: '2.1.0'
+});
+```
+
+Every operation receives a tag derived from its controller class name: the `Controller` suffix is removed and the remainder is camel-cased.
+
+## Controller Parameters
+
+Controller parameters are explicit, except path parameters whose parameter name matches a URL token.
+
+```ts
+import { ApiResponse, HttpBody, HttpPath, HttpQueries, HttpQuery, http } from '@zyno-io/ts-server-foundation';
+
+class ListUsersQuery {
+    includePosts?: boolean;
+    limit!: number;
+}
+
+class CreateUserBody {
+    name!: string;
+}
+
+class UserDto {
+    id!: number;
+    name!: string;
+}
+
+@http.controller('/users')
+class UserController {
+    @http.GET()
+    async list(query: HttpQueries<ListUsersQuery>): Promise<UserDto[]> {
+        return [];
+    }
+
+    @http.GET('/:id')
+    async get(id: HttpPath<number>, search?: HttpQuery<string, { name: 'q' }>): Promise<UserDto> {
+        return { id, name: search ?? '' };
+    }
+
+    @http.POST()
+    async create(body: HttpBody<CreateUserBody>): ApiResponse<UserDto, 201> {
+        return { id: 1, name: body.name };
+    }
+}
+```
+
+`HttpQueries<T>` expands class or object properties into query parameters. Required properties of `T` are required query parameters only when the aggregate controller parameter is required. For `query?: HttpQueries<T>`, OpenAPI marks every expanded parameter optional because the whole aggregate may be omitted; at runtime, supplying any query value still validates the resulting object as `T`, including its required properties. `HttpQuery<T>` documents one query parameter. `HttpBody<T>` becomes a JSON request body unless the reflected body contains file uploads. A route may declare only one `HttpBody<T>` parameter; multiple body parameters fail route registration.
+
+The first paragraph of a route method's JSDoc becomes the OpenAPI operation `summary`. Later paragraphs and JSDoc tags are not included.
+
+Bodies with a required `FileUpload` are documented only as `multipart/form-data`. If every file in the body is optional or nullable, the same schema is exposed for both `application/json` and `multipart/form-data`, allowing requests that omit the files to remain ordinary JSON. A standalone `FileUpload` controller parameter always makes the operation multipart; required and optional standalone parameters are reflected in the multipart schema and request-body requiredness. File constraints are emitted as `x-maxSizeBytes`, `x-allowedTypes`, and multipart encoding content types.
+
+File requiredness is discovered recursively for OpenAPI media-type selection. A required nested object containing a required file therefore makes the body multipart-only, while an optional nested object permits both JSON and multipart schemas. This is schema behavior only: the runtime multipart parser assigns file parts to top-level fields, so flatten upload DTO properties instead of relying on automatic population of `nested.file`.
+
+## Responses
+
+`ApiResponse<T, Status>` documents and emits a JSON response with the given status. The status defaults to `200`, so `ApiResponse<UserDto>` is equivalent to `ApiResponse<UserDto, 200>`.
+
+Plain `Promise<T>` return types document and emit a `200` JSON response. `OkResponse`, `AnyResponse`, `JsonResponseResult`, `RawResponseResult`, `RedirectResponseResult`, and `EmptyResponseResult` keep their existing OpenAPI behavior.
+
+An operation with a required `ParsedJwt` parameter receives `security: [{ bearerAuth: [] }]`, and the document gains an HTTP bearer security scheme with JWT format. An optional `ParsedJwt` does not mark the operation as requiring bearer authentication. Runtime authentication may also read the configured JWT cookie, but the generated document currently advertises only the Bearer mechanism.
+
+## Operation IDs
+
+Operation IDs are camel-cased from the lowercase HTTP method, the controller class name without its `Controller` suffix, and the handler method name. Keep all three stable when generated clients depend on operation IDs.
+
+## Internal Routes
+
+Generated documents exclude internal routes by default:
+
+- `/openapi.json`
+- `/openapi.yaml`
+- `/_devconsole`
+- `/healthz`
+- `/metrics`
+
+Call `serializeOpenApiSchema(app, { includeInternal: true })` if a tool needs the full internal route list.
+
+## Runtime Routes
+
+In development and test mode, the app serves:
+
+- `/openapi.json`
+- `/openapi.yaml`
+
+Route exposure follows this precedence:
+
+| Configuration                               | Result                                              |
+| ------------------------------------------- | --------------------------------------------------- |
+| `ENABLE_OPENAPI_ROUTE=1`                    | Routes enabled in every environment.                |
+| `ENABLE_OPENAPI_ROUTE=0`                    | Routes disabled in every environment.               |
+| Route flag unset, `ENABLE_OPENAPI_SCHEMA=1` | Legacy fallback enables routes.                     |
+| Route flag unset, `ENABLE_OPENAPI_SCHEMA=0` | Legacy fallback disables routes.                    |
+| Both unset                                  | Enabled in development/test and disabled elsewhere. |
+
+The explicit route flag always wins when it conflicts with the legacy schema flag. Both `/openapi.json` and `/openapi.yaml` use the same decision.
+
+## Startup YAML Dump
+
+In development, TSF writes `openapi.yaml` to the current working directory after startup unless `NODE_TEST_CONTEXT` identifies a Node test process. Test and production environments do not dump by default.
+
+`ENABLE_OPENAPI_SCHEMA=1` explicitly enables the dump in any environment, including a Node test context; `ENABLE_OPENAPI_SCHEMA=0` explicitly suppresses it. This flag directly controls writing the file and acts as the legacy route-exposure fallback only when `ENABLE_OPENAPI_ROUTE` is unset.
+
+## Explicit Generation
+
+Generate the schema without starting a long-running server:
+
+```bash
+tsf-dev openapi:generate
+tsf-dev openapi:generate -p tsconfig.json
+```
+
+The command builds the project and runs its package `main` as `node . openapi:generate`. The built-in `App.run()` command writes `openapi.yaml` in the project working directory without starting a long-running server. It uses the same registered route graph as the application; no separate app-module or export selection is needed.
+
+Programmatic generation is also available:
+
+```ts
+import { dumpOpenApiSchema, serializeOpenApiSchema, serializeOpenApiYaml } from '@zyno-io/ts-server-foundation';
+
+const document = serializeOpenApiSchema(app, { includeInternal: false });
+const yaml = serializeOpenApiYaml(app);
+await dumpOpenApiSchema(app, { path: 'openapi.yaml' });
+```

package/docs/content/overview.md

@@ -0,0 +1,98 @@
+# Feature Overview
+
+TS Server Foundation is an application runtime and toolkit for TypeScript services. It combines its own reflected type metadata, dependency injection, HTTP runtime, database layer, operational services, and development tools behind one package. The detailed guides are the source of truth; this page is the map of what the package provides and how the pieces fit together.
+
+The project is built and maintained primarily for Zyno Consulting's own production systems. We publish it openly in the hope that it is useful to others, while its roadmap and maintenance priorities remain guided by the needs of those systems rather than a promise of general-purpose framework support.
+
+## Application Foundation
+
+`createApp()` assembles a service from explicit configuration, controllers, providers, listeners, modules, and an optional database. It owns application startup, HTTP startup, signal handling, workers, DevConsole, health checks, and orderly shutdown.
+
+| Area | Included behavior | Detailed guide |
+| --- | --- | --- |
+| Application lifecycle | Bootstrap and shutdown events, signal handling, idempotent start/stop, and rollback after failed startup | [Dependency Injection](./di.md#application-lifecycle) |
+| Dependency injection | Constructor injection, value/class/factory providers, singleton/request/transient scopes, modules, and global exports | [Dependency Injection](./di.md) |
+| Configuration | Reflected config classes, env-file loading, typed coercion, encrypted `_SECRET` values, and environment snapshots | [Configuration](./configuration.md), [Environment](./env.md) |
+| Type reflection | Runtime type metadata, annotations, custom validators, custom deserializers, aliases, and compiler boundaries | [Type Reflection](./reflection.md), [Architecture](./type-reflection-architecture.md) |
+| CLI and scaffolding | App creation, TypeScript 7 compiler setup, build/watch/run workflows, tests, migrations, OpenAPI, and proto generation | [CLI Tools](./cli.md) |
+
+Use constructor injection inside application code. `resolve()` and its `r()` alias are available for app-level code that cannot receive a constructor dependency. Register `@AutoConstruct()` classes as providers when they must be created during startup.
+
+## HTTP And API Contracts
+
+TSF owns its HTTP router and request pipeline. Controllers use decorators for routing and explicit reflected annotations for wire inputs.
+
+| Area | Included behavior | Detailed guide |
+| --- | --- | --- |
+| HTTP routing | Controllers, exact methods, path parameters, middleware, CORS, workflows, static files, upgrades, and in-memory requests | [HTTP](./http.md) |
+| Inputs | Body/query/path/header annotations, reflected coercion and validation, custom parameter resolvers, and request-scoped caching | [HTTP](./http.md#parameter-injection) |
+| Uploads and streams | Guarded multipart files, size/MIME constraints, temporary-file cleanup, compressed bodies, and raw request streams | [Uploads](./uploads.md) |
+| Responses and errors | JSON/raw/redirect/empty results, response annotations, normalized HTTP errors, and streaming responses | [HTTP](./http.md#responses) |
+| OpenAPI | Schemas generated from the same reflected metadata used by validation, explicit response status types, runtime routes, and YAML generation | [OpenAPI](./openapi.md) |
+| Authentication | HS256/EdDSA JWTs, entity auth middleware, custom resolvers, Basic auth, password hashing, and reset tokens | [Authentication](./authentication.md) |
+
+The HTTP input pipeline deserializes and validates reflected values before controller invocation. Controller outputs use ordinary JSON serialization; OpenAPI response types describe the contract but do not add runtime output validation.
+
+## Database And Persistence
+
+The database layer is a thin active-record and query system over `mysql2` and `pg`, with dialect-aware schema and migration tooling.
+
+| Area | Included behavior | Detailed guide |
+| --- | --- | --- |
+| Databases and entities | MySQL/PostgreSQL adapters, reflected entity schemas, column conversion, active-record helpers, and retrieval APIs | [Database](./database.md) |
+| Queries | Typed filters, joins, selection, paging, patch/delete operations, relations, batched loading, and query observation | [Database](./database.md#query-builder) |
+| Sessions | Transactions, nested savepoints, post-commit/post-rollback hooks, and dialect-specific session locks | [Database](./database.md#sessions-and-transactions) |
+| SQL | Safe values and identifiers, composable fragments, raw database methods, and explicit unsafe escape hatches | [SQL](./sql.md) |
+| Schema and migrations | Multi-dialect schema builder, live-schema diffs, generated migration files, runners, reset, charset, and PostgreSQL schemas | [Migrations](./migrations.md) |
+| Storage annotations | UUIDs, defaults, update expressions, unsigned values, lengths, dates, coordinates, indexes, and references | [Types](./types.md) |
+
+Database I/O performs column-aware storage conversion rather than the HTTP input validation pipeline. Database constraints enforce storage rules; call the reflected validation helpers explicitly when application code needs API-style validation outside HTTP.
+
+## Background And Distributed Services
+
+| Area | Included behavior | Detailed guide |
+| --- | --- | --- |
+| Workers | BullMQ queues, in-process tests, inline execution, cron jobs, dedicated runners, execution records, observers, and DevConsole inspection | [Workers](./worker.md) |
+| Redis | Client configuration, cache helpers, distributed mutexes, broadcasts, and distributed methods | [Redis](./redis.md) |
+| Leader election | Redis-backed ownership with renewal, loss callbacks, and failover | [Leader Service](./leader-service.md) |
+| Mesh | Typed cross-node requests, responses, broadcasts, membership, heartbeats, and leader-backed cleanup | [Mesh Service](./mesh-service.md) |
+| Client tracking | Cross-node client reservation, activation, metadata, lookup, targeted calls, broadcasts, and SRPC integration | [Mesh Client Tracking](./mesh-client.md) |
+| SRPC | HMAC-authenticated bidirectional WebSocket RPC, protobuf codecs, duplicate-client policy, reconnects, observers, and byte streams | [SRPC](./srpc.md) |
+| Mail | SMTP/Postmark providers, direct and template messages, prepared messages, and typed templates | [Mail](./mail.md) |
+
+Redis is feature-dependent, not a requirement for the base HTTP application. Configure it when enabling BullMQ workers, mutexes, caches, broadcasts, leader election, or mesh services.
+
+## Operations And Development
+
+| Area | Included behavior | Detailed guide |
+| --- | --- | --- |
+| Health | `/healthz`, application version, built-in database checks, custom checks, and individual results | [Health Checks](./health.md) |
+| Logging | Scoped Pino loggers, async context, structured errors, custom sinks, HTTP request modes, and Sentry forwarding | [Logging](./logging.md) |
+| Telemetry | OpenTelemetry HTTP/Undici/DNS/Redis/MySQL/PostgreSQL instrumentation, OTLP export, Prometheus metrics, spans, and Sentry | [Telemetry](./telemetry.md) |
+| DevConsole | Local-only routes, OpenAPI, requests, SRPC, database queries/entities, health, mutex, worker, environment, and REPL views | [DevConsole](./devconsole.md) |
+| Testing | Node test runner, app facades, in-memory HTTP, MySQL/PostgreSQL isolation, savepoints, migrations, fixtures, mocks, and assertions | [Testing](./testing.md) |
+| Helpers | Async/process tools, data transforms, JSON, streams, resource cleanup, crypto, validation, dates, UUIDs, errors, and Redis helpers | [Helpers](./helpers.md) |
+
+## Process Model
+
+The generated application exports an `App` through its package entrypoint and accepts explicit runtime commands:
+
+```bash
+node . server:start       # HTTP/API process
+node . worker:start       # dedicated worker process, with health listener
+node . migrate:run        # release-time migrations
+node . openapi:generate   # write openapi.yaml without starting HTTP
+```
+
+Production deployments should build once, run migrations as a release step, and separate API and worker processes when workers are enabled. Normal production server processes do not start the worker runner unless `ENABLE_JOB_RUNNER=true`; `worker:start` forces runner ownership.
+
+`APP_ENV` is required when `NODE_ENV=production`. Tests run with `APP_ENV=test` and `TZ=UTC`. Database date and timestamp formatting uses UTC, but TSF does not force the timezone of an arbitrary server process; set `TZ=UTC` in the deployment environment when the whole application must run in UTC.
+
+In development, DevConsole is available at `/_devconsole/` after the app listens. Its localhost socket check is the security boundary, so do not expose or proxy it to untrusted clients.
+
+## Start Here
+
+- Follow [Getting Started](./getting-started.md) to scaffold or configure an application.
+- Use the [Documentation Index](./README.md) for the complete page list.
+- Check [Public API](./public-api.md) before adding imports from internal paths.
+- Use [Release](./release.md) for build, docs, package, and versioning checks.

package/docs/content/public-api.md

@@ -0,0 +1,84 @@
+# Public API
+
+The package intentionally exposes a small package-level import surface:
+
+- `@zyno-io/ts-server-foundation` for application APIs
+- `@zyno-io/ts-server-foundation/otel` for OpenTelemetry bootstrap
+
+Feature-folder subpaths such as `/http`, `/database/sql`, `/testing`, `/services/logger`, and `/telemetry/sentry` are not exported. Import application APIs from the package root:
+
+```ts
+import { App, BaseDatabase, HttpBody, HttpRequest, TestingHelpers, createApp, http, sql } from '@zyno-io/ts-server-foundation';
+```
+
+The root export is the supported application surface. Internal file layout can change without becoming a package-level breaking contract.
+
+## Root Export Reference
+
+The root barrel groups the supported APIs below. The examples are representative named exports, not separate import paths.
+
+| Area                        | Representative root exports                                                                                                                | Guide                                   |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
+| Application and commands    | `App`, `createApp`, `BaseAppConfig`, `AppModule`, `createModule`, `AutoConstruct`, lifecycle tokens, `cli`                                 | [Getting Started](./getting-started.md) |
+| Dependency injection/events | `Container`, provider types, `resolve`, `EventBus`, `EventToken`, `event`                                                                  | [Dependency Injection](./di.md)         |
+| HTTP and uploads            | `http`, `HttpRequest`, `HttpResponse`, `HttpMiddleware`, `FileUpload`, HTTP errors, request/response workflow tokens                       | [HTTP](./http.md)                       |
+| Authentication and health   | `JWT`, `ParsedJwt`, `Auth`, auth middleware helpers, `HealthcheckService`, `HealthcheckController`                                         | [Authentication](./authentication.md)   |
+| Reflection and validation   | `typeOf`, `ReflectionClass`, `ReflectionKind`, annotation readers, `deserialize`, `validate`, `validatedDeserialize`, registries           | [Type Reflection](./reflection.md)      |
+| Shared types                | HTTP wrapper types, database markers, validation tags, `DateString`, `UuidString`, `PhoneNumber`, `TrimmedString`, utility types           | [Types](./types.md)                     |
+| Database, SQL, migrations   | `BaseDatabase`, `BaseEntity`, `DatabaseSession`, query/relation helpers, `sql`, schema builders, migration runner/diff/maintenance helpers | [Database](./database.md)               |
+| General and Redis helpers   | Async context, process/promise/data/stream/security/date/error/UUID helpers, `Cache`, Redis/broadcast/mutex helpers                        | [Helpers](./helpers.md)                 |
+| Logging and services        | Logger APIs, workers, leader election, mail, mesh, and mesh-client tracking                                                                | [Logging](./logging.md)                 |
+| SRPC                        | `SrpcClient`, `SrpcServer`, `SrpcByteStream`, handlers, errors, and observers                                                              | [SRPC](./srpc.md)                       |
+| OpenAPI                     | `serializeOpenApiSchema`, `serializeOpenApiYaml`, `dumpOpenApiSchema`, schema inspection helpers and document types                        | [OpenAPI](./openapi.md)                 |
+| Telemetry and Sentry        | Span/context helpers plus `installSentry`, `flushSentry`, and related state helpers                                                        | [Telemetry](./telemetry.md)             |
+| DevConsole                  | Controller/runtime/store, local-only middleware, observers, and inspection helpers                                                         | [DevConsole](./devconsole.md)           |
+| Testing                     | `TestingFacade`, facade builders, mock-request helpers, fixtures, expectations, and `TestingHelpers`                                       | [Testing](./testing.md)                 |
+
+The emitted `.d.ts` file is the authoritative symbol-level reference. Package tests compile representative imports from every group and verify that the package export map exposes only `.` and `./otel`.
+
+## OpenTelemetry Bootstrap
+
+OpenTelemetry instrumentation must be initialized before most other imports. Use the dedicated subpath for that early import:
+
+```ts
+import { init } from '@zyno-io/ts-server-foundation/otel';
+
+init();
+
+const { createApp } = await import('@zyno-io/ts-server-foundation');
+```
+
+Sentry helpers, span helpers, HTTP helpers, database helpers, testing helpers, and service classes are exported from the root package.
+
+The `/otel` subpath exports `init`, `shutdownTelemetry`, `resetTelemetryForTests`, `TelemetryInitOptions`/`IOtelOptions`, the HTTP attribute-hook type, and the OTel state/span helpers. `init` is intentionally absent from the root so a bootstrap import does not first load the rest of the application package. Conversely, service/database/HTTP APIs are not exported from `/otel`.
+
+## Application Boundary
+
+`App` owns application lifecycle, DI, config, and command entrypoints. HTTP server APIs live under `app.http`:
+
+```ts
+const app = createApp({ controllers: [UsersController] });
+
+await app.http.listen(3000, '127.0.0.1');
+app.http.registerUpgradeHandler(handler);
+app.http.registerObserver(entry => {
+    // observe completed HTTP requests
+});
+
+await app.stop();
+```
+
+Application entrypoints should normally call `app.run()`, which requires an explicit built-in or registered command such as `server:start` or `openapi:generate`:
+
+```ts
+if (require.main === module) {
+    void app.run();
+}
+```
+
+```bash
+node . server:start
+node . openapi:generate
+```
+
+HTTP server APIs live under `app.http` so the base application class remains focused on lifecycle, DI, config, and command dispatch.