@enbox/dwn-sdk-js 0.0.6 → 0.0.8

package/src/core/record-chain.ts

@@ -0,0 +1,99 @@
+import type { Filter } from '../types/query-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { RecordsWriteMessage } from '../types/records-types.js';
+
+import { RecordsWrite } from '../interfaces/records-write.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+/**
+ * Fetches the initial RecordsWrite message associated with the given (tenant + recordId).
+ */
+export async function fetchInitialWrite(
+  tenant: string,
+  recordId: string,
+  messageStore: MessageStore
+): Promise<RecordsWriteMessage | undefined> {
+
+  const query: Filter = {
+    interface : DwnInterfaceName.Records,
+    method    : DwnMethodName.Write,
+    recordId  : recordId
+  };
+  const { messages } = await messageStore.query(tenant, [query]);
+
+  if (messages.length === 0) {
+    return undefined;
+  }
+
+  const initialWrite = await RecordsWrite.getInitialWrite(messages);
+  return initialWrite;
+}
+
+/**
+ * Constructs the chain of EXISTING records in the datastore where the first record is the root initial `RecordsWrite` of the record chain
+ * and last record is the initial `RecordsWrite` of the descendant record specified.
+ * @param descendantRecordId The ID of the descendent record to start constructing the record chain from by repeatedly looking up the parent.
+ * @returns the record chain where each record is represented by its initial `RecordsWrite`;
+ *          returns empty array if `descendantRecordId` is `undefined`.
+ * @throws {DwnError} if `descendantRecordId` is defined but any initial `RecordsWrite` is not found in the chain of records.
+ */
+export async function constructRecordChain(
+  tenant: string,
+  descendantRecordId: string | undefined,
+  messageStore: MessageStore
+): Promise<RecordsWriteMessage[]> {
+
+  if (descendantRecordId === undefined) {
+    return [];
+  }
+
+  const recordChain: RecordsWriteMessage[] = [];
+
+  // keep walking up the chain from the inbound message's parent, until there is no more parent
+  let currentRecordId: string | undefined = descendantRecordId;
+  while (currentRecordId !== undefined) {
+
+    const initialWrite = await fetchInitialWrite(tenant, currentRecordId, messageStore);
+
+    // RecordsWrite needed should be available since we perform necessary checks at the time of writes,
+    // eg. check the immediate parent in `verifyProtocolPathAndContextId` at the time of writing,
+    // so if this condition is triggered, it means there is an unexpected bug that caused an incomplete chain.
+    // We add additional defensive check here because returning an unexpected/incorrect record chain could lead to security vulnerabilities.
+    if (initialWrite === undefined) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolAuthorizationParentNotFoundConstructingRecordChain,
+        `Unexpected error that should never trigger: no parent found with ID ${currentRecordId} when constructing record chain.`
+      );
+    }
+
+    recordChain.push(initialWrite);
+    currentRecordId = initialWrite.descriptor.parentId;
+  }
+
+  return recordChain.reverse(); // root record first
+}
+
+/**
+ * Determines the timestamp that governs which protocol definition version applies to the given RecordsWrite.
+ * For an update, this is the initial write's `messageTimestamp` (the protocol version is locked at creation time).
+ * For a new initial write, returns `undefined` — the latest protocol definition should be used because the
+ * record is being created now and must conform to the current protocol rules.
+ */
+export async function getGoverningTimestamp(
+  tenant: string,
+  incomingMessage: RecordsWrite,
+  messageStore: MessageStore,
+): Promise<string | undefined> {
+  const existingInitialWrite = await fetchInitialWrite(
+    tenant, incomingMessage.message.recordId, messageStore
+  );
+
+  if (existingInitialWrite !== undefined) {
+    // update case: use the initial write's timestamp
+    return existingInitialWrite.descriptor.messageTimestamp;
+  }
+
+  // initial write case: validate against the latest protocol definition
+  return undefined;
+}

package/src/core/records-grant-authorization.ts

@@ -87,15 +87,14 @@ export class RecordsGrantAuthorization {
       messageStore
     });
 
-    // If the grant specifies a protocol, the subscribe or query must specify the same protocol.
+    // The grant's protocol must match the query/subscribe filter's protocol.
     // NOTE: validated the invoked permission is for Records in GrantAuthorization.performBaseValidation()
     const permissionScope = permissionGrant.scope as RecordsPermissionScope;
-    const protocolInGrant = permissionScope.protocol;
     const protocolInMessage = incomingMessage.descriptor.filter.protocol;
-    if (protocolInGrant !== undefined && protocolInMessage !== protocolInGrant) {
+    if (protocolInMessage !== permissionScope.protocol) {
       throw new DwnError(
         DwnErrorCode.RecordsGrantAuthorizationQueryOrSubscribeProtocolScopeMismatch,
-        `Grant protocol scope ${protocolInGrant} does not match protocol in message ${protocolInMessage}`
+        `Grant protocol scope ${permissionScope.protocol} does not match protocol in message ${protocolInMessage}`
       );
     }
   }
@@ -124,15 +123,14 @@ export class RecordsGrantAuthorization {
       messageStore
     });
 
-    // If the grant specifies a protocol, the delete must be deleting a record with the same protocol.
+    // The grant's protocol must match the protocol of the record being deleted.
     // NOTE: validated the invoked permission is for Records in GrantAuthorization.performBaseValidation()
     const permissionScope = permissionGrant.scope as RecordsPermissionScope;
-    const protocolInGrant = permissionScope.protocol;
     const protocolOfRecordToDelete = recordsWriteToDelete.descriptor.protocol;
-    if (protocolInGrant !== undefined && protocolOfRecordToDelete !== protocolInGrant) {
+    if (protocolOfRecordToDelete !== permissionScope.protocol) {
       throw new DwnError(
         DwnErrorCode.RecordsGrantAuthorizationDeleteProtocolScopeMismatch,
-        `Grant protocol scope ${protocolInGrant} does not match protocol in record to delete ${protocolOfRecordToDelete}`
+        `Grant protocol scope ${permissionScope.protocol} does not match protocol in record to delete ${protocolOfRecordToDelete}`
       );
     }
   }

package/src/dwn.ts

@@ -1,24 +1,25 @@
-
 import type { DataStore } from './types/data-store.js';
 import type { DidResolver } from '@enbox/dids';
-import type { EventStream } from './types/subscriptions.js';
 import type { MessageStore } from './types/message-store.js';
-import type { MethodHandler } from './types/method-handler.js';
 import type { ResumableTaskStore } from './types/resumable-task-store.js';
 import type { StateIndex } from './types/state-index.js';
 import type { TenantGate } from './core/tenant-gate.js';
 import type { UnionMessageReply } from './core/message-reply.js';
+import type { EventLog, SubscriptionListener } from './types/subscriptions.js';
 import type { GenericMessage, GenericMessageReply } from './types/message-types.js';
-import type { MessagesReadMessage, MessagesReadReply, MessagesSubscribeMessage, MessagesSubscribeMessageOptions, MessagesSubscribeReply, MessagesSyncMessage, MessagesSyncReply, MessageSubscriptionHandler } from './types/messages-types.js';
+import type { HandlerDependencies, MethodHandler } from './types/method-handler.js';
+import type { MessagesReadMessage, MessagesReadReply, MessagesSubscribeMessage, MessagesSubscribeMessageOptions, MessagesSubscribeReply, MessagesSyncMessage, MessagesSyncReply } from './types/messages-types.js';
 import type { ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply } from './types/protocols-types.js';
-import type { RecordsCountMessage, RecordsCountReply, RecordsDeleteMessage, RecordsQueryMessage, RecordsQueryReply, RecordsReadMessage, RecordsReadReply, RecordsSubscribeMessage, RecordsSubscribeMessageOptions, RecordsSubscribeReply, RecordSubscriptionHandler, RecordsWriteMessage, RecordsWriteMessageOptions } from './types/records-types.js';
+import type { RecordsCountMessage, RecordsCountReply, RecordsDeleteMessage, RecordsQueryMessage, RecordsQueryReply, RecordsReadMessage, RecordsReadReply, RecordsSubscribeMessage, RecordsSubscribeMessageOptions, RecordsSubscribeReply, RecordsWriteMessage, RecordsWriteMessageOptions } from './types/records-types.js';
 
 import { AllowAllTenantGate } from './core/tenant-gate.js';
+import { CoreProtocolRegistry } from './core/core-protocol.js';
 import { Message } from './core/message.js';
 import { messageReplyFromError } from './core/message-reply.js';
 import { MessagesReadHandler } from './handlers/messages-read.js';
 import { MessagesSubscribeHandler } from './handlers/messages-subscribe.js';
 import { MessagesSyncHandler } from './handlers/messages-sync.js';
+import { PermissionsProtocol } from './protocols/permissions.js';
 import { ProtocolsConfigureHandler } from './handlers/protocols-configure.js';
 import { ProtocolsQueryHandler } from './handlers/protocols-query.js';
 import { RecordsCountHandler } from './handlers/records-count.js';
@@ -40,88 +41,60 @@ export class Dwn {
   private resumableTaskStore: ResumableTaskStore;
   private stateIndex: StateIndex;
   private tenantGate: TenantGate;
-  private eventStream?: EventStream;
+  private eventLog?: EventLog;
   private storageController: StorageController;
   private resumableTaskManager: ResumableTaskManager;
+  private _coreProtocols: CoreProtocolRegistry;
 
   private constructor(config: DwnConfig) {
     this.didResolver = config.didResolver!;
     this.tenantGate = config.tenantGate!;
-    this.eventStream = config.eventStream!;
     this.messageStore = config.messageStore;
     this.dataStore = config.dataStore;
     this.resumableTaskStore = config.resumableTaskStore;
     this.stateIndex = config.stateIndex;
-    this.eventStream = config.eventStream;
+
+    this.eventLog = config.eventLog;
+
     this.storageController = new StorageController({
       messageStore : this.messageStore,
       dataStore    : this.dataStore,
       stateIndex   : this.stateIndex,
-      eventStream  : this.eventStream
+      eventLog     : this.eventLog
     });
     this.resumableTaskManager = new ResumableTaskManager(
       config.resumableTaskStore,
       this.storageController
     );
 
+    // Initialize the core protocol registry with built-in system protocols.
+    this._coreProtocols = new CoreProtocolRegistry();
+    this._coreProtocols.register(new PermissionsProtocol());
+
+    // Build the shared dependency bag once; every handler receives the same object
+    // and accesses only the dependencies it needs.
+    const deps: HandlerDependencies = {
+      didResolver          : this.didResolver,
+      messageStore         : this.messageStore,
+      dataStore            : this.dataStore,
+      stateIndex           : this.stateIndex,
+      resumableTaskManager : this.resumableTaskManager,
+      coreProtocols        : this._coreProtocols,
+      eventLog             : this.eventLog,
+    };
+
     this.methodHandlers = {
-      [DwnInterfaceName.Messages + DwnMethodName.Read]: new MessagesReadHandler(
-        this.didResolver,
-        this.messageStore,
-        this.dataStore,
-      ),
-      [DwnInterfaceName.Messages + DwnMethodName.Subscribe]: new MessagesSubscribeHandler(
-        this.didResolver,
-        this.messageStore,
-        this.eventStream,
-      ),
-      [DwnInterfaceName.Messages + DwnMethodName.Sync]: new MessagesSyncHandler(
-        this.didResolver,
-        this.messageStore,
-        this.stateIndex,
-      ),
-      [DwnInterfaceName.Protocols + DwnMethodName.Configure]: new ProtocolsConfigureHandler(
-        this.didResolver,
-        this.messageStore,
-        this.stateIndex,
-        this.eventStream
-      ),
-      [DwnInterfaceName.Protocols + DwnMethodName.Query]: new ProtocolsQueryHandler(
-        this.didResolver,
-        this.messageStore,
-        this.dataStore
-      ),
-      [DwnInterfaceName.Records + DwnMethodName.Count]: new RecordsCountHandler(
-        this.didResolver,
-        this.messageStore,
-      ),
-      [DwnInterfaceName.Records + DwnMethodName.Delete]: new RecordsDeleteHandler(
-        this.didResolver,
-        this.messageStore,
-        this.resumableTaskManager
-      ),
-      [DwnInterfaceName.Records + DwnMethodName.Query]: new RecordsQueryHandler(
-        this.didResolver,
-        this.messageStore,
-        this.dataStore
-      ),
-      [DwnInterfaceName.Records + DwnMethodName.Read]: new RecordsReadHandler(
-        this.didResolver,
-        this.messageStore,
-        this.dataStore
-      ),
-      [DwnInterfaceName.Records + DwnMethodName.Subscribe]: new RecordsSubscribeHandler(
-        this.didResolver,
-        this.messageStore,
-        this.eventStream
-      ),
-      [DwnInterfaceName.Records + DwnMethodName.Write]: new RecordsWriteHandler(
-        this.didResolver,
-        this.messageStore,
-        this.dataStore,
-        this.stateIndex,
-        this.eventStream
-      )
+      [DwnInterfaceName.Messages + DwnMethodName.Read]       : new MessagesReadHandler(deps),
+      [DwnInterfaceName.Messages + DwnMethodName.Subscribe]  : new MessagesSubscribeHandler(deps),
+      [DwnInterfaceName.Messages + DwnMethodName.Sync]       : new MessagesSyncHandler(deps),
+      [DwnInterfaceName.Protocols + DwnMethodName.Configure] : new ProtocolsConfigureHandler(deps),
+      [DwnInterfaceName.Protocols + DwnMethodName.Query]     : new ProtocolsQueryHandler(deps),
+      [DwnInterfaceName.Records + DwnMethodName.Count]       : new RecordsCountHandler(deps),
+      [DwnInterfaceName.Records + DwnMethodName.Delete]      : new RecordsDeleteHandler(deps),
+      [DwnInterfaceName.Records + DwnMethodName.Query]       : new RecordsQueryHandler(deps),
+      [DwnInterfaceName.Records + DwnMethodName.Read]        : new RecordsReadHandler(deps),
+      [DwnInterfaceName.Records + DwnMethodName.Subscribe]   : new RecordsSubscribeHandler(deps),
+      [DwnInterfaceName.Records + DwnMethodName.Write]       : new RecordsWriteHandler(deps),
     };
   }
 
@@ -148,19 +121,28 @@ export class Dwn {
     await this.dataStore.open();
     await this.resumableTaskStore.open();
     await this.stateIndex.open();
-    await this.eventStream?.open();
+    await this.eventLog?.open();
 
     await this.resumableTaskManager.resumeTasksAndWaitForCompletion();
   }
 
   public async close(): Promise<void> {
-    await this.eventStream?.close();
+    await this.eventLog?.close();
     await this.messageStore.close();
     await this.dataStore.close();
     await this.resumableTaskStore.close();
     await this.stateIndex.close();
   }
 
+  /**
+   * The registry of core protocols (hardcoded, immutable, always-installed).
+   * Used by handlers and utilities that need to check whether a protocol URI
+   * belongs to a core protocol or to dispatch lifecycle hooks.
+   */
+  public get coreProtocols(): CoreProtocolRegistry {
+    return this._coreProtocols;
+  }
+
   /**
    * Returns the internal storage components for advanced operations that
    * cannot be expressed through the standard `processMessage()` pipeline
@@ -168,11 +150,11 @@ export class Dwn {
    *
    * Callers are responsible for maintaining consistency across stores.
    */
-  public get storage(): { messageStore: MessageStore; stateIndex: StateIndex; eventStream: EventStream | undefined } {
+  public get storage(): { messageStore: MessageStore; stateIndex: StateIndex; eventLog: EventLog | undefined } {
     return {
       messageStore : this.messageStore,
       stateIndex   : this.stateIndex,
-      eventStream  : this.eventStream,
+      eventLog     : this.eventLog,
     };
   }
 
@@ -264,7 +246,7 @@ export class Dwn {
  */
 export interface MessageOptions {
   dataStream?: ReadableStream<Uint8Array>;
-  subscriptionHandler?: MessageSubscriptionHandler | RecordSubscriptionHandler;
+  subscriptionHandler?: SubscriptionListener;
 };
 
 /**
@@ -274,8 +256,11 @@ export type DwnConfig = {
   didResolver?: DidResolver;
   tenantGate?: TenantGate;
 
-  // event stream is optional if a DWN does not wish to provide subscription services.
-  eventStream?: EventStream;
+  /**
+   * Persistent event log with cursor-based reads and in-process subscriptions.
+   * Optional — if not provided, subscriptions will not be supported.
+   */
+  eventLog?: EventLog;
 
   messageStore: MessageStore;
   dataStore: DataStore;

package/src/event-stream/event-emitter-event-log.ts

@@ -0,0 +1,283 @@
+import type { KeyValues } from '../types/query-types.js';
+import type {
+  EventLog,
+  EventLogEntry,
+  EventLogReadOptions,
+  EventLogReadResult,
+  EventLogSubscribeOptions,
+  EventSubscription,
+  MessageEvent,
+  SubscriptionListener,
+} from '../types/subscriptions.js';
+
+import mitt from 'mitt';
+
+import { FilterUtility } from '../utils/filter.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+const EVENTS_LISTENER_CHANNEL = 'events';
+
+/**
+ * Payload shape used internally by mitt. We bundle the three EventListener
+ * arguments into a single object because mitt emits one value per event.
+ */
+type EmitterPayload = { tenant: string; event: MessageEvent; indexes: KeyValues; seq: number };
+
+/**
+ * mitt event map — every channel name maps to an `EmitterPayload`.
+ * Using `Record<string, EmitterPayload>` lets us create channels dynamically.
+ */
+type EmitterEvents = Record<string, EmitterPayload>;
+
+/**
+ * Internal storage entry — the event plus its indexes.
+ */
+type StoredEntry = {
+  event : MessageEvent;
+  indexes : KeyValues;
+};
+
+export interface EventEmitterEventLogConfig {
+  /**
+   * Maximum number of events to retain per tenant.
+   * Oldest events are evicted when the limit is reached.
+   * Defaults to 10_000.
+   */
+  maxEventsPerTenant?: number;
+
+  /**
+   * An optional error handler in order to be able to react to any errors or warnings.
+   * By default we log errors with `console.error`.
+   */
+  errorHandler?: (error: any) => void;
+}
+
+/**
+ * In-memory implementation of {@link EventLog} backed by `mitt` for in-process
+ * pub/sub and a per-tenant `Map<number, StoredEntry>` for persistence with
+ * cursor-based reads.
+ *
+ * Suitable for single-process embedded DWN instances and tests.
+ * For multi-node deployments, use a distributed implementation (NATS, Redis, etc.).
+ */
+export class EventEmitterEventLog implements EventLog {
+  private emitter = mitt<EmitterEvents>();
+  private isOpen: boolean = false;
+  private errorHandler: (error: any) => void = (error): void => { console.error('event log error', error); };
+  private maxEventsPerTenant: number;
+
+  /**
+   * Per-tenant ordered event storage.
+   * Key: tenant DID → Map of seq → StoredEntry.
+   */
+  private tenantLogs: Map<string, Map<number, StoredEntry>> = new Map();
+
+  /**
+   * Per-tenant monotonic sequence counter.
+   */
+  private tenantSeqs: Map<string, number> = new Map();
+
+  constructor(config: EventEmitterEventLogConfig = {}) {
+    this.maxEventsPerTenant = config.maxEventsPerTenant ?? 10_000;
+
+    if (config.errorHandler) {
+      this.errorHandler = config.errorHandler;
+    }
+  }
+
+  public async open(): Promise<void> {
+    this.isOpen = true;
+  }
+
+  public async close(): Promise<void> {
+    this.isOpen = false;
+    this.emitter.all.clear();
+    this.tenantLogs.clear();
+    this.tenantSeqs.clear();
+  }
+
+  public async emit(tenant: string, event: MessageEvent, indexes: KeyValues): Promise<string> {
+    if (!this.isOpen) {
+      this.errorHandler(new DwnError(
+        DwnErrorCode.EventLogNotOpenError,
+        'a message emitted when EventLog is closed'
+      ));
+      return '';
+    }
+
+    // Assign a monotonic sequence number for this tenant.
+    const prevSeq = this.tenantSeqs.get(tenant) ?? 0;
+    const seq = prevSeq + 1;
+    this.tenantSeqs.set(tenant, seq);
+
+    // Persist the event.
+    let log = this.tenantLogs.get(tenant);
+    if (log === undefined) {
+      log = new Map();
+      this.tenantLogs.set(tenant, log);
+    }
+    log.set(seq, { event, indexes });
+
+    // Evict oldest entries if the log exceeds the retention limit.
+    if (log.size > this.maxEventsPerTenant) {
+      const evictCount = log.size - this.maxEventsPerTenant;
+      let evicted = 0;
+      for (const key of log.keys()) {
+        if (evicted >= evictCount) { break; }
+        log.delete(key);
+        evicted++;
+      }
+    }
+
+    // Notify in-process subscribers.
+    const channel = `${tenant}_${EVENTS_LISTENER_CHANNEL}`;
+    this.emitter.emit(channel, { tenant, event, indexes, seq });
+
+    return String(seq);
+  }
+
+  public async read(tenant: string, options: EventLogReadOptions = {}): Promise<EventLogReadResult> {
+    const { cursor, limit, filters } = options;
+    const cursorSeq = cursor !== undefined ? EventEmitterEventLog.parseCursor(cursor) : undefined;
+    const log = this.tenantLogs.get(tenant);
+
+    if (log === undefined || log.size === 0) {
+      return { events: [], cursor };
+    }
+
+    const results: EventLogEntry[] = [];
+    const maxResults = limit ?? Number.MAX_SAFE_INTEGER;
+
+    for (const [seq, entry] of log) {
+      // Skip entries at or before the cursor.
+      if (cursorSeq !== undefined && seq <= cursorSeq) { continue; }
+
+      // Apply filters if provided (OR semantics — match any filter).
+      if (filters !== undefined && filters.length > 0) {
+        if (!FilterUtility.matchAnyFilter(entry.indexes, filters)) { continue; }
+      }
+
+      results.push({
+        seq,
+        event   : entry.event,
+        indexes : entry.indexes,
+      });
+
+      if (results.length >= maxResults) { break; }
+    }
+
+    const lastSeq = results.length > 0 ? results[results.length - 1].seq : undefined;
+    return { events: results, cursor: lastSeq !== undefined ? String(lastSeq) : cursor };
+  }
+
+  /**
+   * Parse an opaque cursor string into an internal sequence number.
+   */
+  private static parseCursor(cursor: string): number {
+    const seq = Number(cursor);
+    if (Number.isNaN(seq) || seq < 0) {
+      throw new DwnError(DwnErrorCode.EventLogNotOpenError, `invalid cursor: '${cursor}'`);
+    }
+    return seq;
+  }
+
+  public async subscribe(
+    tenant: string,
+    id: string,
+    listener: SubscriptionListener,
+    options?: EventLogSubscribeOptions,
+  ): Promise<EventSubscription> {
+    const channel = `${tenant}_${EVENTS_LISTENER_CHANNEL}`;
+    const { cursor, filters } = options ?? {};
+
+    if (cursor !== undefined) {
+      // ---- Cursor mode: catch-up from stored events, then EOSE, then live ----
+      const cursorSeq = EventEmitterEventLog.parseCursor(cursor);
+
+      // Buffer live events that arrive during catch-up to avoid losing them.
+      type BufferedEvent = { event: MessageEvent; seq: number };
+      const pendingLiveEvents: BufferedEvent[] = [];
+      let catchUpComplete = false;
+
+      // Step 1: Register live listener FIRST so no events are missed during read.
+      const handler = (payload: EmitterPayload): void => {
+        if (filters !== undefined && filters.length > 0) {
+          if (!FilterUtility.matchAnyFilter(payload.indexes, filters)) { return; }
+        }
+        if (!catchUpComplete) {
+          pendingLiveEvents.push({ event: payload.event, seq: payload.seq });
+        } else {
+          listener({ type: 'event', cursor: String(payload.seq), event: payload.event });
+        }
+      };
+
+      this.emitter.on(channel, handler);
+
+      // Step 2: Read stored events from cursor and deliver them.
+      const readResult = await this.read(tenant, { cursor, filters });
+      // The read cursor is the last event's seq (string) or the input cursor if nothing new.
+      const eoseCursor = readResult.cursor ?? cursor;
+      const lastCatchUpSeq = readResult.cursor !== undefined ? Number(readResult.cursor) : cursorSeq;
+
+      for (const entry of readResult.events) {
+        listener({ type: 'event', cursor: String(entry.seq), event: entry.event });
+      }
+
+      // Step 3: Deliver any live events that arrived during catch-up (with seq > lastCatchUpSeq).
+      catchUpComplete = true;
+      for (const liveEvent of pendingLiveEvents) {
+        if (liveEvent.seq > lastCatchUpSeq) {
+          listener({ type: 'event', cursor: String(liveEvent.seq), event: liveEvent.event });
+        }
+      }
+
+      // Step 4: Send EOSE marker.
+      listener({ type: 'eose', cursor: eoseCursor });
+
+      return {
+        id,
+        close: async (): Promise<void> => { this.emitter.off(channel, handler); }
+      };
+    }
+
+    // ---- No cursor: live events only ----
+
+    const handler = (payload: EmitterPayload): void => {
+      if (filters !== undefined && filters.length > 0) {
+        if (!FilterUtility.matchAnyFilter(payload.indexes, filters)) { return; }
+      }
+      listener({ type: 'event', cursor: String(payload.seq), event: payload.event });
+    };
+
+    this.emitter.on(channel, handler);
+
+    return {
+      id,
+      close: async (): Promise<void> => { this.emitter.off(channel, handler); }
+    };
+  }
+
+  public async trim(tenant: string, olderThan: number | string): Promise<void> {
+    const log = this.tenantLogs.get(tenant);
+    if (log === undefined) { return; }
+
+    if (typeof olderThan === 'number') {
+      // Trim by sequence number: delete entries with seq < olderThan.
+      for (const seq of log.keys()) {
+        if (seq < olderThan) {
+          log.delete(seq);
+        } else {
+          break; // Map is ordered by insertion (ascending seq), safe to stop.
+        }
+      }
+    } else {
+      // Trim by ISO-8601 timestamp: delete entries whose message timestamp is before the given time.
+      for (const [seq, entry] of log) {
+        const messageTimestamp = (entry.indexes['messageTimestamp'] as string) ?? '';
+        if (messageTimestamp < olderThan) {
+          log.delete(seq);
+        }
+      }
+    }
+  }
+}