@zyno-io/ts-server-foundation 26.712.36

package/docs/content/types.md

@@ -0,0 +1,286 @@
+# Types
+
+Custom type annotations integrate with reflected type metadata, validation, deserialization, OpenAPI, and the migration generator.
+
+Import them from the package root:
+
+```ts
+import {
+    DateString,
+    EmailAddress,
+    GreaterThan,
+    Length,
+    OptionalNulls,
+    PhoneNumber,
+    TrimmedString,
+    UUID,
+    UuidString
+} from '@zyno-io/ts-server-foundation';
+```
+
+The important distinction is that not every type affects every layer. Some types only validate input, some only change generated database schema, and some do both.
+
+In the table below, runtime validation/deserialization means the explicit reflection helpers and automatic HTTP input pipeline. Entity creation and database saves do not automatically run these validators or deserialization transforms; database-specific runtime conversion is documented in [Database](./database.md#runtime-value-conversion-and-validation).
+
+## Type Utility Helpers
+
+### `OptionalNulls<T>`
+
+`OptionalNulls<T>` makes properties optional when their type includes `null`, while leaving non-nullable properties required.
+
+```ts
+class DbEntity extends BaseEntity {
+    name!: string;
+    color!: string | null;
+}
+
+type ControllerDto = OptionalNulls<Pick<DbEntity, 'name' | 'color'>>;
+// { name: string; color?: string | null }
+```
+
+## Storage And Schema Effects
+
+| Type                      | Runtime validation/deserialization                                      | Migration column                                                   | OpenAPI schema                                |
+| ------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------- |
+| `DateString`              | Validates `YYYY-MM-DD`.                                                 | `date` on MySQL and PostgreSQL.                                    | `string`, `format: date`.                     |
+| `UuidString`              | Validates UUID-formatted strings.                                       | MySQL `char(36)`, PostgreSQL `uuid`.                               | `string`, `format: uuid`.                     |
+| `UUID`                    | Validates UUID-formatted strings.                                       | MySQL `binary(16)`, PostgreSQL `uuid`.                             | `string`, `format: uuid`.                     |
+| `PhoneNumber`             | Normalizes to E.164 and rejects invalid phones.                         | `varchar(20)`.                                                     | `string`.                                     |
+| `PhoneNumberNANP`         | Normalizes to NANP digits without `+1` and rejects invalid phones.      | `varchar(20)`.                                                     | `string`.                                     |
+| `Length<N>`               | `MinLength<N>` and `MaxLength<N>`.                                      | `char(N)`.                                                         | `string` with `minLength: N`, `maxLength: N`. |
+| `string & MaxLength<N>`   | `maxLength` validation.                                                 | `varchar(N)`.                                                      | `string` with `maxLength: N`.                 |
+| `TrimmedString`           | Trims during deserialization.                                           | Normal string mapping unless combined with another annotation.     | Normal string schema.                         |
+| `NonEmptyTrimmedString`   | Trims and applies `MinLength<1>`.                                       | Normal string mapping unless combined with another annotation.     | `string` with `minLength: 1`.                 |
+| `EmailAddress`            | Regex validation.                                                       | Normal string mapping unless combined with another annotation.     | `string` with the email regex pattern.        |
+| `number & GreaterThan<N>` | Rejects values `<= N`.                                                  | MySQL numeric columns are unsigned when the lower bound is `>= 0`. | `number` with `exclusiveMinimum: N`.          |
+| `number & LessThan<N>`    | Rejects values `>= N`.                                                  | Does not choose a column type.                                     | `number` with `exclusiveMaximum: N`.          |
+| `ValidDate`               | Rejects `Invalid Date` values.                                          | Normal `Date` mapping: MySQL `datetime`, PostgreSQL `timestamp`.   | `string`, `format: date-time`.                |
+| `UnsignedNumber`          | `Minimum<0>` validation.                                                | MySQL numeric columns are unsigned when the minimum is `>= 0`.     | `number` with `minimum: 0`.                   |
+| `MySQLCoordinate`         | `Coordinate` object shape.                                              | MySQL `point`.                                                     | Normal object schema.                         |
+| `NullableMySQLCoordinate` | `Coordinate \| null` object shape.                                      | MySQL `point`, nullable.                                           | Normal nullable object schema.                |
+| `HasDefault`              | Marks undefined values as omittable for entity creation/insert helpers. | Does not choose a column type.                                     | No OpenAPI effect.                            |
+| `OnUpdate<T>`             | No runtime validation.                                                  | Adds the column `ON UPDATE` expression where supported.            | No OpenAPI effect.                            |
+
+For fixed-width storage, use `Length<N>`. For variable-width storage, use `string & MaxLength<N>`.
+
+## Strings
+
+### `TrimmedString` and `NonEmptyTrimmedString`
+
+`TrimmedString` trims incoming string values during reflected deserialization. `NonEmptyTrimmedString` also applies `MinLength<1>`.
+
+These types do not change the database column type by themselves. In an entity, they still use the normal string mapping unless combined with `Length<N>`, `MaxLength<N>`, or a database annotation.
+
+```ts
+import { NonEmptyTrimmedString, TrimmedString } from '@zyno-io/ts-server-foundation';
+
+class UserInput {
+    name!: NonEmptyTrimmedString;
+    notes!: TrimmedString;
+}
+```
+
+### `EmailAddress`
+
+`EmailAddress` validates against the project email regex and emits that pattern into OpenAPI.
+
+It does not imply a database-specific email column type. In an entity it maps like a normal string, so add `MaxLength<N>` when the column size matters.
+
+```ts
+import { EmailAddress } from '@zyno-io/ts-server-foundation';
+import { MaxLength } from '@zyno-io/ts-server-foundation';
+
+class User {
+    email!: EmailAddress & MaxLength<255>;
+}
+```
+
+### `Length<N>`
+
+`Length<N>` is a fixed-length string type. It is implemented as `MinLength<N> & MaxLength<N>` plus a TSF marker annotation, so validation, OpenAPI, and the migration type mapper can all read it.
+
+In generated migrations, `Length<6>` becomes `char(6)`. If you want `varchar(6)`, use `string & MaxLength<6>` instead.
+
+```ts
+import { Length } from '@zyno-io/ts-server-foundation';
+
+class VerificationCode {
+    code!: Length<6>; // char(6)
+}
+```
+
+## Dates
+
+### `DateString`
+
+`DateString` validates `YYYY-MM-DD`, maps to a database `date` column, and appears in OpenAPI as a date string.
+
+Use this for calendar dates without a time. Use `Date` or `ValidDate` for timestamps.
+
+```ts
+import { DateString } from '@zyno-io/ts-server-foundation';
+
+class Event {
+    date!: DateString; // date
+}
+```
+
+### `ValidDate`
+
+`ValidDate` rejects `Invalid Date` values during validation.
+
+It keeps normal `Date` storage semantics: MySQL `datetime`, PostgreSQL `timestamp`, and OpenAPI `string` with `format: date-time`.
+
+```ts
+import { ValidDate } from '@zyno-io/ts-server-foundation';
+
+class ScheduledTask {
+    startsAt!: ValidDate;
+}
+```
+
+## Phone Numbers
+
+Phone types use `google-libphonenumber` during deserialization and validation. In generated migrations, both phone types map to `varchar(20)`.
+
+### `PhoneNumber`
+
+International E.164 format with `+` prefix:
+
+```ts
+import { PhoneNumber } from '@zyno-io/ts-server-foundation';
+
+class Contact {
+    phone!: PhoneNumber; // '+12025550125'
+}
+```
+
+### `PhoneNumberNANP`
+
+North American Numbering Plan format without the `+1` prefix:
+
+```ts
+import { PhoneNumberNANP } from '@zyno-io/ts-server-foundation';
+
+class Contact {
+    phone!: PhoneNumberNANP; // '2025550125'
+}
+```
+
+### Utilities
+
+```ts
+import { cleanPhone, formatPhoneFriendly } from '@zyno-io/ts-server-foundation';
+
+cleanPhone('(202) 555-0125'); // '+12025550125'
+cleanPhone('invalid'); // null
+formatPhoneFriendly('+12025550125', 'US'); // '(202) 555-0125'
+```
+
+## Database Annotations
+
+### `UuidString` and `UUID`
+
+Both aliases validate UUID-formatted strings and emit OpenAPI `string` schemas with `format: uuid`. Their MySQL storage differs:
+
+- `UuidString` uses `char(36)` and remains a string in database bindings and hydrated entities.
+- `UUID` uses `binary(16)` and converts between the application string and compact MySQL storage.
+- PostgreSQL uses its native `uuid` type for both aliases.
+
+```ts
+import { UUID, UuidString } from '@zyno-io/ts-server-foundation';
+
+class Resource {
+    id!: UUID;
+    externalId!: UuidString;
+}
+```
+
+### `HasDefault`
+
+Marks a field as having an application/database default so entity creation and insert helpers can treat `undefined` as "omit this column".
+
+`HasDefault` does not pick a database column type. It only changes optional/default handling.
+
+```ts
+import { HasDefault } from '@zyno-io/ts-server-foundation';
+
+class User {
+    role!: string & HasDefault;
+    isAdmin: boolean & HasDefault = false;
+}
+```
+
+Fields with TypeScript initializers are also read by the migration generator and can produce SQL defaults. For example, `count: number = 0` produces `DEFAULT '0'`, and `createdAt: Date = new Date()` produces `DEFAULT CURRENT_TIMESTAMP`.
+
+### `OnUpdate<T>`
+
+Column `ON UPDATE` expression annotation:
+
+```ts
+import { OnUpdate } from '@zyno-io/ts-server-foundation';
+
+class User {
+    updatedAt!: Date & OnUpdate<'CURRENT_TIMESTAMP'>;
+}
+```
+
+This is primarily useful for MySQL timestamp columns. PostgreSQL does not have a direct column-level `ON UPDATE` equivalent.
+
+### `UnsignedNumber`
+
+Number with a minimum value of `0`. In MySQL migrations, any numeric field with a minimum value greater than or equal to zero is emitted as unsigned.
+
+```ts
+import { UnsignedNumber } from '@zyno-io/ts-server-foundation';
+
+class Counter {
+    value!: UnsignedNumber;
+}
+```
+
+### `MySQLCoordinate` and `NullableMySQLCoordinate`
+
+MySQL `POINT` geometry type. These are MySQL-specific types; do not use them in PostgreSQL entities unless you provide a custom mapping.
+
+```ts
+import { MySQLCoordinate, NullableMySQLCoordinate } from '@zyno-io/ts-server-foundation';
+
+class Location {
+    coords!: MySQLCoordinate;
+    optionalCoords!: NullableMySQLCoordinate;
+}
+
+const coords = { x: -73.9857, y: 40.7484 };
+```
+
+## Utility Types
+
+The package also exports common utility types:
+
+```ts
+type ConcretePrimitive = string | number | boolean;
+type DefinedPrimitive = ConcretePrimitive | null;
+type Primitive = DefinedPrimitive | undefined;
+type StrictBool = true | false;
+type KVObject<T = any> = Record<string, T>;
+type NestedKVObject<T = any> = KVObject<T | T[] | KVObject<T>>;
+type Serializable<T = ConcretePrimitive> = T | T[] | NestedKVObject<T> | NestedKVObject<T>[];
+```
+
+Field and method helpers:
+
+```ts
+type RequireFields<T, K extends keyof T> = T & { [P in K]-?: T[P] };
+type ObjectKeysMatching<O, V> = {
+    [K in keyof O]: O[K] extends V ? K : V extends O[K] ? K : never;
+}[keyof O];
+type MethodsOf<T> = { [K in keyof T as T[K] extends (...args: any[]) => any ? K : never]: T[K] };
+type MethodKeys<T> = keyof MethodsOf<T>;
+```
+
+Class helpers:
+
+```ts
+import { getClassName, isClass } from '@zyno-io/ts-server-foundation';
+```

package/docs/content/uploads.md

@@ -0,0 +1,145 @@
+# Uploads
+
+Multipart upload parsing is integrated with the HTTP parameter resolver. File parts are accepted only when a route explicitly declares matching `FileUpload` fields through a `FileUpload` parameter or a `FileUpload` property in `HttpBody<T>`.
+
+## File Parameters
+
+```ts
+import { FileUpload, http, HttpBody } from '@zyno-io/ts-server-foundation';
+
+interface UploadBody {
+    description?: string;
+}
+
+@http.controller('/files')
+class FilesController {
+    @http.POST()
+    async upload(body: HttpBody<UploadBody>, file: FileUpload<{ maxSize: '40MB'; allowedTypes: 'image/*' }>) {
+        return {
+            description: body.description,
+            name: file.originalName,
+            path: file.path,
+            size: file.size,
+            type: file.type,
+            detectedType: file.detectedType
+        };
+    }
+}
+```
+
+A standalone `FileUpload` parameter is required unless the controller parameter is optional. If the named file is absent, a required parameter returns HTTP `400`; an optional parameter receives `undefined`. This applies to non-multipart requests and multipart requests containing only text fields. A multipart file under an undeclared field name is rejected with HTTP `400`, even when the declared upload parameter is optional.
+
+`FileUpload<Options>` supports:
+
+| Option         | Description                                                               |
+| -------------- | ------------------------------------------------------------------------- |
+| `maxSize`      | Per-file byte limit as a number or string such as `'40MB'`.               |
+| `allowedTypes` | MIME type or list of MIME types. Exact matches, `type/*`, and `*/*` work. |
+
+The multipart part `Content-Type` must match `allowedTypes` before the file is written. When `allowedTypes` is set, the framework also buffers a signature sample, asks `file-type` to detect the format, and requires the detected MIME type to match. Both checks honor wildcards. Detection is still mandatory for `*/*`: an empty, text-only, truncated, or otherwise undetectable signature is rejected. Use allowed types that `file-type` can recognize, and do not treat detection as malware scanning or complete content validation.
+
+`FileUpload` fields:
+
+| Field               | Description                                                          |
+| ------------------- | -------------------------------------------------------------------- |
+| `path`              | Temporary file path on disk.                                         |
+| `size`              | Uploaded byte count.                                                 |
+| `type`              | MIME type from the multipart part, or `application/octet-stream`.    |
+| `declaredType`      | Same declared MIME type from the multipart part.                     |
+| `detectedType`      | MIME type detected by `file-type` when `allowedTypes` is set.        |
+| `detectedExtension` | Extension detected by `file-type` when `allowedTypes` is set.        |
+| `originalName`      | Original client filename. A sanitized copy is used in the temp path. |
+| `name`              | Alias for `originalName`.                                            |
+
+## Multipart Body Fields
+
+Regular multipart fields are merged into the parsed body. A field named `_payload` is parsed as JSON and merged into the body object.
+
+```text
+_payload={"description":"Profile photo"}
+file=<binary>
+```
+
+If multiple text fields use the same name, the parsed body stores them in order as an array; declare the corresponding DTO property as an array. Duplicate files are arrays in `request.uploadedFiles` and the raw parsed body. A standalone `FileUpload` parameter selects the first file under its name. If its named field is absent, it falls back only when exactly one file exists across the route's other declared upload fields.
+
+Typed multi-file body properties are not supported: `file: FileUpload` expects one file and rejects the duplicate-file array. Use `HttpRequest.uploadedFiles` when an endpoint intentionally accepts repeated files, and apply application-level checks to the array.
+
+A body DTO can declare file fields directly:
+
+```ts
+class AttachmentBody {
+    title!: string;
+    attachment?: FileUpload<{ maxSize: '2MB'; allowedTypes: 'application/pdf' }>;
+}
+
+@http.controller('/attachments')
+class AttachmentController {
+    @http.POST()
+    upload(body: HttpBody<AttachmentBody>) {
+        return { title: body.title, fileName: body.attachment?.originalName };
+    }
+}
+```
+
+For OpenAPI, a required body file makes the request multipart-only. When all body files are optional or nullable, the operation advertises both JSON (for requests without files) and multipart content.
+
+Keep runtime upload properties at the top level of the body DTO. Multipart file parts are assigned by their flat field name; a nested `nested.file: FileUpload` schema cannot be populated automatically from a file part.
+
+## Cleanup
+
+Uploaded files are written to a temporary directory created with the `tsf-upload-` prefix. The `onResponse` workflow runs while uploaded files still exist. Immediately afterward, the HTTP router removes every upload directory in a cleanup `finally`, including JSON/multipart parse failures, MIME and size rejections, controller errors, and failures thrown by `onResponse` listeners.
+
+`FileUpload.path` is request-scoped. Do not store it for later background work without copying the file before the controller returns. By the time `app.http.request()` resolves—or rejects because the final response workflow failed—the temporary path has been removed.
+
+## Raw Streaming
+
+Use `HttpRequestStream` for endpoints that intentionally accept a raw body stream and bypass body guards.
+
+```ts
+import { http, HttpRequestStream } from '@zyno-io/ts-server-foundation';
+
+@http.controller('/raw')
+class RawController {
+    @http.POST()
+    async upload(request: HttpRequestStream) {
+        for await (const chunk of request) {
+            await writeChunk(chunk);
+        }
+        return { ok: true };
+    }
+}
+```
+
+Do not combine `HttpRequestStream` with `HttpBody<T>` or `FileUpload` on the same route; route registration rejects that combination. Raw streaming also bypasses MIME policies, multipart declaration checks, content decoding, `content-length` checks, and request byte limits, so the handler must enforce every appropriate limit itself.
+
+## Cached Body Reads
+
+`HttpRequest.readBodyBuffer()`, `readBodyText()`, and `readBody()` read the request body and cache the buffer on `request.body`.
+
+```ts
+const first = await request.readBodyBuffer();
+const second = await request.readBodyBuffer();
+
+first === second; // true
+request.body === first; // true
+```
+
+Cached reads are reusable. If the request stream is already being consumed through `request.stream`, body-buffer reads throw because the stream cannot be consumed twice.
+
+## Testing Multipart Requests
+
+`HttpRequest` can build multipart bodies for tests.
+
+```ts
+const request = HttpRequest.POST('/files').multiPart([
+    { name: '_payload', value: JSON.stringify({ description: 'Avatar' }) },
+    {
+        name: 'file',
+        file: Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64'),
+        fileName: 'avatar.png',
+        contentType: 'image/png'
+    }
+]);
+```
+
+This uses the same parser path as a real multipart request.

package/docs/content/worker.md

@@ -0,0 +1,182 @@
+# Workers
+
+The worker layer uses BullMQ with Redis outside test mode. In `APP_ENV=test`, it uses an in-process queue so tests do not require Redis unless a test explicitly starts an app with a non-test config.
+
+Enable worker services with `createApp({ enableWorker: true })`. This registers `WorkerService`, `WorkerRunnerService`, the queue registry, and the recorder.
+
+```typescript
+const app = createApp({
+    enableWorker: true,
+    providers: [SendEmailJob]
+});
+```
+
+Normal server processes can enqueue jobs. Runner ownership is controlled by `ENABLE_JOB_RUNNER`:
+
+| Environment           | Default runner behavior                                                                                  |
+| --------------------- | -------------------------------------------------------------------------------------------------------- |
+| `production`          | runner off unless `ENABLE_JOB_RUNNER=true`                                                               |
+| non-production        | runner on unless `ENABLE_JOB_RUNNER=false`                                                               |
+| `node . worker:start` | runner forced on; the HTTP listener also starts, including `/healthz` unless health checks were disabled |
+
+Production deployments should run API/server pods with `node . server:start` and `ENABLE_JOB_RUNNER` unset or false, and separate worker pods with `node . worker:start`.
+
+## Defining Jobs
+
+Jobs extend `BaseJob<I, O>` and are registered with `@WorkerJob()`.
+
+```typescript
+import { BaseJob, WorkerJob } from '@zyno-io/ts-server-foundation';
+
+interface SendEmailInput {
+    to: string;
+    subject: string;
+}
+
+@WorkerJob({ queueName: 'mail' })
+class SendEmailJob extends BaseJob<SendEmailInput, { sent: boolean }> {
+    async handle(data: SendEmailInput) {
+        return { sent: true };
+    }
+}
+```
+
+The job class must also be registered as a provider so the runner can resolve it through DI.
+
+`BaseJob<I, O>` contains one required method, `handle(data: I): O | Promise<O>`. `@WorkerJob()` sets the job class's queue and cron metadata and adds it to the process registry; it does not add the class to the app's DI container. The decorator accepts `queueName` (`queue` is an alias) and `cronSchedule` (`cron` is an alias).
+
+The equivalent static metadata remains available for jobs that cannot use decorator arguments:
+
+```typescript
+@WorkerJob()
+class DailyCleanupJob extends BaseJob<void, void> {
+    static QUEUE_NAME = 'maintenance';
+    static CRON_SCHEDULE = '0 2 * * *';
+
+    async handle() {
+        await cleanup();
+    }
+}
+```
+
+Decorator values override the inherited `QUEUE_NAME = 'default'` and `CRON_SCHEDULE = null` defaults on that job class.
+
+## Queueing Jobs
+
+Use `WorkerService.queueJob()` for normal queueing and `WorkerService.runJob()` for immediate execution.
+
+```typescript
+const worker = app.get(WorkerService);
+
+await worker.queueJob(SendEmailJob, {
+    to: 'user@example.com',
+    subject: 'Welcome'
+});
+
+const execution = await worker.runJob(SendEmailJob, {
+    to: 'user@example.com',
+    subject: 'Welcome'
+});
+```
+
+`runJob()` always creates an in-process queue record and executes it immediately through `WorkerRunnerService`; it does not enqueue a BullMQ job. `queueJob(..., { runImmediately: true })` uses the same inline path. Without `runImmediately`, test mode uses the in-memory queue while non-test environments enqueue through BullMQ.
+
+In `APP_ENV=test`, `queueJob()` returns `undefined` unless `runInTest: true` is passed. This keeps tests from accidentally scheduling background work.
+
+```typescript
+await worker.queueJob(SendEmailJob, data, {
+    runInTest: true,
+    runImmediately: true
+});
+```
+
+## Job Options
+
+| Option             | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `delay`            | Delay in milliseconds before the job is ready.         |
+| `queueName`        | Override the queue for this job instance.              |
+| `runInTest`        | Allow queueing in `APP_ENV=test`.                      |
+| `runImmediately`   | Bypass BullMQ and execute inline through the runner.   |
+| `recordToDatabase` | Insert a `_jobs` record when a database is configured. |
+| `repeatKey`        | Internal repeat key used for cron scheduling.          |
+
+The default queue comes from `BaseAppConfig.BULL_QUEUE`. If unset, it is `default`.
+
+Outside `APP_ENV=test`, BullMQ requires a `BULL_REDIS_HOST`/`BULL_REDIS_SENTINEL_HOST` connection or the corresponding generic `REDIS_HOST`/`REDIS_SENTINEL_HOST` fallback.
+
+## Cron Jobs
+
+Use `cronSchedule` or `cron` on `@WorkerJob()`.
+
+```typescript
+@WorkerJob({ queueName: 'daily', cronSchedule: '0 2 * * *' })
+class DailyCleanupJob extends BaseJob<void, void> {
+    async handle() {
+        await cleanup();
+    }
+}
+```
+
+When the runner starts, it registers BullMQ job schedulers for registered cron jobs. In test-mode in-process queues, the runner schedules one pending repeat job per registered job class and repeat key.
+
+## Queue Registry
+
+`WorkerQueueRegistry` is primarily an internal queue abstraction. In test mode it stores queued jobs in memory and exposes:
+
+- `add(jobClass, data, options)`
+- `getQueuedJobs(queue?)`
+- `getAllQueuedJobs()`
+- `markCompleted(job, result)`
+- `markFailed(job, result)`
+- `remove(job)`
+- `clear(queue?)`
+- `WorkerQueueRegistry.closeQueues()`
+
+Outside test mode, `WorkerService.queueJob()` writes to BullMQ. Workers deserialize jobs by class name and resolve the matching registered provider through DI.
+
+## Recorder
+
+`WorkerRecorderService` keeps in-memory execution records for the lifetime of the process and can optionally write completed/failed records into a `_jobs` table when a `BaseDatabase` provider is configured and the job option `recordToDatabase` is true. The application must provision that table through its own migration; registering worker services does not add it to the database entity registry or create it automatically. `getRecords()` returns shallow copies. The recorder itself is unbounded; DevConsole intentionally displays only the latest 200 records.
+
+```typescript
+await worker.queueJob(SendEmailJob, data, {
+    runImmediately: true,
+    recordToDatabase: true
+});
+
+const records = app.get(WorkerRecorderService).getRecords();
+```
+
+The database record contains queue, queue id, attempt, job name, input data, status, result, and timestamps.
+
+## Request Context
+
+Jobs execute inside helper context data containing the current job metadata:
+
+```typescript
+import { getContextProp } from '@zyno-io/ts-server-foundation';
+
+const job = getContextProp<{ queue: string; id: string; name: string }>('job');
+```
+
+## Observers
+
+`registerWorkerObserver()` receives process-wide queue/execution events and returns an unsubscribe function.
+
+```typescript
+import { registerWorkerObserver } from '@zyno-io/ts-server-foundation';
+
+const unsubscribe = registerWorkerObserver(entry => {
+    console.log(entry.type, entry.job.name, entry.job.id);
+});
+```
+
+Entries are `added`, `delayed`, `active`, `completed`, or `failed`; completed/failed entries also include the execution record. Observer exceptions are isolated from queueing and job execution. DevConsole uses the same observation surface, so observers are process-wide rather than scoped to one app.
+
+## Current Limits
+
+- Queue names are discovered from `BULL_QUEUE` and registered `@WorkerJob({ queueName })` classes. Avoid arbitrary per-call `queueName` overrides unless worker processes also register a job class on that queue.
+- Retry/backoff policy is application-defined; the current worker options do not expose BullMQ retry options.
+- Recorder/database failures currently propagate through job execution and can turn an otherwise successful handler into a failed job; choose `recordToDatabase` only when that failure coupling is intended.
+- Runner shutdown waits for active handlers without a timeout or cancellation signal.

package/docs/openapi.md

@@ -0,0 +1,3 @@
+# OpenAPI
+
+The canonical OpenAPI documentation lives at [docs/content/openapi.md](./content/openapi.md).