@enbox/dwn-sdk-js 0.0.7 → 0.1.0

package/src/store/storage-controller.ts

@@ -1,11 +1,13 @@
 import type { DataStore } from '../types/data-store.js';
-import type { EventStream } from '../types/subscriptions.js';
+import type { EventLog } from '../types/subscriptions.js';
+import type { Filter } from '../types/query-types.js';
 import type { GenericMessage } from '../types/message-types.js';
 import type { MessageStore } from '../types/message-store.js';
 import type { StateIndex } from '../types/state-index.js';
 import type { RecordsDeleteMessage, RecordsQueryReplyEntry, RecordsWriteMessage } from '../types/records-types.js';
 
 import { DwnConstant } from '../core/dwn-constant.js';
+import { FilterUtility } from '../utils/filter.js';
 import { Message } from '../core/message.js';
 import { Records } from '../utils/records.js';
 import { RecordsDelete } from '../interfaces/records-delete.js';
@@ -18,6 +20,11 @@ export type ResumableRecordsDeleteData = {
   message: RecordsDeleteMessage;
 };
 
+export type ResumableRecordsSquashData = {
+  tenant: string;
+  message: RecordsWriteMessage;
+};
+
 /**
  * A class that provides an abstraction for the usage of MessageStore, DataStore, and StateIndex.
  */
@@ -26,18 +33,18 @@ export class StorageController {
   private messageStore: MessageStore;
   private dataStore: DataStore;
   private stateIndex: StateIndex;
-  private eventStream?: EventStream;
+  private eventLog?: EventLog;
 
-  public constructor({ messageStore, dataStore, stateIndex, eventStream }: {
-    messageStore: MessageStore,
-    dataStore: DataStore,
-    stateIndex: StateIndex,
-    eventStream?: EventStream}
+  public constructor({ messageStore, dataStore, stateIndex, eventLog }: {
+    messageStore : MessageStore,
+    dataStore : DataStore,
+    stateIndex : StateIndex,
+    eventLog? : EventLog}
   ) {
     this.messageStore = messageStore;
     this.dataStore = dataStore;
     this.stateIndex = stateIndex;
-    this.eventStream = eventStream;
+    this.eventLog = eventLog;
   }
 
   public async performRecordsDelete({ tenant, message }: ResumableRecordsDeleteData): Promise<void> {
@@ -66,9 +73,9 @@ export class StorageController {
     await this.messageStore.put(tenant, message, indexes);
     await this.stateIndex.insert(tenant, messageCid, indexes);
 
-    // only emit if the event stream is set
-    if (this.eventStream !== undefined) {
-      this.eventStream.emit(tenant, { message, initialWrite }, indexes);
+    // only emit if the event log is set
+    if (this.eventLog !== undefined) {
+      await this.eventLog.emit(tenant, { message, initialWrite }, indexes);
     }
 
     if (message.descriptor.prune) {
@@ -82,6 +89,76 @@ export class StorageController {
     );
   }
 
+  /**
+   * Performs the squash processing for a `RecordsWrite` with `squash: true`.
+   * Deletes all sibling records at the same protocol path and parent context whose
+   * `messageTimestamp` is strictly older than the squash record's `messageTimestamp`.
+   * Unlike normal `RecordsDelete` tombstones, squash targets are fully purged — no initial writes
+   * are retained.
+   *
+   * This method is idempotent — it can be safely re-run on resume after a crash.
+   */
+  public async performRecordsSquash({ tenant, message }: ResumableRecordsSquashData): Promise<void> {
+    const { protocol, protocolPath, messageTimestamp } = message.descriptor;
+
+    // Build a filter to find all sibling records at the same protocol path and parent context.
+    // We query by interface only (not method) so that both RecordsWrite and RecordsDelete messages are found.
+    const filter: Filter = {
+      interface    : DwnInterfaceName.Records,
+      protocol,
+      protocolPath : protocolPath,
+    };
+
+    // Scope by parent context for nested records
+    const parentContextId = Records.getParentContextFromOfContextId(message.contextId);
+    if (parentContextId !== undefined && parentContextId !== '') {
+      const prefixFilter = FilterUtility.constructPrefixFilterAsRangeFilter(parentContextId);
+      filter.contextId = prefixFilter;
+    }
+
+    // Query for all records at this path and context
+    const { messages: siblingMessages } = await this.messageStore.query(tenant, [filter]);
+
+    // Group messages by recordId — RecordsWrite messages use `message.recordId`,
+    // RecordsDelete messages use `message.descriptor.recordId`.
+    const recordIdToMessages = new Map<string, GenericMessage[]>();
+    for (const msg of siblingMessages) {
+      let recordId: string;
+      if (Records.isRecordsWrite(msg)) {
+        recordId = msg.recordId;
+      } else {
+        recordId = (msg as RecordsDeleteMessage).descriptor.recordId;
+      }
+
+      const existing = recordIdToMessages.get(recordId);
+      if (existing !== undefined) {
+        existing.push(msg);
+      } else {
+        recordIdToMessages.set(recordId, [msg]);
+      }
+    }
+
+    // Delete all records whose newest message timestamp is strictly older than the squash timestamp.
+    // Skip the squash record itself.
+    for (const [recordId, messages] of recordIdToMessages) {
+      if (recordId === message.recordId) {
+        continue;
+      }
+
+      // Use the newest message's timestamp to determine if the record predates the squash.
+      const newestMessage = await Message.getNewestMessage(messages);
+      if (newestMessage === undefined) {
+        continue;
+      }
+
+      const newestTimestamp = newestMessage.descriptor.messageTimestamp;
+      if (newestTimestamp < messageTimestamp) {
+        // Fully purge this record — all messages (including initial write) and their data
+        await StorageController.purgeRecordMessages(tenant, messages, this.messageStore, this.dataStore, this.stateIndex);
+      }
+    }
+  }
+
   /**
    * Deletes the data referenced by the given message if needed.
    * @param message The message to check if the data it references should be deleted.
@@ -164,7 +241,7 @@ export class StorageController {
    * Purges (permanent hard-delete) all messages of the SAME `recordId` given and their associated data and events.
    * Assumes that the given `recordMessages` are all of the same `recordId`.
    */
-  private static async purgeRecordMessages(
+  public static async purgeRecordMessages(
     tenant: string,
     recordMessages: GenericMessage[],
     messageStore: MessageStore,

package/src/types/message-types.ts

@@ -65,13 +65,13 @@ export type DelegatedGrantRecordsWriteMessage = {
     signature: GeneralJws;
   },
   recordId: string,
-  contextId?: string;
+  contextId: string;
   // NOTE: This is a direct expansion and copy of `DataEncodedRecordsWriteMessage` to avoid circular references.
   descriptor: {
     interface: DwnInterfaceName.Records;
     method: DwnMethodName.Write;
-    protocol?: string;
-    protocolPath?: string;
+    protocol: string;
+    protocolPath: string;
     recipient?: string;
     schema?: string;
     parentId?: string;

package/src/types/messages-types.ts

@@ -1,5 +1,5 @@
-import type { MessageEvent } from './subscriptions.js';
 import type { RangeCriterion } from './query-types.js';
+import type { SubscriptionListener } from './subscriptions.js';
 import type { AuthorizationModel, GenericMessage, GenericMessageReply, MessageSubscription } from './message-types.js';
 import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 
@@ -59,10 +59,13 @@ export type MessagesSyncReply = GenericMessageReply & {
   entries? : string[]; // messageCid[] (for 'leaves' action)
 };
 
-export type MessageSubscriptionHandler = (event: MessageEvent) => void;
+/**
+ * @deprecated Use {@link SubscriptionListener} directly. Retained as an alias for migration.
+ */
+export type MessageSubscriptionHandler = SubscriptionListener;
 
 export type MessagesSubscribeMessageOptions = {
-  subscriptionHandler: MessageSubscriptionHandler;
+  subscriptionHandler: SubscriptionListener;
 };
 
 export type MessagesSubscribeMessage = {
@@ -80,4 +83,10 @@ export type MessagesSubscribeDescriptor = {
   messageTimestamp: string;
   filters: MessagesFilter[];
   permissionGrantId?: string;
+  /**
+   * Opaque EventLog cursor string to resume from. When provided, the handler replays
+   * events from the EventLog starting after this cursor instead of returning no
+   * initial snapshot. An EOSE marker is sent after catch-up.
+   */
+  cursor?: string;
 };

package/src/types/method-handler.ts

@@ -1,5 +1,10 @@
-import type { MessageSubscriptionHandler } from './messages-types.js';
-import type { RecordSubscriptionHandler } from './records-types.js';
+import type { CoreProtocolRegistry } from '../core/core-protocol.js';
+import type { DataStore } from './data-store.js';
+import type { DidResolver } from '@enbox/dids';
+import type { MessageStore } from './message-store.js';
+import type { ResumableTaskManager } from '../core/resumable-task-manager.js';
+import type { StateIndex } from './state-index.js';
+import type { EventLog, SubscriptionListener } from './subscriptions.js';
 import type { GenericMessage, GenericMessageReply } from './message-types.js';
 
 /**
@@ -13,6 +18,23 @@ export interface MethodHandler {
     tenant: string;
     message: GenericMessage;
     dataStream?: ReadableStream<Uint8Array>
-    subscriptionHandler?: MessageSubscriptionHandler | RecordSubscriptionHandler;
+    subscriptionHandler?: SubscriptionListener;
   }): Promise<GenericMessageReply>;
-}
+}
+
+/**
+ * Shared dependency bag for all DWN method handlers.
+ *
+ * Every handler receives the same object; each handler accesses only the
+ * dependencies it needs.  Adding a new dependency here is a single-line
+ * change — no handler constructor signatures need updating.
+ */
+export type HandlerDependencies = {
+  didResolver: DidResolver;
+  messageStore: MessageStore;
+  dataStore?: DataStore;
+  stateIndex?: StateIndex;
+  resumableTaskManager?: ResumableTaskManager;
+  coreProtocols?: CoreProtocolRegistry;
+  eventLog?: EventLog;
+};

package/src/types/mitt.d.ts

@@ -0,0 +1,28 @@
+// mitt v3 does not include `"type": "module"` in its package.json, so under
+// TypeScript's `NodeNext` module resolution the `export default function` in
+// mitt's own typings is treated as a CJS namespace rather than a callable.
+// This ambient module declaration re-exports the factory as a proper ESM
+// default so `import mitt from 'mitt'` type-checks correctly.
+declare module 'mitt' {
+  type EventType = string | symbol;
+  type Handler<T = unknown> = (event: T) => void;
+  type EventHandlerList<T = unknown> = Array<Handler<T>>;
+  type WildCardEventHandlerList<T = Record<string, unknown>> = Array<
+    (type: keyof T, event: T[keyof T]) => void
+  >;
+  type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<
+    keyof Events | '*',
+    EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>
+  >;
+
+  interface Emitter<Events extends Record<EventType, unknown>> {
+    all: EventHandlerMap<Events>;
+    on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): void;
+    off<Key extends keyof Events>(type: Key, handler?: Handler<Events[Key]>): void;
+    emit<Key extends keyof Events>(type: Key, event: Events[Key]): void;
+  }
+
+  export default function mitt<Events extends Record<EventType, unknown>>(
+    all?: EventHandlerMap<Events>
+  ): Emitter<Events>;
+}

package/src/types/permission-types.ts

@@ -76,6 +76,13 @@ export type ProtocolPermissionScope = {
   protocol?: string;
 };
 
+/**
+ * Permission scope for the Messages interface.
+ *
+ * A `Read` scope is a unified scope that authorizes `MessagesRead`, `MessagesSubscribe`, and `MessagesSync` operations.
+ * The `Subscribe` and `Sync` method values are retained for backward compatibility with existing grants but are
+ * functionally equivalent to `Read` — new grants SHOULD use `Read` exclusively.
+ */
 export type MessagesPermissionScope = {
   interface: DwnInterfaceName.Messages;
   method: DwnMethodName.Read | DwnMethodName.Subscribe | DwnMethodName.Sync;

package/src/types/protocols-types.ts

@@ -75,6 +75,7 @@ export enum ProtocolAction {
   Delete = 'delete',
   Prune = 'prune',
   Read = 'read',
+  Squash = 'squash',
   Update = 'update'
 }
 
@@ -154,6 +155,47 @@ export type ProtocolSizeDefinition = {
   max?: number;
 };
 
+/**
+ * Supported strategies for handling writes that would exceed a `$recordLimit`.
+ */
+export enum ProtocolRecordLimitStrategy {
+  /** Reject the incoming write with an error. The author must delete old records first. */
+  Reject = 'reject',
+  /** Automatically delete the oldest record(s) (by `dateCreated`) to make room for the new one. */
+  PurgeOldest = 'purgeOldest',
+}
+
+/**
+ * Limits the number of records at a given protocol path within the same parent context.
+ *
+ * For root-level records, the count is across the entire protocol for the tenant.
+ * For nested records, the count is scoped to the parent record's context.
+ *
+ * Only initial writes (new records) count toward the limit; updates to existing records do not.
+ */
+export type ProtocolRecordLimitDefinition = {
+  /** Maximum number of records allowed at this path within the same parent context. Must be >= 1. */
+  max: number;
+
+  /**
+   * Strategy when the limit is reached.
+   * Currently only `'reject'` is implemented. Future strategies (e.g. `'purgeOldest'`)
+   * are defined in the wire format but not yet enforced.
+   */
+  strategy: ProtocolRecordLimitStrategy | `${ProtocolRecordLimitStrategy}` | (string & {});
+};
+
+/**
+ * Delivery strategy for records at a given protocol path.
+ * Controls how a DWN server proactively distributes records to participants' DWN endpoints.
+ *
+ * - `'direct'`    — The origin DWN pushes new records to all participants' DWN endpoints.
+ *                    Best for small participant sets (2–50).
+ * - `'subscribe'` — Participant providers establish `RecordsSubscribe` connections to the
+ *                    origin DWN. Best for asymmetric fan-out or unbounded audiences.
+ */
+export type ProtocolDeliveryStrategy = 'direct' | 'subscribe';
+
 /**
  * Tag rules for records at a given protocol path. Each non-`$`-prefixed property
  * is a JSON Schema object constraining that tag's value.
@@ -192,7 +234,7 @@ export type ProtocolTagSchema = {
 /**
  * Union of all value types that can appear as properties of a `ProtocolRuleSet`.
  * This includes:
- * - `$`-prefixed directive values (`$encryption`, `$actions`, `$role`, `$ref`, `$size`, `$tags`)
+ * - `$`-prefixed directive values (`$encryption`, `$actions`, `$role`, `$ref`, `$size`, `$tags`, `$delivery`)
  * - Child `ProtocolRuleSet` entries (non-`$` keys)
  */
 type ProtocolRuleSetValue =
@@ -201,6 +243,8 @@ type ProtocolRuleSetValue =
   | ProtocolPathEncryption
   | ProtocolTagsDefinition
   | ProtocolSizeDefinition
+  | ProtocolRecordLimitDefinition
+  | ProtocolDeliveryStrategy
   | boolean
   | string
   | undefined;
@@ -247,6 +291,39 @@ export type ProtocolRuleSet = {
    */
   $tags?: ProtocolTagsDefinition;
 
+  /**
+   * If $recordLimit is set, the number of records at this protocol path within the same
+   * parent context is constrained. When the limit is reached, the `strategy` determines
+   * whether the write is rejected or the oldest record is purged.
+   */
+  $recordLimit?: ProtocolRecordLimitDefinition;
+
+  /**
+   * If `$immutable` is `true`, records at this protocol path are write-once: they can be
+   * created but never updated after the initial write. `RecordsDelete` is still governed
+   * by `$actions` — immutability means the record's data cannot change, not that it
+   * cannot be removed.
+   */
+  $immutable?: boolean;
+
+  /**
+   * Delivery strategy hint for records at this protocol path.
+   * When set, the DWN server SHOULD proactively deliver records to participants' DWN endpoints.
+   *
+   * - `'direct'`    — Origin DWN pushes to all participant DWN endpoints upon receipt.
+   * - `'subscribe'` — Participant providers subscribe to the origin DWN via `RecordsSubscribe`.
+   */
+  $delivery?: ProtocolDeliveryStrategy;
+
+  /**
+   * If `$squash` is `true`, enables squash writes at this protocol path.
+   * A squash write is a `RecordsWrite` with `squash: true` in the descriptor that
+   * atomically creates a new record (the snapshot) and deletes all sibling records
+   * at the same protocol path within the same parent context that have a
+   * `messageTimestamp` strictly older than the squash record's `messageTimestamp`.
+   */
+  $squash?: boolean;
+
   /**
    * Non-`$`-prefixed keys are nested child `ProtocolRuleSet` entries.
    * At runtime, JSON Schema validation ensures only valid child rule sets appear here.

package/src/types/records-types.ts

@@ -1,5 +1,6 @@
 import type { GeneralJws } from './jws-types.js';
 import type { JweEncryption } from '../utils/encryption.js';
+import type { SubscriptionListener } from './subscriptions.js';
 import type { AuthorizationModel, GenericMessage, GenericMessageReply, GenericSignaturePayload, MessageSubscription, Pagination } from './message-types.js';
 import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import type { PaginationCursor, RangeCriterion, RangeFilter, StartsWithFilter } from './query-types.js';
@@ -23,8 +24,8 @@ export type RecordsWriteTagsFilter = StartsWithFilter | RangeFilter | string | n
 export type RecordsWriteDescriptor = {
   interface: DwnInterfaceName.Records;
   method: DwnMethodName.Write;
-  protocol?: string;
-  protocolPath?: string;
+  protocol: string;
+  protocolPath: string;
   recipient?: string;
   schema?: string;
   tags?: RecordsWriteTags;
@@ -37,6 +38,14 @@ export type RecordsWriteDescriptor = {
   datePublished?: string;
   dataFormat: string;
   permissionGrantId?: string;
+
+  /**
+   * When `true`, this record is a squash (snapshot) write. The protocol rule set at this record's
+   * `protocolPath` must have `$squash: true`; otherwise the message is rejected.
+   * A squash write must be an initial write (a new record, not an update).
+   * This is an immutable property.
+   */
+  squash?: true;
 };
 
 export type RecordsWriteMessageOptions = {
@@ -57,7 +66,7 @@ export type InternalRecordsWriteMessage = GenericMessage & {
 export type RecordsWriteMessage = {
   authorization: AuthorizationModel; // overriding `GenericMessage` with `authorization` being required
   recordId: string,
-  contextId?: string;
+  contextId: string;
   descriptor: RecordsWriteDescriptor;
   attestation?: GeneralJws;
   encryption?: JweEncryption;
@@ -122,6 +131,12 @@ export type RecordsSubscribeDescriptor = {
   filter: RecordsFilter;
   dateSort?: DateSort;
   pagination?: Pagination;
+  /**
+   * Opaque EventLog cursor string to resume from. When provided, the handler replays
+   * events from the EventLog starting after this cursor instead of querying the
+   * MessageStore for an initial snapshot. An EOSE marker is sent after catch-up.
+   */
+  cursor?: string;
 };
 
 export type RecordsFilter = {
@@ -157,7 +172,7 @@ export type RecordsWriteAttestationPayload = {
 
 export type RecordsWriteSignaturePayload = GenericSignaturePayload & {
   recordId: string;
-  contextId?: string;
+  contextId: string;
   attestationCid?: string;
   encryptionCid?: string;
 };
@@ -176,10 +191,13 @@ export type RecordEvent = {
   initialWrite?: RecordsWriteMessage;
 };
 
-export type RecordSubscriptionHandler = (event: RecordEvent) => void;
+/**
+ * @deprecated Use {@link SubscriptionListener} directly. Retained as an alias for migration.
+ */
+export type RecordSubscriptionHandler = SubscriptionListener;
 
 export type RecordsSubscribeMessageOptions = {
-  subscriptionHandler: RecordSubscriptionHandler;
+  subscriptionHandler: SubscriptionListener;
 };
 
 export type RecordsSubscribeMessage = GenericMessage & {

package/src/types/subscriptions.ts

@@ -1,9 +1,13 @@
-import type { GenericMessageReply } from '../types/message-types.js';
-import type { KeyValues } from './query-types.js';
 import type { RecordsWriteMessage } from './records-types.js';
-import type { GenericMessage, MessageSubscription } from './message-types.js';
+import type { Filter, KeyValues } from './query-types.js';
+import type { GenericMessage, GenericMessageReply, MessageSubscription } from './message-types.js';
 
-export type EventListener = (tenant: string, event: MessageEvent, indexes: KeyValues) => void;
+/**
+ * Internal listener type used by {@link EventLog.emit} to notify in-process
+ * subscribers. Not intended for direct consumer use — consumers should use
+ * {@link SubscriptionListener} via {@link EventLog.subscribe}.
+ */
+export type EventListener = (tenant: string, event: MessageEvent, indexes: KeyValues, seq: number) => void;
 
 /**
  * MessageEvent contains the message being emitted and an optional initial write message.
@@ -14,16 +18,6 @@ export type MessageEvent = {
   initialWrite?: RecordsWriteMessage
 };
 
-/**
- * The EventStream interface implements a pub/sub system based on Message filters.
- */
-export interface EventStream {
-  subscribe(tenant: string, id: string, listener: EventListener): Promise<EventSubscription>;
-  emit(tenant: string, event: MessageEvent, indexes: KeyValues): void;
-  open(): Promise<void>;
-  close(): Promise<void>;
-}
-
 export interface EventSubscription {
   id: string;
   close: () => Promise<void>;
@@ -32,3 +26,173 @@ export interface EventSubscription {
 export type SubscriptionReply = GenericMessageReply & {
   subscription?: MessageSubscription;
 };
+
+// ---------------------------------------------------------------------------
+// Subscription events — discriminated union for event + EOSE delivery
+// ---------------------------------------------------------------------------
+
+/**
+ * A regular subscription event carrying a message and its EventLog cursor.
+ */
+export type SubscriptionEvent = {
+  type : 'event';
+  /**
+   * Opaque cursor string assigned by the EventLog implementation. Clients should
+   * persist this value and pass it back to `subscribe()` or `read()` to resume
+   * from this point. The format is implementation-defined (e.g. numeric sequence
+   * for in-memory, Redis stream ID, NATS stream sequence, etc.).
+   */
+  cursor : string;
+  /** The event payload (message + optional initialWrite). */
+  event : MessageEvent;
+};
+
+/**
+ * End-of-Stored-Events marker. Sent after all catch-up events have been replayed
+ * from the EventLog. After EOSE, all subsequent events are live.
+ *
+ * Only delivered when a subscription is created with a `cursor`. Subscriptions
+ * without a cursor never receive EOSE.
+ */
+export type SubscriptionEose = {
+  type : 'eose';
+  /**
+   * Opaque cursor string of the last stored event that was replayed.
+   * Echoes the input cursor when no stored events matched (i.e. already caught up).
+   */
+  cursor : string;
+};
+
+/**
+ * Discriminated union of subscription event types delivered to
+ * {@link SubscriptionListener} callbacks.
+ */
+export type SubscriptionMessage = SubscriptionEvent | SubscriptionEose;
+
+/**
+ * Callback for {@link EventLog.subscribe}. Receives either a regular event
+ * (with cursor) or an EOSE marker indicating catch-up replay is complete.
+ */
+export type SubscriptionListener = (message: SubscriptionMessage) => void;
+
+/**
+ * Options for {@link EventLog.subscribe}.
+ */
+export type EventLogSubscribeOptions = {
+  /**
+   * Opaque cursor string to resume from (exclusive — events after this cursor
+   * are replayed). When provided, stored events are replayed first, followed by
+   * an EOSE marker, then live events. When omitted, only live events are delivered.
+   *
+   * Cursor values are implementation-defined and must be obtained from a prior
+   * interaction with the same EventLog instance (e.g. `SubscriptionEvent.cursor`,
+   * `EventLogReadResult.cursor`, or the return value of `emit()`).
+   */
+  cursor? : string;
+
+  /**
+   * Filters evaluated against event indexes. Events must match at least one
+   * filter (OR semantics). When omitted, all events are delivered.
+   */
+  filters? : Filter[];
+};
+
+// ---------------------------------------------------------------------------
+// EventLog — persistent, cursor-based event delivery
+// ---------------------------------------------------------------------------
+
+/**
+ * A single entry returned by {@link EventLog.read}.
+ */
+export type EventLogEntry = {
+  /** Monotonic sequence number scoped to (instance, tenant). */
+  seq: number;
+
+  /** The event payload. */
+  event: MessageEvent;
+
+  /** Indexes associated with the event (used for filter matching). */
+  indexes: KeyValues;
+};
+
+/**
+ * Options accepted by {@link EventLog.read}.
+ */
+export type EventLogReadOptions = {
+  /** Opaque cursor string to resume from (exclusive — returns events after this cursor). */
+  cursor? : string;
+
+  /** Maximum number of events to return. */
+  limit? : number;
+
+  /** Optional filters evaluated server-side. Events must match at least one filter (OR semantics). */
+  filters?: Filter[];
+};
+
+/**
+ * Result returned by {@link EventLog.read}.
+ */
+export type EventLogReadResult = {
+  /** Events matching the read request, ordered by ascending seq. */
+  events : EventLogEntry[];
+
+  /**
+   * Opaque cursor string for resuming subsequent reads or subscriptions.
+   *
+   * - When events are returned: cursor of the last event.
+   * - When no events are returned but a cursor was provided: the input cursor
+   *   (meaning "you are caught up, nothing new since this point").
+   * - When no events exist and no cursor was provided: `undefined`.
+   */
+  cursor? : string;
+};
+
+/**
+ * The EventLog interface provides persistent, ordered event storage with
+ * cursor-based reads and subscription support.
+ *
+ * It persists events before delivery, exposing opaque cursor strings
+ * that enable cursor-based resume after disconnects.
+ *
+ * The interface is intentionally transport-agnostic — implementations can be
+ * backed by LevelDB (embedded), SQL, NATS JetStream, Redis Streams, etc.
+ * Each implementation owns the catch-up + live transition strategy appropriate
+ * to its backend (e.g., NATS pull consumers, Redis XREAD, in-memory buffering).
+ */
+export interface EventLog {
+  /**
+   * Persist an event and notify in-process subscribers.
+   * @returns The opaque cursor string assigned to the event, or empty string on failure.
+   */
+  emit(tenant: string, event: MessageEvent, indexes: KeyValues): Promise<string>;
+
+  /**
+   * Read events from the log starting after `cursor`, optionally filtered.
+   */
+  read(tenant: string, options?: EventLogReadOptions): Promise<EventLogReadResult>;
+
+  /**
+   * Subscribe to events for a tenant.
+   *
+   * When `options.cursor` is provided, the implementation replays stored events
+   * from that cursor through the listener, delivers an EOSE marker, then
+   * continues with live events. The catch-up → live transition (including
+   * buffering and deduplication) is owned by the implementation.
+   *
+   * When `options.cursor` is omitted, only live events are delivered.
+   *
+   * @param tenant   The tenant DID to subscribe to.
+   * @param id       A unique subscription identifier (used for close/tracking).
+   * @param listener Callback that receives {@link SubscriptionMessage} events.
+   * @param options  Optional cursor and filters for catch-up replay.
+   */
+  subscribe(tenant: string, id: string, listener: SubscriptionListener, options?: EventLogSubscribeOptions): Promise<EventSubscription>;
+
+  /**
+   * Delete events older than the given sequence number or ISO-8601 timestamp.
+   */
+  trim(tenant: string, olderThan: number | string): Promise<void>;
+
+  open(): Promise<void>;
+  close(): Promise<void>;
+}