@pattern-stack/codegen 0.9.2 → 0.10.1

package/consumer-skills/entities/yaml-reference.md

@@ -0,0 +1,118 @@
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Entity YAML reference
+
+Every block of an `entities/<name>.yaml` file and what it generates.
+
+## `entity:` — identity
+
+```yaml
+entity:
+  name: contact            # REQUIRED. singular snake_case. Drives class names + table.
+  plural: contacts         # optional; inferred (pluralized) if omitted
+  table: contacts          # optional; defaults to the plural
+  pattern: Synced          # the family — Base | Synced | Activity | Metadata | Knowledge
+                           #   (or an app-defined pattern). See families-and-queries.md.
+```
+
+## `fields:` — columns
+
+Each key is a `snake_case` column; the generated TS property is `camelCase`.
+
+```yaml
+fields:
+  email:
+    type: string           # string | integer | decimal | boolean | uuid | date | datetime | json | enum
+    required: true         # NOT NULL + required in Create DTO
+    max_length: 255        # string length constraint (DB + Zod)
+    index: true            # single-column index
+  status:
+    type: enum
+    choices: [active, inactive, archived]   # enum members
+  metadata:
+    type: json             # jsonb column
+  score:
+    type: decimal
+    nullable: true
+```
+
+Type notes:
+- `uuid` — typically the PK and foreign keys.
+- `enum` — requires `choices:`; generates a TS union + DB check/enum.
+- `json` — `jsonb`; typed as `Record<string, unknown>` unless you narrow it in
+  your own code.
+- `datetime` vs `date` — timestamp vs date-only column.
+
+## `behaviors:` — cross-cutting columns + logic
+
+```yaml
+behaviors:
+  - timestamps             # createdAt, updatedAt (auto-managed)
+  - soft_delete            # deletedAt; queries auto-filter deleted rows; GET :id 404s on deleted
+  - user_tracking          # createdBy, updatedBy
+```
+
+Behaviors compose — list any subset.
+
+## `relationships:` — foreign keys + typed accessors
+
+```yaml
+relationships:
+  account:
+    type: belongs_to       # belongs_to | has_many | has_one
+    target: account        # the referenced entity (must have its own YAML)
+    foreign_key: account_id
+```
+
+- `belongs_to` adds the FK column on this entity.
+- `has_many` / `has_one` are the inverse side (no column here; drives the typed
+  relation accessor + Drizzle `relations()`).
+- Cross-entity targets must resolve at generation time — regenerate the set with
+  `codegen entity new --all`.
+
+## `generate:` — output toggles
+
+```yaml
+generate:
+  writes: true             # default true — emit POST/PATCH/DELETE + create/update/delete use cases
+```
+
+Set `writes: false` for a read-only resource (only GET routes + read use cases).
+
+## EAV (custom fields)
+
+Two independent flags:
+
+```yaml
+# On a normal entity (e.g. opportunity): opt into custom fields
+eav: true
+```
+
+When `eav: true`:
+- Service gains **paired reads**: `findById` (typed entity) and
+  `findByIdWithFields` (entity + merged `fields` bag); same for `list`.
+- `Create*` / `Update*` use cases accept `{ ...core, fields?: Record<string,
+  unknown> }` and run a transactional dual-write.
+- Controller adds `GET /:id/with-fields`, `GET /with-fields`, and accepts the
+  `fields` bag on POST/PATCH.
+
+```yaml
+# On the value-table entity itself (e.g. field_value): mark it AS the EAV store
+eav_value_table: true
+eav_definition_table: field_definition   # where keys → definition ids resolve
+```
+
+When `eav_value_table: true`:
+- Repository gets `upsertCurrentValues(rows, tx)` (composite conflict target).
+- Service gets `upsertFieldsTransactional(...)` and `findMergedByEntity(...)`
+  with internal definition-id resolution.
+- The module auto-imports the definition-table module so DI resolves without
+  consumer wiring.
+
+The EAV dual-write is coordinated by the **use case** inside `db.transaction` —
+services stay single-domain (see the layer rules in the `entities` L0 skill).
+
+## `queries:` — declarative finders
+
+See `families-and-queries.md` for the full `queries:` block (column finders,
+unique, ordered, filtered+paginated search).

package/consumer-skills/events/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: events
+description: Load when authoring a domain event, publishing one from a use case, or subscribing to one in a project that ran `codegen subsystem install events`. Triggers include `events/*.yaml` files, the generated `TypedEventBus` facade, injecting `TYPED_EVENT_BUS` / `EVENT_BUS`, `publish(...)` inside a Drizzle transaction (the outbox), `subscribe(...)`, the `domain_events` table, and event directions / pools.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+user-invocable: false
+---
+
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Events
+
+The events subsystem is the transactional event backbone vendored into your app by `codegen subsystem install events`. You declare each event type as a YAML file; codegen generates a typed `TypedEventBus` facade, a discriminated union of every event, Zod payload schemas, and a runtime registry. You publish events inside the same database transaction as your domain write (the outbox pattern); a background loop drains them and delivers to subscribers.
+
+The vendored code lives under `<paths.subsystems>/events/` (default `src/shared/subsystems/events/`), imported as `@shared/subsystems/events`. The generated files live under `<paths.subsystems>/events/generated/` and are reproduced from `events/*.yaml` on every `codegen` run — do not hand-edit them.
+
+## Mental model
+
+**An event is an immutable fact** — "contact was created", "Stripe webhook arrived", "opportunity moved to `won`". It has no lifecycle beyond being delivered. **A job is the stateful work** that reacts to a fact. If you are tempted to put `status`, `attempts`, `retry_count`, or `scope` on an event, stop — you want a job (see the `jobs` skill). The event is the trigger; the job is the work.
+
+### The outbox
+
+Publishing an event is an `INSERT` into the `domain_events` table, performed **inside the same transaction as your domain write**. Either both commit or neither does — no phantom events, no domain drift if the process crashes between commit and publish. A separate polling loop drains pending rows and dispatches them to subscribers. This is strictly stronger than `await commit(); await publish()`.
+
+The single most important rule: **always pass the transaction (`tx`) when publishing from a use case that also writes domain state.** Dropping it silently detaches the event from the transaction.
+
+### Directions and pools
+
+Every domain event declares a **direction**, which determines the lane it drains through:
+
+| direction | carries | example |
+|---|---|---|
+| `inbound` | external → us (webhooks, pub/sub, inbound email) | `stripe_payment_received` |
+| `change` | internal domain mutations (drive projections/reactions) | `contact_created` |
+| `outbound` | us → external (webhooks fired, sync pushes) | `webhook_outbound_contact_sync` |
+
+Direction is a **routing** concern, not a payload concern — two events with identical payloads can have different directions. Each direction drains through its own reserved lane so a slow outbound handler can't stall internal change-event propagation.
+
+There is also an `audit` **tier** (orthogonal to direction) for observational facts that should live in the outbox but must never spawn work — see `authoring-events.md`.
+
+### Typed facade vs. raw port
+
+- `IEventBus` (token `EVENT_BUS`) is the narrow underlying port: `publish`, `publishMany`, `subscribe`. It knows nothing about your specific event types.
+- `TypedEventBus` (token `TYPED_EVENT_BUS`) is the generated, injectable wrapper. Its `publish<T>()` enforces the typed payload for `T` and stamps `metadata.pool` / `metadata.direction` / `metadata.version` from the registry. **Use `TypedEventBus` in new code.** The raw port stays available for forwarders that publish types not in the registry.
+
+## Routing table
+
+| For this task | Read |
+|---|---|
+| Declaring an `events/*.yaml`, payload types, directions, `tier: audit`, entity `emits:` | `authoring-events.md` |
+| Publishing inside a transaction, the outbox, idempotency, subscribing, wiring `EventsModule` | `typed-bus-and-outbox.md` |
+
+To run a durable background job *when an event fires*, that is the Event-to-Job Bridge — see the `bridge` skill. To do the work directly (not via an event), see the `jobs` skill.
+
+## Non-obvious rules
+
+- **Always pass `tx` to `publish` inside a use-case transaction.** It is the entire outbox guarantee. There is no type-level enforcement of this yet — it is a discipline.
+- **Events have no lifecycle; jobs do.** The `status` column on `domain_events` (`pending | processed | failed`) is delivery state for the drain loop, not a domain state machine.
+- **Use `TypedEventBus.publish<'type'>(...)` once the type is generated.** Misspelled event names and wrong payload shapes become compile errors.
+- **Subscribers must be fast.** A subscriber that makes an HTTP call blocks the drain batch (it dispatches ~50 rows serially). Heavy reactions belong in a job — subscribe, then enqueue.
+- **The event `id` is the idempotency key.** For replays/backfills, derive the id deterministically from the source event (e.g. Stripe's `evt_...`) so a re-insert is a no-op rather than a duplicate.
+- **Regenerate after editing YAML.** Re-run `codegen` (e.g. `codegen entity new --all`) after touching any `events/*.yaml` to refresh the generated facade, union, schemas, and registry.
+
+## Do not
+
+- Do not put job-style fields on an event (`status: running`, `attempts`, `scope`, `parent_id`). Those belong on a job.
+- Do not drop the `tx` argument in `publish(...)` inside a transaction.
+- Do not collapse the three directions into one pool — lane isolation is the point.
+- Do not couple two services with a direct method call when the second merely reacts to a state change in the first. Publish a `change` event from the first, subscribe (or bridge a job) from the second.
+- Do not do heavy I/O directly in a subscriber. Enqueue a job instead.
+- Do not hand-edit anything under `<paths.subsystems>/events/generated/`. It is regenerated from `events/*.yaml`.
+- Do not route events through user pools (`batch`, `interactive`) — events only ever drain through the reserved `events_*` lanes.

package/consumer-skills/events/authoring-events.md

@@ -0,0 +1,164 @@
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Authoring Events
+
+How to declare an event in YAML, what each field means, what gets generated, and when to reach for the `audit` tier. Read the `events` `SKILL.md` first for the outbox/direction mental model. For publishing and subscribing, see `typed-bus-and-outbox.md`.
+
+## One YAML file per event
+
+Events live in `events/` at your repo root, sibling to `entities/`. One file per type; the filename matches the `type` field (snake_case).
+
+```yaml
+# events/contact_created.yaml
+type: contact_created
+direction: change
+aggregate: contact          # must match an entity name
+version: 1
+payload:
+  contact_id: { type: uuid }
+  account_id: { type: uuid, nullable: true }
+  created_by: { type: uuid }
+```
+
+```yaml
+# events/stripe_payment_received.yaml
+type: stripe_payment_received
+direction: inbound
+source: stripe              # inbound: logical origin
+version: 1
+description: Stripe charge.succeeded webhook, post-signature-verification.
+payload:
+  event_id:     { type: string, description: "Stripe event id (evt_...)" }
+  customer_id:  { type: string }
+  amount_cents: { type: number }
+  currency:     { type: string }
+  received_at:  { type: date }
+retry:
+  attempts: 5
+  backoff: exponential
+```
+
+```yaml
+# events/webhook_outbound_contact_sync.yaml
+type: webhook_outbound_contact_sync
+direction: outbound
+destination: crm            # outbound: logical target
+aggregate: contact
+payload:
+  contact_id:  { type: uuid }
+  operation:   { type: string }   # "create" | "update" | "delete"
+  occurred_at: { type: date }
+```
+
+After editing any `events/*.yaml`, re-run codegen (e.g. `codegen entity new --all`) to regenerate the typed artifacts.
+
+## Field reference
+
+| Field | Required | Notes |
+|---|---|---|
+| `type` | yes | Unique snake_case business key; matches the filename. Becomes the discriminator and the `publish<T>()` key. |
+| `direction` | for `tier: domain` | `inbound \| change \| outbound`. Drives the default pool. **Omit for `tier: audit`.** |
+| `tier` | no | `domain` (default) or `audit`. Audit events are outbox-only and never spawn jobs — see below. |
+| `aggregate` | for `change` | The owning entity name. Required for `change` events; optional elsewhere. Lets you query/replay events for a given entity id. |
+| `source` | inbound only | Logical origin ("stripe", "email"). |
+| `destination` | outbound only | Logical target ("crm", "slack"). |
+| `payload` | yes | Map of snake_case keys → field specs. Keys become camelCase TS props. |
+| `pool` | no | Override the direction's default pool. Only valid within the same category (a `change` event can't opt into `events_inbound`). User pools are never valid. Rarely needed — if you reach for it, revisit the direction. **Must be omitted for `tier: audit`.** |
+| `retry` | no | `{ attempts, backoff }`; hints surfaced to the bus. |
+| `version` | no | Integer, defaults to 1. Stamped on every publish; multi-version coexistence is not exercised yet. |
+
+### Payload field types
+
+`uuid | string | number | boolean | date | json | array`.
+
+- `nullable: true` makes the TS prop `T | null`.
+- `array` requires an `items:` scalar type (`items: uuid | string | number | boolean | date`) and emits `T[]` + `z.array(T)`.
+- `json` means an arbitrary JSON object (`Record<string, unknown>`). **Do not use `json` for array-shaped data** — Zod will reject it at the publish boundary.
+
+### Default pool from direction (domain tier)
+
+| direction | default pool |
+|---|---|
+| `inbound` | `events_inbound` |
+| `change` | `events_change` |
+| `outbound` | `events_outbound` |
+
+## Tier: domain vs. audit
+
+`tier` classifies the *kind* of fact and controls whether a job can be bound to the event.
+
+| tier | direction | pool | can a job trigger on it? |
+|---|---|---|---|
+| `domain` (default) | required | from direction | yes |
+| `audit` | omitted | null | no — codegen rejects it |
+
+Use `audit` for high-volume **observational** events that should exist in the outbox (so you can query/replay them) but must never spawn downstream work. The motivating case: a polling CRM sync emitting one "I scanned this row" event per record would otherwise queue thousands of inert bridge jobs per run.
+
+```yaml
+# events/crm_sync_completed.yaml
+type: crm_sync_completed
+tier: audit                  # outbox-only; not bridge-eligible
+aggregate: integration       # still scoped for query-by-id
+version: 1
+description: A CRM sync run finished. Observational — no domain state changed.
+payload:
+  integration_id: { type: uuid }
+  provider:       { type: string }
+  counts:         { type: json }
+  duration_ms:    { type: number }
+```
+
+For an `audit` event the generated registry entry has `pool: null` and `direction: null`; both columns land NULL. In-process subscribers (`subscribe(...)`) may still listen to audit events — only the bridge refuses to bind jobs to them.
+
+**The discipline:** if a well-behaved consumer would write another row or enqueue work, it is a `domain` event; if it would only bump a counter or update a dashboard, it is `audit`.
+
+Codegen hard-errors on misuse:
+- `tier: audit` with a `pool` → error naming the event.
+- `tier: audit` with a `direction` → error naming the event.
+- A job whose `@JobHandler.triggers` points at an audit event → `AuditEventTriggerError`. Use a domain event or remove the trigger.
+
+## Entity `events:` block is sugar for change events
+
+An entity's YAML may keep an `events:` block. At parse time each entry desugars into an equivalent `events/<name>.yaml` with `direction: change` and `aggregate: <entity>`. Both paths produce the same registry entry — inline blocks are convenience, not a second source of truth.
+
+## Entity `emits:` for typed auto-emission
+
+An entity can declare which change events its generated use cases emit:
+
+```yaml
+# entities/contact.yaml
+emits:
+  - contact_created
+  - contact_updated
+  - contact_deleted
+```
+
+Each entry must resolve to an `events/<type>.yaml` with `direction: change` and `aggregate: contact`, or codegen hard-errors. With `emits:` present, generated use cases call the typed facade inside the domain transaction:
+
+```ts
+async execute(input: CreateContactInput): Promise<Contact> {
+  return this.db.transaction(async (tx) => {
+    const contact = await this.contacts.create(input, tx);
+    await this.events.publish('contact_created', contact.id, {
+      contactId: contact.id,
+      accountId: contact.accountId,
+      createdBy: input.actorId,
+    }, { tx });
+    return contact;
+  });
+}
+```
+
+## What gets generated
+
+Five files under `<paths.subsystems>/events/generated/`, all reproduced from your YAML — never hand-edited:
+
+| File | Contents |
+|---|---|
+| `types.ts` | Per-event interfaces, the `AppDomainEvent` discriminated union, and helpers `EventTypeName`, `EventOfType<T>`, `PayloadOfType<T>`. |
+| `schemas.ts` | A Zod schema per payload, plus a keyed map for boundary validation. |
+| `registry.ts` | `eventRegistry` — the runtime metadata map (direction, pool, aggregate, version, retry) read by the facade, the bridge, and startup validation. |
+| `bus.ts` | The `TypedEventBus` facade with typed `publish<T>()` / `subscribe<T>()`. |
+| `index.ts` | Re-export surface. |
+
+The typed payload flows end to end: declaring `payload.contact_id: { type: uuid }` makes `PayloadOfType<'contact_created'>` require `contactId: string`, and `publish('contact_created', id, { ... })` typechecks the object against it.

package/consumer-skills/events/typed-bus-and-outbox.md

@@ -0,0 +1,163 @@
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Publishing, the Outbox, and Subscribing
+
+How to publish events transactionally, how the outbox drain works, how to subscribe, idempotency, and how to wire `EventsModule` into your app. Read the `events` `SKILL.md` first for the mental model and `authoring-events.md` for the YAML shape.
+
+## Publishing inside a transaction
+
+Every use case that mutates domain state and emits an event **must pass the transaction** so the event row is part of the same atomic write. Inject the typed facade:
+
+```ts
+import { Inject, Injectable } from '@nestjs/common';
+import { TypedEventBus, TYPED_EVENT_BUS } from '@shared/subsystems/events';
+
+@Injectable()
+export class CreateContactUseCase {
+  constructor(
+    @Inject(TYPED_EVENT_BUS) private readonly events: TypedEventBus,
+    private readonly db: DrizzleClient,
+    private readonly contacts: ContactRepository,
+  ) {}
+
+  async execute(input: CreateContactInput): Promise<Contact> {
+    return this.db.transaction(async (tx) => {
+      const contact = await this.contacts.create(input, tx);
+      await this.events.publish(
+        'contact_created',
+        contact.id,
+        {
+          contactId: contact.id,
+          accountId: contact.accountId,
+          createdBy: input.actorId,
+        },
+        { tx }, // ← the outbox guarantee
+      );
+      return contact;
+    });
+  }
+}
+```
+
+`TypedEventBus.publish(type, aggregateId, payload, opts?)`:
+- Validates the payload against the generated Zod schema at the boundary (skippable with `CODEGEN_EVENT_VALIDATE=off`).
+- Stamps `id`, `occurredAt`, and `metadata.pool` / `metadata.direction` / `metadata.version` from the registry.
+- Inserts one `domain_events` row using `opts.tx` if provided, else the top-level connection.
+
+**Dropping `tx` silently detaches the event.** The backend uses `tx ?? db`, so without `tx` the insert runs outside your domain transaction — the domain write can commit while the event insert fails independently. There is no compile-time guard; treat passing `tx` as non-negotiable.
+
+### Raw `EVENT_BUS` for untyped publishes
+
+The raw port stays available for forwarders that publish types not in the registry (e.g. proxying an external source):
+
+```ts
+import { EVENT_BUS, type IEventBus } from '@shared/subsystems/events';
+
+@Inject(EVENT_BUS) private readonly bus: IEventBus;
+
+await this.bus.publish(
+  { id, type, aggregateId, aggregateType, payload, occurredAt },
+  tx,
+);
+```
+
+New code should prefer `TypedEventBus`.
+
+## The outbox table and drain loop
+
+`domain_events` is the outbox. Key columns: `id` (UUID, the idempotency key), `type`, `aggregate_id`, `aggregate_type`, `payload` (jsonb), `occurred_at`, `processed_at`, `status` (`pending | processed | failed`), `error`, `metadata`, and first-class `pool` / `direction` / `tier` columns (populated from `metadata` at insert so the drain can filter by lane without unpacking JSON). `tier` (`'domain'` | `'audit'`, default `'domain'`) is always emitted; the `domain_events_tier_routing_check` constraint enforces that `tier='audit'` rows have null `pool`/`direction`. `tenant_id` is the only conditional column — emitted only under `events.multi_tenant: true`.
+
+The drain loop (Drizzle backend):
+1. Claims a batch (default 50) of `pending` rows with `FOR UPDATE SKIP LOCKED`, optionally filtered by pool, ordered by `occurred_at ASC`. `SKIP LOCKED` lets multiple worker processes drain concurrently without double-dispatching.
+2. For each row, invokes every registered handler for `event.type`.
+3. On success: `status='processed'`, `processed_at=now()` — in the same transaction that locked the row, so nothing can strand half-claimed.
+4. On failure: retries up to 3 attempts; if still failing, `status='failed'` with the error. No automatic retry after that — a permanently broken handler does not burn a worker forever.
+
+Default poll interval is 1s, so there is a ~1s latency floor. There is no stale-event sweeper — it is unnecessary because the lock lifetime equals the dispatch transaction.
+
+## Subscribing
+
+```ts
+import { TypedEventBus, TYPED_EVENT_BUS } from '@shared/subsystems/events';
+
+@Inject(TYPED_EVENT_BUS) private readonly events: TypedEventBus;
+
+this.events.subscribe('contact_created', async (event) => {
+  // event is narrowed to ContactCreatedEvent — event.payload.contactId is typed
+  await this.readModel.upsert(event.payload.contactId);
+});
+```
+
+`subscribe<T>()` returns an unsubscribe function. Subscriptions are **per-process** in the Drizzle backend — a subscriber registered in process A does not receive events drained in process B. In a multi-process deployment, each process runs its own subscribers.
+
+**Keep subscribers fast.** The drain dispatches a batch serially; a subscriber doing HTTP or other slow I/O stalls the whole batch. For anything slow, durable, or that needs retry, do not work inline — enqueue a job. For durable async fanout from an event to a job, use the `bridge` skill; for fire-and-forget cheap reactions (metrics, cache busts), an in-process subscriber is fine.
+
+## Idempotency
+
+The event `id` is the dedup token. Handlers can redeliver (a process can crash between dispatch and the `processed` update), so:
+
+- **Make handlers idempotent** — safe to call twice with the same `event.id`. A common pattern is a small "seen ids" table the handler checks first.
+- **For inbound webhooks, reuse the source system's id.** If Stripe sends `evt_123` twice, deriving the outbox `id` from `evt_123` means the second insert hits `ON CONFLICT (id) DO NOTHING` instead of creating a duplicate.
+- **Never regenerate `id` on replay/backfill** — compute it deterministically from the source event.
+
+## Ordering
+
+- Same aggregate, single worker: FIFO (`ORDER BY occurred_at ASC`). With multiple workers, same-aggregate ordering holds only probabilistically.
+- Across aggregates: not strictly ordered — treat it as roughly wall-clock.
+
+If a handler depends on strict cross-aggregate ordering, reshape it to tolerate independent timelines.
+
+## Wiring `EventsModule`
+
+Register once in `AppModule`; it is `global: true`, so entity modules need not import it individually:
+
+```ts
+import { EventsModule } from '@shared/subsystems/events';
+
+@Module({
+  imports: [
+    DatabaseModule,
+    EventsModule.forRoot({ backend: 'drizzle' }),
+    // ...
+  ],
+})
+export class AppModule {}
+```
+
+`forRoot` options:
+- `backend: 'drizzle' | 'memory' | 'redis'` — match `events.backend` in your config. Tests override to `'memory'`.
+- `multiTenant: true` — opt-in multi-tenancy (see below).
+- `pools: ['events_change']` — restrict this process's drain loop to specific lanes. A common split is one process per direction so a slow outbound handler cannot stall change-event propagation. Undefined drains all lanes.
+
+### Backend notes
+
+- **`drizzle`** (default) — Postgres outbox; transactional, crash-safe; ~1s polling floor.
+- **`memory`** — synchronous, in-process, for tests. `publish` dispatches immediately (no `tx` semantics); exposes `publishedEvents[]`, `publishedEventsForPool()`, `publishedEventsForDirection()`, and `clear()` for assertions. Because dispatch is synchronous, tests need no timers.
+- **`redis`** — present but not a scaffold default. **It does not participate in the Drizzle transaction** — passing `tx` is a silent no-op, so you lose the outbox guarantee. Only reach for it after measuring an actual throughput bottleneck (the Drizzle outbox tops out around ~1000 events/s).
+
+### Multi-tenancy
+
+Set `events.multi_tenant: true` in config, re-run `codegen subsystem install events --force` to re-emit the schema with a `tenant_id` column (then cut a migration), and pass `multiTenant: true` to `EventsModule.forRoot(...)`:
+
+```ts
+EventsModule.forRoot({ backend: 'drizzle', multiTenant: true });
+```
+
+When on, `publish` throws `MissingTenantIdError` (naming the event type) if `opts.metadata.tenantId` is absent. Explicit `null` is permitted for tenant-less background events. Keep the config flag and the module option in agreement.
+
+## Testing with events
+
+Swap the backend to memory and assert on what was published:
+
+```ts
+Test.createTestingModule({
+  imports: [EventsModule.forRoot({ backend: 'memory' })],
+});
+
+// in a test:
+expect(bus.publishedEvents).toContainEqual(
+  expect.objectContaining({ type: 'contact_created' }),
+);
+```
+
+Call `bus.clear()` in `beforeEach`. For Drizzle integration tests, `DrizzleEventBus.drainOnce()` runs exactly one drain cycle so you do not have to sleep past the poll interval.

package/consumer-skills/jobs/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: jobs
+description: Load when authoring a `@JobHandler` class, kicking off a background job from a use case, or configuring job pools in a project that ran `codegen subsystem install jobs`. Triggers include `@JobHandler`, `JobContext`, `ctx.step` / `ctx.spawnChild`, injecting `JOB_ORCHESTRATOR` / `JOB_RUN_SERVICE`, registering `JobsDomainModule` / `JobWorkerModule`, and editing the `jobs:` block in `codegen.config.yaml`.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+user-invocable: false
+---
+
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Jobs
+
+The jobs subsystem is the durable background-work engine vendored into your app by `codegen subsystem install jobs`. It gives you a way to run work asynchronously, retry it, scope it to a domain entity, cancel it as a tree, and resume it after a crash without redoing finished steps. You author jobs as plain TypeScript classes decorated with `@JobHandler`; the runtime handles claiming, retry, memoization, and lifecycle.
+
+The vendored code lives under `<paths.subsystems>/jobs/` (default `src/shared/subsystems/jobs/`) and is imported as `@shared/subsystems/jobs`. Do not hand-edit it — it is managed by the package.
+
+## Mental model
+
+A job is **stateful work**. Each execution is a row in the `job_run` table — a durable state machine you can query, cancel, and replay. This is the sharp line versus events: an *event* is an immutable fact ("contact was created"); a *job* is the work that reacts to it. If you catch yourself wanting `status`, `attempts`, or a retry policy on something, you want a job. See the sibling `events` skill for that distinction.
+
+Three tables back the system, one concept each:
+
+| Table | Meaning |
+|---|---|
+| `job` | One row per registered handler type. Materialized from your `@JobHandler` metadata at app boot. |
+| `job_run` | One row per execution. The durable state machine: queryable by scope, cancellable as a tree. |
+| `job_step` | One row per checkpoint inside a run. Powers memoization (skip already-done work on retry). |
+
+There is **one** claim mechanism: a worker polls `job_run` directly with `SELECT ... FOR UPDATE SKIP LOCKED`. There is no separate queue table and no separate "enqueue" port. You start work with `IJobOrchestrator.start(...)`; the worker discovers the row on its next poll.
+
+Run hierarchy: a child run carries `parent_run_id` and `root_run_id`. Cancelling a run cascades to its tree via `root_run_id` according to each child's close policy.
+
+### State machine
+
+```
+pending → running → { completed | failed | timed_out | canceled }
+```
+
+"Scheduled for later" is not a separate state — it is `status='pending'` with `run_at` in the future; the claim query simply skips it until `run_at` passes.
+
+## Routing table
+
+| For this task | Read |
+|---|---|
+| Writing a `@JobHandler`, using `JobContext`, `ctx.step`, spawning children, scope, plugging into a use case | `handler-authoring.md` |
+| Choosing/configuring pools, concurrency, ordering guarantees, the `jobs:` config block, embedded vs. standalone workers | `pools-and-ordering.md` |
+
+For running a job *in response to a domain event*, that is the Event-to-Job Bridge — see the `bridge` skill. You declare triggers on the same `@JobHandler` decorator; this skill covers everything else about the handler.
+
+## Non-obvious rules
+
+- **Jobs are TypeScript classes, not YAML.** There is no jobs-as-YAML codegen. You write a `@JobHandler` class; the package ships the orchestration around it.
+- **A `@JobHandler` class must also be a registered NestJS provider.** The decorator registers the class with the job registry for orchestration; it does NOT register it in Nest's DI container. Add it to the `providers` of its owning module, or the worker throws an unresolvable-provider error when it tries to run it.
+- **`step_id` must be stable across replays.** Hardcode it (`'pull_emails'`) or derive it deterministically from input. Never `Date.now()`, never random. Memoization is keyed on `(job_run_id, step_id)`; an unstable id defeats it.
+- **The default pool is `batch`.** `interactive` exists but must be opted into explicitly.
+- **The `events_inbound` / `events_change` / `events_outbound` pools are reserved.** A `@JobHandler({ pool: 'events_*' })` throws `ReservedPoolViolationError` at app boot. Those lanes belong to the event/bridge machinery. To run a job when an event fires, use `@JobHandler.triggers` (the `bridge` skill), not a reserved pool.
+- **Concurrency and dedupe are different things.** Dedupe collapses duplicate enqueues (returns the existing run id, no new row). Concurrency lets the new row exist but gates when it is claimed. Both are set once on the decorator, not per call site.
+- **`ctx.waitFor` / `ctx.signal` / `ctx.sleep` do not exist.** If you need a delay, use `ctx.spawnChild(type, input, { runAt })`. If you need to pause for external input, split the work across parent + child runs.
+
+## Do not
+
+- Do not look for an `IJobQueue` or a `job_queue` table — they do not exist. Start work with `IJobOrchestrator.start(type, input, opts)`.
+- Do not target a reserved `events_*` pool from a `@JobHandler`. It fails at boot.
+- Do not use `Date.now()` or randomness for a `step_id`.
+- Do not wrap `ctx.spawnChild` inside a `ctx.step` — a child run is its own memoization root.
+- Do not hand-edit anything under `<paths.subsystems>/jobs/`. It is vendored from the package.
+- Do not reach for a job when the caller is waiting synchronously on the result — that is a use case, not a job. Jobs are durable because they are asynchronous.