@pattern-stack/codegen 0.9.1 → 0.10.0

package/consumer-skills/jobs/handler-authoring.md

@@ -0,0 +1,236 @@
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Authoring a Job Handler
+
+This is the surface your application code touches most: how to write a `@JobHandler` class, use `JobContext` correctly, and kick a job off from a use case. Read the `jobs` `SKILL.md` first for the mental model.
+
+## Minimal handler
+
+```ts
+import {
+  JobHandler,
+  JobHandlerBase,
+  JobContext,
+  ParentClosePolicy,
+} from '@shared/subsystems/jobs';
+import type { ScopeEntityType } from '@shared/jobs/scope-entity-type';
+
+interface OnboardingInput {
+  accountId: string;
+}
+
+interface OnboardingOutput {
+  emailCount: number;
+}
+
+@JobHandler<OnboardingInput>('onboarding', {
+  pool: 'batch',
+  scope: {
+    entity: 'account' satisfies ScopeEntityType,
+    from: (input) => input.accountId,
+  },
+  retry: { attempts: 3, backoff: 'exponential', baseMs: 1000 },
+  concurrency: {
+    key: (input) => `account:${input.accountId}`,
+    collisionMode: 'queue',
+  },
+  dedupe: {
+    key: (input) => `onboarding:${input.accountId}`,
+    windowMs: 24 * 60 * 60 * 1000,
+  },
+  timeoutMs: 60 * 60 * 1000,
+  replayFrom: 'last_checkpoint',
+})
+export class OnboardingHandler extends JobHandlerBase<OnboardingInput, OnboardingOutput> {
+  constructor(
+    private readonly emails: EmailService,
+    private readonly facts: FactService,
+  ) {
+    super();
+  }
+
+  async run(ctx: JobContext<OnboardingInput>): Promise<OnboardingOutput> {
+    const emails = await ctx.step('pull_emails', () =>
+      this.emails.pullForAccount(ctx.input.accountId),
+    );
+
+    await ctx.spawnChild(
+      'process_facts',
+      { emailIds: emails.map((e) => e.id) },
+      { closePolicy: ParentClosePolicy.Terminate },
+    );
+
+    return { emailCount: emails.length };
+  }
+}
+```
+
+The handler class:
+- **extends `JobHandlerBase<TInput, TOutput>`** and implements the single `run(ctx)` method.
+- is decorated with `@JobHandler<TInput>('job_type', meta)`. The string is the unique job type — it is what you pass to `orchestrator.start(...)`.
+
+### Register the class as a provider
+
+The decorator registers the class with the job registry so the worker knows the type exists. It does **not** register it with Nest's DI container — that is on you. Add the handler to the `providers` array of its owning module (e.g. an entity/feature module). At runtime the worker resolves it via the Nest module tree; a handler that is not a registered provider fails when its first run is claimed. Constructor injection works like any provider, as long as the providing module is imported where your handler lives.
+
+## Decorator metadata reference
+
+Everything except the `type` positional argument is optional.
+
+| Field | Shape | Notes |
+|---|---|---|
+| `pool` | `string` | Default `'batch'`. Must not be a reserved `events_*` pool — app boot throws `ReservedPoolViolationError`. `interactive` is allowed but must be explicit. See `pools-and-ordering.md`. |
+| `scope` | `{ entity: ScopeEntityType; from: (input) => string }` | Ties each run to a domain entity id so you can later list/cancel "everything for this account". `entity` should be `'<name>' satisfies ScopeEntityType`. |
+| `retry` | `{ attempts, backoff: 'fixed' \| 'exponential', baseMs, nonRetryableErrors? }` | Run-level retry across the whole handler. Independent of step-level retry. |
+| `concurrency` | `{ key: (input) => string; collisionMode: 'queue' \| 'reject' \| 'replace' }` | Evaluated at enqueue. See collision modes below. |
+| `dedupe` | `{ key: (input) => string; windowMs: number }` | Collapses duplicate enqueues inside the window — returns the existing run id, no new row. |
+| `timeoutMs` | `number` | Hard wall-clock cap across all retries. Breach → `status='timed_out'`. |
+| `replayFrom` | `'scratch' \| 'last_step' \| 'last_checkpoint'` | Default `'last_checkpoint'`. Only matters when a run is replayed. |
+| `triggers` | `JobTrigger<TInput>[]` | Bind this job to domain events — covered by the `bridge` skill, not here. |
+
+### Concurrency collision modes
+
+Set once on the decorator, not per call site. Two runs collide when their `key(input)` matches and the incumbent is still in a non-terminal state.
+
+- `queue` (default) — the new run is accepted as `pending`; it is only claimed once the incumbent leaves its non-terminal state. Serializes by key.
+- `reject` — the new `start(...)` throws `JobCollisionError` carrying the incumbent's run id.
+- `replace` — the incumbent is cancelled (cascade), the new run starts. The "latest wins" pattern.
+
+Concurrency is orthogonal to dedupe: dedupe short-circuits (no new row); concurrency queues (new row exists, claim is gated).
+
+### Replay modes
+
+`replayFrom` is a memoization policy only — the same handler code runs in all cases. It controls what `job_step` rows survive when a run is replayed:
+
+- `scratch` — clear all step rows, re-enter from empty. Your steps must be safe to re-run.
+- `last_step` — clear only the failing step's row; completed steps stay memoized.
+- `last_checkpoint` (default) — clear nothing; every completed step returns its cached output.
+
+## Using `JobContext`
+
+```ts
+ctx.input    // your TInput, typed via @JobHandler<TInput> — no cast needed
+ctx.run      // the JobRun row (id, rootRunId, parentRunId, scope, tags, attempts, ...)
+ctx.step(id, fn, opts?)            // durable, memoized step
+ctx.spawnChild(type, input, opts?) // launch a child run, returns its JobRun
+ctx.logger   // a NestJS Logger scoped to this run — prefer it over console.log
+```
+
+### `ctx.step(stepId, fn, opts?)` — durable memoized step
+
+Wrap anything slow, side-effectful, or externally costly. The first successful run persists `fn`'s output to `job_step`; on a retry or replay, the cached value is returned without calling `fn` again.
+
+Rules:
+- `stepId` must be **stable across replays** — hardcode (`'pull_emails'`) or derive deterministically (`` `recompute:${ctx.input.accountId}` ``). Never `Date.now()`, never random, never a mutable counter.
+- `stepId` is unique within a run. Calling `ctx.step('x', …)` twice with the same id returns the cached value the second time.
+- `fn`'s return value must be JSON-serializable — it is stored in a `jsonb` column.
+- Design `fn` to be idempotent if you use `replayFrom: 'scratch'`.
+- An error inside `fn` marks the step failed and rethrows. If the run has retries left, the whole run re-enters `pending`; on the next tick, completed sibling steps stay memoized and only this step retries.
+
+Step-level retry (separate from run-level retry, wraps just this step):
+
+```ts
+await ctx.step('fetch_profile', () => api.get(...), {
+  retry: { attempts: 2, backoff: 'fixed', baseMs: 500 },
+  timeoutMs: 30_000,
+});
+```
+
+### `ctx.spawnChild(type, input, opts?)` — launch a child run
+
+```ts
+const child = await ctx.spawnChild(
+  'process_facts',
+  { emailIds },
+  {
+    closePolicy: ParentClosePolicy.Terminate, // default; children die if the parent does
+    runAt: new Date(Date.now() + 5_000),       // optional delay
+    priority: 10,
+    tags: { triggeredBy: 'onboarding' },
+  },
+);
+```
+
+- `parent_run_id` and `root_run_id` are wired automatically.
+- `closePolicy` is recorded on the child at spawn time; later changes to the parent do not retroactively rewrite it.
+  - `ParentClosePolicy.Terminate` (default) — running children are cancelled when the parent reaches any terminal state.
+  - `ParentClosePolicy.Cancel` — same effect, but the parent's `finished_at` is held until children finish transitioning.
+  - `ParentClosePolicy.Abandon` — children are left running (fire-and-forget).
+- Do not wrap `spawnChild` in a `ctx.step` — the child is its own memoization root. If you need cross-invocation idempotency on a child, put `dedupe` on the child job type.
+- There is **no built-in "await child completion"** primitive. If you need sequencing, split the parent's logic: the parent spawns the child (with its own scope) and completes; a follow-up handler watches for child completion via `listForScope`.
+
+## Kicking a job off from a use case
+
+Inject the orchestrator token and call `start`:
+
+```ts
+import { Inject, Injectable } from '@nestjs/common';
+import { JOB_ORCHESTRATOR, type IJobOrchestrator } from '@shared/subsystems/jobs';
+
+@Injectable()
+export class StartOnboardingUseCase {
+  constructor(
+    @Inject(JOB_ORCHESTRATOR) private readonly jobs: IJobOrchestrator,
+  ) {}
+
+  async execute(accountId: string) {
+    return this.jobs.start(
+      'onboarding',
+      { accountId },
+      {
+        scope: { entityType: 'account', entityId: accountId },
+        triggerSource: 'manual',
+        tags: { source: 'admin-ui' },
+      },
+    );
+  }
+}
+```
+
+- `start` returns the inserted `JobRun` immediately; the worker picks it up on its next poll.
+- If `dedupe` matches an in-window prior run, `start` returns the existing run id — free idempotency for the caller.
+- With `collisionMode: 'reject'`, `start` throws `JobCollisionError` synchronously — catch it in the use case.
+- Pass `triggerSource: 'manual' | 'schedule' | 'event' | 'parent'` so the run's `trigger_source` is accurate for observability.
+
+## Managing runs by entity — `IJobRunService`
+
+`scope` on the decorator makes "everything for this account" queryable:
+
+```ts
+import { JOB_RUN_SERVICE, type IJobRunService } from '@shared/subsystems/jobs';
+
+@Inject(JOB_RUN_SERVICE) private readonly runs: IJobRunService;
+
+await this.runs.listForScope('account', accountId, { status: 'running' });
+await this.runs.cancelForScope('account', accountId);      // cascades per close policy
+await this.runs.rescheduleForScope('account', accountId, tomorrow);
+```
+
+The entity type is a plain string at the database layer; type safety comes from `satisfies ScopeEntityType` at the call site. `ScopeEntityType` is a generated union of every entity that declared `scopeable: true` in its YAML — re-run codegen after adding a new scopeable entity to refresh `@shared/jobs/scope-entity-type`.
+
+## Common shapes
+
+- **Fan-out** — parent `ctx.step`s a batch, then `ctx.spawnChild` per item with `ParentClosePolicy.Terminate`. Cancel the parent → children die.
+- **Sequenced pipeline** — chain `ctx.step` calls in one handler (simplest), or split into dedicated handler types with `ParentClosePolicy.Abandon` so each hop is independently queryable and retryable.
+- **Latest-wins loop** — `concurrency.collisionMode: 'replace'`, keyed by the entity id. A newer trigger cancels the incumbent.
+- **Webhook ingestion** — `dedupe.key: (input) => input.externalId` collapses replays within the window, no app-level idempotency table needed.
+- **Long batch with safe resume** — `replayFrom: 'last_checkpoint'` (the default) + one `ctx.step` per work unit → a crash only repeats unfinished work.
+
+## Testing a handler
+
+`@JobHandler` classes work inside `Test.createTestingModule` with the memory backend, which is behavior-parity with the production backend for claim order, collision modes, step memoization, cascade cancel, dedupe, and replay:
+
+```ts
+const moduleRef = await Test.createTestingModule({
+  imports: [JobWorkerModule.forRoot({ mode: 'embedded', backend: 'memory' })],
+  providers: [OnboardingHandler, /* ...deps */],
+}).compile();
+```
+
+Then `orchestrator.start('onboarding', input)`, advance a few ticks, and assert on the stored runs and steps.
+
+## When NOT to use a handler
+
+- **Synchronous request/response** — if the caller awaits the result, write a use case, not a job.
+- **Reacting to every domain event** — those flow through the events subsystem and (for durable async fanout) the bridge, not a direct handler. See the `events` and `bridge` skills.
+- **Per-request rate limiting** — there is no built-in request rate-limit primitive in the core contract.

package/consumer-skills/jobs/pools-and-ordering.md

@@ -0,0 +1,161 @@
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Pools, Ordering, and Configuration
+
+How pools work, how to configure them in `codegen.config.yaml`, how to get the ordering guarantee you actually need, and how to wire the job worker into your app. Read this when you are choosing a pool for a handler, adding a custom pool, or deciding between embedded and standalone workers.
+
+## What a pool is
+
+A pool is a logical lane. Each pool maps to:
+- A distinct queue identifier (written into `job_run.pool`).
+- One worker instance per active pool per process.
+- A `concurrency` cap — the max number of in-flight runs that pool processes at once.
+
+**Pools are absolute lanes — there is no cross-pool preemption.** A high-priority `batch` run does not jump ahead of `interactive`. If you need isolation between two classes of work, give them separate pools. This is deliberate: priority-based scheduling within one queue can starve low-priority work under sustained load; separate lanes cannot.
+
+## The default pools
+
+Your installed `jobs:` config ships five pools:
+
+| Pool | concurrency | reserved | Use for |
+|---|---|---|---|
+| `events_inbound` | 20 | yes | (framework) external → us event traffic |
+| `events_change` | 30 | yes | (framework) internal change-event traffic |
+| `events_outbound` | 10 | yes | (framework) us → external event traffic |
+| `interactive` | 20 | no | User-waiting work: exports, renders, ad-hoc one-offs |
+| `batch` | 5 | no | Background work: onboarding, ingest, long jobs. **Default for your handlers.** |
+
+You may override `concurrency` (and `description`) on the non-reserved pools, and you may add your own.
+
+### Reserved pools are off-limits to your handlers
+
+The three `events_*` pools exist only to carry event/bridge traffic, one lane per event direction. A `@JobHandler({ pool: 'events_change' })` (or any reserved pool) throws `ReservedPoolViolationError` at app boot — the error names the offending class. You cannot flip `reserved` off in config, and you cannot mark your own pools `reserved`.
+
+To run a job *when an event fires*, declare `@JobHandler.triggers` and let the bridge enqueue it into your chosen (non-reserved) pool. See the `bridge` skill.
+
+## The `jobs:` config block
+
+`codegen subsystem install jobs` injects this into `codegen.config.yaml`:
+
+```yaml
+jobs:
+  backend: drizzle                 # 'drizzle' (default, Postgres) | 'memory' (tests) | 'bullmq' (opt-in)
+
+  extensions:
+    drizzle:
+      poll_interval_ms: 1000
+      # listen_notify: true        # opt-in Postgres LISTEN/NOTIFY for sub-second wakeups
+
+  multi_tenant: false              # true → service layer requires a tenantId
+
+  worker_mode: embedded            # embedded | standalone (operational hint; see below)
+
+  pools:
+    events_inbound:  { queue: jobs-events-inbound,  concurrency: 20, reserved: true }
+    events_change:   { queue: jobs-events-change,   concurrency: 30, reserved: true }
+    events_outbound: { queue: jobs-events-outbound, concurrency: 10, reserved: true }
+    interactive:     { queue: jobs-interactive,     concurrency: 20 }
+    batch:           { queue: jobs-batch,           concurrency: 5 }
+```
+
+Field notes:
+
+| Key | What it controls |
+|---|---|
+| `backend` | Which orchestrator implementation runs. `drizzle` (Postgres) is the portable default. `memory` is for tests. `bullmq` is opt-in (see below). |
+| `extensions.<backend>.*` | Backend-specific knobs. Each backend reads only its own key; unknown keys are ignored, not errors. |
+| `multi_tenant` | When `true`, service methods require a `tenantId` (explicit `null` allowed for cross-tenant work). The `tenant_id` column exists regardless, so flipping this later needs no migration. |
+| `worker_mode` | Informational hint only — both worker entrypoints are always scaffolded. See "Worker topology". |
+| `pools.<name>.queue` | The queue identifier written into `job_run.pool`. Must be unique. |
+| `pools.<name>.concurrency` | Per-process max in-flight for that pool. Running more processes multiplies it. |
+
+## Adding a custom pool
+
+Pure config change — no code edits:
+
+```yaml
+jobs:
+  pools:
+    # framework defaults are merged automatically; you only add yours
+    agents:
+      queue: jobs-agents
+      concurrency: 3
+      description: "Long-running LLM / agent work"
+```
+
+Then any `@JobHandler({ pool: 'agents', … })` targets it. The worker discovers the pool at boot and starts its claim loop.
+
+## Ordering: parallelism vs. order
+
+By default a pool runs at its configured concurrency, so two runs in the same pool can execute concurrently. There is **no implicit ordering guarantee**. If you genuinely need ordered execution, choose the narrowest knob that satisfies the requirement:
+
+1. **Per-entity ordering (preferred).** Set `concurrency` on the `@JobHandler` with a key derived from the entity and `collisionMode: 'queue'`:
+
+   ```ts
+   @JobHandler<ProvisionInput>('provision_workspace', {
+     concurrency: {
+       key: (input) => `account:${input.accountId}`,
+       collisionMode: 'queue',
+     },
+   })
+   ```
+
+   This serializes runs sharing the same key while keeping unrelated keys parallel. Keeps throughput high.
+
+2. **Whole-pool serialization (blunt).** Set `concurrency: 1` on the pool in config. Serializes *every* run in that pool end to end. Use only when every run in the pool genuinely needs strict order — it caps throughput hard.
+
+If you think you need strict ordering *across different entities*, reconsider — that is usually a sign the work should tolerate independent timelines.
+
+## Worker topology — embedded vs. standalone
+
+Both entrypoints are always scaffolded. The choice is operational; switching needs no regeneration.
+
+**Embedded** — your `AppModule` imports `JobWorkerModule.forRoot({ mode: 'embedded' })`. The API process and the workers share the same process. Simplest; good default for dev and small deployments.
+
+**Standalone** — run the scaffolded `worker.ts` as its own process. `main.ts` does not import `JobWorkerModule`; the worker boots a bare Nest application context (no HTTP listener) with the database module plus the jobs modules. Lets you scale workers independently of the API.
+
+## Wiring into your app
+
+Two modules, both `global: true`:
+
+```ts
+import { JobWorkerModule } from '@shared/subsystems/jobs';
+
+@Module({
+  imports: [
+    DatabaseModule,
+    // Brings the orchestrator/services AND runs the worker claim loops:
+    JobWorkerModule.forRoot({ mode: 'embedded', backend: 'drizzle' }),
+    // ...
+  ],
+})
+export class AppModule {}
+```
+
+`JobWorkerModule.forRoot({ mode, backend?, pools?, multiTenant?, shutdownTimeoutMs? })` imports `JobsDomainModule` internally and starts a worker per active pool. The protocol tokens (`JOB_ORCHESTRATOR`, `JOB_RUN_SERVICE`, `JOB_STEP_SERVICE`) become available project-wide.
+
+- Pass `pools: ['batch', 'agents']` to restrict which pools *this* process services — useful for heterogeneous standalone deploys. Pools omitted from the list are not claimed by this process.
+- A process that only needs to *start* jobs (not run them) can import `JobsDomainModule.forRoot({ backend })` alone — services available, no worker loop.
+
+Tests swap the backend:
+
+```ts
+JobWorkerModule.forRoot({ mode: 'embedded', backend: 'memory' })
+```
+
+## Backend choice
+
+The portability contract is the same across backends: code written against `IJobOrchestrator` + `IJobRunService` + `IJobStepService` works on any backend. Backend-specific features live under `extensions.<backend>`.
+
+- **`drizzle`** (default) — Postgres only, no extra infra. The worker polls `job_run`. Extensions: `poll_interval_ms`, opt-in `listen_notify`.
+- **`memory`** — in-process, for tests. Behavior-parity with Drizzle for the scenarios that matter.
+- **`bullmq`** — opt-in via `backend: bullmq`. Postgres `job_run` stays the domain source of truth; BullMQ replaces only the claim/dispatch half. Extensions include a Bull Board admin UI mount and `FlowProducer` access. Choose this only after you have a measured reason to.
+
+## Multi-tenancy
+
+`jobs.multi_tenant: true` is a single opt-in:
+- Backend methods accept a `tenantId`; a missing one throws when the flag is on (explicit `null` allowed for cross-tenant background work).
+- Claim, `listForScope`, `cancel`, etc. filter by `tenantId`.
+- The `tenant_id` column is always present, so flipping the flag never needs a migration.
+
+Also pass `multiTenant: true` to `JobWorkerModule.forRoot(...)` so the runtime enforces it, and keep the config flag and the module option in agreement.

package/consumer-skills/subsystems/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: subsystems
+description: >-
+  Load when installing or wiring an infrastructure subsystem in a project that
+  uses @pattern-stack/codegen — events, jobs, cache, storage, sync, bridge,
+  observability, auth, or the OpenAPI config. Covers `codegen subsystem
+  install`, the `forRoot` registration ORDER in app.module.ts, which subsystems
+  depend on which, and multi-tenancy opt-in. Get the order wrong and the bridge
+  sits idle or observability sees nothing — this skill is the source of truth
+  for ordering until the CLI enforces it.
+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. -->
+
+# Infrastructure subsystems
+
+Subsystems are the generated infrastructure your use cases call: an event bus,
+a job queue, a cache, file storage, an external-sync engine, the event-to-job
+bridge, a read-only observability facade, and OAuth auth. Each follows one
+pattern — **Protocol (port) → Backend (adapter) → Factory (`DynamicModule.
+forRoot`)** — and each is `global: true`, so you register it once in
+`app.module.ts` and inject its token anywhere.
+
+## Mental model
+
+- **Install vendors runtime + injects config.** `codegen subsystem install
+  <name>` copies the subsystem's runtime into `<subsystems-root>/<name>/`
+  (default `src/shared/subsystems/<name>/`) and adds its block to
+  `codegen.config.yaml`. You then add one `forRoot(...)` line to `app.module.ts`.
+- **Backends are swappable; tests use memory.** Most subsystems ship a Drizzle
+  (Postgres) production backend and a memory backend for tests. Swap via the
+  `forRoot({ backend })` arg — app code is unchanged.
+- **Order matters.** Some subsystems consume others. The bridge consumes events
+  + jobs; observability composes events/jobs/bridge/sync read ports via
+  optional DI. Registering them in the wrong order means a silently idle bridge
+  or an observability facade that reports nothing. See `wiring-and-order.md`.
+
+## The subsystems
+
+| Subsystem | Token / module | Install | Depends on |
+|---|---|---|---|
+| events | `EventsModule` | `subsystem install events` | — |
+| jobs | `JobsDomainModule` + `JobWorkerModule` | `subsystem install jobs` | — |
+| cache | `CacheModule` | `subsystem install cache` | jobs (optional, for cleanup) |
+| storage | `StorageModule` | `subsystem install storage` | — |
+| sync | `SyncModule` | `subsystem install sync` | — |
+| bridge | `BridgeModule` | `subsystem install bridge` | **events + jobs** |
+| observability | `ObservabilityModule` | `subsystem install observability` | composes events/jobs/bridge/sync (optional) |
+| auth | `AuthModule` | `subsystem install auth` | — |
+| auth-integrations | `IntegrationsAuthModule` | `subsystem install auth-integrations` | **auth** |
+| openapi | (config only) | `subsystem install openapi-config` | registry vendored at init |
+
+## Registration order (authoritative)
+
+In `app.module.ts`, import in this order (omit what you haven't installed):
+
+1. `DatabaseModule` — provides `DRIZZLE`; must be first.
+2. `OpenApiModule` — the registry singleton (vendored at init).
+3. `EventsModule.forRoot(...)`
+4. `JobsDomainModule.forRoot(...)` **and** `JobWorkerModule.forRoot(...)`
+5. `CacheModule` / `StorageModule` / `SyncModule.forRoot(...)`
+6. `BridgeModule.forRoot(...)` — **after** events + jobs.
+7. `ObservabilityModule.forRoot(...)` — **last** of the subsystems (composes the
+   ones above via optional DI).
+8. `...GENERATED_MODULES` — your entity modules.
+
+For auth: register `AuthModule.forRoot(...)` before the `IntegrationsAuthModule`
+that depends on it. Full per-subsystem `forRoot` signatures, the bridge reserved
+pools, and multi-tenancy are in `wiring-and-order.md`.
+
+## Non-obvious rules
+
+- **Jobs is two modules, not one.** `JobsDomainModule.forRoot({ backend })`
+  wires the orchestrator/run-services; `JobWorkerModule.forRoot({ mode, backend,
+  pools })` runs the worker loop. Pool *definitions* (concurrency, reserved
+  lanes) live in `codegen.config.yaml` under `jobs.pools`; `JobWorkerModule`'s
+  `pools:` is the list of *active* pool names this process drains.
+- **The bridge will sit idle unless its reserved pools are polled.** The worker
+  must drain `events_inbound` / `events_change` / `events_outbound` — spread
+  `...BRIDGE_RESERVED_POOLS` into `JobWorkerModule`'s `pools`, or use `allPools:
+  true`. `BridgeModule` fails fast at boot if they aren't polled. See the
+  `bridge` skill.
+- **Observability composes optionally.** It reads whatever sibling subsystems
+  are present; missing ones are simply absent from its output. That's why it
+  must be registered after them.
+- **Multi-tenancy is a config flip + a `forRoot` flag + a migration** — never a
+  runtime-only toggle. See `wiring-and-order.md`.
+- **`--backend memory`** is for tests; the scaffolded default is `drizzle`
+  (`local` for storage).
+
+## Do not
+
+- **Do not register `BridgeModule` before `EventsModule` + the jobs modules** —
+  it consumes their tokens.
+- **Do not register `ObservabilityModule` before the subsystems it reports on.**
+- **Do not route your own jobs into the reserved `events_*` pools** — those are
+  the bridge's; module init rejects it. Declare your own pool.
+- **Do not hand-edit vendored subsystem files** under `<subsystems-root>/<name>/`
+  — `codegen update` overwrites them. Compose/subclass instead.
+- **Do not expect `codegen update` to refresh subsystem *schemas*.** It re-syncs
+  runtime source, not the tenancy-gated Drizzle schema files. If a schema shape
+  changed across versions, re-run `subsystem install <name> --force
+  --force-config`.

package/consumer-skills/subsystems/wiring-and-order.md

@@ -0,0 +1,120 @@
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Subsystem wiring & registration order
+
+The exact `forRoot` signatures and a complete `app.module.ts` example. All
+modules are `global: true` — register once here; inject the token anywhere.
+
+## Complete `app.module.ts`
+
+```ts
+import { Global, Module } from '@nestjs/common';
+import { DatabaseModule } from './shared/database/database.module';
+import { GENERATED_MODULES } from './generated/modules';
+import { OPENAPI_REGISTRY, OpenApiRegistry } from './shared/openapi';
+
+import { EventsModule } from '@shared/subsystems/events';
+import { JobsDomainModule, JobWorkerModule } from '@shared/subsystems/jobs';
+import { CacheModule } from '@shared/subsystems/cache';
+import { StorageModule } from '@shared/subsystems/storage';
+import { SyncModule } from '@shared/subsystems/sync';
+import { BridgeModule, BRIDGE_RESERVED_POOLS } from '@shared/subsystems/bridge';
+import { ObservabilityModule } from '@shared/subsystems/observability';
+
+@Global()
+@Module({
+  providers: [{ provide: OPENAPI_REGISTRY, useValue: new OpenApiRegistry() }],
+  exports: [OPENAPI_REGISTRY],
+})
+class OpenApiModule {}
+
+@Module({
+  imports: [
+    // 1. database first — provides DRIZZLE
+    DatabaseModule,
+    // 2. openapi registry singleton
+    OpenApiModule,
+    // 3. events
+    EventsModule.forRoot({ backend: 'drizzle' }),
+    // 4. jobs — domain layer + worker loop
+    JobsDomainModule.forRoot({ backend: 'drizzle' }),
+    JobWorkerModule.forRoot({
+      mode: 'embedded',
+      backend: 'drizzle',
+      // include the bridge's reserved pools so wrappers actually drain:
+      pools: ['interactive', 'batch', ...BRIDGE_RESERVED_POOLS],
+    }),
+    // 5. cache / storage / sync
+    CacheModule.forRoot({ backend: 'drizzle' }),
+    StorageModule.forRoot({ backend: 'local' }),
+    SyncModule.forRoot({ backend: 'drizzle' }),
+    // 6. bridge — AFTER events + jobs
+    BridgeModule.forRoot({ backend: 'drizzle', multiTenant: false }),
+    // 7. observability — LAST (composes the siblings above)
+    ObservabilityModule.forRoot({ reporters: { bridgeMetrics: true } }),
+    // 8. your generated entity modules
+    ...GENERATED_MODULES,
+  ],
+})
+export class AppModule {}
+```
+
+## Per-subsystem `forRoot`
+
+| Module | Signature | Notes |
+|---|---|---|
+| `EventsModule` | `forRoot({ backend, multiTenant?, pools? })` | `backend: 'drizzle' \| 'memory'`. `pools` restricts this process's drain loop to specific event lanes. |
+| `JobsDomainModule` | `forRoot({ backend, multiTenant?, extensions? })` | `backend: 'drizzle' \| 'memory' \| 'bullmq'`. Domain layer (orchestrator, run/step services). `extensions.bullmq` / `extensions.drizzle` are the opt-in backend extras. |
+| `JobWorkerModule` | `forRoot({ mode, backend?, pools?, allPools?, shutdownTimeoutMs? })` | `mode: 'embedded' \| 'standalone'`. `pools` = active pool names this process drains (defaults to all non-reserved). `allPools: true` drains every pool incl. reserved. |
+| `CacheModule` | `forRoot({ backend })` | optionally registers a cleanup job when jobs is present. |
+| `StorageModule` | `forRoot({ backend })` | `backend: 'local' \| 'memory'`. Implement S3/GCS by implementing the storage protocol. |
+| `SyncModule` | `forRoot({ backend, multiTenant? })` | wires the cursor store / run recorder / differ ports — NOT the orchestrator (that's per-entity; see the `sync` skill). |
+| `BridgeModule` | `forRoot({ backend, multiTenant? })` | must come after events + jobs; fails fast at boot if reserved pools aren't polled. |
+| `ObservabilityModule` | `forRoot({ reporters? })` | read-only facade; `reporters.bridgeMetrics: true` opts into the 60s bridge sampler. Register last. |
+| `AuthModule` | `forRoot({ encryptionKey, oauthStateStore })` | `global: true`; provides `ENCRYPTION_KEY` + `OAUTH_STATE_STORE`. Register before `IntegrationsAuthModule`. |
+
+## Pool configuration (jobs)
+
+Pool *definitions* live in `codegen.config.yaml`, not in `forRoot`:
+
+```yaml
+jobs:
+  backend: drizzle
+  pools:
+    - { name: interactive, concurrency: 8 }
+    - { name: batch,       concurrency: 2 }
+    # the bridge's reserved lanes (events_inbound/_change/_outbound) are
+    # provided by BRIDGE_RESERVED_POOLS — see the bridge skill
+```
+
+`JobWorkerModule.forRoot({ pools })` then names which of those a given worker
+process drains — scale horizontally by running one worker per pool subset.
+
+## Multi-tenancy opt-in (events / jobs / sync / bridge)
+
+Three coordinated steps — never a runtime-only toggle:
+
+1. Flip the config flag, e.g. `events.multi_tenant: true` in
+   `codegen.config.yaml`.
+2. Re-run the install to re-emit the tenancy-aware schema:
+   `codegen subsystem install <name> --force --force-config`.
+3. Pass `multiTenant: true` to that subsystem's `forRoot(...)`, and cut an Atlas
+   migration for the new `tenant_id` column(s).
+
+With `multiTenant: true`, the enforcement sites throw a `MissingTenantIdError`
+when a tenant id is required but absent (explicit `null` is allowed for
+tenant-less / cross-tenant work).
+
+## Why ordering matters (the dependency graph)
+
+- **bridge → events + jobs.** The bridge claims `domain_events` rows and starts
+  wrapper job runs in the reserved pools. Without events + jobs registered (and
+  the reserved pools polled) it has nothing to consume and nowhere to write.
+- **observability → events/jobs/bridge/sync (optional).** It composes the read
+  ports of whatever siblings exist, via optional DI. Register it last so those
+  ports are already bound; missing siblings are simply omitted from its output.
+- **auth-integrations → auth.** The integration adapters need the encryption key
+  + token provided by `AuthModule`.
+
+Until the CLI enforces this graph, treat this file as the source of truth and
+keep `app.module.ts` in the order above.