@enbox/dwn-sdk-js 0.3.0 → 0.3.2

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

@@ -7,6 +7,9 @@ import type {
   EventLogSubscribeOptions,
   EventSubscription,
   MessageEvent,
+  ProgressGapInfo,
+  ProgressGapReason,
+  ProgressToken,
   SubscriptionListener,
 } from '../types/subscriptions.js';
 
@@ -21,7 +24,7 @@ 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 };
+type EmitterPayload = { tenant: string; event: MessageEvent; indexes: KeyValues; seq: number; messageCid: string };
 
 /**
  * mitt event map — every channel name maps to an `EmitterPayload`.
@@ -30,11 +33,12 @@ type EmitterPayload = { tenant: string; event: MessageEvent; indexes: KeyValues;
 type EmitterEvents = Record<string, EmitterPayload>;
 
 /**
- * Internal storage entry — the event plus its indexes.
+ * Internal storage entry — the event plus its indexes and message CID.
  */
 type StoredEntry = {
   event : MessageEvent;
   indexes : KeyValues;
+  messageCid : string;
 };
 
 export interface EventEmitterEventLogConfig {
@@ -77,14 +81,92 @@ export class EventEmitterEventLog implements EventLog {
    */
   private tenantSeqs: Map<string, number> = new Map();
 
+  /**
+   * Epoch for this EventLog instance. Generated once at construction as a
+   * UUID v4. Changes every restart (correct for in-memory — state is lost).
+   */
+  private readonly epoch: string;
+
   constructor(config: EventEmitterEventLogConfig = {}) {
     this.maxEventsPerTenant = config.maxEventsPerTenant ?? 10_000;
+    this.epoch = crypto.randomUUID();
 
     if (config.errorHandler) {
       this.errorHandler = config.errorHandler;
     }
   }
 
+  /**
+   * Derives a stable `streamId` for a given tenant. Deterministic — same
+   * tenant always produces the same streamId on any instance.
+   */
+  private async getStreamId(tenant: string): Promise<string> {
+    const bytes = new TextEncoder().encode(tenant);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', bytes);
+    const hashArray = new Uint8Array(hashBuffer);
+    // Take first 16 hex chars (64 bits) of the hash for a compact stable ID.
+    return Array.from(hashArray.slice(0, 8), (b: number) => b.toString(16).padStart(2, '0')).join('');
+  }
+
+  /**
+   * Constructs a {@link ProgressToken} from internal state.
+   */
+  private async buildToken(tenant: string, seq: number, messageCid: string): Promise<ProgressToken> {
+    return {
+      streamId : await this.getStreamId(tenant),
+      epoch    : this.epoch,
+      position : String(seq),
+      messageCid,
+    };
+  }
+
+  /**
+   * Validates a cursor against the current EventLog state. Throws
+   * `DwnError(EventLogProgressGap)` with {@link ProgressGapInfo} metadata
+   * if the cursor cannot be resumed.
+   */
+  private async validateCursor(tenant: string, cursor: ProgressToken): Promise<void> {
+    const expectedStreamId = await this.getStreamId(tenant);
+
+    let reason: ProgressGapReason;
+    if (cursor.streamId !== expectedStreamId) {
+      reason = 'stream_mismatch';
+    } else if (cursor.epoch !== this.epoch) {
+      reason = 'epoch_mismatch';
+    } else {
+      // Check if position is still within replay bounds.
+      const log = this.tenantLogs.get(tenant);
+      if (log !== undefined && log.size > 0) {
+        const firstSeq = log.keys().next().value as number;
+        const cursorSeq = EventEmitterEventLog.parsePosition(cursor.position);
+        if (cursorSeq < firstSeq - 1) {
+          // Cursor position has been evicted — events between cursor and firstSeq are lost.
+          reason = 'token_too_old';
+        } else {
+          return; // Cursor is valid.
+        }
+      } else {
+        return; // No events for tenant — cursor is vacuously valid (will get empty catch-up + EOSE).
+      }
+    }
+
+    // Build gap metadata.
+    const bounds = await this.getReplayBounds(tenant);
+    const gapInfo: ProgressGapInfo = {
+      requested       : cursor,
+      oldestAvailable : bounds?.oldest ?? cursor,
+      latestAvailable : bounds?.latest ?? cursor,
+      reason,
+    };
+
+    const error = new DwnError(
+      DwnErrorCode.EventLogProgressGap,
+      `progress token gap: ${reason}`
+    );
+    (error as any).gapInfo = gapInfo;
+    throw error;
+  }
+
   public async open(): Promise<void> {
     this.isOpen = true;
   }
@@ -96,13 +178,13 @@ export class EventEmitterEventLog implements EventLog {
     this.tenantSeqs.clear();
   }
 
-  public async emit(tenant: string, event: MessageEvent, indexes: KeyValues): Promise<string> {
+  public async emit(tenant: string, event: MessageEvent, indexes: KeyValues, messageCid: string): Promise<ProgressToken | undefined> {
     if (!this.isOpen) {
       this.errorHandler(new DwnError(
         DwnErrorCode.EventLogNotOpenError,
         'a message emitted when EventLog is closed'
       ));
-      return '';
+      return undefined;
     }
 
     // Assign a monotonic sequence number for this tenant.
@@ -116,7 +198,7 @@ export class EventEmitterEventLog implements EventLog {
       log = new Map();
       this.tenantLogs.set(tenant, log);
     }
-    log.set(seq, { event, indexes });
+    log.set(seq, { event, indexes, messageCid });
 
     // Evict oldest entries if the log exceeds the retention limit.
     if (log.size > this.maxEventsPerTenant) {
@@ -131,14 +213,20 @@ export class EventEmitterEventLog implements EventLog {
 
     // Notify in-process subscribers.
     const channel = `${tenant}_${EVENTS_LISTENER_CHANNEL}`;
-    this.emitter.emit(channel, { tenant, event, indexes, seq });
+    this.emitter.emit(channel, { tenant, event, indexes, seq, messageCid });
 
-    return String(seq);
+    return this.buildToken(tenant, seq, messageCid);
   }
 
   public async read(tenant: string, options: EventLogReadOptions = {}): Promise<EventLogReadResult> {
     const { cursor, limit, filters } = options;
-    const cursorSeq = cursor !== undefined ? EventEmitterEventLog.parseCursor(cursor) : undefined;
+
+    // Validate cursor before attempting to read.
+    if (cursor !== undefined) {
+      await this.validateCursor(tenant, cursor);
+    }
+
+    const cursorSeq = cursor !== undefined ? EventEmitterEventLog.parsePosition(cursor.position) : undefined;
     const log = this.tenantLogs.get(tenant);
 
     if (log === undefined || log.size === 0) {
@@ -159,26 +247,45 @@ export class EventEmitterEventLog implements EventLog {
 
       results.push({
         seq,
-        event   : entry.event,
-        indexes : entry.indexes,
+        event      : entry.event,
+        indexes    : entry.indexes,
+        messageCid : entry.messageCid,
       });
 
       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 };
+    if (results.length > 0) {
+      const lastEntry = results[results.length - 1];
+      // Use the messageCid captured during the synchronous iteration above —
+      // no re-lookup needed, so eviction during the await cannot lose it.
+      const lastToken = await this.buildToken(tenant, lastEntry.seq, lastEntry.messageCid!);
+      return { events: results, cursor: lastToken };
+    }
+
+    return { events: results, cursor };
   }
 
   /**
-   * Parse an opaque cursor string into an internal sequence number.
+   * Parse a position string into an internal sequence number using BigInt
+   * for safe handling of values beyond `Number.MAX_SAFE_INTEGER`.
+   *
+   * The returned `number` is safe for the in-memory EventLog which uses
+   * `Map<number, StoredEntry>` keys — in-memory sequences will never
+   * exceed safe integer range. The BigInt parse validates correctness
+   * before the narrowing conversion.
    */
-  private static parseCursor(cursor: string): number {
-    const seq = Number(cursor);
-    if (Number.isNaN(seq) || seq < 0) {
-      throw new DwnError(DwnErrorCode.EventLogNotOpenError, `invalid cursor: '${cursor}'`);
+  private static parsePosition(position: string): number {
+    try {
+      const big = BigInt(position);
+      if (big < 0n) {
+        throw new DwnError(DwnErrorCode.EventLogNotOpenError, `invalid cursor position: '${position}'`);
+      }
+      return Number(big);
+    } catch (e) {
+      if (e instanceof DwnError) { throw e; }
+      throw new DwnError(DwnErrorCode.EventLogNotOpenError, `invalid cursor position: '${position}'`);
     }
-    return seq;
   }
 
   public async subscribe(
@@ -190,12 +297,20 @@ export class EventEmitterEventLog implements EventLog {
     const channel = `${tenant}_${EVENTS_LISTENER_CHANNEL}`;
     const { cursor, filters } = options ?? {};
 
+    // Helper to build a token from a live emitter payload.
+    const tokenFromPayload = async (payload: EmitterPayload): Promise<ProgressToken> => {
+      return this.buildToken(tenant, payload.seq, payload.messageCid);
+    };
+
     if (cursor !== undefined) {
       // ---- Cursor mode: catch-up from stored events, then EOSE, then live ----
-      const cursorSeq = EventEmitterEventLog.parseCursor(cursor);
+      // Validate cursor before subscribing — throws DwnError(EventLogProgressGap) on gap.
+      await this.validateCursor(tenant, cursor);
+
+      const cursorSeq = EventEmitterEventLog.parsePosition(cursor.position);
 
       // Buffer live events that arrive during catch-up to avoid losing them.
-      type BufferedEvent = { event: MessageEvent; seq: number };
+      type BufferedEvent = { event: MessageEvent; seq: number; messageCid: string };
       const pendingLiveEvents: BufferedEvent[] = [];
       let catchUpComplete = false;
 
@@ -205,9 +320,11 @@ export class EventEmitterEventLog implements EventLog {
           if (!FilterUtility.matchAnyFilter(payload.indexes, filters)) { return; }
         }
         if (!catchUpComplete) {
-          pendingLiveEvents.push({ event: payload.event, seq: payload.seq });
+          pendingLiveEvents.push({ event: payload.event, seq: payload.seq, messageCid: payload.messageCid });
         } else {
-          listener({ type: 'event', cursor: String(payload.seq), event: payload.event });
+          void tokenFromPayload(payload).then((token) => {
+            listener({ type: 'event', cursor: token, event: payload.event });
+          });
         }
       };
 
@@ -215,19 +332,27 @@ export class EventEmitterEventLog implements EventLog {
 
       // 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.
+      // The read cursor is the token of the last read event, or the input cursor if nothing new.
       const eoseCursor = readResult.cursor ?? cursor;
-      const lastCatchUpSeq = readResult.cursor !== undefined ? Number(readResult.cursor) : cursorSeq;
+      const lastCatchUpSeq = readResult.cursor !== undefined
+        ? EventEmitterEventLog.parsePosition(readResult.cursor.position)
+        : cursorSeq;
 
+      // Use the messageCid captured by read() during its synchronous iteration.
+      // This eliminates re-lookup races: read() populates entry.messageCid before
+      // any async yield, so eviction during read()'s buildToken() cannot lose it.
       for (const entry of readResult.events) {
-        listener({ type: 'event', cursor: String(entry.seq), event: entry.event });
+        const token = await this.buildToken(tenant, entry.seq, entry.messageCid ?? '');
+        listener({ type: 'event', cursor: token, event: entry.event });
       }
 
       // Step 3: Deliver any live events that arrived during catch-up (with seq > lastCatchUpSeq).
+      // messageCid was captured at buffer time from the EmitterPayload.
       catchUpComplete = true;
       for (const liveEvent of pendingLiveEvents) {
         if (liveEvent.seq > lastCatchUpSeq) {
-          listener({ type: 'event', cursor: String(liveEvent.seq), event: liveEvent.event });
+          const token = await this.buildToken(tenant, liveEvent.seq, liveEvent.messageCid);
+          listener({ type: 'event', cursor: token, event: liveEvent.event });
         }
       }
 
@@ -246,7 +371,9 @@ export class EventEmitterEventLog implements EventLog {
       if (filters !== undefined && filters.length > 0) {
         if (!FilterUtility.matchAnyFilter(payload.indexes, filters)) { return; }
       }
-      listener({ type: 'event', cursor: String(payload.seq), event: payload.event });
+      void tokenFromPayload(payload).then((token) => {
+        listener({ type: 'event', cursor: token, event: payload.event });
+      });
     };
 
     this.emitter.on(channel, handler);
@@ -257,6 +384,26 @@ export class EventEmitterEventLog implements EventLog {
     };
   }
 
+  public async getReplayBounds(tenant: string): Promise<{ oldest: ProgressToken; latest: ProgressToken } | undefined> {
+    const log = this.tenantLogs.get(tenant);
+    if (log === undefined || log.size === 0) {
+      return undefined;
+    }
+
+    // Map is ordered by insertion (ascending seq). First and last keys are min/max.
+    const keys = [...log.keys()];
+    const oldestSeq = keys[0];
+    const latestSeq = keys[keys.length - 1];
+
+    const oldestEntry = log.get(oldestSeq)!;
+    const latestEntry = log.get(latestSeq)!;
+
+    const oldest = await this.buildToken(tenant, oldestSeq, oldestEntry.messageCid);
+    const latest = await this.buildToken(tenant, latestSeq, latestEntry.messageCid);
+
+    return { oldest, latest };
+  }
+
   public async trim(tenant: string, olderThan: number | string): Promise<void> {
     const log = this.tenantLogs.get(tenant);
     if (log === undefined) { return; }

package/src/handlers/messages-subscribe.ts

@@ -1,7 +1,7 @@
 import type { MessageStore } from '../types/message-store.js';
-import type { SubscriptionListener } from '../types/subscriptions.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { MessagesSubscribeMessage, MessagesSubscribeReply } from '../types/messages-types.js';
+import type { ProgressGapInfo, SubscriptionListener } from '../types/subscriptions.js';
 
 import { authenticate } from '../core/auth.js';
 import { Message } from '../core/message.js';
@@ -61,6 +61,13 @@ export class MessagesSubscribeHandler implements MethodHandler {
         subscription,
       };
     } catch (error) {
+      if (error instanceof DwnError && error.code === DwnErrorCode.EventLogProgressGap) {
+        const gapInfo = (error as any).gapInfo as ProgressGapInfo | undefined;
+        return {
+          status : { code: 410, detail: 'Progress token gap' },
+          error  : gapInfo !== undefined ? { code: 'ProgressGap' as const, ...gapInfo } : undefined,
+        };
+      }
       return messageReplyFromError(error, 500);
     }
   }

package/src/handlers/protocols-configure.ts

@@ -83,7 +83,7 @@ export class ProtocolsConfigureHandler implements MethodHandler {
 
       // only emit if the event log is set
       if (this.deps.eventLog !== undefined) {
-        await this.deps.eventLog.emit(tenant, { message }, indexes);
+        await this.deps.eventLog.emit(tenant, { message }, indexes, messageCid);
       }
 
       messageReply = {

package/src/handlers/records-subscribe.ts

@@ -1,9 +1,9 @@
 import type { CoreProtocolRegistry } from '../core/core-protocol.js';
 import type { MessageSort } from '../types/message-types.js';
 import type { MessageStore } from '../types//message-store.js';
-import type { SubscriptionListener } from '../types/subscriptions.js';
 import type { Filter, PaginationCursor } from '../types/query-types.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
+import type { ProgressGapInfo, SubscriptionListener } from '../types/subscriptions.js';
 import type { RecordsQueryReplyEntry, RecordsSubscribeMessage, RecordsSubscribeReply } from '../types/records-types.js';
 
 import { authenticate } from '../core/auth.js';
@@ -93,6 +93,13 @@ export class RecordsSubscribeHandler implements MethodHandler {
           subscription,
         };
       } catch (error) {
+        if (error instanceof DwnError && error.code === DwnErrorCode.EventLogProgressGap) {
+          const gapInfo = (error as any).gapInfo as ProgressGapInfo | undefined;
+          return {
+            status : { code: 410, detail: 'Progress token gap' },
+            error  : gapInfo !== undefined ? { code: 'ProgressGap' as const, ...gapInfo } : undefined,
+          };
+        }
         return messageReplyFromError(error, 500);
       }
     }

package/src/handlers/records-write.ts

@@ -165,7 +165,8 @@ export class RecordsWriteHandler implements MethodHandler {
 
       const indexes = await recordsWrite.constructIndexes(isLatestBaseState);
       await this.deps.messageStore.put(tenant, messageWithOptionalEncodedData, indexes);
-      await this.deps.stateIndex!.insert(tenant, await Message.getCid(message), indexes);
+      const messageCid = await Message.getCid(message);
+      await this.deps.stateIndex!.insert(tenant, messageCid, indexes);
 
       // NOTE: We only emit a `RecordsWrite` when the message is the latest base state.
       // Because we allow a `RecordsWrite` which is not the latest state to be written, but not queried, we shouldn't emit it either.
@@ -176,7 +177,7 @@ export class RecordsWriteHandler implements MethodHandler {
       // records (<= 30 KB).  This allows live sync to store the record
       // immediately without a separate MessagesRead round-trip.
       if (this.deps.eventLog !== undefined && isLatestBaseState) {
-        await this.deps.eventLog.emit(tenant, { message: messageWithOptionalEncodedData, initialWrite }, indexes);
+        await this.deps.eventLog.emit(tenant, { message: messageWithOptionalEncodedData, initialWrite }, indexes, messageCid);
       }
     } catch (error) {
       if (error instanceof DwnError) {

package/src/index.ts

@@ -1,6 +1,6 @@
 // export everything that we want to be consumable
 export type { DwnConfig } from './dwn.js';
-export type { EventListener, EventLog, EventLogEntry, EventLogReadOptions, EventLogReadResult, EventLogSubscribeOptions, EventSubscription, MessageEvent, SubscriptionEose, SubscriptionEvent, SubscriptionListener, SubscriptionMessage, SubscriptionReply } from './types/subscriptions.js';
+export type { EventListener, EventLog, EventLogEntry, EventLogReadOptions, EventLogReadResult, EventLogSubscribeOptions, EventSubscription, MessageEvent, ProgressGapInfo, ProgressGapReason, ProgressToken, SubscriptionEose, SubscriptionEvent, SubscriptionListener, SubscriptionMessage, SubscriptionReply } from './types/subscriptions.js';
 export type { AuthorizationModel, Descriptor, DelegatedGrantRecordsWriteMessage, GenericMessage, GenericMessageReply, GenericSignaturePayload, MessageSort, MessageSubscription, Pagination, QueryResultEntry, Status } from './types/message-types.js';
 export type { MessagesFilter, MessagesReadMessage as MessagesReadMessage, MessagesReadReply as MessagesReadReply, MessagesReadReplyEntry as MessagesReadReplyEntry, MessagesReadDescriptor, MessagesSubscribeDescriptor, MessagesSubscribeMessage, MessagesSubscribeReply, MessagesSubscribeMessageOptions, MessagesSyncAction, MessagesSyncDescriptor, MessagesSyncDiffEntry, MessagesSyncMessage, MessagesSyncReply } from './types/messages-types.js';
 export type { GT, LT, Filter, FilterValue, KeyValues, EqualFilter, OneOfFilter, RangeFilter, RangeCriterion, PaginationCursor, QueryOptions, RangeValue, StartsWithFilter } from './types/query-types.js';

package/src/interfaces/messages-subscribe.ts

@@ -1,5 +1,6 @@
 import type { MessagesFilter } from '../types/messages-types.js';
 import type { MessageSigner } from '../types/signer.js';
+import type { ProgressToken } from '../types/subscriptions.js';
 import type { MessagesSubscribeDescriptor, MessagesSubscribeMessage } from '../types/messages-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
@@ -16,10 +17,10 @@ export type MessagesSubscribeOptions = {
   filters?: MessagesFilter[];
   permissionGrantId?: string;
   /**
-   * Opaque EventLog cursor string to resume from. When provided, catch-up events are
-   * replayed from the EventLog and an EOSE marker is delivered before live events.
+   * Progress token to resume from. When provided, catch-up events are replayed
+   * from the EventLog and an EOSE marker is delivered before live events.
    */
-  cursor?: string;
+  cursor?: ProgressToken;
 };
 
 export class MessagesSubscribe extends AbstractMessage<MessagesSubscribeMessage> {

package/src/interfaces/records-subscribe.ts

@@ -1,6 +1,7 @@
 import type { MessageSigner } from '../types/signer.js';
 import type { MessageStore } from '../types/message-store.js';
 import type { Pagination } from '../types/message-types.js';
+import type { ProgressToken } from '../types/subscriptions.js';
 import type { DataEncodedRecordsWriteMessage, DateSort, RecordsFilter, RecordsSubscribeDescriptor, RecordsSubscribeMessage } from '../types/records-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
@@ -23,10 +24,10 @@ export type RecordsSubscribeOptions = {
   protocolRole?: string;
 
   /**
-   * Opaque EventLog cursor string to resume from. When provided, catch-up events are
-   * replayed from the EventLog and an EOSE marker is delivered before live events.
+   * Progress token to resume from. When provided, catch-up events are replayed
+   * from the EventLog and an EOSE marker is delivered before live events.
    */
-  cursor?: string;
+  cursor?: ProgressToken;
 
   /**
    * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.

package/src/store/storage-controller.ts

@@ -75,7 +75,7 @@ export class StorageController {
 
     // only emit if the event log is set
     if (this.eventLog !== undefined) {
-      await this.eventLog.emit(tenant, { message, initialWrite }, indexes);
+      await this.eventLog.emit(tenant, { message, initialWrite }, indexes, messageCid);
     }
 
     if (message.descriptor.prune) {

package/src/types/messages-types.ts

@@ -1,7 +1,7 @@
 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';
+import type { ProgressGapInfo, ProgressToken, SubscriptionListener } from './subscriptions.js';
 
 /**
  * filters used when filtering for any type of Message across interfaces
@@ -10,6 +10,12 @@ export type MessagesFilter = {
   interface?: string;
   method?: string;
   protocol?: string;
+  /** Prefix filter for protocolPath. Matches records whose protocolPath equals
+   *  the prefix or starts with the prefix followed by '/'. */
+  protocolPathPrefix?: string;
+  /** Prefix filter for contextId. Matches records whose contextId equals
+   *  the prefix or starts with the prefix followed by '/'. */
+  contextIdPrefix?: string;
   messageTimestamp?: RangeCriterion;
 };
 
@@ -100,6 +106,8 @@ export type MessagesSubscribeMessage = {
 
 export type MessagesSubscribeReply = GenericMessageReply & {
   subscription?: MessageSubscription;
+  /** Present when status.code is 410 — structured gap metadata. */
+  error?: { code: 'ProgressGap' } & ProgressGapInfo;
 };
 
 export type MessagesSubscribeDescriptor = {
@@ -109,9 +117,9 @@ export type MessagesSubscribeDescriptor = {
   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
+   * Progress token to resume from. When provided, the handler replays events
+   * from the EventLog starting after this position instead of returning no
    * initial snapshot. An EOSE marker is sent after catch-up.
    */
-  cursor?: string;
+  cursor?: ProgressToken;
 };

package/src/types/records-types.ts

@@ -1,9 +1,9 @@
 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';
+import type { ProgressGapInfo, ProgressToken, SubscriptionListener } from './subscriptions.js';
 
 export enum DateSort {
   CreatedAscending = 'createdAscending',
@@ -132,11 +132,11 @@ export type RecordsSubscribeDescriptor = {
   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
+   * Progress token to resume from. When provided, the handler replays events
+   * from the EventLog starting after this position instead of querying the
    * MessageStore for an initial snapshot. An EOSE marker is sent after catch-up.
    */
-  cursor?: string;
+  cursor?: ProgressToken;
 };
 
 export type RecordsFilter = {
@@ -203,6 +203,8 @@ export type RecordsSubscribeReply = GenericMessageReply & {
   subscription?: MessageSubscription;
   entries?: RecordsQueryReplyEntry[];
   cursor?: PaginationCursor;
+  /** Present when status.code is 410 — structured gap metadata. */
+  error?: { code: 'ProgressGap' } & ProgressGapInfo;
 };
 
 export type RecordsReadMessage = {