@enbox/dwn-sdk-js 0.4.0 → 0.4.1

package/src/store/storage-controller.ts

@@ -1,10 +1,9 @@
 import type { DataStore } from '../types/data-store.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 type { ProgressToken } from '../types/subscriptions.js';
+import type { RecordsDeleteMessage, RecordsWriteMessage } from '../types/records-types.js';
 
 import { DwnConstant } from '../core/dwn-constant.js';
 import { FilterUtility } from '../utils/filter.js';
@@ -25,29 +24,28 @@ export type ResumableRecordsSquashData = {
   message: RecordsWriteMessage;
 };
 
+export type RecordsDeleteTaskResult = {
+  position?: ProgressToken;
+};
+
 /**
- * A class that provides an abstraction for the usage of MessageStore, DataStore, and StateIndex.
+ * A class that provides an abstraction for coordinated MessageStore and DataStore mutations.
  */
 export class StorageController {
 
   private readonly messageStore: MessageStore;
   private readonly dataStore: DataStore;
-  private readonly stateIndex: StateIndex;
-  private readonly eventLog?: EventLog;
 
-  public constructor({ messageStore, dataStore, stateIndex, eventLog }: {
+  public constructor({ messageStore, dataStore }: {
     messageStore : MessageStore,
     dataStore : DataStore,
-    stateIndex : StateIndex,
-    eventLog? : EventLog}
+  }
   ) {
     this.messageStore = messageStore;
     this.dataStore = dataStore;
-    this.stateIndex = stateIndex;
-    this.eventLog = eventLog;
   }
 
-  public async performRecordsDelete({ tenant, message }: ResumableRecordsDeleteData): Promise<void> {
+  public async performRecordsDelete({ tenant, message }: ResumableRecordsDeleteData): Promise<RecordsDeleteTaskResult> {
     // get existing records matching the `recordId`
     const query = {
       interface : DwnInterfaceName.Records,
@@ -58,8 +56,15 @@ export class StorageController {
     // find which message is the newest, and if the incoming message is the newest
     const newestExistingMessage = await Message.getNewestMessage(existingMessages);
 
-    if (!Records.canPerformDeleteAgainstRecord(message, newestExistingMessage)) {
-      return;
+    if (newestExistingMessage === undefined) {
+      return {};
+    }
+
+    // Same tombstone-lattice gate as the RecordsDelete handler: state can advance between
+    // acceptance and task replay, and a beaten delete accepted earlier must not displace the
+    // tombstone that has since become the record's canonical winner.
+    if (await Records.isDeleteBeatenByExistingTombstone(message, newestExistingMessage)) {
+      return {};
     }
 
     // NOTE: code above is duplicated from `RecordsDeleteHandler` and is already performed if this was invoked by the `RecordsDeleteHandler`,
@@ -68,15 +73,14 @@ export class StorageController {
 
     const recordsDelete = await RecordsDelete.parse(message);
     const initialWrite = await RecordsWrite.getInitialWrite(existingMessages);
-    const indexes = recordsDelete.constructIndexes(initialWrite);
-    const messageCid = await Message.getCid(message);
-    await this.messageStore.put(tenant, message, indexes);
-    await this.stateIndex.insert(tenant, messageCid, indexes);
-
-    // only emit if the event log is set
-    if (this.eventLog !== undefined) {
-      await this.eventLog.emit(tenant, { message, initialWrite }, indexes, messageCid);
-    }
+    const newestPreDeleteWrite = await Records.getNewestRecordsWrite(existingMessages) ?? initialWrite;
+
+    // Tombstone mutable query-visibility facts (`tag.*`, `published`, `datePublished`) come from
+    // the newest retained RecordsWrite. This remains true when replacing an existing tombstone:
+    // tombstones carry no visibility facts in their descriptors, so the retained write is the
+    // durable source of truth for later prune/replay/replication index reconstruction.
+    const indexes = recordsDelete.constructIndexes(initialWrite, newestPreDeleteWrite);
+    const { position } = await this.messageStore.put(tenant, message, indexes);
 
     if (message.descriptor.prune) {
       // purge/hard-delete all descendant records. Cascade is intentionally protocol-agnostic:
@@ -84,14 +88,16 @@ export class StorageController {
       // of which protocol a descendant lives in. Cross-protocol composing children (linked via
       // `$ref`/`uses`) participate in the cascade. See issue #298 for the design discussion.
       await StorageController.purgeRecordDescendants(
-        tenant, message.descriptor.recordId, this.messageStore, this.dataStore, this.stateIndex
+        tenant, message.descriptor.recordId, this.messageStore, this.dataStore
       );
     }
 
-    // delete all existing messages that are not newest, except for the initial write
-    await StorageController.deleteAllOlderMessagesButKeepInitialWrite(
-      tenant, existingMessages, message, this.messageStore, this.dataStore, this.stateIndex
+    // displace every other message for this record, retaining the writes needed for replay and future tombstone visibility
+    await StorageController.deleteDisplacedMessagesAndRetainWrites(
+      tenant, existingMessages, message, this.messageStore, this.dataStore, [newestPreDeleteWrite]
     );
+
+    return { position };
   }
 
   /**
@@ -159,7 +165,7 @@ export class StorageController {
       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);
+        await StorageController.purgeRecordMessages(tenant, messages, this.messageStore, this.dataStore);
       }
     }
   }
@@ -216,8 +222,7 @@ export class StorageController {
     tenant: string,
     recordId: string,
     messageStore: MessageStore,
-    dataStore: DataStore,
-    stateIndex: StateIndex
+    dataStore: DataStore
   ): Promise<void> {
     const filter: Filter = {
       interface : DwnInterfaceName.Records,
@@ -244,11 +249,11 @@ export class StorageController {
     }
 
     for (const childRecordId of recordIdToMessagesMap.keys()) {
-      await StorageController.purgeRecordDescendants(tenant, childRecordId, messageStore, dataStore, stateIndex);
+      await StorageController.purgeRecordDescendants(tenant, childRecordId, messageStore, dataStore);
     }
 
     for (const childRecordId of recordIdToMessagesMap.keys()) {
-      await StorageController.purgeRecordMessages(tenant, recordIdToMessagesMap.get(childRecordId)!, messageStore, dataStore, stateIndex);
+      await StorageController.purgeRecordMessages(tenant, recordIdToMessagesMap.get(childRecordId)!, messageStore, dataStore);
     }
   }
 
@@ -260,8 +265,7 @@ export class StorageController {
     tenant: string,
     recordMessages: GenericMessage[],
     messageStore: MessageStore,
-    dataStore: DataStore,
-    stateIndex: StateIndex
+    dataStore: DataStore
   ): Promise<void> {
     // delete the data from the data store first so no chance of orphaned data (not having a message referencing it) in case of server crash
     // NOTE: only the `RecordsWrite` with latest timestamp can possibly have data associated with it so we do this filtering as an optimization
@@ -275,60 +279,67 @@ export class StorageController {
     const newestRecordsWrite = (await Message.getNewestMessage(recordsWrites)) as RecordsWriteMessage;
     await dataStore.delete(tenant, newestRecordsWrite.recordId, newestRecordsWrite.descriptor.dataCid);
 
-    // then delete all events associated with the record messages before deleting the messages so we don't have orphaned events
     const messageCids = await Promise.all(recordMessages.map((message) => Message.getCid(message)));
-    await stateIndex.delete(tenant, messageCids);
 
-    // finally delete all record messages
     await Promise.all(messageCids.map((messageCid) => messageStore.delete(tenant, messageCid)));
   }
 
   /**
-   * Deletes all messages in `existingMessages` that are older than the `newestMessage` in the given tenant,
-   * but keep the initial write write for future processing by ensuring its `isLatestBaseState` index is "false".
+   * Deletes all messages in `existingMessages` that the `retainedMessage` displaces, while keeping
+   * the initial write and the caller-supplied writes as non-latest state for future replay and
+   * tombstone visibility reconstruction. Displacement is deliberately NOT a timestamp comparison:
+   * a RecordsDelete displaces even a newer RecordsWrite (delete-wins convergence), and on
+   * resumable-task replay the retained message itself is back in `existingMessages` and must
+   * survive — so membership is decided by CID.
    */
-  public static async deleteAllOlderMessagesButKeepInitialWrite(
+  public static async deleteDisplacedMessagesAndRetainWrites(
     tenant: string,
     existingMessages: GenericMessage[],
-    newestMessage: GenericMessage,
+    retainedMessage: GenericMessage,
     messageStore: MessageStore,
     dataStore: DataStore,
-    stateIndex: StateIndex
+    additionalRetainedRecordsWrites: RecordsWriteMessage[],
   ): Promise<void> {
-    const deletedMessageCids: string[] = [];
+    const retainedMessageCid = await Message.getCid(retainedMessage);
+    const additionalRetainedRecordsWriteCids = new Set<string>();
+    for (const retainedRecordsWrite of additionalRetainedRecordsWrites) {
+      additionalRetainedRecordsWriteCids.add(await Message.getCid(retainedRecordsWrite));
+    }
 
     // NOTE: under normal operation, there should only be at most two existing records per `recordId` (initial + a potential subsequent write/delete),
     // but the DWN may crash before `delete()` is called below, so we use a loop as a tactic to clean up lingering data as needed
     for (const message of existingMessages) {
-      const messageIsOld = await Message.isOlder(message, newestMessage);
-      if (messageIsOld) {
+      const messageCid = await Message.getCid(message);
+      const messageIsDisplaced = messageCid !== retainedMessageCid;
+      if (messageIsDisplaced) {
         // the easiest implementation here is delete each old messages
-        // and re-create it with the right index (isLatestBaseState = 'false') if the message is the initial write,
+        // and re-create it with the right index (isLatestBaseState = 'false') if the message is a retained write,
         // but there is room for better/more efficient implementation here
 
-        await StorageController.deleteFromDataStoreIfNeeded(dataStore, tenant, message, newestMessage);
+        await StorageController.deleteFromDataStoreIfNeeded(dataStore, tenant, message, retainedMessage);
 
-        // delete message from message store
-        const messageCid = await Message.getCid(message);
-        await messageStore.delete(tenant, messageCid);
-
-        // if the existing message is the initial write
-        // we actually need to keep it BUT, need to ensure the message is no longer marked as the latest state
-        const existingMessageIsInitialWrite = await RecordsWrite.isInitialWrite(message);
-        if (existingMessageIsInitialWrite) {
-          const existingRecordsWrite = await RecordsWrite.parse(message as RecordsWriteMessage);
+        // Retained writes must stay in the message store and state index so future deletes and
+        // replicas can reconstruct tombstone visibility, but they must no longer be latest state.
+        const shouldKeepAsNonLatestWrite =
+          await RecordsWrite.isInitialWrite(message) ||
+          additionalRetainedRecordsWriteCids.has(messageCid);
+        if (shouldKeepAsNonLatestWrite) {
+          const retainedRecordsWriteMessage = StorageController.stripInlineData(message as RecordsWriteMessage);
+          const existingRecordsWrite = await RecordsWrite.parse(retainedRecordsWriteMessage);
           const isLatestBaseState = false;
           const indexes = await existingRecordsWrite.constructIndexes(isLatestBaseState);
-          const writeMessage = message as RecordsQueryReplyEntry;
-          delete writeMessage.encodedData;
-          await messageStore.put(tenant, writeMessage, indexes);
+          await messageStore.updateMessageAndIndexes(tenant, messageCid, retainedRecordsWriteMessage, indexes);
         } else {
-          const messageCid = await Message.getCid(message);
-          deletedMessageCids.push(messageCid);
+          // delete message from message store
+          await messageStore.delete(tenant, messageCid);
         }
       }
-
-      await stateIndex.delete(tenant, deletedMessageCids);
     }
   }
+
+  private static stripInlineData(message: RecordsWriteMessage): RecordsWriteMessage {
+    const retainedMessage = { ...message } as RecordsWriteMessage & { encodedData?: string };
+    delete retainedMessage.encodedData;
+    return retainedMessage;
+  }
 }

package/src/types/message-store.ts

@@ -1,3 +1,4 @@
+import type { ProgressToken } from './subscriptions.js';
 import type { Filter, KeyValues, PaginationCursor } from './query-types.js';
 import type { GenericMessage, MessageSort, Pagination } from './message-types.js';
 
@@ -5,6 +6,24 @@ export interface MessageStoreOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Result of a {@link MessageStore.put} operation.
+ */
+export type MessageStorePutResult = {
+  /**
+   * `inserted` when a new row was created; `duplicate` when a row for the same
+   * `(tenant, messageCid)` already exists.
+   */
+  status: 'inserted' | 'duplicate';
+
+  /**
+   * The inserted row's log position. Present for stores that maintain a
+   * replication log; omitted for duplicates and store implementations whose
+   * durable log support has not landed.
+   */
+  position?: ProgressToken;
+};
+
 export interface MessageStore {
   /**
    * opens a connection to the underlying store
@@ -25,7 +44,7 @@ export interface MessageStore {
     message: GenericMessage,
     indexes: KeyValues,
     options?: MessageStoreOptions
-  ): Promise<void>;
+  ): Promise<MessageStorePutResult>;
 
   /**
    * Fetches a single message by `cid` from the underlying store.
@@ -56,6 +75,30 @@ export interface MessageStore {
     options?: MessageStoreOptions
   ): Promise<number>;
 
+  /**
+   * Replaces the indexes of an existing message in place: same row and same log
+   * sequence.
+   */
+  updateIndexes(
+    tenant: string,
+    messageCid: string,
+    indexes: KeyValues,
+    options?: MessageStoreOptions
+  ): Promise<void>;
+
+  /**
+   * Replaces the stored same-CID message payload and indexes in place: same
+   * row and same log sequence. The replacement message must resolve to
+   * `messageCid` under DWN CID rules.
+   */
+  updateMessageAndIndexes(
+    tenant: string,
+    messageCid: string,
+    message: GenericMessage,
+    indexes: KeyValues,
+    options?: MessageStoreOptions
+  ): Promise<void>;
+
   /**
    * Deletes the message associated with the id provided.
    */
@@ -65,4 +108,4 @@ export interface MessageStore {
    * Clears the entire store. Mainly used for cleaning up in test environment.
    */
   clear(): Promise<void>;
-}
+}

package/src/types/message-types.ts

@@ -1,4 +1,5 @@
 import type { GeneralJws } from './jws-types.js';
+import type { ProgressToken } from './subscriptions.js';
 import type { PublicKeyJwk } from './jose-types.js';
 import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import type { PaginationCursor, SortDirection } from './query-types.js';
@@ -145,10 +146,11 @@ export type Status = {
 
 export type GenericMessageReply = {
   status: Status;
+  position?: ProgressToken;
 };
 
 export type MessageSort = {
   dateCreated?: SortDirection;
   datePublished?: SortDirection;
   messageTimestamp?: SortDirection;
-};
+};

package/src/types/messages-types.ts

@@ -42,57 +42,38 @@ export type MessagesReadReply = GenericMessageReply & {
   entry?: MessagesReadReplyEntry;
 };
 
-export type MessagesSyncAction = 'root' | 'subtree' | 'leaves' | 'diff';
-
-export type MessagesSyncDescriptor = {
-  interface : DwnInterfaceName.Messages;
-  method : DwnMethodName.Sync;
-  messageTimestamp : string;
-  action : MessagesSyncAction;
-  protocol? : string; // optional protocol scope
-  prefix? : string; // bit path for subtree/leaves (e.g. "0110101...")
-  permissionGrantIds? : string[];
-  /**
-   * For `action: 'diff'`: a map of `{ bitPrefix: hexHash }` representing the client's
-   * subtree hashes at `depth`. The server compares each hash against its own tree
-   * and returns the set difference in a single round-trip.
-   *
-   * Only non-default (non-empty) subtree hashes need to be included — prefixes
-   * whose hash equals the default empty-subtree hash may be omitted.
-   */
-  hashes? : Record<string, string>;
-  /**
-   * For `action: 'diff'`: the bit depth at which the client computed its subtree
-   * hashes. Required when `action` is `'diff'`.
-   */
-  depth? : number;
+export type MessagesQueryDescriptor = {
+  interface: DwnInterfaceName.Messages;
+  method: DwnMethodName.Query;
+  messageTimestamp: string;
+  filters: MessagesFilter[];
+  permissionGrantIds?: string[];
+  cursor?: ProgressToken;
+  limit?: number;
+  cidsOnly?: boolean;
 };
 
-export type MessagesSyncMessage = GenericMessage & {
-  authorization : AuthorizationModel; // overriding `GenericMessage` with `authorization` being required
-  descriptor : MessagesSyncDescriptor;
+export type MessagesQueryMessage = {
+  authorization: AuthorizationModel;
+  descriptor: MessagesQueryDescriptor;
 };
 
-/**
- * Entry in a diff response representing a message the server has that the
- * client does not (or vice versa). Optionally includes the full message
- * and inline data for small payloads.
- */
-export type MessagesSyncDiffEntry = {
-  messageCid : string;
-  message? : GenericMessage;
-  /** Base64url-encoded data for small RecordsWrite payloads (≤ maxInlineDataSize). */
-  encodedData? : string;
+export type MessagesQueryReplyEntry = {
+  seq: string;
+  messageCid: string;
+  isLatestBaseState: boolean;
+  protocol?: string;
+  message?: GenericMessage;
+  encodedData?: string;
 };
 
-export type MessagesSyncReply = GenericMessageReply & {
-  root? : string; // hex-encoded root hash (for 'root' action)
-  hash? : string; // hex-encoded subtree hash (for 'subtree' action)
-  entries? : string[]; // messageCid[] (for 'leaves' action)
-  /** For 'diff' action: messageCids (or full messages) that the server has but the client doesn't. */
-  onlyRemote? : MessagesSyncDiffEntry[];
-  /** For 'diff' action: bit prefixes where the client has entries the server doesn't. */
-  onlyLocal? : string[];
+export type MessagesQueryReply = GenericMessageReply & {
+  entries?: MessagesQueryReplyEntry[];
+  cursor?: ProgressToken;
+  drained?: boolean;
+  fingerprint?: string;
+  /** Present when status.code is 410 — structured gap metadata. */
+  error?: { code: 'ProgressGap' } & ProgressGapInfo;
 };
 
 export type MessagesSubscribeMessageOptions = {

package/src/types/method-handler.ts

@@ -3,7 +3,7 @@ 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 { ValidationStateReader } from './validation-state-reader.js';
 import type { EventLog, SubscriptionListener } from './subscriptions.js';
 import type { GenericMessage, GenericMessageReply } from './message-types.js';
 
@@ -17,7 +17,7 @@ export interface MethodHandler {
   handle(input: {
     tenant: string;
     message: GenericMessage;
-    dataStream?: ReadableStream<Uint8Array>
+    dataStream?: ReadableStream<Uint8Array>;
     subscriptionHandler?: SubscriptionListener;
   }): Promise<GenericMessageReply>;
 }
@@ -32,8 +32,8 @@ export interface MethodHandler {
 export type HandlerDependencies = {
   didResolver: DidResolver;
   messageStore: MessageStore;
+  validationStateReader: ValidationStateReader;
   dataStore?: DataStore;
-  stateIndex?: StateIndex;
   resumableTaskManager?: ResumableTaskManager;
   coreProtocols?: CoreProtocolRegistry;
   eventLog?: EventLog;

package/src/types/permission-types.ts

@@ -90,7 +90,7 @@ export type ProtocolPermissionScope = {
  * Permission scope for the Messages interface.
  *
  * `Read` is the only valid method and acts as a unified scope that authorizes
- * `MessagesRead`, `MessagesSubscribe`, and `MessagesSync` operations.
+ * `MessagesRead`, `MessagesQuery`, and `MessagesSubscribe` operations.
  */
 export type MessagesPermissionScope = {
   interface: DwnInterfaceName.Messages;

package/src/types/subscriptions.ts

@@ -23,15 +23,18 @@ export type ProgressToken = {
   epoch : string;
   /** Monotonic decimal string within `(streamId, epoch)`. Compared numerically. */
   position : string;
-  /** The CID of the message associated with this event. */
-  messageCid : string;
+  /**
+   * The CID of the message associated with this event. Omitted for high-water
+   * cursors that do not point at a delivered in-scope message.
+   */
+  messageCid? : string;
 };
 
 /**
  * Reason code for a {@link ProgressGapInfo} — explains why the cursor
  * cannot be resumed.
  */
-export type ProgressGapReason = 'token_too_old' | 'epoch_mismatch' | 'stream_mismatch';
+export type ProgressGapReason = 'token_too_old' | 'token_too_new' | 'epoch_mismatch' | 'stream_mismatch' | 'message_mismatch';
 
 /**
  * Metadata attached to a `DwnError(DwnErrorCode.EventLogProgressGap, ...)`
@@ -51,14 +54,7 @@ export type ProgressGapInfo = {
 };
 
 /**
- * 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.
+ * MessageEvent contains a committed message and an optional initial write message.
  */
 export type MessageEvent = {
   message: GenericMessage;
@@ -92,6 +88,16 @@ export type SubscriptionEvent = {
   cursor : ProgressToken;
   /** The event payload (message + optional initialWrite). */
   event : MessageEvent;
+  /** Original row sequence for this message. */
+  seq? : string;
+  /** CID of the message that produced this event. */
+  messageCid? : string;
+  /** Whether this event's source row was latest base state at read time. */
+  isLatestBaseState? : boolean;
+  /** Protocol index value associated with the source row, when present. */
+  protocol? : string;
+  /** Base64url-encoded inline data carried beside the message payload. */
+  encodedData? : string;
 };
 
 /**
@@ -148,8 +154,7 @@ export type EventLogSubscribeOptions = {
    * an EOSE marker, then live events. When omitted, only live events are delivered.
    *
    * Tokens must be obtained from a prior interaction with the same EventLog
-   * instance (e.g. `SubscriptionEvent.cursor`, `EventLogReadResult.cursor`,
-   * or the return value of `emit()`).
+   * instance (e.g. `SubscriptionEvent.cursor` or `EventLogReadResult.cursor`).
    */
   cursor? : ProgressToken;
 
@@ -168,18 +173,23 @@ export type EventLogSubscribeOptions = {
  * A single entry returned by {@link EventLog.read}.
  */
 export type EventLogEntry = {
-  /** Monotonic sequence number scoped to (instance, tenant). */
-  seq: number;
+  /** Monotonic sequence number scoped to (instance, tenant), as a decimal string. */
+  seq: string;
+
+  /** The actual delivered log position. Equal to `seq` for store-backed feeds. */
+  position?: string;
 
   /** The event payload. */
   event: MessageEvent;
+  /** Base64url-encoded inline data carried beside the message payload. */
+  encodedData?: string;
 
   /** Indexes associated with the event (used for filter matching). */
   indexes: KeyValues;
 
   /**
    * The CID of the message that produced this event. Populated by
-   * implementations that track it (e.g. {@link EventEmitterEventLog}).
+   * implementations that track it.
    * Consumers should fall back to computing the CID from the message
    * if this is absent.
    */
@@ -207,15 +217,11 @@ export type EventLogReadResult = {
   /** Events matching the read request, ordered by ascending seq. */
   events : EventLogEntry[];
 
-  /**
-   * Progress token for resuming subsequent reads or subscriptions.
-   *
-   * - When events are returned: token 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`.
-   */
+  /** High-water progress token for resuming subsequent reads or subscriptions. */
   cursor? : ProgressToken;
+
+  /** True when the scan reached the captured tenant head. */
+  drained : boolean;
 };
 
 /**
@@ -226,21 +232,11 @@ export type EventLogReadResult = {
  * 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).
+ * backed by an embedded store, SQL, or another durable ordered feed. Each
+ * implementation owns the catch-up + live transition strategy appropriate to
+ * its backend.
  */
 export interface EventLog {
-  /**
-   * Persist an event and notify in-process subscribers.
-   * @param tenant     The tenant DID.
-   * @param event      The event payload.
-   * @param indexes    Index values for the event.
-   * @param messageCid The CID of the message being emitted — embedded in the returned token.
-   * @returns A {@link ProgressToken} assigned to the event, or `undefined` on failure.
-   */
-  emit(tenant: string, event: MessageEvent, indexes: KeyValues, messageCid: string): Promise<ProgressToken | undefined>;
-
   /**
    * Read events from the log starting after `cursor`, optionally filtered.
    */
@@ -270,11 +266,26 @@ export interface EventLog {
    */
   getReplayBounds(tenant: string): Promise<{ oldest: ProgressToken; latest: ProgressToken } | undefined>;
 
-  /**
-   * 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>;
 }
+
+export type Wake = {
+  tenant : string;
+  seq : string;
+};
+
+export interface WakePublisher {
+  publish(wake: Wake): void;
+}
+
+export interface WakeSubscriber {
+  subscribe(listener: (wake: Wake) => void): () => void;
+}
+
+export interface ReplicationFeedReader {
+  logRead(tenant: string, options?: EventLogReadOptions): Promise<EventLogReadResult>;
+  logBounds(tenant: string): Promise<{ oldest: ProgressToken; latest: ProgressToken } | undefined>;
+  fingerprint(tenant: string, scopes: string[]): Promise<string>;
+  epoch(): Promise<string>;
+}