@pattern-stack/codegen 0.8.1 → 0.9.0

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

@@ -0,0 +1,32 @@
+/**
+ * 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/`.
+ */
+interface EventKeyset {
+    occurredAt: Date;
+    id: string;
+}
+/** Default page size when `limit` is omitted. */
+declare const DEFAULT_EVENT_LIST_LIMIT = 50;
+/** Hard upper bound on page size. */
+declare const MAX_EVENT_LIST_LIMIT = 200;
+/** Clamp a caller-supplied `limit` into `[1, MAX_EVENT_LIST_LIMIT]`. */
+declare function clampEventLimit(limit: number | undefined): number;
+declare function encodeEventCursor(keyset: EventKeyset): string;
+/**
+ * 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.
+ */
+declare function decodeEventCursor(cursor: string): EventKeyset | null;
+
+export { DEFAULT_EVENT_LIST_LIMIT, type EventKeyset, MAX_EVENT_LIST_LIMIT, clampEventLimit, decodeEventCursor, encodeEventCursor };

package/dist/runtime/subsystems/events/event-keyset-cursor.js

@@ -0,0 +1,38 @@
+// runtime/subsystems/events/event-keyset-cursor.ts
+var DEFAULT_EVENT_LIST_LIMIT = 50;
+var MAX_EVENT_LIST_LIMIT = 200;
+function clampEventLimit(limit) {
+  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;
+}
+function encodeEventCursor(keyset) {
+  const tuple = [keyset.occurredAt.toISOString(), keyset.id];
+  return Buffer.from(JSON.stringify(tuple), "utf8").toString("base64url");
+}
+function decodeEventCursor(cursor) {
+  try {
+    const json = Buffer.from(cursor, "base64url").toString("utf8");
+    const parsed = JSON.parse(json);
+    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;
+  }
+}
+export {
+  DEFAULT_EVENT_LIST_LIMIT,
+  MAX_EVENT_LIST_LIMIT,
+  clampEventLimit,
+  decodeEventCursor,
+  encodeEventCursor
+};
+//# sourceMappingURL=event-keyset-cursor.js.map

package/dist/runtime/subsystems/events/event-keyset-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../runtime/subsystems/events/event-keyset-cursor.ts"],"sourcesContent":["/**\n * Keyset (seek) cursor codec for `IEventReadPort.listEvents` (OBS-LIST-1).\n *\n * The list is ordered `occurred_at DESC, id DESC`. The cursor encodes the\n * `(occurredAt, id)` of the last row on the previous page so the next page\n * seeks with `WHERE (occurred_at, id) < (cursorOccurredAt, cursorId)`.\n *\n * The cursor is opaque to consumers: a base64url-encoded JSON tuple. Shape\n * is an implementation detail — never parse it outside this module.\n *\n * Mirrors the jobs keyset codec; kept separate because the events subsystem\n * must not depend on `runtime/subsystems/jobs/`.\n */\n\nexport interface EventKeyset {\n  occurredAt: Date;\n  id: string;\n}\n\n/** Default page size when `limit` is omitted. */\nexport const DEFAULT_EVENT_LIST_LIMIT = 50;\n/** Hard upper bound on page size. */\nexport const MAX_EVENT_LIST_LIMIT = 200;\n\n/** Clamp a caller-supplied `limit` into `[1, MAX_EVENT_LIST_LIMIT]`. */\nexport function clampEventLimit(limit: number | undefined): number {\n  if (typeof limit !== 'number' || !Number.isFinite(limit)) {\n    return DEFAULT_EVENT_LIST_LIMIT;\n  }\n  const floored = Math.floor(limit);\n  if (floored < 1) return 1;\n  if (floored > MAX_EVENT_LIST_LIMIT) return MAX_EVENT_LIST_LIMIT;\n  return floored;\n}\n\nexport function encodeEventCursor(keyset: EventKeyset): string {\n  const tuple = [keyset.occurredAt.toISOString(), keyset.id];\n  return Buffer.from(JSON.stringify(tuple), 'utf8').toString('base64url');\n}\n\n/**\n * Decode an opaque cursor back into its `(occurredAt, id)` keyset. Returns\n * `null` for malformed input so user-supplied garbage is treated as \"start\n * from the beginning\" rather than throwing.\n */\nexport function decodeEventCursor(cursor: string): EventKeyset | null {\n  try {\n    const json = Buffer.from(cursor, 'base64url').toString('utf8');\n    const parsed = JSON.parse(json) as unknown;\n    if (!Array.isArray(parsed) || parsed.length !== 2) return null;\n    const [iso, id] = parsed;\n    if (typeof iso !== 'string' || typeof id !== 'string') return null;\n    const occurredAt = new Date(iso);\n    if (Number.isNaN(occurredAt.getTime())) return null;\n    return { occurredAt, id };\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";AAoBO,IAAM,2BAA2B;AAEjC,IAAM,uBAAuB;AAG7B,SAAS,gBAAgB,OAAmC;AACjE,MAAI,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,KAAK,GAAG;AACxD,WAAO;AAAA,EACT;AACA,QAAM,UAAU,KAAK,MAAM,KAAK;AAChC,MAAI,UAAU,EAAG,QAAO;AACxB,MAAI,UAAU,qBAAsB,QAAO;AAC3C,SAAO;AACT;AAEO,SAAS,kBAAkB,QAA6B;AAC7D,QAAM,QAAQ,CAAC,OAAO,WAAW,YAAY,GAAG,OAAO,EAAE;AACzD,SAAO,OAAO,KAAK,KAAK,UAAU,KAAK,GAAG,MAAM,EAAE,SAAS,WAAW;AACxE;AAOO,SAAS,kBAAkB,QAAoC;AACpE,MAAI;AACF,UAAM,OAAO,OAAO,KAAK,QAAQ,WAAW,EAAE,SAAS,MAAM;AAC7D,UAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,QAAI,CAAC,MAAM,QAAQ,MAAM,KAAK,OAAO,WAAW,EAAG,QAAO;AAC1D,UAAM,CAAC,KAAK,EAAE,IAAI;AAClB,QAAI,OAAO,QAAQ,YAAY,OAAO,OAAO,SAAU,QAAO;AAC9D,UAAM,aAAa,IAAI,KAAK,GAAG;AAC/B,QAAI,OAAO,MAAM,WAAW,QAAQ,CAAC,EAAG,QAAO;AAC/C,WAAO,EAAE,YAAY,GAAG;AAAA,EAC1B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

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

@@ -0,0 +1,94 @@
+import { DomainEvent } from './event-bus.protocol.js';
+import '../../types/drizzle.js';
+import 'drizzle-orm/node-postgres';
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+interface EventPage {
+    items: EventSummary[];
+    nextCursor: string | null;
+}
+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. */
+declare function rootRunIdOf(event: DomainEvent): string | null;
+
+export { type EventPage, type EventSummary, type IEventReadPort, type ListEventsQuery, rootRunIdOf };

package/dist/runtime/subsystems/events/event-read.protocol.js

@@ -0,0 +1,9 @@
+// runtime/subsystems/events/event-read.protocol.ts
+function rootRunIdOf(event) {
+  const v = event.metadata?.["rootRunId"];
+  return typeof v === "string" ? v : null;
+}
+export {
+  rootRunIdOf
+};
+//# sourceMappingURL=event-read.protocol.js.map

package/dist/runtime/subsystems/events/event-read.protocol.js.map

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

package/dist/runtime/subsystems/events/events.module.js

@@ -15,6 +15,7 @@ import { Module } from "@nestjs/common";
 
 // runtime/subsystems/events/events.tokens.ts
 var EVENT_BUS = "EVENT_BUS";
+var EVENT_READ_PORT = "EVENT_READ_PORT";
 var TYPED_EVENT_BUS = "TYPED_EVENT_BUS";
 var EVENTS_MULTI_TENANT = "EVENTS_MULTI_TENANT";
 var REDIS_URL = /* @__PURE__ */ Symbol("REDIS_URL");
@@ -25,7 +26,38 @@ var DRIZZLE = "DRIZZLE";
 
 // runtime/subsystems/events/event-bus.drizzle-backend.ts
 import { Injectable, Inject, Logger, Optional } from "@nestjs/common";
-import { eq, and, inArray, asc } from "drizzle-orm";
+import { eq, and, inArray, asc, desc, gte, lt, or, sql as sql2 } from "drizzle-orm";
+
+// runtime/subsystems/events/event-keyset-cursor.ts
+var DEFAULT_EVENT_LIST_LIMIT = 50;
+var MAX_EVENT_LIST_LIMIT = 200;
+function clampEventLimit(limit) {
+  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;
+}
+function encodeEventCursor(keyset) {
+  const tuple = [keyset.occurredAt.toISOString(), keyset.id];
+  return Buffer.from(JSON.stringify(tuple), "utf8").toString("base64url");
+}
+function decodeEventCursor(cursor) {
+  try {
+    const json = Buffer.from(cursor, "base64url").toString("utf8");
+    const parsed = JSON.parse(json);
+    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;
+  }
+}
 
 // runtime/subsystems/events/domain-events.schema.ts
 import {
@@ -129,6 +161,24 @@ function toInsertValues(event) {
     tenantId
   };
 }
+function toEventSummary(r) {
+  const metadata = r.metadata ?? void 0;
+  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),
+    processedAt: r.processedAt == null ? null : r.processedAt instanceof Date ? r.processedAt : new Date(r.processedAt)
+  };
+}
 var DrizzleEventBus = class {
   constructor(db, opts, bridgeHook = null) {
     this.db = db;
@@ -194,6 +244,48 @@ var DrizzleEventBus = class {
     };
   }
   // ============================================================================
+  // IEventReadPort (OBS-LIST-1)
+  // ============================================================================
+  async listEvents(query = {}) {
+    const limit = clampEventLimit(query.limit);
+    const conditions = [];
+    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) {
+      conditions.push(
+        sql2`${domainEvents.metadata}->>'rootRunId' = ${query.rootRunId}`
+      );
+    }
+    if (query.tenantId !== void 0) {
+      conditions.push(
+        query.tenantId === null ? sql2`${domainEvents.tenantId} is null` : eq(domainEvents.tenantId, query.tenantId)
+      );
+    }
+    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) : void 0).orderBy(desc(domainEvents.occurredAt), desc(domainEvents.id)).limit(limit + 1);
+    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
   // ============================================================================
   /**
@@ -318,6 +410,27 @@ DrizzleEventBus = __decorateClass([
 
 // runtime/subsystems/events/event-bus.memory-backend.ts
 import { Inject as Inject2, Injectable as Injectable2, Logger as Logger2, Optional as Optional2 } from "@nestjs/common";
+function toEventSummary2(event) {
+  const metadata = event.metadata;
+  const str = (key) => {
+    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
+  };
+}
 var MemoryEventBus = class {
   logger = new Logger2(MemoryEventBus.name);
   /** All events published since construction (or last clear). */
@@ -353,6 +466,53 @@ var MemoryEventBus = class {
       set.delete(h);
     };
   }
+  // ============================================================================
+  // IEventReadPort (OBS-LIST-1)
+  // ============================================================================
+  async listEvents(query = {}) {
+    const limit = clampEventLimit(query.limit);
+    const keyset = query.cursor ? decodeEventCursor(query.cursor) : null;
+    const str = (e, key) => {
+      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 !== void 0) {
+        const t = str(e, "tenantId");
+        if (query.tenantId === null) {
+          if (t !== null) return false;
+        } else if (t !== query.tenantId) {
+          return false;
+        }
+      }
+      return true;
+    });
+    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(toEventSummary2);
+    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() {
     this.publishedEvents.length = 0;
@@ -930,10 +1090,20 @@ var EventsModule = class {
             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, bus) => 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]
     };
   }
   static forRoot(options = { backend: "drizzle" }) {
@@ -961,9 +1131,13 @@ var EventsModule = class {
       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]
     };
   }
 };