@pattern-stack/codegen 0.9.2 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,7 @@
     "dist",
     "runtime",
     "templates",
+    "consumer-skills",
     "examples/auth-integrations/**",
     "src/config/*.mjs",
     "src/schema/naming-config.schema.mjs",

package/runtime/subsystems/events/event-bus.drizzle-backend.ts

@@ -59,17 +59,16 @@ const POLL_BATCH_SIZE = 50;
  * the per-event extraction logic in one place so publish/publishMany stay
  * in sync.
  */
-function toInsertValues(event: DomainEvent) {
+function toInsertValues(event: DomainEvent, multiTenant: boolean) {
   const metadata = event.metadata ?? undefined;
   const pool = (metadata?.['pool'] as string | undefined) ?? null;
   const direction = (metadata?.['direction'] as string | undefined) ?? null;
-  const tenantId = (metadata?.['tenantId'] as string | undefined) ?? null;
   // AUDIT-1: tier defaults to 'domain' when absent. The DB CHECK
   // constraint (`domain_events_tier_routing_check`) enforces the
   // tier ⇔ routing-fields invariant at the storage boundary; no
   // JS-side assertion is needed here.
   const tier = (metadata?.['tier'] as string | undefined) ?? 'domain';
-  return {
+  const base = {
     id: event.id,
     type: event.type,
     aggregateId: event.aggregateId,
@@ -82,8 +81,14 @@ function toInsertValues(event: DomainEvent) {
     pool,
     direction,
     tier,
-    tenantId,
   };
+  // EVT-8: `tenant_id` is a scaffold-time conditional column, emitted only
+  // when `events.multi_tenant: true`. Only write it when multi-tenancy is
+  // on — under single-tenant scaffolds the column does not exist, so the
+  // key must be omitted from the insert.
+  if (!multiTenant) return base;
+  const tenantId = (metadata?.['tenantId'] as string | undefined) ?? null;
+  return { ...base, tenantId };
 }
 
 /**
@@ -107,7 +112,11 @@ function toEventSummary(r: DomainEventRecord) {
     direction: r.direction,
     tier: r.tier,
     rootRunId: typeof rootRunId === 'string' ? rootRunId : null,
-    tenantId: r.tenantId,
+    // EVT-8: `tenant_id` is a scaffold-time conditional column. Read it
+    // structurally so this projection typechecks against both the
+    // multi-tenant schema (column present) and the single-tenant schema
+    // (column absent → undefined → null).
+    tenantId: (r as { tenantId?: string | null }).tenantId ?? null,
     occurredAt:
       r.occurredAt instanceof Date
         ? r.occurredAt
@@ -175,13 +184,17 @@ export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit,
 
   async publish(event: DomainEvent, tx?: DrizzleTransaction): Promise<void> {
     const client = (tx ?? this.db) as DrizzleClient;
-    await client.insert(domainEvents).values(toInsertValues(event));
+    const multiTenant = this.opts.multiTenant ?? false;
+    await client.insert(domainEvents).values(toInsertValues(event, multiTenant));
   }
 
   async publishMany(events: DomainEvent[], tx?: DrizzleTransaction): Promise<void> {
     if (events.length === 0) return;
     const client = (tx ?? this.db) as DrizzleClient;
-    await client.insert(domainEvents).values(events.map(toInsertValues));
+    const multiTenant = this.opts.multiTenant ?? false;
+    await client
+      .insert(domainEvents)
+      .values(events.map((e) => toInsertValues(e, multiTenant)));
   }
 
   async findById(eventId: string): Promise<DomainEvent | null> {
@@ -241,11 +254,20 @@ export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit,
         sql`${domainEvents.metadata}->>'rootRunId' = ${query.rootRunId}`,
       );
     }
-    if (query.tenantId !== undefined) {
+    // EVT-8: `tenant_id` is a scaffold-time conditional column (emitted only
+    // under `events.multi_tenant: true`). Guard the filter behind the same
+    // `multiTenant` flag, and read the column structurally so this backend
+    // typechecks against both the multi-tenant schema (column present) and
+    // the single-tenant schema (column absent). When multi-tenancy is off
+    // there is no `tenant_id` column to filter on.
+    if (this.opts.multiTenant && query.tenantId !== undefined) {
+      const tenantIdColumn = (
+        domainEvents as unknown as { tenantId: typeof domainEvents.pool }
+      ).tenantId;
       conditions.push(
         query.tenantId === null
-          ? (sql`${domainEvents.tenantId} is null` as SQL<unknown>)
-          : eq(domainEvents.tenantId, query.tenantId),
+          ? (sql`${tenantIdColumn} is null` as SQL<unknown>)
+          : eq(tenantIdColumn, query.tenantId),
       );
     }
 

package/runtime/subsystems/events/events.module.ts

@@ -57,9 +57,27 @@ import { DRIZZLE } from '../../constants/tokens';
 import type { DrizzleClient } from '../../types/drizzle';
 import { DrizzleEventBus } from './event-bus.drizzle-backend';
 import { MemoryEventBus } from './event-bus.memory-backend';
-import { RedisEventBus } from './event-bus.redis-backend';
+// #6 — `RedisEventBus` is lazy-loaded only when `backend: 'redis'` is selected.
+// The file is filtered out of the vendor set for non-redis installs (see
+// `backendFileFilter` in src/cli/commands/subsystem.ts); the dynamic-string
+// import below makes TS treat the specifier as `any` so the consumer's tsc
+// never tries to resolve the absent file.
 import { TypedEventBus } from './generated/bus';
 
+/**
+ * Lazy-load the Redis backend. Routed through a non-literal specifier so
+ * the consumer's `tsc` doesn't resolve `./event-bus.redis-backend` at type
+ * check time — important because that file is filtered out of drizzle/
+ * memory installs (#6).
+ */
+async function loadRedisEventBus(): Promise<new (url: string) => object> {
+  // Non-literal specifier — TS gives this an `any` module type, sidestepping
+  // resolution of a file that may not be vendored.
+  const specifier = './event-bus.redis-backend';
+  const mod = (await import(specifier)) as { RedisEventBus: new (url: string) => object };
+  return mod.RedisEventBus;
+}
+
 export interface EventsModuleOptions {
   backend: 'drizzle' | 'memory' | 'redis';
   /**
@@ -124,11 +142,11 @@ function buildTypedBusProviders(multiTenant: boolean): Provider[] {
  * drizzle backend is selected but no DRIZZLE provider is registered, we
  * throw a clear error instead of silently constructing a broken bus.
  */
-function buildEventBusAsync(
+async function buildEventBusAsync(
   options: EventsModuleOptions,
   db: DrizzleClient | null,
   redisUrl: string,
-): unknown {
+): Promise<unknown> {
   if (options.backend === 'drizzle') {
     if (!db) {
       throw new Error(
@@ -139,6 +157,9 @@ function buildEventBusAsync(
     return new DrizzleEventBus(db, options);
   }
   if (options.backend === 'redis') {
+    // #6: lazy import — the redis backend ships only with `--backend redis`
+    // installs; drizzle/memory consumers never touch the file.
+    const RedisEventBus = await loadRedisEventBus();
     return new RedisEventBus(redisUrl);
   }
   return new MemoryEventBus(options);
@@ -214,9 +235,20 @@ export class EventsModule {
         providers: [
           { provide: EVENTS_MODULE_OPTIONS, useValue: options },
           { provide: REDIS_URL, useValue: resolvedUrl },
-          { provide: EVENT_BUS, useClass: RedisEventBus },
-          // Register concrete class so NestJS can resolve lifecycle hooks
-          RedisEventBus,
+          {
+            // #6: useFactory + dynamic import so the consumer's tsc never
+            // needs to resolve `event-bus.redis-backend.ts` for drizzle/
+            // memory installs (the file is filtered out by
+            // `backendFileFilter`). Nest awaits async factories + manages
+            // lifecycle on the returned instance, so we drop the old bare
+            // `RedisEventBus` provider entry.
+            provide: EVENT_BUS,
+            useFactory: async (url: string): Promise<object> => {
+              const RedisEventBus = await loadRedisEventBus();
+              return new RedisEventBus(url);
+            },
+            inject: [REDIS_URL],
+          },
           ...buildTypedBusProviders(multiTenant),
         ],
         exports: [EVENT_BUS, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],

package/runtime/subsystems/events/index.ts

@@ -23,6 +23,12 @@ export { EventsModule } from './events.module';
 export type { EventsModuleOptions } from './events.module';
 export { MemoryEventBus } from './event-bus.memory-backend';
 export { DrizzleEventBus } from './event-bus.drizzle-backend';
-export { RedisEventBus } from './event-bus.redis-backend';
+// #6 — backend-specific implementation classes are NOT re-exported here.
+// `RedisEventBus` is only vendored when the consumer installs with
+// `--backend redis`; surfacing it from this barrel would force the consumer's
+// tsc to resolve `./event-bus.redis-backend` even on a drizzle/memory install
+// (the file is filtered out → TS2307). Consumers who select redis import the
+// class directly from `./event-bus.redis-backend` if they need it at all —
+// `EventsModule.forRoot({ backend: 'redis' })` lazy-loads it internally.
 export { domainEvents } from './domain-events.schema';
 export type { DomainEventRecord } from './domain-events.schema';

package/runtime/subsystems/jobs/bullmq.config.ts

@@ -6,9 +6,29 @@
  * `jobs.extensions.bullmq.*` config namespace (CLAUDE.md core/extension
  * protocol). The Drizzle backend never reads any of it.
  */
-import type { ConnectionOptions } from 'bullmq';
 import { loadPoolConfig, type PoolConfig } from './pool-config.loader';
 
+/**
+ * #6 — Structural mirror of BullMQ's `ConnectionOptions`. Declared locally
+ * so this config file (which ships into EVERY jobs install, drizzle or
+ * bullmq) does NOT need the `bullmq` peer dep resolved by the consumer's
+ * tsc. The bullmq backend internally casts to the real `ConnectionOptions`
+ * — that file is only vendored when `--backend bullmq` is selected
+ * (see `backendFileFilter`).
+ *
+ * Accepts the `{ url }` shape this resolver emits, plus the host/port/
+ * password/db form BullMQ also accepts, with an open index for any extra
+ * ioredis options consumers may flow through.
+ */
+export type BullMqConnectionOptions = {
+  url?: string;
+  host?: string;
+  port?: number;
+  password?: string;
+  db?: number;
+  [key: string]: unknown;
+};
+
 /**
  * Typed shape of `codegen.config.yaml: jobs.extensions.bullmq`. Snake_case
  * because it mirrors the YAML the consumer authors.
@@ -53,7 +73,7 @@ export interface BullMqExtensionsConfig {
  * orchestrator + worker actually consume.
  */
 export interface BullMqResolvedConfig {
-  connection: ConnectionOptions;
+  connection: BullMqConnectionOptions;
   queuePrefix?: string;
   bullBoard?: { enabled: boolean; mountPath: string };
 }
@@ -85,7 +105,7 @@ export function resolveBullMqConfig(
     ext?.redis_url ?? process.env.REDIS_URL ?? DEFAULT_REDIS_URL;
 
   const resolved: BullMqResolvedConfig = {
-    connection: { url } as ConnectionOptions,
+    connection: { url },
     queuePrefix: ext?.queue_prefix,
   };
   if (ext?.bull_board?.enabled) {

package/runtime/subsystems/jobs/index.ts

@@ -81,19 +81,24 @@ export { DrizzleJobRunService } from './job-run-service.drizzle-backend';
 export { DrizzleJobStepService } from './job-step-service.drizzle-backend';
 
 // ─── BULLMQ-1: BullMQ backend (additive; opt-in via jobs.backend: bullmq) ──
-export {
-  BullMQJobOrchestrator,
-  sha1JobId,
-} from './job-orchestrator.bullmq-backend';
-export {
-  BullMQJobWorker,
-  type BullMQJobWorkerOptions,
-} from './job-worker.bullmq-backend';
+// #6 — backend-specific implementation classes are NOT re-exported from this
+// public barrel. `BullMQJobOrchestrator` + `BullMQJobWorker` are only vendored
+// when the consumer installs with `--backend bullmq`; surfacing them here
+// would force every consumer's tsc to resolve those files even on a drizzle
+// install (filtered out → TS2307). Consumers who select bullmq import them
+// directly from their backend file; `JobsDomainModule.forRoot({ backend:
+// 'bullmq' })` + `JobWorkerModule` lazy-load them internally.
+//
+// `bullmq.config.ts` (tokens + helpers) IS still re-exported — it always
+// ships (its only type surface is a local `BullMqConnectionOptions`, no
+// `bullmq` peer-dep resolution required). The module files static-import
+// from it.
 export {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
   resolveBullMqConfig,
   resolvePoolQueueName,
+  type BullMqConnectionOptions,
   type BullMqExtensionsConfig,
   type BullMqResolvedConfig,
 } from './bullmq.config';

package/runtime/subsystems/jobs/job-worker.bullmq-backend.ts

@@ -94,13 +94,16 @@ export class BullMQJobWorker {
     }
     this.worker = new WorkerCtor(
       this.options.queueName,
-      (job) => this.process(job as Job<BullJobPayload>),
+      // #6 / noImplicitAny — explicit annotations so the file stays
+      // strict-clean even when consumers compile under a stricter tsconfig
+      // than the one used to type-check the runtime tree.
+      (job: Job<BullJobPayload>) => this.process(job),
       {
         connection: this.options.connection,
         concurrency: this.options.concurrency,
       },
     );
-    this.worker.on('failed', (job, err) => {
+    this.worker.on('failed', (job: Job<BullJobPayload> | undefined, err: Error) => {
       // BullMQ fires `failed` after EACH attempt; only mirror to job_run when
       // attempts are exhausted (BullMQ will not retry further).
       if (!job) return;

package/runtime/subsystems/jobs/job-worker.module.ts

@@ -52,12 +52,17 @@ import {
   type PoolConfig,
 } from './pool-config.loader';
 import { JobWorker, type JobWorkerOptions } from './job-worker';
-import { BullMQJobWorker } from './job-worker.bullmq-backend';
-import type { ConnectionOptions } from 'bullmq';
+// #6 — `BullMQJobWorker` is lazy-loaded only when `backend: 'bullmq'` is
+// selected (`spawnBullMQWorker` below). The file is filtered out of drizzle/
+// memory installs (see `backendFileFilter`). The `ConnectionOptions` type
+// previously imported from `'bullmq'` is replaced by `BullMqConnectionOptions`
+// from `./bullmq.config` (a self-contained structural mirror that does NOT
+// require the `bullmq` peer dep to type-check).
 import {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
   resolvePoolQueueName,
+  type BullMqConnectionOptions,
   type BullMqResolvedConfig,
 } from './bullmq.config';
 import {
@@ -157,7 +162,7 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
      */
     @Optional()
     @Inject(BULLMQ_CONNECTION)
-    private readonly bullConnection: ConnectionOptions | null = null,
+    private readonly bullConnection: BullMqConnectionOptions | null = null,
     @Optional()
     @Inject(BULLMQ_RESOLVED_CONFIG)
     private readonly bullConfig: BullMqResolvedConfig | null = null,
@@ -233,7 +238,7 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
       const worker = this.options.workerFactory
         ? this.options.workerFactory(workerOptions)
         : backend === 'bullmq'
-          ? this.spawnBullMQWorker(poolName, def.queue, def.concurrency, poolConfig)
+          ? await this.spawnBullMQWorker(poolName, def.queue, def.concurrency, poolConfig)
           : this.spawnWorker(workerOptions);
       // `JobWorker` extends Nest's lifecycle hooks but the worker isn't
       // a Nest provider here (we manage the array ourselves). Call
@@ -364,12 +369,20 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
    * orchestrator's `dispatch` via `resolvePoolQueueName(pool, …)` so producer
    * and consumer agree.
    */
-  private spawnBullMQWorker(
+  /**
+   * #6 — async + dynamic-import. The `job-worker.bullmq-backend.ts` file is
+   * filtered out of the vendor set for drizzle/memory installs (no `bullmq`
+   * peer dep needed). The non-literal import specifier makes TS treat the
+   * module as `any` so the consumer's tsc never tries to resolve an absent
+   * file. This method is only entered when `backend === 'bullmq'` — at which
+   * point the file IS vendored.
+   */
+  private async spawnBullMQWorker(
     pool: string,
     _queueAlias: string,
     concurrency: number,
     poolConfig: PoolConfig,
-  ): BullMQJobWorker {
+  ): Promise<Pick<JobWorker, 'onModuleInit' | 'onModuleDestroy'>> {
     if (!this.db) {
       throw new Error(
         `JobWorkerModule: BullMQ worker spawning requires the Drizzle client ` +
@@ -390,7 +403,14 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
       );
     }
     const queueName = resolvePoolQueueName(pool, this.bullConfig, poolConfig);
-    return new BullMQJobWorker(
+    const specifier = './job-worker.bullmq-backend';
+    const mod = (await import(specifier)) as {
+      BullMQJobWorker: new (...args: unknown[]) => Pick<
+        JobWorker,
+        'onModuleInit' | 'onModuleDestroy'
+      >;
+    };
+    return new mod.BullMQJobWorker(
       this.db,
       this.orchestrator,
       this.stepService,

package/runtime/subsystems/jobs/jobs-domain.module.ts

@@ -15,6 +15,7 @@
  * and the type system reserves the slot.
  */
 import { Module, type DynamicModule, type Provider } from '@nestjs/common';
+import { DRIZZLE } from '../../constants/tokens';
 import {
   JOB_ORCHESTRATOR,
   JOB_RUN_SERVICE,
@@ -24,7 +25,10 @@ import {
 import { DrizzleJobOrchestrator } from './job-orchestrator.drizzle-backend';
 import { DrizzleJobRunService } from './job-run-service.drizzle-backend';
 import { DrizzleJobStepService } from './job-step-service.drizzle-backend';
-import { BullMQJobOrchestrator } from './job-orchestrator.bullmq-backend';
+// #6 — `BullMQJobOrchestrator` is lazy-loaded only when `backend: 'bullmq'`
+// is selected. The backend file is filtered out of drizzle/memory installs
+// (see `backendFileFilter`); a non-literal dynamic import below sidesteps
+// consumer-side tsc resolution of an absent file.
 import { MemoryJobOrchestrator } from './job-orchestrator.memory-backend';
 import { MemoryJobRunService } from './job-run-service.memory-backend';
 import { MemoryJobStepService } from './job-step-service.memory-backend';
@@ -102,10 +106,31 @@ export class JobsDomainModule {
       // run/step services stay Drizzle (domain reads + `listForScope` are
       // Postgres queries, unchanged per spec). Only the orchestrator's
       // claim/dispatch half swaps to BullMQ.
+      //
+      // #6 — the bullmq backend module is filtered out of drizzle/memory
+      // installs (no `bullmq` peer dep, no consumer-side tsc compile of an
+      // unused file). The factory below dynamic-imports it via a non-literal
+      // specifier so TS treats the module type as `any` and never tries to
+      // resolve the absent file on a drizzle/memory consumer.
       const resolved = resolveBullMqConfig(opts.extensions?.bullmq);
       providers.push({ provide: BULLMQ_CONNECTION, useValue: resolved.connection });
       providers.push({ provide: BULLMQ_RESOLVED_CONFIG, useValue: resolved });
-      providers.push({ provide: JOB_ORCHESTRATOR, useClass: BullMQJobOrchestrator });
+      providers.push({
+        provide: JOB_ORCHESTRATOR,
+        useFactory: async (...args: unknown[]): Promise<object> => {
+          const specifier = './job-orchestrator.bullmq-backend';
+          const mod = (await import(specifier)) as {
+            BullMQJobOrchestrator: new (...args: unknown[]) => object;
+          };
+          return new mod.BullMQJobOrchestrator(...args);
+        },
+        // The bullmq orchestrator constructor mirrors DrizzleJobOrchestrator's
+        // injection list: DRIZZLE + JOBS_MULTI_TENANT + the resolved BullMQ
+        // tokens. Importing token references would force a static dep on the
+        // tokens file in this module's import graph; using the existing
+        // symbols already in scope is sufficient.
+        inject: [DRIZZLE, JOBS_MULTI_TENANT, BULLMQ_CONNECTION, BULLMQ_RESOLVED_CONFIG],
+      });
       providers.push({ provide: JOB_RUN_SERVICE, useClass: DrizzleJobRunService });
       providers.push({ provide: JOB_STEP_SERVICE, useClass: DrizzleJobStepService });
     } else {

package/templates/subsystem/events/domain-events.schema.ejs.t

@@ -13,12 +13,26 @@ force: true
  * First-class routing columns (EVT-1):
  *   - `pool`       — populated by DrizzleEventBus.publish() (EVT-4); enables
  *                    pool-filtered drain queries without unpacking metadata JSON.
+ *                    NULL when `tier='audit'` (audit events are not routed).
  *   - `direction`  — `inbound` | `change` | `outbound`; mirrors the routing
  *                    dimension used by jobs' reserved `events_inbound` /
  *                    `events_change` / `events_outbound` pools.
+ *                    NULL when `tier='audit'`.
  *   - `tenant_id`  — scaffold-time conditional: emitted only when
  *                    `events.multi_tenant: true` in `codegen.config.yaml`.
  *                    See EVT-8 and the JOB-6 precedent for the same pattern.
+ *                    The DrizzleEventBus reads/writes this column behind the
+ *                    same `multiTenant` flag, so the backend typechecks
+ *                    against both the multi-tenant and single-tenant schema.
+ *
+ * Audit-tier column (AUDIT-1):
+ *   - `tier`       — `'domain'` | `'audit'`. Defaults to `'domain'`. Always
+ *                    emitted (the DrizzleEventBus always writes/reads it).
+ *                    Audit-tier rows are observability-only (subscribers may
+ *                    observe but the bridge MUST NOT spawn jobs from them);
+ *                    they have null `pool` and `direction` by construction.
+ *                    The CHECK constraint `domain_events_tier_routing_check`
+ *                    enforces `tier='audit' ⇔ (pool IS NULL AND direction IS NULL)`.
  *
  * The `metadata` JSON column continues to carry these values for protocol
  * stability; the first-class columns are an optimization for drain filtering.
@@ -27,8 +41,11 @@ force: true
  *   - (status, occurred_at)             — polling drain filter
  *   - (aggregate_id, aggregate_type)    — event replay per aggregate
  *   - (pool, status, occurred_at)       — per-pool drain filter (EVT-1)
+ *   - (tier, status, occurred_at)       — per-tier filter for the observability
+ *                                          viewer's tier toggle (AUDIT-1).
  */
 import {
+  check,
   index,
   jsonb,
   pgTable,
@@ -36,6 +53,7 @@ import {
   timestamp,
   uuid,
 } from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
 import type { InferSelectModel } from 'drizzle-orm';
 
 export const domainEvents = pgTable(
@@ -53,10 +71,17 @@ export const domainEvents = pgTable(
     /** Error message from the last failed dispatch attempt. */
     error: text('error'),
     metadata: jsonb('metadata').$type<Record<string, unknown>>(),
-    /** Routing pool (e.g. `events_inbound`, `events_change`, `events_outbound`). Populated by DrizzleEventBus.publish() in EVT-4. */
+    /** Routing pool (e.g. `events_inbound`, `events_change`, `events_outbound`). Populated by DrizzleEventBus.publish() in EVT-4. NULL when `tier='audit'`. */
     pool: text('pool'),
-    /** Routing direction: `inbound` | `change` | `outbound`. Populated by DrizzleEventBus.publish() in EVT-4. */
+    /** Routing direction: `inbound` | `change` | `outbound`. Populated by DrizzleEventBus.publish() in EVT-4. NULL when `tier='audit'`. */
     direction: text('direction'),
+    /**
+     * Event tier: `'domain'` (default) or `'audit'`. Audit-tier rows are
+     * observability-only and have null `pool`/`direction` by construction —
+     * enforced by the `domain_events_tier_routing_check` CHECK constraint
+     * declared below. (AUDIT-1)
+     */
+    tier: text('tier').notNull().default('domain'),
 <% if (multiTenant) { -%>
     tenantId: text('tenant_id'),                // scaffold-time conditional — see EVT-8
 <% } -%>
@@ -76,6 +101,22 @@ export const domainEvents = pgTable(
     idxDomainEventsPoolStatusOccurredAt: index(
       'idx_domain_events_pool_status_occurred_at',
     ).on(t.pool, t.status, t.occurredAt),
+    /** Per-tier filter (AUDIT-1). Backs the observability viewer's tier toggle. */
+    idxDomainEventsTierStatusOccurredAt: index(
+      'idx_domain_events_tier_status_occurred_at',
+    ).on(t.tier, t.status, t.occurredAt),
+    /**
+     * Tier ↔ routing-fields invariant (AUDIT-1):
+     *   - `tier` is one of `'domain' | 'audit'`.
+     *   - `tier='audit'` ⇔ `pool IS NULL AND direction IS NULL`.
+     *   - `tier='domain'` ⇒ `pool` and `direction` are populated (the
+     *     DrizzleEventBus inserts always supply them; the bus stamps them
+     *     in AUDIT-3).
+     */
+    tierRoutingCheck: check(
+      'domain_events_tier_routing_check',
+      sql`${t.tier} in ('domain','audit') AND ((${t.tier} = 'audit') = (${t.pool} is null and ${t.direction} is null))`,
+    ),
   }),
 );