@pattern-stack/codegen 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/subsystems/auth/index.ts

@@ -112,5 +112,13 @@ export {
 // Controller
 export { AuthController } from './controllers/auth.controller';
 
+// Middleware — RequesterContext boundary (bridges auth → ambient tenant scope)
+export {
+  installRequesterContext,
+  makeRequesterContextMiddleware,
+  resolveRequesterContext,
+  type RequesterContextOptions,
+} from './middleware/requester-context';
+
 // Module
 export { AuthModule, type AuthModuleOptions } from './auth.module';

package/runtime/subsystems/auth/middleware/requester-context.ts

@@ -0,0 +1,141 @@
+/**
+ * RequesterContext boundary install — bridges authentication to ambient
+ * tenant scoping.
+ *
+ * This is the missing link that makes `BaseRepository`'s ambient scoping
+ * (see `base-classes/tenant-context.ts`) actually engage on HTTP requests:
+ * it reads the requester off each request (via the consumer-bound
+ * `IUserContext`) and runs the rest of the request inside `withRequester(...)`,
+ * so every downstream repository read/write is automatically scoped — no
+ * threaded `userId`.
+ *
+ * ## Wiring (one line in your bootstrap)
+ *
+ * In `main.ts`, after `NestFactory.create`:
+ *
+ * ```ts
+ * import { installRequesterContext } from './shared/subsystems/auth/middleware/requester-context';
+ * const app = await NestFactory.create(AppModule);
+ * installRequesterContext(app); // no-op + warn if AUTH_USER_CONTEXT is unbound
+ * ```
+ *
+ * `installRequesterContext` resolves `AUTH_USER_CONTEXT` from the root DI
+ * container (so it sees the binding the consumer provides in AppModule) and
+ * registers a global Express middleware. Pairs with Swagger's `@ApiBearerAuth`
+ * "Authorize" button: paste a token there and every request it sends now flows
+ * through this boundary into a scoped repository call.
+ *
+ * ## Trust + failure model
+ *
+ * - The middleware TRUSTS whatever `IUserContext` returns — authentication and
+ *   authorization (validating the token, deciding which scope a requester may
+ *   claim) are the `IUserContext` implementation's job, exactly as for a
+ *   hand-threaded `userId`.
+ * - When the requester cannot be resolved (no/invalid credentials — e.g. a
+ *   public route, or the OAuth callback itself), the request proceeds WITHOUT
+ *   an ambient context (`onUnresolved: 'unscoped'`, the default). A
+ *   `userTracking` repo in lenient mode then runs unscoped; in strict mode it
+ *   throws downstream — which is correct: unauthenticated callers must not
+ *   reach scoped data. Set `onUnresolved: 'reject'` to fail the request at the
+ *   boundary instead.
+ */
+import type { INestApplication } from '@nestjs/common';
+import {
+  withRequester,
+  type RequesterContext,
+} from '../../../base-classes/tenant-context';
+import { AUTH_USER_CONTEXT } from '../auth.tokens';
+import type { IUserContext } from '../protocols/user-context';
+
+/** Minimal Express-style middleware signature (avoids an `express` dep). */
+type NextFn = (err?: unknown) => void;
+type RequestHandler = (req: unknown, res: unknown, next: NextFn) => void;
+
+export interface RequesterContextOptions {
+  /**
+   * What to do when `IUserContext` cannot resolve a requester (throws, or
+   * returns no `userId`).
+   * - `'unscoped'` (default): proceed without a context — public routes work;
+   *   scoped repos run unscoped (lenient) or throw downstream (strict).
+   * - `'reject'`: fail the request at the boundary (`next(error)`).
+   */
+  onUnresolved?: 'unscoped' | 'reject';
+}
+
+/**
+ * Resolve the ambient context for a request: prefer the richer
+ * `resolveRequester` (org/superuser), else derive plain `'user'` scope from
+ * `getCurrentUserId`. Returns `undefined` when no requester can be determined.
+ */
+export async function resolveRequesterContext(
+  userContext: IUserContext,
+  req: unknown,
+): Promise<RequesterContext | undefined> {
+  if (typeof userContext.resolveRequester === 'function') {
+    const ctx = await userContext.resolveRequester(req);
+    return ctx?.userId ? ctx : undefined;
+  }
+  const userId = await userContext.getCurrentUserId(req);
+  return userId ? { userId, organizationId: null } : undefined;
+}
+
+/**
+ * Build the global middleware. Runs the remainder of the request inside
+ * `withRequester(...)` so the ambient context propagates through every `await`
+ * to downstream repositories.
+ */
+export function makeRequesterContextMiddleware(
+  userContext: IUserContext,
+  options: RequesterContextOptions = {},
+): RequestHandler {
+  const onUnresolved = options.onUnresolved ?? 'unscoped';
+  return (req, _res, next) => {
+    resolveRequesterContext(userContext, req).then(
+      (ctx) => {
+        if (!ctx) {
+          next();
+          return;
+        }
+        // als.run executes its callback synchronously; Express dispatches the
+        // rest of the pipeline inside next(), so all downstream handlers (and
+        // their awaits) inherit this context.
+        withRequester(ctx, async () => {
+          next();
+        });
+      },
+      (err) => {
+        if (onUnresolved === 'reject') {
+          next(err);
+          return;
+        }
+        next();
+      },
+    );
+  };
+}
+
+/**
+ * Register the requester-context boundary on a Nest app. Resolves
+ * `AUTH_USER_CONTEXT` from the root container (so it sees the consumer's
+ * AppModule binding) and installs the global middleware. No-ops with a warning
+ * when `AUTH_USER_CONTEXT` is not bound, so calling it unconditionally in
+ * bootstrap is safe.
+ */
+export function installRequesterContext(
+  app: INestApplication,
+  options: RequesterContextOptions = {},
+): void {
+  const userContext = app.get<IUserContext>(AUTH_USER_CONTEXT, {
+    strict: false,
+  });
+  if (!userContext) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[auth] installRequesterContext: AUTH_USER_CONTEXT is not bound — ' +
+        'request scoping NOT installed. Provide an IUserContext under ' +
+        'AUTH_USER_CONTEXT in your AppModule to enable ambient tenant scoping.',
+    );
+    return;
+  }
+  app.use(makeRequesterContextMiddleware(userContext, options));
+}

package/runtime/subsystems/auth/protocols/user-context.ts

@@ -17,6 +17,23 @@
  * dependency on `express` / `fastify` / NestJS request types. The concrete
  * adapter narrows it (e.g. via a `Request` import).
  */
+import type { RequesterContext } from '../../../base-classes/tenant-context';
+
 export interface IUserContext {
   getCurrentUserId(req: unknown): Promise<string>;
+  /**
+   * Optional richer resolution of the full ambient requester context — the
+   * org/superuser dimensions on top of `userId`. When implemented, the
+   * `RequesterContextMiddleware` (see `../middleware/requester-context`) uses
+   * it verbatim to scope reads/writes; when omitted, the middleware falls back
+   * to `{ userId: await getCurrentUserId(req), organizationId: null }` (plain
+   * `'user'` scope).
+   *
+   * Implement this when the app supports org-shared (`'org'`) or admin
+   * (`'superuser'`) data visibility — resolve `organizationId` + the
+   * `orgUserIds` member list here, at the trust boundary, so repositories stay
+   * single-table. AUTHORIZATION (which scope a requester may claim) is the
+   * implementation's responsibility; the repo trusts what this returns.
+   */
+  resolveRequester?(req: unknown): Promise<RequesterContext>;
 }

package/runtime/subsystems/bridge/bridge.module.ts

@@ -149,6 +149,11 @@ export class BridgeModule implements OnModuleInit {
 
   async onModuleInit(): Promise<void> {
     if (!this.workerOpts) return;
+    // BULLMQ-1 Phase 1 — `allPools: true` activates every pool (reserved
+    // `events_*` included), so the reserved-pool guarantee holds by
+    // construction. Short-circuit pass without inspecting the (typically
+    // omitted) explicit `pools` list.
+    if (this.workerOpts.allPools) return;
     const activePools = this.workerOpts.pools ?? [];
     const missing = BRIDGE_RESERVED_POOLS.filter(
       (p) => !activePools.includes(p),

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

@@ -29,10 +29,20 @@
  * via EventsModule.forRoot({ backend: '...' }) without touching use cases.
  */
 import { Injectable, OnModuleDestroy, OnModuleInit, Inject, Logger, Optional } from '@nestjs/common';
-import { eq, and, inArray, asc, type SQL } from 'drizzle-orm';
+import { eq, and, inArray, asc, desc, gte, lt, or, sql, type SQL } from 'drizzle-orm';
 import type { DomainEvent, DrizzleTransaction, IEventBus } from './event-bus.protocol';
+import type {
+  EventPage,
+  IEventReadPort,
+  ListEventsQuery,
+} from './event-read.protocol';
+import {
+  clampEventLimit,
+  decodeEventCursor,
+  encodeEventCursor,
+} from './event-keyset-cursor';
 import type { DrizzleClient } from '../../types/drizzle';
-import { domainEvents } from './domain-events.schema';
+import { domainEvents, type DomainEventRecord } from './domain-events.schema';
 import { DRIZZLE } from '../../constants/tokens';
 import { EVENTS_MODULE_OPTIONS } from './events.tokens';
 import type { EventsModuleOptions } from './events.module';
@@ -76,8 +86,43 @@ function toInsertValues(event: DomainEvent) {
   };
 }
 
+/**
+ * Project a raw `domain_events` row into the narrow `EventSummary` shape.
+ * Shared with the memory backend via this helper kept module-local to each
+ * backend (the events subsystem has no cross-backend projection file yet;
+ * the two are byte-identical and small).
+ */
+function toEventSummary(r: DomainEventRecord) {
+  const metadata = (r.metadata ?? undefined) as
+    | Record<string, unknown>
+    | undefined;
+  const rootRunId = metadata?.['rootRunId'];
+  return {
+    id: r.id,
+    type: r.type,
+    aggregateId: r.aggregateId,
+    aggregateType: r.aggregateType,
+    status: r.status,
+    pool: r.pool,
+    direction: r.direction,
+    tier: r.tier,
+    rootRunId: typeof rootRunId === 'string' ? rootRunId : null,
+    tenantId: r.tenantId,
+    occurredAt:
+      r.occurredAt instanceof Date
+        ? r.occurredAt
+        : new Date(r.occurredAt as unknown as string),
+    processedAt:
+      r.processedAt == null
+        ? null
+        : r.processedAt instanceof Date
+          ? r.processedAt
+          : new Date(r.processedAt as unknown as string),
+  };
+}
+
 @Injectable()
-export class DrizzleEventBus implements IEventBus, OnModuleInit, OnModuleDestroy {
+export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(DrizzleEventBus.name);
   private polling = false;
   private pollTimer: ReturnType<typeof setTimeout> | null = null;
@@ -178,6 +223,67 @@ export class DrizzleEventBus implements IEventBus, OnModuleInit, OnModuleDestroy
     };
   }
 
+  // ============================================================================
+  // IEventReadPort (OBS-LIST-1)
+  // ============================================================================
+
+  async listEvents(query: ListEventsQuery = {}): Promise<EventPage> {
+    const limit = clampEventLimit(query.limit);
+    const conditions: SQL<unknown>[] = [];
+
+    if (query.poolId) conditions.push(eq(domainEvents.pool, query.poolId));
+    if (query.direction)
+      conditions.push(eq(domainEvents.direction, query.direction));
+    if (query.since) conditions.push(gte(domainEvents.occurredAt, query.since));
+    if (query.rootRunId) {
+      // Filter on the JSON correlation id: metadata->>'rootRunId'.
+      conditions.push(
+        sql`${domainEvents.metadata}->>'rootRunId' = ${query.rootRunId}`,
+      );
+    }
+    if (query.tenantId !== undefined) {
+      conditions.push(
+        query.tenantId === null
+          ? (sql`${domainEvents.tenantId} is null` as SQL<unknown>)
+          : eq(domainEvents.tenantId, query.tenantId),
+      );
+    }
+
+    // Keyset seek: WHERE (occurred_at, id) < (cursorOccurredAt, cursorId).
+    if (query.cursor) {
+      const keyset = decodeEventCursor(query.cursor);
+      if (keyset) {
+        conditions.push(
+          or(
+            lt(domainEvents.occurredAt, keyset.occurredAt),
+            and(
+              eq(domainEvents.occurredAt, keyset.occurredAt),
+              lt(domainEvents.id, keyset.id),
+            ),
+          )!,
+        );
+      }
+    }
+
+    const rows = (await this.db
+      .select()
+      .from(domainEvents)
+      .where(conditions.length > 0 ? and(...conditions) : undefined)
+      .orderBy(desc(domainEvents.occurredAt), desc(domainEvents.id))
+      .limit(limit + 1)) as DomainEventRecord[];
+
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const items = page.map(toEventSummary);
+    const last = page[page.length - 1];
+    const nextCursor =
+      hasMore && last
+        ? encodeEventCursor({ occurredAt: last.occurredAt, id: last.id })
+        : null;
+
+    return { items, nextCursor };
+  }
+
   // ============================================================================
   // Polling
   // ============================================================================

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

@@ -21,11 +21,52 @@
  */
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import type { DomainEvent, IEventBus } from './event-bus.protocol';
+import type {
+  EventPage,
+  EventSummary,
+  IEventReadPort,
+  ListEventsQuery,
+} from './event-read.protocol';
+import {
+  clampEventLimit,
+  decodeEventCursor,
+  encodeEventCursor,
+} from './event-keyset-cursor';
 import { EVENTS_MODULE_OPTIONS } from './events.tokens';
 import type { EventsModuleOptions } from './events.module';
 
+/**
+ * Project an in-memory `DomainEvent` into the narrow `EventSummary` shape.
+ * The memory backend has no first-class columns, so `pool` / `direction` /
+ * `tier` / `tenantId` / `rootRunId` are read from `metadata` (mirroring how
+ * the Drizzle backend stamps them onto columns at publish time). `status`
+ * is reported as `'processed'` — the memory bus dispatches synchronously,
+ * so once an event is in `publishedEvents` it has been handled.
+ */
+function toEventSummary(event: DomainEvent): EventSummary {
+  const metadata = event.metadata;
+  const str = (key: string): string | null => {
+    const v = metadata?.[key];
+    return typeof v === 'string' ? v : null;
+  };
+  return {
+    id: event.id,
+    type: event.type,
+    aggregateId: event.aggregateId,
+    aggregateType: event.aggregateType,
+    status: 'processed',
+    pool: str('pool'),
+    direction: str('direction'),
+    tier: str('tier') ?? 'domain',
+    rootRunId: str('rootRunId'),
+    tenantId: str('tenantId'),
+    occurredAt: event.occurredAt,
+    processedAt: event.occurredAt,
+  };
+}
+
 @Injectable()
-export class MemoryEventBus implements IEventBus {
+export class MemoryEventBus implements IEventBus, IEventReadPort {
   private readonly logger = new Logger(MemoryEventBus.name);
 
   /** All events published since construction (or last clear). */
@@ -86,6 +127,67 @@ export class MemoryEventBus implements IEventBus {
     };
   }
 
+  // ============================================================================
+  // IEventReadPort (OBS-LIST-1)
+  // ============================================================================
+
+  async listEvents(query: ListEventsQuery = {}): Promise<EventPage> {
+    const limit = clampEventLimit(query.limit);
+    const keyset = query.cursor ? decodeEventCursor(query.cursor) : null;
+
+    const str = (e: DomainEvent, key: string): string | null => {
+      const v = e.metadata?.[key];
+      return typeof v === 'string' ? v : null;
+    };
+
+    const matched = this.publishedEvents.filter((e) => {
+      if (query.poolId && str(e, 'pool') !== query.poolId) return false;
+      if (query.direction && str(e, 'direction') !== query.direction)
+        return false;
+      if (query.rootRunId && str(e, 'rootRunId') !== query.rootRunId)
+        return false;
+      if (query.since && e.occurredAt.getTime() < query.since.getTime())
+        return false;
+      if (query.tenantId !== undefined) {
+        const t = str(e, 'tenantId');
+        if (query.tenantId === null) {
+          if (t !== null) return false;
+        } else if (t !== query.tenantId) {
+          return false;
+        }
+      }
+      return true;
+    });
+
+    // Order occurred_at DESC, id DESC to match the Drizzle backend keyset.
+    matched.sort((a, b) => {
+      const dt = b.occurredAt.getTime() - a.occurredAt.getTime();
+      if (dt !== 0) return dt;
+      return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+    });
+
+    const seeked = keyset
+      ? matched.filter((e) => {
+          const ct = e.occurredAt.getTime();
+          const kt = keyset.occurredAt.getTime();
+          if (ct < kt) return true;
+          if (ct > kt) return false;
+          return e.id < keyset.id;
+        })
+      : matched;
+
+    const hasMore = seeked.length > limit;
+    const page = hasMore ? seeked.slice(0, limit) : seeked;
+    const items = page.map(toEventSummary);
+    const last = page[page.length - 1];
+    const nextCursor =
+      hasMore && last
+        ? encodeEventCursor({ occurredAt: last.occurredAt, id: last.id })
+        : null;
+
+    return { items, nextCursor };
+  }
+
   /** Remove all published events and subscriptions. Useful in beforeEach. */
   clear(): void {
     this.publishedEvents.length = 0;

package/runtime/subsystems/events/event-keyset-cursor.ts

@@ -0,0 +1,59 @@
+/**
+ * Keyset (seek) cursor codec for `IEventReadPort.listEvents` (OBS-LIST-1).
+ *
+ * The list is ordered `occurred_at DESC, id DESC`. The cursor encodes the
+ * `(occurredAt, id)` of the last row on the previous page so the next page
+ * seeks with `WHERE (occurred_at, id) < (cursorOccurredAt, cursorId)`.
+ *
+ * The cursor is opaque to consumers: a base64url-encoded JSON tuple. Shape
+ * is an implementation detail — never parse it outside this module.
+ *
+ * Mirrors the jobs keyset codec; kept separate because the events subsystem
+ * must not depend on `runtime/subsystems/jobs/`.
+ */
+
+export interface EventKeyset {
+  occurredAt: Date;
+  id: string;
+}
+
+/** Default page size when `limit` is omitted. */
+export const DEFAULT_EVENT_LIST_LIMIT = 50;
+/** Hard upper bound on page size. */
+export const MAX_EVENT_LIST_LIMIT = 200;
+
+/** Clamp a caller-supplied `limit` into `[1, MAX_EVENT_LIST_LIMIT]`. */
+export function clampEventLimit(limit: number | undefined): number {
+  if (typeof limit !== 'number' || !Number.isFinite(limit)) {
+    return DEFAULT_EVENT_LIST_LIMIT;
+  }
+  const floored = Math.floor(limit);
+  if (floored < 1) return 1;
+  if (floored > MAX_EVENT_LIST_LIMIT) return MAX_EVENT_LIST_LIMIT;
+  return floored;
+}
+
+export function encodeEventCursor(keyset: EventKeyset): string {
+  const tuple = [keyset.occurredAt.toISOString(), keyset.id];
+  return Buffer.from(JSON.stringify(tuple), 'utf8').toString('base64url');
+}
+
+/**
+ * Decode an opaque cursor back into its `(occurredAt, id)` keyset. Returns
+ * `null` for malformed input so user-supplied garbage is treated as "start
+ * from the beginning" rather than throwing.
+ */
+export function decodeEventCursor(cursor: string): EventKeyset | null {
+  try {
+    const json = Buffer.from(cursor, 'base64url').toString('utf8');
+    const parsed = JSON.parse(json) as unknown;
+    if (!Array.isArray(parsed) || parsed.length !== 2) return null;
+    const [iso, id] = parsed;
+    if (typeof iso !== 'string' || typeof id !== 'string') return null;
+    const occurredAt = new Date(iso);
+    if (Number.isNaN(occurredAt.getTime())) return null;
+    return { occurredAt, id };
+  } catch {
+    return null;
+  }
+}

package/runtime/subsystems/events/event-read.protocol.ts

@@ -0,0 +1,97 @@
+/**
+ * IEventReadPort — read-side port over `domain_events` (OBS-LIST-1).
+ *
+ * The publish/subscribe `IEventBus` (EVENT_BUS) is a *write + dispatch*
+ * port; it deliberately does not expose tabular reads beyond `findById`.
+ * The observability combiner needs a paginated, filterable list of
+ * `domain_events` for its events viewer, so we add a dedicated read port
+ * rather than overloading `IEventBus`.
+ *
+ * Keeping reads on a separate port means:
+ *   - the combiner can compose it `@Optional()` independently of EVENT_BUS;
+ *   - the Redis backend (which retains no history) simply does not provide
+ *     it — there is no "list" semantics to fake;
+ *   - the write/dispatch surface stays minimal.
+ *
+ * Both `DrizzleEventBus` and `MemoryEventBus` implement this port (they
+ * already hold the rows / in-memory log); `EventsModule.forRoot` binds the
+ * `EVENT_READ_PORT` token to the same instance for drizzle/memory backends.
+ */
+
+import type { DomainEvent } from './event-bus.protocol';
+
+/**
+ * Filter + keyset-pagination input for `IEventReadPort.listEvents`.
+ *
+ * Ordered `occurred_at DESC, id DESC`. `rootRunId` filters on the JSON
+ * `metadata->>'rootRunId'` — the correlation id stamped by the jobs/bridge
+ * machinery so an event can be traced back to the run tree that emitted it.
+ */
+export interface ListEventsQuery {
+  /** Filter on `metadata->>'rootRunId'` (correlation id). */
+  rootRunId?: string;
+  /** Filter on the first-class `pool` column. */
+  poolId?: string;
+  /** Filter on the first-class `direction` column (inbound|change|outbound). */
+  direction?: string;
+  /** Lower bound on `occurred_at` (inclusive). */
+  since?: Date;
+  /** Opaque keyset cursor from a previous page's `nextCursor`. */
+  cursor?: string;
+  /** Page size. Backend clamps to a sane default + max. */
+  limit?: number;
+  /**
+   * Multi-tenancy filter on the first-class `tenant_id` column. Only
+   * meaningful when the consumer publishes tenant-scoped events
+   * (`events.multi_tenant: true`); otherwise leave undefined.
+   *   - `string` — filter `tenant_id = :tenantId`.
+   *   - `null`   — filter `tenant_id IS NULL`.
+   *   - `undefined` — no tenant filter.
+   */
+  tenantId?: string | null;
+}
+
+/**
+ * Summary row for the events list. A narrow projection over `domain_events`
+ * carrying what the viewer + correlation timeline need. `rootRunId` is
+ * surfaced (lifted out of `metadata`) so the timeline can stitch without a
+ * second metadata dig.
+ */
+export interface EventSummary {
+  id: string;
+  type: string;
+  aggregateId: string;
+  aggregateType: string;
+  status: string;
+  pool: string | null;
+  direction: string | null;
+  tier: string;
+  rootRunId: string | null;
+  tenantId: string | null;
+  occurredAt: Date;
+  processedAt: Date | null;
+}
+
+/**
+ * One page of `listEvents` results. `nextCursor` is `null` when there are
+ * no more rows.
+ */
+export interface EventPage {
+  items: EventSummary[];
+  nextCursor: string | null;
+}
+
+export interface IEventReadPort {
+  /**
+   * Paginated, filterable list of `domain_events` (OBS-LIST-1). Newest
+   * first (`occurred_at` desc, `id` desc keyset tie-break). Returns an
+   * `EventPage` with an opaque `nextCursor` for keyset pagination.
+   */
+  listEvents(query?: ListEventsQuery): Promise<EventPage>;
+}
+
+/** A `DomainEvent` whose metadata may carry a `rootRunId` correlation id. */
+export function rootRunIdOf(event: DomainEvent): string | null {
+  const v = event.metadata?.['rootRunId'];
+  return typeof v === 'string' ? v : null;
+}

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

@@ -47,6 +47,7 @@
 import { Module, type DynamicModule, type Provider } from '@nestjs/common';
 import {
   EVENT_BUS,
+  EVENT_READ_PORT,
   EVENTS_MODULE_OPTIONS,
   EVENTS_MULTI_TENANT,
   REDIS_URL,
@@ -180,10 +181,21 @@ export class EventsModule {
             REDIS_URL,
           ],
         },
+        {
+          // Read port (OBS-LIST-1). Drizzle + memory backends implement
+          // IEventReadPort on the EVENT_BUS instance; the redis backend
+          // retains no history, so EVENT_READ_PORT resolves to `null` and
+          // optional consumers (the observability combiner) degrade to
+          // empty results.
+          provide: EVENT_READ_PORT,
+          useFactory: (options: EventsModuleOptions, bus: unknown) =>
+            options.backend === 'redis' ? null : bus,
+          inject: [EVENTS_MODULE_OPTIONS, EVENT_BUS],
+        },
         TypedEventBus,
         { provide: TYPED_EVENT_BUS, useExisting: TypedEventBus },
       ],
-      exports: [EVENT_BUS, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
+      exports: [EVENT_BUS, EVENT_READ_PORT, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
     };
   }
 
@@ -222,9 +234,13 @@ export class EventsModule {
       providers: [
         { provide: EVENTS_MODULE_OPTIONS, useValue: options },
         provider,
+        // Read port (OBS-LIST-1): drizzle + memory backends implement
+        // IEventReadPort on the same instance as EVENT_BUS. The redis
+        // backend retains no history and does not provide this token.
+        { provide: EVENT_READ_PORT, useExisting: EVENT_BUS },
         ...buildTypedBusProviders(multiTenant),
       ],
-      exports: [EVENT_BUS, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
+      exports: [EVENT_BUS, EVENT_READ_PORT, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
     };
   }
 }

package/runtime/subsystems/events/events.tokens.ts

@@ -11,6 +11,22 @@
  */
 export const EVENT_BUS = 'EVENT_BUS' as const;
 
+/**
+ * Injection token for the read-side `IEventReadPort` over `domain_events`
+ * (OBS-LIST-1).
+ *
+ * Bound by `EventsModule.forRoot` to the same backend instance as
+ * `EVENT_BUS` for the `drizzle` and `memory` backends (both implement
+ * `IEventReadPort`). The `redis` backend retains no history and therefore
+ * does NOT provide this token — consumers composing it (e.g. the
+ * observability combiner) inject it `@Optional()` and degrade to empty
+ * results.
+ *
+ * String constant (not Symbol) so it matches by value across import
+ * boundaries — same convention as `EVENT_BUS`.
+ */
+export const EVENT_READ_PORT = 'EVENT_READ_PORT' as const;
+
 /**
  * Injection token for the generated `TypedEventBus` facade.
  *