@enbox/dwn-sdk-js 0.0.6 → 0.0.8

package/src/store/index-level.ts

@@ -4,6 +4,13 @@ import type { LevelWrapperBatchOperation, LevelWrapperIteratorOptions, } from '.
 import { isEmptyObject } from '../utils/object.js';
 import { lexicographicalCompare } from '../utils/string.js';
 import { SortDirection } from '../types/query-types.js';
+import {
+  countWithCompoundIndex,
+  createCompoundIndexDeleteOperation,
+  createCompoundIndexPutOperation,
+  queryWithCompoundIndex,
+  selectCompoundIndex,
+} from './index-level-compound.js';
 import { createLevelDatabase, LevelWrapper } from './level-wrapper.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { FilterSelector, FilterUtility } from '../utils/filter.js';
@@ -36,9 +43,6 @@ export type CompoundIndexDefinition = {
 
 const INDEX_SUBLEVEL_NAME = 'index';
 
-/** Separator between compound key segments (higher than \x00 so prefix scans work correctly). */
-const COMPOUND_SEGMENT_SEPARATOR = '\x01';
-
 export interface IndexLevelOptions {
   signal?: AbortSignal;
 }
@@ -121,7 +125,9 @@ export class IndexLevel {
 
     // create compound index entries for any registered compound indexes whose properties are all present in the indexes.
     for (const compoundIndex of this._compoundIndexes) {
-      const compoundOp = this.createCompoundIndexPutOperation(tenant, item, compoundIndex);
+      const compoundOp = createCompoundIndexPutOperation(
+        this.db, tenant, item, compoundIndex, IndexLevel.encodeValue, IndexLevel.delimiter
+      );
       if (compoundOp !== undefined) {
         opCreationPromises.push(compoundOp);
       }
@@ -171,7 +177,9 @@ export class IndexLevel {
 
     // delete compound index entries
     for (const compoundIndex of this._compoundIndexes) {
-      const compoundOp = this.createCompoundIndexDeleteOperation(tenant, messageCid, indexes, compoundIndex);
+      const compoundOp = createCompoundIndexDeleteOperation(
+        this.db, tenant, messageCid, indexes, compoundIndex, IndexLevel.encodeValue, IndexLevel.delimiter
+      );
       if (compoundOp !== undefined) {
         opCreationPromises.push(compoundOp);
       }
@@ -289,9 +297,13 @@ export class IndexLevel {
 
     // Strategy 1: try compound index for single-filter queries
     if (filters.length === 1 && !isEmptyObject(filters[0])) {
-      const compoundResult = this.selectCompoundIndex(filters[0], queryOptions);
+      const compoundResult = selectCompoundIndex(filters[0], queryOptions, this._compoundIndexes);
       if (compoundResult !== undefined) {
-        return this.queryWithCompoundIndex(tenant, filters[0], queryOptions, compoundResult, options);
+        return queryWithCompoundIndex(
+          this.db, tenant, filters[0], queryOptions, compoundResult,
+          IndexLevel.encodeValue, IndexLevel.delimiter,
+          this.queryWithIteratorPaging.bind(this), options
+        );
       }
     }
 
@@ -315,9 +327,12 @@ export class IndexLevel {
 
     // try compound index for single-filter queries
     if (filters.length === 1 && !isEmptyObject(filters[0])) {
-      const compoundResult = this.selectCompoundIndex(filters[0], { ...queryOptions });
+      const compoundResult = selectCompoundIndex(filters[0], { ...queryOptions }, this._compoundIndexes);
       if (compoundResult !== undefined) {
-        return this.countWithCompoundIndex(tenant, filters[0], compoundResult, options);
+        return countWithCompoundIndex(
+          this.db, tenant, filters[0], compoundResult,
+          IndexLevel.encodeValue, this.query.bind(this), options
+        );
       }
     }
 
@@ -462,9 +477,18 @@ export class IndexLevel {
     }
 
     try {
-      await Promise.all(filters.map(filter => {
-        return this.executeSingleFilterQuery(tenant, filter, sortProperty, matches, options );
-      }));
+      // Execute filters sequentially rather than with Promise.all.
+      // Firefox's IndexedDB implementation has two related async issues that cause flaky failures:
+      //   1. Concurrent cursors/transactions can silently miss recently-committed data
+      //   2. A read transaction opened immediately after a write transaction's oncomplete event
+      //      can fail to see the written data (write-read race)
+      // Serializing eliminates both races. Performance impact is negligible: only 3 call sites
+      // (non-owner RecordsQuery/Subscribe/Count) ever pass multiple filters, and each filter
+      // reduces to a single bounded LevelDB range scan completing in single-digit ms.
+      // See: https://github.com/enboxorg/enbox/issues/264
+      for (const filter of filters) {
+        await this.executeSingleFilterQuery(tenant, filter, sortProperty, matches, options);
+      }
     } catch (error) {
       if ((error as DwnError).code === DwnErrorCode.IndexInvalidSortPropertyInMemory) {
         // return empty results if the sort property is invalid.
@@ -486,6 +510,10 @@ export class IndexLevel {
 
   /**
    * Execute a filtered query against a single filter and return all results.
+   *
+   * Sub-queries (exact match, range, OneOf) are executed sequentially to avoid opening
+   * multiple concurrent IndexedDB cursors. Firefox's IDB implementation intermittently
+   * drops results when cursors overlap — see https://github.com/enboxorg/enbox/issues/264
    */
   private async executeSingleFilterQuery(
     tenant: string,
@@ -495,13 +523,30 @@ export class IndexLevel {
     levelOptions?: IndexLevelOptions
   ): Promise<void> {
 
-    // Note: We have an array of Promises in order to support OR (anyOf) matches when given a list of accepted values for a property
-    const filterPromises: Promise<IndexedItem[]>[] = [];
+    // Collects results from each sub-query sequentially to avoid concurrent IndexedDB cursor races in Firefox.
+    const processResults = (indexItems: IndexedItem[]): void => {
+      for (const indexedItem of indexItems) {
+        // short circuit: if a data is already included to the final matched key set (by a different `Filter`),
+        // no need to evaluate if the data satisfies this current filter being evaluated
+        // otherwise check that the item is a match.
+        if (matches.has(indexedItem.messageCid) || !FilterUtility.matchFilter(indexedItem.indexes, filter)) {
+          continue;
+        }
+
+        // ensure that each matched item has the sortProperty, otherwise fail the entire query.
+        if (indexedItem.indexes[sortProperty] === undefined) {
+          throw new DwnError(DwnErrorCode.IndexInvalidSortPropertyInMemory, `invalid sort property ${sortProperty}`);
+        }
+
+        matches.set(indexedItem.messageCid, indexedItem);
+      }
+    };
 
     // If the filter is empty, then we just iterate over one of the indexes that contains all the records and return all items.
     if (isEmptyObject(filter)) {
-      const getAllItemsPromise = this.getAllItems(tenant, sortProperty);
-      filterPromises.push(getAllItemsPromise);
+      const allItems = await this.getAllItems(tenant, sortProperty);
+      processResults(allItems);
+      return;
     }
 
     // else the filter is not empty
@@ -511,40 +556,19 @@ export class IndexLevel {
       // We will find the union of these many individual queries later.
       if (FilterUtility.isEqualFilter(propertyFilter)) {
         // propertyFilter is an EqualFilter, meaning it is a non-object primitive type
-        const exactMatchesPromise = this.filterExactMatches(tenant, propertyName, propertyFilter, levelOptions);
-        filterPromises.push(exactMatchesPromise);
+        const exactMatches = await this.filterExactMatches(tenant, propertyName, propertyFilter, levelOptions);
+        processResults(exactMatches);
       } else if (FilterUtility.isOneOfFilter(propertyFilter)) {
         // `propertyFilter` is a OneOfFilter
-        // Support OR matches by querying for each values separately, then adding them to the promises array.
+        // Support OR matches by querying for each value separately and sequentially.
         for (const propertyValue of new Set(propertyFilter)) {
-          const exactMatchesPromise = this.filterExactMatches(tenant, propertyName, propertyValue, levelOptions);
-          filterPromises.push(exactMatchesPromise);
+          const exactMatches = await this.filterExactMatches(tenant, propertyName, propertyValue, levelOptions);
+          processResults(exactMatches);
         }
       } else if (FilterUtility.isRangeFilter(propertyFilter)) {
         // `propertyFilter` is a `RangeFilter`
-        const rangeMatchesPromise = this.filterRangeMatches(tenant, propertyName, propertyFilter, levelOptions);
-        filterPromises.push(rangeMatchesPromise);
-      }
-    }
-
-    // acting as an OR match for the property, any of the promises returning a match will be treated as a property match
-    for (const promise of filterPromises) {
-      const indexItems = await promise;
-      // reminder: the promise returns a list of IndexedItem satisfying a particular property match
-      for (const indexedItem of indexItems) {
-        // short circuit: if a data is already included to the final matched key set (by a different `Filter`),
-        // no need to evaluate if the data satisfies this current filter being evaluated
-        // otherwise check that the item is a match.
-        if (matches.has(indexedItem.messageCid) || !FilterUtility.matchFilter(indexedItem.indexes, filter)) {
-          continue;
-        }
-
-        // ensure that each matched item has the sortProperty, otherwise fail the entire query.
-        if (indexedItem.indexes[sortProperty] === undefined) {
-          throw new DwnError(DwnErrorCode.IndexInvalidSortPropertyInMemory, `invalid sort property ${sortProperty}`);
-        }
-
-        matches.set(indexedItem.messageCid, indexedItem);
+        const rangeMatches = await this.filterRangeMatches(tenant, propertyName, propertyFilter, levelOptions);
+        processResults(rangeMatches);
       }
     }
   }
@@ -749,303 +773,6 @@ export class IndexLevel {
     }
   }
 
-  // =========================================================================
-  // Compound index methods
-  // =========================================================================
-
-  /**
-   * Gets the compound index partition for a given compound index definition.
-   * Compound index sublevels use the naming convention `__compound:<name>__`.
-   */
-  private async getCompoundIndexPartition(tenant: string, compoundIndex: CompoundIndexDefinition): Promise<LevelWrapper<string>> {
-    const partitionName = `__compound:${compoundIndex.name}__`;
-    return (await this.db.partition(tenant)).partition(partitionName);
-  }
-
-  /**
-   * Builds a compound index key from the given indexes and compound index definition.
-   *
-   * Key format: `<prop1>\x01<prop2>\x01...\x01<sortValue>\x00<messageCid>`
-   *
-   * @returns the compound key, or undefined if the indexes don't contain all required properties.
-   */
-  private static buildCompoundKey(messageCid: string, indexes: KeyValues, compoundIndex: CompoundIndexDefinition): string | undefined {
-    const segments: string[] = [];
-
-    for (const property of compoundIndex.properties) {
-      const value = indexes[property];
-      if (value === undefined || Array.isArray(value)) {
-        return undefined; // compound indexes don't support array values or missing properties
-      }
-      segments.push(IndexLevel.encodeValue(value));
-    }
-
-    const sortValue = indexes[compoundIndex.sortProperty];
-    if (sortValue === undefined || Array.isArray(sortValue)) {
-      return undefined;
-    }
-
-    // join prefix segments with \x01, then append sort value and messageCid with the standard delimiters
-    const prefixPart = segments.join(COMPOUND_SEGMENT_SEPARATOR);
-    const sortPart = IndexLevel.encodeValue(sortValue);
-    return prefixPart + COMPOUND_SEGMENT_SEPARATOR + sortPart + IndexLevel.delimiter + messageCid;
-  }
-
-  /**
-   * Builds the prefix portion of a compound key from filter values (without the sort/messageCid suffix).
-   * Used for range scans: all entries with this prefix match the filter.
-   */
-  private static buildCompoundPrefix(filter: Filter, compoundIndex: CompoundIndexDefinition): string | undefined {
-    const segments: string[] = [];
-
-    for (const property of compoundIndex.properties) {
-      const filterValue = filter[property];
-      if (filterValue === undefined || typeof filterValue === 'object') {
-        return undefined; // compound prefix only works with equality filters
-      }
-      segments.push(IndexLevel.encodeValue(filterValue));
-    }
-
-    return segments.join(COMPOUND_SEGMENT_SEPARATOR) + COMPOUND_SEGMENT_SEPARATOR;
-  }
-
-  /**
-   * Creates a put operation for a compound index entry.
-   * Returns undefined if the indexes don't contain all required compound index properties.
-   */
-  private createCompoundIndexPutOperation(
-    tenant: string,
-    item: IndexedItem,
-    compoundIndex: CompoundIndexDefinition
-  ): Promise<LevelWrapperBatchOperation<string>> | undefined {
-    const key = IndexLevel.buildCompoundKey(item.messageCid, item.indexes, compoundIndex);
-    if (key === undefined) {
-      return undefined;
-    }
-
-    return this.createOperationForPartition(tenant, `__compound:${compoundIndex.name}__`, {
-      type  : 'put',
-      key,
-      value : JSON.stringify(item),
-    });
-  }
-
-  /**
-   * Creates a delete operation for a compound index entry.
-   * Returns undefined if the indexes don't contain all required compound index properties.
-   */
-  private createCompoundIndexDeleteOperation(
-    tenant: string,
-    messageCid: string,
-    indexes: KeyValues,
-    compoundIndex: CompoundIndexDefinition
-  ): Promise<LevelWrapperBatchOperation<string>> | undefined {
-    const key = IndexLevel.buildCompoundKey(messageCid, indexes, compoundIndex);
-    if (key === undefined) {
-      return undefined;
-    }
-
-    return this.createOperationForPartition(tenant, `__compound:${compoundIndex.name}__`, {
-      type: 'del',
-      key,
-    });
-  }
-
-  /**
-   * Generic helper to create a batch operation for any named partition under a tenant.
-   */
-  private async createOperationForPartition(
-    tenant: string,
-    partitionName: string,
-    operation: LevelWrapperBatchOperation<string>
-  ): Promise<LevelWrapperBatchOperation<string>> {
-    const tenantPartition = await this.db.partition(tenant);
-    return tenantPartition.createPartitionOperation(partitionName, operation);
-  }
-
-  /**
-   * Selects the best compound index that covers the given filter and sort requirements.
-   *
-   * A compound index "covers" a query when:
-   * 1. Every property in the compound index definition is present in the filter as an equality filter.
-   * 2. The compound index's sort property matches the query's sort property.
-   *
-   * Among multiple matching compound indexes, the one with the most properties is preferred
-   * (more specific = fewer false positives in the prefix scan).
-   */
-  private selectCompoundIndex(filter: Filter, queryOptions: QueryOptions): CompoundIndexDefinition | undefined {
-    let bestMatch: CompoundIndexDefinition | undefined;
-    let bestPropertyCount = 0;
-
-    for (const compoundIndex of this._compoundIndexes) {
-      // check that the sort property matches
-      if (compoundIndex.sortProperty !== queryOptions.sortProperty) {
-        continue;
-      }
-
-      // check that all compound properties are present in the filter as equality filters
-      let allPropertiesMatch = true;
-      for (const property of compoundIndex.properties) {
-        const filterValue = filter[property];
-        if (filterValue === undefined || typeof filterValue === 'object') {
-          allPropertiesMatch = false;
-          break;
-        }
-      }
-
-      if (allPropertiesMatch && compoundIndex.properties.length > bestPropertyCount) {
-        bestMatch = compoundIndex;
-        bestPropertyCount = compoundIndex.properties.length;
-      }
-    }
-
-    return bestMatch;
-  }
-
-  /**
-   * Queries using a compound index. This is the most efficient query strategy: a single LevelDB
-   * range scan that filters, sorts, and paginates all at once.
-   *
-   * The compound key encodes the filter properties as a prefix and the sort property as a suffix,
-   * so iterating over keys with the filter prefix yields results in sort order.
-   *
-   * Any remaining filter properties not covered by the compound index are verified in memory.
-   */
-  private async queryWithCompoundIndex(
-    tenant: string,
-    filter: Filter,
-    queryOptions: QueryOptions,
-    compoundIndex: CompoundIndexDefinition,
-    options?: IndexLevelOptions
-  ): Promise<IndexedItem[]> {
-    const { sortDirection = SortDirection.Ascending, cursor, limit } = queryOptions;
-
-    const prefix = IndexLevel.buildCompoundPrefix(filter, compoundIndex);
-    if (prefix === undefined) {
-      // should not happen since selectCompoundIndex already validated, but guard against it
-      return this.queryWithIteratorPaging(tenant, [filter], queryOptions, options);
-    }
-
-    const partition = await this.getCompoundIndexPartition(tenant, compoundIndex);
-
-    // determine the iterator bounds from the prefix
-    const iteratorOptions: LevelWrapperIteratorOptions<string> = {};
-
-    if (cursor !== undefined) {
-      // build the full compound key for the cursor position
-      const cursorSortEncoded = IndexLevel.encodeValue(cursor.value);
-      const cursorKey = prefix + cursorSortEncoded + IndexLevel.delimiter + cursor.messageCid;
-
-      if (sortDirection === SortDirection.Ascending) {
-        iteratorOptions.gt = cursorKey;
-        // upper bound: everything with this prefix (prefix + \xff is past all valid compound keys with this prefix)
-        iteratorOptions.lt = prefix + '\xff';
-      } else {
-        iteratorOptions.lt = cursorKey;
-        iteratorOptions.gt = prefix;
-        iteratorOptions.reverse = true;
-      }
-    } else {
-      if (sortDirection === SortDirection.Ascending) {
-        iteratorOptions.gt = prefix;
-        iteratorOptions.lt = prefix + '\xff';
-      } else {
-        // for descending without cursor, start from the end of the prefix range
-        iteratorOptions.gt = prefix;
-        iteratorOptions.lt = prefix + '\xff';
-        iteratorOptions.reverse = true;
-      }
-    }
-
-    // determine which filter properties are NOT covered by the compound index
-    // (need in-memory verification for these)
-    // NOTE: the compound index equality properties are fully covered by the prefix scan,
-    // but the sort property is only covered for ordering — any range filter on the sort
-    // property must still be applied as a residual filter.
-    const coveredEqualityProperties = new Set(compoundIndex.properties);
-    const residualFilter: Filter = {};
-    let hasResidualFilter = false;
-    for (const property in filter) {
-      if (!coveredEqualityProperties.has(property)) {
-        residualFilter[property] = filter[property];
-        hasResidualFilter = true;
-      }
-    }
-
-    const matches: IndexedItem[] = [];
-    for await (const [_key, value] of partition.iterator(iteratorOptions, options)) {
-      if (limit !== undefined && matches.length === limit) {
-        break;
-      }
-
-      const item = JSON.parse(value) as IndexedItem;
-
-      // verify any residual filter properties in memory
-      if (hasResidualFilter && !FilterUtility.matchFilter(item.indexes, residualFilter)) {
-        continue;
-      }
-
-      matches.push(item);
-    }
-
-    return matches;
-  }
-
-  /**
-   * Counts items matching a compound index prefix without loading full records.
-   * Iterates only keys (not values) for maximum efficiency.
-   */
-  private async countWithCompoundIndex(
-    tenant: string,
-    filter: Filter,
-    compoundIndex: CompoundIndexDefinition,
-    options?: IndexLevelOptions
-  ): Promise<number> {
-    const prefix = IndexLevel.buildCompoundPrefix(filter, compoundIndex);
-    if (prefix === undefined) {
-      // fallback
-      const results = await this.query(tenant, [filter], { sortProperty: compoundIndex.sortProperty }, options);
-      return results.length;
-    }
-
-    const partition = await this.getCompoundIndexPartition(tenant, compoundIndex);
-
-    // determine which filter properties are NOT covered by the compound index
-    // (same logic as queryWithCompoundIndex: sort property range filters are residual)
-    const coveredEqualityProperties = new Set(compoundIndex.properties);
-    let hasResidualFilter = false;
-    const residualFilter: Filter = {};
-    for (const property in filter) {
-      if (!coveredEqualityProperties.has(property)) {
-        residualFilter[property] = filter[property];
-        hasResidualFilter = true;
-      }
-    }
-
-    const iteratorOptions: LevelWrapperIteratorOptions<string> = {
-      gt : prefix,
-      lt : prefix + '\xff',
-    };
-
-    let count = 0;
-    if (hasResidualFilter) {
-      // must read values to check residual filter
-      for await (const [_key, value] of partition.iterator(iteratorOptions, options)) {
-        const item = JSON.parse(value) as IndexedItem;
-        if (FilterUtility.matchFilter(item.indexes, residualFilter)) {
-          count++;
-        }
-      }
-    } else {
-      // no residual filter — iterate keys via iterator without parsing values
-      for await (const [_key, _value] of partition.iterator(iteratorOptions, options)) {
-        count++;
-      }
-    }
-
-    return count;
-  }
-
   // =========================================================================
   // Query strategy selection
   // =========================================================================

package/src/store/storage-controller.ts

@@ -1,5 +1,5 @@
 import type { DataStore } from '../types/data-store.js';
-import type { EventStream } from '../types/subscriptions.js';
+import type { EventLog } from '../types/subscriptions.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';
@@ -26,18 +26,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 +66,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) {

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;