@enbox/dwn-sdk-js 0.4.15 → 0.4.17

package/src/interfaces/protocols-configure.ts

@@ -9,6 +9,7 @@ import type {
 
 import { AbstractMessage } from '../core/abstract-message.js';
 import { DwnConstant } from '../core/dwn-constant.js';
+import { FilterUtility } from '../utils/filter.js';
 import { Message } from '../core/message.js';
 import { PermissionGrant } from '../protocols/permission-grant.js';
 import { ProtocolsGrantAuthorization } from '../core/protocols-grant-authorization.js';
@@ -18,7 +19,7 @@ import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import { getRoleAudienceContextId, getRuleSetAtPath, isCrossProtocolRef, parseCrossProtocolRef } from '../utils/protocols.js';
 import { normalizeProtocolUrl, normalizeSchemaUrl, validateProtocolUrlNormalized, validateSchemaUrlNormalized } from '../utils/url.js';
-import { ProtocolAction, ProtocolActor, ProtocolRecordLimitStrategy } from '../types/protocols-types.js';
+import { ProtocolAction, ProtocolActor } from '../types/protocols-types.js';
 
 export type ProtocolsConfigureOptions = {
   messageTimestamp?: string;
@@ -300,7 +301,7 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
 
     // Validate $recordLimit
     if (ruleSet.$recordLimit !== undefined) {
-      const { max, strategy } = ruleSet.$recordLimit;
+      const { max } = ruleSet.$recordLimit;
 
       if (!Number.isInteger(max) || max < 1) {
         throw new DwnError(
@@ -315,15 +316,6 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
           `Invalid $recordLimit.max value ${max} at protocol path '${ruleSetProtocolPath}': must be <= ${DwnConstant.maxRecordLimit}.`
         );
       }
-
-      const validStrategies = Object.values(ProtocolRecordLimitStrategy) as string[];
-      if (!validStrategies.includes(strategy as string)) {
-        throw new DwnError(
-          DwnErrorCode.ProtocolsConfigureInvalidRecordLimit,
-          `Invalid $recordLimit.strategy '${strategy}' at protocol path '${ruleSetProtocolPath}': ` +
-          `must be one of ${validStrategies.join(', ')}.`
-        );
-      }
     }
 
     if (ruleSet.$tags !== undefined) {
@@ -412,8 +404,7 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
           ProtocolsConfigure.validateCrossProtocolAlias(actionRule.of, uses, ruleSetProtocolPath, 'of');
         } else {
           // Local `of`: must be self or ancestor
-          const isSelfOrAncestor = ruleSetProtocolPath === actionRule.of
-            || ruleSetProtocolPath.startsWith(actionRule.of + '/');
+          const isSelfOrAncestor = FilterUtility.matchesSubtree(actionRule.of, ruleSetProtocolPath);
           if (!isSelfOrAncestor) {
             throw new DwnError(
               DwnErrorCode.ProtocolsConfigureInvalidActionOfNotAnAncestor,

package/src/store/index-level.ts

@@ -4,6 +4,7 @@ import type { LevelWrapperBatchOperation, LevelWrapperIteratorOptions, } from '.
 import { isEmptyObject } from '@enbox/common';
 import { lexicographicalCompare } from '../utils/string.js';
 import { SortDirection } from '../types/query-types.js';
+import { assertValidSubtreeFilters, FilterSelector, FilterUtility, isSubtreeFilter } from '../utils/filter.js';
 import {
   countWithCompoundIndex,
   createCompoundIndexDeleteOperation,
@@ -13,7 +14,6 @@ import {
 } 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';
 
 export type IndexLevelConfig = {
   location: string,
@@ -318,17 +318,12 @@ export class IndexLevel {
    * @returns {IndexedItem[]} an array of `IndexedItem` that match the given filters.
    */
   async query(tenant: string, filters: Filter[], queryOptions: QueryOptions, options?: IndexLevelOptions): Promise<IndexedItem[]> {
+    assertValidSubtreeFilters(filters);
 
     // Strategy 1: try compound index for single-filter queries
-    if (filters.length === 1 && !isEmptyObject(filters[0])) {
-      const compoundResult = selectCompoundIndex(filters[0], queryOptions, this._compoundIndexes);
-      if (compoundResult !== undefined) {
-        return queryWithCompoundIndex(
-          this.db, tenant, filters[0], queryOptions, compoundResult,
-          IndexLevel.encodeValue, IndexLevel.delimiter,
-          this.queryWithIteratorPaging.bind(this), options
-        );
-      }
+    const compoundQuery = this.queryUsingCompoundIndex(tenant, filters, queryOptions, options);
+    if (compoundQuery !== undefined) {
+      return compoundQuery;
     }
 
     // Strategy 2: in-memory paging for concise filters
@@ -340,6 +335,47 @@ export class IndexLevel {
     return this.queryWithIteratorPaging(tenant, filters, queryOptions, options);
   }
 
+  /**
+   * Queries one bounded page without selecting the in-memory strategy.
+   *
+   * Projection callers use this when they must close the outer iterator before
+   * opening related index ranges. A matching compound index is preferred;
+   * otherwise the requested-sort index is streamed directly.
+   */
+  async queryWithBoundedPaging(
+    tenant: string,
+    filters: Filter[],
+    queryOptions: QueryOptions,
+    options?: IndexLevelOptions,
+  ): Promise<IndexedItem[]> {
+    assertValidSubtreeFilters(filters);
+
+    const compoundQuery = this.queryUsingCompoundIndex(tenant, filters, queryOptions, options);
+    return compoundQuery ?? this.queryWithIteratorPaging(tenant, filters, queryOptions, options);
+  }
+
+  private queryUsingCompoundIndex(
+    tenant: string,
+    filters: Filter[],
+    queryOptions: QueryOptions,
+    options?: IndexLevelOptions,
+  ): Promise<IndexedItem[]> | undefined {
+    if (filters.length !== 1 || isEmptyObject(filters[0])) {
+      return undefined;
+    }
+
+    const compoundIndex = selectCompoundIndex(filters[0], queryOptions, this._compoundIndexes);
+    if (compoundIndex === undefined) {
+      return undefined;
+    }
+
+    return queryWithCompoundIndex(
+      this.db, tenant, filters[0], queryOptions, compoundIndex,
+      IndexLevel.encodeValue, IndexLevel.delimiter,
+      this.queryWithIteratorPaging.bind(this), options
+    );
+  }
+
   /**
    * Counts the number of items that match the given filters without loading full records.
    *
@@ -348,6 +384,7 @@ export class IndexLevel {
    */
   async count(tenant: string, filters: Filter[], queryOptions: Omit<QueryOptions, 'limit' | 'cursor'>,
     options?: IndexLevelOptions): Promise<number> {
+    assertValidSubtreeFilters(filters);
 
     // try compound index for single-filter queries
     if (filters.length === 1 && !isEmptyObject(filters[0])) {
@@ -365,6 +402,117 @@ export class IndexLevel {
     return results.length;
   }
 
+  /**
+   * Finds the inclusive rank boundary for one `$recordLimit` parent group.
+   *
+   * The existing `parentId` index keeps the scan isolated to one nested-record
+   * group. Root records have no `parentId`, so they are read from the exact
+   * `protocolPath` range and explicitly fenced to rows without a parent. The
+   * bounded max-heap retains only the earliest `max` rank keys while the range
+   * is streamed; no group-sized array is materialized.
+   */
+  public async findRecordLimitRankCutoff(
+    tenant: string,
+    candidateFilter: Filter,
+    parentId: string | undefined,
+    max: number,
+    options?: IndexLevelOptions,
+  ): Promise<string | undefined> {
+    if (!Number.isInteger(max) || max < 1) {
+      throw new TypeError(`IndexLevel: record-limit max must be a positive integer.`);
+    }
+
+    const protocolPath = candidateFilter.protocolPath;
+    if (typeof protocolPath !== 'string') {
+      throw new TypeError(`IndexLevel: record-limit candidate filter must contain one protocolPath.`);
+    }
+
+    const indexName = parentId === undefined ? 'protocolPath' : 'parentId';
+    const indexValue = parentId ?? protocolPath;
+    const matchPrefix = IndexLevel.keySegmentJoin(IndexLevel.encodeValue(indexValue), '');
+    const partition = await this.getIndexPartition(tenant, indexName);
+    const rankHeap: string[] = [];
+
+    for await (const [key, value] of partition.iterator({ gt: matchPrefix }, options)) {
+      if (!key.startsWith(matchPrefix)) {
+        break;
+      }
+
+      const item = JSON.parse(value) as IndexedItem;
+      if ((parentId === undefined && item.indexes.parentId !== undefined) ||
+          !FilterUtility.matchFilter(item.indexes, candidateFilter)) {
+        continue;
+      }
+
+      IndexLevel.addToBoundedMaxHeap(rankHeap, IndexLevel.createRecordLimitRankKey(item.indexes), max);
+    }
+
+    return rankHeap[0];
+  }
+
+  /**
+   * Builds the deterministic `$recordLimit` rank key: oldest creation time,
+   * then record ID. Message CID deliberately does not participate because
+   * occupancy belongs to the logical record, not a particular update.
+   */
+  public static createRecordLimitRankKey(indexes: KeyValues): string {
+    const { dateCreated, recordId } = indexes;
+    if (typeof dateCreated !== 'string' || typeof recordId !== 'string') {
+      throw new TypeError(`IndexLevel: record-limit candidates require string dateCreated and recordId indexes.`);
+    }
+
+    return IndexLevel.keySegmentJoin(IndexLevel.encodeValue(dateCreated), IndexLevel.encodeValue(recordId));
+  }
+
+  private static addToBoundedMaxHeap(heap: string[], value: string, max: number): void {
+    if (heap.length < max) {
+      heap.push(value);
+      IndexLevel.siftRecordLimitRankUp(heap, heap.length - 1);
+      return;
+    }
+
+    if (lexicographicalCompare(value, heap[0]) >= 0) {
+      return;
+    }
+
+    heap[0] = value;
+    IndexLevel.siftRecordLimitRankDown(heap, 0);
+  }
+
+  private static siftRecordLimitRankUp(heap: string[], startIndex: number): void {
+    let index = startIndex;
+    while (index > 0) {
+      const parentIndex = (index - 1) >>> 1;
+      if (lexicographicalCompare(heap[parentIndex], heap[index]) >= 0) {
+        return;
+      }
+
+      [heap[parentIndex], heap[index]] = [heap[index], heap[parentIndex]];
+      index = parentIndex;
+    }
+  }
+
+  private static siftRecordLimitRankDown(heap: string[], startIndex: number): void {
+    let index = startIndex;
+    while (true) {
+      const leftIndex = index * 2 + 1;
+      if (leftIndex >= heap.length) {
+        return;
+      }
+
+      const rightIndex = leftIndex + 1;
+      const largerChildIndex = rightIndex < heap.length && lexicographicalCompare(heap[rightIndex], heap[leftIndex]) > 0
+        ? rightIndex
+        : leftIndex;
+      if (lexicographicalCompare(heap[index], heap[largerChildIndex]) >= 0) {
+        return;
+      }
+
+      [heap[index], heap[largerChildIndex]] = [heap[largerChildIndex], heap[index]];
+      index = largerChildIndex;
+    }
+  }
+
   /**
    * Queries the sort property index for items that match the filters. If no filters are provided, all items are returned.
    * This query is a linear iterator over the sorted index, checking each item for a match.
@@ -589,6 +737,17 @@ export class IndexLevel {
           const exactMatches = await this.filterExactMatches(tenant, propertyName, propertyValue, levelOptions);
           processResults(exactMatches);
         }
+      } else if (isSubtreeFilter(propertyFilter)) {
+        const exactMatches = await this.filterExactMatches(tenant, propertyName, propertyFilter.subtree, levelOptions);
+        processResults(exactMatches);
+
+        const descendantMatches = await this.filterSubtreeDescendantMatches(
+          tenant,
+          propertyName,
+          propertyFilter.subtree,
+          levelOptions,
+        );
+        processResults(descendantMatches);
       } else if (FilterUtility.isRangeFilter(propertyFilter)) {
         // `propertyFilter` is a `RangeFilter`
         const rangeMatches = await this.filterRangeMatches(tenant, propertyName, propertyFilter, levelOptions);
@@ -633,6 +792,34 @@ export class IndexLevel {
     return matches;
   }
 
+  /**
+   * Returns every slash-delimited descendant of one hierarchical path.
+   *
+   * The lower bound removes JSON's closing quote so it is the encoded key
+   * prefix itself. ASCII `/` and `0` are adjacent in the store's lexicographic
+   * ordering, making `path0` the first value outside that prefix without
+   * relying on a finite Unicode sentinel.
+   */
+  private async filterSubtreeDescendantMatches(
+    tenant: string,
+    propertyName: string,
+    subtree: string,
+    options?: IndexLevelOptions,
+  ): Promise<IndexedItem[]> {
+    const encodedPrefix = IndexLevel.encodeValue(`${subtree}/`).slice(0, -1);
+    const iteratorOptions: LevelWrapperIteratorOptions<string> = {
+      gte : encodedPrefix,
+      lt  : IndexLevel.encodeValue(`${subtree}0`),
+    };
+
+    const filterPartition = await this.getIndexPartition(tenant, propertyName);
+    const matches: IndexedItem[] = [];
+    for await (const [ _key, value ] of filterPartition.iterator(iteratorOptions, options)) {
+      matches.push(JSON.parse(value) as IndexedItem);
+    }
+    return matches;
+  }
+
   /**
    * Returns items that match the range filter.
    *

package/src/store/message-store-level.ts

@@ -1,5 +1,5 @@
 
-import type { CompoundIndexDefinition } from './index-level.js';
+import type { CompoundIndexDefinition, IndexedItem } from './index-level.js';
 import type {
   EventLogEntry,
   EventLogReadOptions,
@@ -13,22 +13,32 @@ import type {
 import type { Filter, KeyValues, PaginationCursor, QueryOptions } from '../types/query-types.js';
 import type { GenericMessage, MessageSort, Pagination } from '../types/message-types.js';
 import type { LevelDatabase, LevelWrapperBatchOperation } from './level-wrapper.js';
-import type { MessageStore, MessageStoreLatestStateTransition, MessageStoreOptions, MessageStorePutResult } from '../types/message-store.js';
+import type {
+  MessageStore,
+  MessageStoreLatestStateTransition,
+  MessageStoreOptions,
+  MessageStorePutResult,
+  MessageStoreQueryOptions,
+  RecordLimitOccupancy,
+} from '../types/message-store.js';
 
 import * as block from 'multiformats/block';
 import * as cbor from '@ipld/dag-cbor';
 
+import { runWithCrossContextLock } from '@enbox/common';
+
 import { Cid } from '../utils/cid.js';
 import { CID } from 'multiformats/cid';
 import { executeUnlessAborted } from '../utils/abort.js';
-import { FilterUtility } from '../utils/filter.js';
 import { IndexLevel } from './index-level.js';
 import { Message } from '../core/message.js';
 import { Replication } from '../utils/replication.js';
 import { sha256 } from 'multiformats/hashes/sha2';
 import { SortDirection } from '../types/query-types.js';
+import { assertValidSubtreeFilters, FilterUtility } from '../utils/filter.js';
 import { createLevelDatabase, LevelWrapper } from './level-wrapper.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 
 
 /**
@@ -89,6 +99,8 @@ const HEADS_PARTITION = 'heads';
 const META_PARTITION = 'meta';
 
 const EPOCH_KEY = 'epoch';
+const RECORD_LIMIT_RAW_PAGE_SIZE = 128;
+const RECORD_LIMIT_GROUP_CACHE_SIZE = 128;
 const CURRENT_PARTITIONS = new Set([
   BLOCKS_PARTITION,
   INDEX_PARTITION,
@@ -136,6 +148,29 @@ type StorePartitions = {
   meta: LevelWrapper<string>;
 };
 
+type RecordLimitPopulationInput = {
+  tenant: string;
+  filters: Filter[];
+  queryOptions: QueryOptions;
+  recordLimit: RecordLimitOccupancy;
+  options?: MessageStoreQueryOptions;
+};
+
+type RecordLimitOccupantInput = {
+  tenant: string;
+  index: IndexLevel;
+  item: IndexedItem;
+  candidateFilter: Filter;
+  recordLimit: RecordLimitOccupancy;
+  groupCutoffs: Map<string, string>;
+  options?: MessageStoreQueryOptions;
+};
+
+type RecordLimitPageInput = Omit<RecordLimitOccupantInput, 'item'> & {
+  items: IndexedItem[];
+  limit?: number;
+};
+
 /**
  * A {@link MessageStore} and {@link ReplicationFeedReader} implementation that works in both the
  * browser and server-side, backed by a SINGLE LevelDB root: message blocks, query indexes, the
@@ -143,8 +178,9 @@ type StorePartitions = {
  * the store epoch are all sublevels of one Level instance, so every mutation commits as one fully
  * atomic batch.
  *
- * A per-tenant async write mutex spans seq assignment through batch write, so commit order equals
- * seq order by construction. Seq assignment is gap-free (a failed batch never persists the head),
+ * A per-tenant cross-context write lock spans seq assignment through batch write, so commit order
+ * equals seq order by construction even when browser tabs, workers, or service workers share the
+ * same IndexedDB database. Seq assignment is gap-free (a failed batch never persists the head),
  * while the readable log stays sparse after compaction and under filters — readers never assume
  * contiguity.
  */
@@ -154,7 +190,6 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
   private readonly wakePublisher?: WakePublisher;
   private partitionsPromise?: Promise<StorePartitions>;
   private epochPromise?: Promise<string>;
-  private readonly writeLocks: Map<string, Promise<void>> = new Map();
 
   /**
    * @param {MessageStoreLevelConfig} config
@@ -304,7 +339,7 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
     filters: Filter[],
     messageSort?: MessageSort,
     pagination?: Pagination,
-    options?: MessageStoreOptions
+    options?: MessageStoreQueryOptions
   ): Promise<{ messages: GenericMessage[], cursor?: PaginationCursor}> {
     options?.signal?.throwIfAborted();
 
@@ -312,7 +347,15 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
     // this adds 1 to the limit if provided, that way we can check to see if there are additional results and provide a return cursor.
     const queryOptions = MessageStoreLevel.buildQueryOptions(messageSort, pagination);
     const index = await this.index();
-    const results = await index.query(tenant, filters, queryOptions, options);
+    const results = options?.recordLimit === undefined
+      ? await index.query(tenant, filters, queryOptions, options)
+      : await this.collectRecordLimitPopulation({
+        tenant,
+        filters,
+        queryOptions,
+        recordLimit: options.recordLimit,
+        options,
+      });
 
     let cursor: PaginationCursor | undefined;
     // checks to see if the returned results are greater than the limit, which would indicate additional results.
@@ -338,13 +381,170 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
     tenant: string,
     filters: Filter[],
     messageSort?: MessageSort,
-    options?: MessageStoreOptions
+    options?: MessageStoreQueryOptions
   ): Promise<number> {
     options?.signal?.throwIfAborted();
 
     const queryOptions = MessageStoreLevel.buildQueryOptions(messageSort);
     const index = await this.index();
-    return index.count(tenant, filters, queryOptions, options);
+    if (options?.recordLimit === undefined) {
+      return index.count(tenant, filters, queryOptions, options);
+    }
+
+    let count = 0;
+    for await (const _item of this.iterateRecordLimitPopulation({
+      tenant,
+      filters,
+      queryOptions,
+      recordLimit: options.recordLimit,
+      options,
+    })) {
+      count++;
+    }
+    return count;
+  }
+
+  /**
+   * Materializes one bounded page from the shared record-limit population iterator.
+   */
+  private async collectRecordLimitPopulation(input: RecordLimitPopulationInput): Promise<IndexedItem[]> {
+    const results: IndexedItem[] = [];
+    for await (const item of this.iterateRecordLimitPopulation(input)) {
+      results.push(item);
+    }
+    return results;
+  }
+
+  /**
+   * Streams caller-filtered records in requested order and admits only records
+   * inside their direct-parent group's deterministic rank boundary.
+   *
+   * Raw candidates are fetched into a small page before any parent lookup is
+   * opened. This is deliberate: browser-level/IndexedDB cursors must not be
+   * held open while another index transaction is awaited.
+   */
+  private async * iterateRecordLimitPopulation(input: RecordLimitPopulationInput): AsyncGenerator<IndexedItem> {
+    const { filters, options, queryOptions, recordLimit, tenant } = input;
+    const index = await this.index();
+    const candidateFilter = MessageStoreLevel.buildRecordLimitCandidateFilter(recordLimit);
+    const groupCutoffs = new Map<string, string>();
+    const outputLimit = queryOptions.limit;
+    let outputCount = 0;
+    let rawCursor = queryOptions.cursor;
+
+    if (outputLimit !== undefined && outputLimit <= 0) {
+      return;
+    }
+
+    while (true) {
+      const rawItems = await index.queryWithBoundedPaging(tenant, filters, {
+        ...queryOptions,
+        cursor : rawCursor,
+        limit  : RECORD_LIMIT_RAW_PAGE_SIZE,
+      }, options);
+      if (rawItems.length === 0) {
+        return;
+      }
+
+      const occupants = await this.filterRecordLimitOccupants({
+        tenant,
+        index,
+        items : rawItems,
+        candidateFilter,
+        recordLimit,
+        groupCutoffs,
+        options,
+        limit : outputLimit === undefined ? undefined : outputLimit - outputCount,
+      });
+      for (const occupant of occupants) {
+        yield occupant;
+        outputCount++;
+        if (outputLimit !== undefined && outputCount >= outputLimit) {
+          return;
+        }
+      }
+
+      if (rawItems.length < RECORD_LIMIT_RAW_PAGE_SIZE) {
+        return;
+      }
+      rawCursor = IndexLevel.createCursorFromItem(rawItems.at(-1)!, queryOptions.sortProperty);
+    }
+  }
+
+  private async filterRecordLimitOccupants(input: RecordLimitPageInput): Promise<IndexedItem[]> {
+    const { items, limit, ...occupantInput } = input;
+    const occupants: IndexedItem[] = [];
+    for (const item of items) {
+      if (await this.isWithinRecordLimit({ ...occupantInput, item })) {
+        occupants.push(item);
+        if (limit !== undefined && occupants.length >= limit) {
+          break;
+        }
+      }
+    }
+    return occupants;
+  }
+
+  private async isWithinRecordLimit(input: RecordLimitOccupantInput): Promise<boolean> {
+    if (!FilterUtility.matchFilter(input.item.indexes, input.candidateFilter)) {
+      return false;
+    }
+
+    const indexedParentId = input.item.indexes.parentId;
+    if (indexedParentId !== undefined && typeof indexedParentId !== 'string') {
+      throw new TypeError(`MessageStoreLevel: record-limit candidate parentId must be a string.`);
+    }
+    const parentId = indexedParentId as string | undefined;
+    const groupKey = parentId === undefined ? 'root' : `parent:${parentId}`;
+
+    let cutoff = input.groupCutoffs.get(groupKey);
+    if (cutoff !== undefined) {
+      // Refresh insertion order so the fixed-size map acts as a small LRU.
+      input.groupCutoffs.delete(groupKey);
+      input.groupCutoffs.set(groupKey, cutoff);
+    } else {
+      cutoff = await input.index.findRecordLimitRankCutoff(
+        input.tenant,
+        input.candidateFilter,
+        parentId,
+        input.recordLimit.max,
+        input.options,
+      );
+      if (cutoff === undefined) {
+        return false;
+      }
+      MessageStoreLevel.cacheRecordLimitCutoff(input.groupCutoffs, groupKey, cutoff);
+    }
+
+    return IndexLevel.createRecordLimitRankKey(input.item.indexes) <= cutoff;
+  }
+
+  private static cacheRecordLimitCutoff(
+    cache: Map<string, string>,
+    groupKey: string,
+    cutoff: string,
+  ): void {
+    if (cache.size >= RECORD_LIMIT_GROUP_CACHE_SIZE) {
+      const oldestKey = cache.keys().next().value as string | undefined;
+      if (oldestKey !== undefined) {
+        cache.delete(oldestKey);
+      }
+    }
+    cache.set(groupKey, cutoff);
+  }
+
+  private static buildRecordLimitCandidateFilter(recordLimit: RecordLimitOccupancy): Filter {
+    const filter: Filter = {
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      isLatestBaseState : true,
+      protocol          : recordLimit.protocol,
+      protocolPath      : recordLimit.protocolPath,
+    };
+    if (recordLimit.contextId !== undefined) {
+      filter.contextId = { subtree: recordLimit.contextId };
+    }
+    return filter;
   }
 
   /**
@@ -718,8 +918,11 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
   async logRead(tenant: string, options: EventLogReadOptions = {}): Promise<EventLogReadResult> {
     const partitions = await this.partitions();
     const { cursor, limit, filters } = options;
+    if (filters !== undefined) {
+      assertValidSubtreeFilters(filters);
+    }
 
-    // Head-captured-first: the per-tenant write mutex serializes commits in position order, so an
+    // Head-captured-first: the per-tenant write lock serializes commits in position order, so an
     // observed head H is a visibility barrier — every position <= H is already committed when the
     // range scans below run, and anything committed afterward has a position > H and waits for
     // the next page.
@@ -731,8 +934,10 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
     const startPosition = cursor === undefined ? 0n : BigInt(cursor.position);
 
     if (head === 0n) {
-      // Nothing to scan — caught up at the input position.
-      return { events: [], cursor, drained: true };
+      // Nothing to scan — caught up at the input position. A caller without a
+      // cursor still gets the position-zero anchor so an empty log yields a
+      // checkpointable token instead of forcing a rescan on every pass.
+      return { events: [], cursor: cursor ?? await this.buildToken(tenant, 0n), drained: true };
     }
 
     const maxResults = limit ?? Number.MAX_SAFE_INTEGER;
@@ -863,20 +1068,8 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
    * a later batch could land first).
    */
   private async withTenantWriteLock<T>(tenant: string, task: () => Promise<T>): Promise<T> {
-    const previous = this.writeLocks.get(tenant) ?? Promise.resolve();
-    let release!: () => void;
-    const current = new Promise<void>((resolve) => { release = resolve; });
-    this.writeLocks.set(tenant, current);
-
-    await previous;
-    try {
-      return await task();
-    } finally {
-      release();
-      if (this.writeLocks.get(tenant) === current) {
-        this.writeLocks.delete(tenant);
-      }
-    }
+    const lockName = `enbox:dwn-message-store:${JSON.stringify([this.config.location!, tenant])}`;
+    return runWithCrossContextLock(lockName, task);
   }
 
   /**

package/src/store/storage-controller.ts

@@ -6,7 +6,6 @@ import type { MessageStore, MessageStorePutResult } from '../types/message-store
 import type { RecordsDeleteMessage, 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';
@@ -123,8 +122,7 @@ export class StorageController {
     // 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;
+      filter.contextId = { subtree: parentContextId };
     }
 
     // Query for all records at this path and context