@enbox/dwn-sdk-js 0.4.16 → 0.4.17

package/src/handlers/records-query.ts

@@ -10,12 +10,12 @@ import { EncryptionControl } from '../core/encryption-control.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
 import { ProtocolAuthorization } from '../core/protocol-authorization.js';
-import { queryRecordsWithRecordLimitOccupancy } from '../utils/record-limit-occupancy.js';
 import { Records } from '../utils/records.js';
 import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
 import { RecordsQuery } from '../interfaces/records-query.js';
 import { SortDirection } from '../types/query-types.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { queryRecordsWithRecordLimitOccupancy, resolveRecordLimitOccupancy } from '../utils/record-limit-occupancy.js';
 
 type RecordsQueryProjectionInput = {
   tenant: string;
@@ -254,17 +254,22 @@ export class RecordsQueryHandler implements MethodHandler {
     const {
       tenant, recordsQuery, requester, filters, messageSort, pagination
     } = input;
+    const recordLimit = await resolveRecordLimitOccupancy({
+      validationStateReader : this.deps.validationStateReader,
+      tenant,
+      recordsFilter         : recordsQuery.message.descriptor.filter,
+      messageTimestamp      : recordsQuery.message.descriptor.messageTimestamp,
+    });
     const controlFilters = Records.buildControlRecordsFilters(filters);
     const currentAudienceRecordIdCache = new Map<string, string | undefined>();
     if (controlFilters.length === 0) {
       const result = await queryRecordsWithRecordLimitOccupancy({
-        messageStore          : this.deps.messageStore,
-        validationStateReader : this.deps.validationStateReader,
+        messageStore: this.deps.messageStore,
         tenant,
         filters,
+        recordLimit,
         messageSort,
         pagination,
-        messageTimestamp      : recordsQuery.message.descriptor.messageTimestamp,
       });
       return EncryptionControl.projectCurrentAudienceRecordPage({
         messageStore : this.deps.messageStore,
@@ -280,13 +285,12 @@ export class RecordsQueryHandler implements MethodHandler {
 
     if (pagination?.limit === undefined || pagination.limit <= 0) {
       const result = await queryRecordsWithRecordLimitOccupancy({
-        messageStore          : this.deps.messageStore,
-        validationStateReader : this.deps.validationStateReader,
+        messageStore: this.deps.messageStore,
         tenant,
         filters,
+        recordLimit,
         messageSort,
         pagination,
-        messageTimestamp      : recordsQuery.message.descriptor.messageTimestamp,
       });
       const projectedResult = await EncryptionControl.projectCurrentAudienceRecordPage({
         messageStore : this.deps.messageStore,
@@ -311,13 +315,12 @@ export class RecordsQueryHandler implements MethodHandler {
     do {
       const remainingLimit = pagination.limit - visibleMessages.length;
       const result = await queryRecordsWithRecordLimitOccupancy({
-        messageStore          : this.deps.messageStore,
-        validationStateReader : this.deps.validationStateReader,
+        messageStore : this.deps.messageStore,
         tenant,
         filters,
+        recordLimit,
         messageSort,
-        pagination            : { ...pagination, cursor, limit: remainingLimit },
-        messageTimestamp      : recordsQuery.message.descriptor.messageTimestamp,
+        pagination   : { ...pagination, cursor, limit: remainingLimit },
       });
       const projectedResult = await EncryptionControl.projectCurrentAudienceRecordPage({
         messageStore : this.deps.messageStore,

package/src/handlers/records-subscribe.ts

@@ -17,7 +17,11 @@ import { RecordsSubscribe } from '../interfaces/records-subscribe.js';
 import { SortDirection } from '../types/query-types.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
-import { isRecordLimitOccupant, queryRecordsWithRecordLimitOccupancy } from '../utils/record-limit-occupancy.js';
+import {
+  isRecordLimitOccupant,
+  queryRecordsWithRecordLimitOccupancy,
+  resolveRecordLimitOccupancy,
+} from '../utils/record-limit-occupancy.js';
 
 type ProjectedRecordsSubscriptionHandler = {
   listener: SubscriptionListener;
@@ -604,17 +608,22 @@ export class RecordsSubscribeHandler implements MethodHandler {
     messageSort: MessageSort,
     pagination: { cursor?: PaginationCursor; limit?: number } | undefined,
   ): Promise<{ messages: RecordsQueryReplyEntry[], cursor?: PaginationCursor }> {
+    const recordLimit = await resolveRecordLimitOccupancy({
+      validationStateReader : this.deps.validationStateReader,
+      tenant,
+      recordsFilter         : recordsSubscribe.message.descriptor.filter,
+      messageTimestamp      : recordsSubscribe.message.descriptor.messageTimestamp,
+    });
     const controlFilters = Records.buildControlRecordsFilters(filters);
     const currentAudienceRecordIdCache = new Map<string, string | undefined>();
     if (controlFilters.length === 0) {
       const result = await queryRecordsWithRecordLimitOccupancy({
-        messageStore          : this.deps.messageStore,
-        validationStateReader : this.deps.validationStateReader,
+        messageStore: this.deps.messageStore,
         tenant,
         filters,
+        recordLimit,
         messageSort,
         pagination,
-        messageTimestamp      : recordsSubscribe.message.descriptor.messageTimestamp,
       });
       return EncryptionControl.projectCurrentAudienceRecordPage({
         messageStore: this.deps.messageStore,
@@ -627,13 +636,12 @@ export class RecordsSubscribeHandler implements MethodHandler {
 
     if (pagination?.limit === undefined || pagination.limit <= 0) {
       const result = await queryRecordsWithRecordLimitOccupancy({
-        messageStore          : this.deps.messageStore,
-        validationStateReader : this.deps.validationStateReader,
+        messageStore: this.deps.messageStore,
         tenant,
         filters,
+        recordLimit,
         messageSort,
         pagination,
-        messageTimestamp      : recordsSubscribe.message.descriptor.messageTimestamp,
       });
       const projectedResult = await EncryptionControl.projectCurrentAudienceRecordPage({
         messageStore: this.deps.messageStore,
@@ -655,13 +663,12 @@ export class RecordsSubscribeHandler implements MethodHandler {
     do {
       const remainingLimit = pagination.limit - visibleMessages.length;
       const result = await queryRecordsWithRecordLimitOccupancy({
-        messageStore          : this.deps.messageStore,
-        validationStateReader : this.deps.validationStateReader,
+        messageStore : this.deps.messageStore,
         tenant,
         filters,
+        recordLimit,
         messageSort,
-        pagination            : { ...pagination, cursor, limit: remainingLimit },
-        messageTimestamp      : recordsSubscribe.message.descriptor.messageTimestamp,
+        pagination   : { ...pagination, cursor, limit: remainingLimit },
       });
       const projectedResult = await EncryptionControl.projectCurrentAudienceRecordPage({
         messageStore: this.deps.messageStore,

package/src/handlers/records-write.ts

@@ -1,5 +1,6 @@
 import type { CoreProtocol } from '../core/core-protocol.js';
 import type { ProgressToken } from '../types/subscriptions.js';
+import type { ProtocolRuleSet } from '../types/protocols-types.js';
 import type { GenericMessage, GenericMessageReply } from '../types/message-types.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { RecordsQueryReplyEntry, RecordsWriteMessage } from '../types/records-types.js';
@@ -64,8 +65,13 @@ export class RecordsWriteHandler implements MethodHandler {
       return messageReplyFromError(e, 400);
     }
 
+    let protocolRuleSet: ProtocolRuleSet;
     try {
-      await ProtocolAuthorization.validateReferentialIntegrity(tenant, recordsWrite, this.deps.validationStateReader);
+      protocolRuleSet = await ProtocolAuthorization.validateReferentialIntegrity(
+        tenant,
+        recordsWrite,
+        this.deps.validationStateReader,
+      );
     } catch (e) {
       return messageReplyFromError(e, 400);
     }
@@ -87,7 +93,7 @@ export class RecordsWriteHandler implements MethodHandler {
     // messageTimestamp is <= the most recent squash record at the same path and parent context.
     // The squash record acts as a temporal floor — no record older than the latest squash can exist.
     try {
-      await this.enforceSquashBackstop(tenant, message);
+      await this.enforceSquashBackstop(tenant, message, protocolRuleSet);
     } catch (e) {
       return messageReplyFromError(e, 409);
     }
@@ -445,38 +451,17 @@ export class RecordsWriteHandler implements MethodHandler {
    * and there exists a squash record at the same protocol path and parent context whose
    * `messageTimestamp` is >= the incoming message's `messageTimestamp`, reject with 409.
    *
+   * The rule set is the exact policy already resolved by referential-integrity validation. Reusing
+   * it prevents a second store lookup from observing different state or failing open.
+   *
    * This check only applies to protocol-based records at `$squash: true` paths.
    */
-  private async enforceSquashBackstop(tenant: string, message: RecordsWriteMessage): Promise<void> {
-    // Only applies to protocol-based records
-    if (message.descriptor.protocol === undefined || message.descriptor.protocolPath === undefined) {
-      return;
-    }
-
-    // Fetch the protocol definition active at the incoming message timestamp to check if $squash is enabled at this path.
-    // The reader resolves core protocols (e.g. permissions) from the registry.
-    let protocolDefinition;
-    try {
-      protocolDefinition = await this.deps.validationStateReader.fetchProtocolDefinition(
-        tenant,
-        message.descriptor.protocol,
-        message.descriptor.messageTimestamp,
-      );
-    } catch (error) {
-      // If the protocol definition can't be found, skip the backstop check.
-      // Authorization will handle the missing protocol error later.
-      console.warn(`enforceSquashBackstop: failed to fetch protocol definition for '${message.descriptor.protocol}':`, error);
-      return;
-    }
-
-    // Walk the structure to find the rule set for this protocol path
-    const pathSegments = message.descriptor.protocolPath.split('/');
-    let ruleSet = protocolDefinition.structure[pathSegments[0]];
-    for (let i = 1; i < pathSegments.length && ruleSet !== undefined; i++) {
-      ruleSet = ruleSet[pathSegments[i]] as typeof ruleSet;
-    }
-
-    if (ruleSet?.$squash !== true) {
+  private async enforceSquashBackstop(
+    tenant: string,
+    message: RecordsWriteMessage,
+    ruleSet: ProtocolRuleSet,
+  ): Promise<void> {
+    if (ruleSet.$squash !== true) {
       return;
     }
 

package/src/index.ts

@@ -9,9 +9,8 @@ export { StoreValidationStateReader } from './core/validation-state-reader.js';
 export type { RecordedValidationRead } from './core/recording-validation-state-reader.js';
 export { RecordingValidationStateReader } from './core/recording-validation-state-reader.js';
 export type { MessagesFilter, MessagesQueryDescriptor, MessagesQueryMessage, MessagesQueryReply, MessagesQueryReplyEntry, MessagesReadMessage, MessagesReadReply, MessagesReadReplyEntry, MessagesReadDescriptor, MessagesSubscribeDescriptor, MessagesSubscribeMessage, MessagesSubscribeReply, MessagesSubscribeMessageOptions } 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';
+export type { GT, LT, Filter, FilterValue, KeyValues, EqualFilter, OneOfFilter, RangeFilter, RangeCriterion, PaginationCursor, QueryOptions, RangeValue, StartsWithFilter, SubtreeFilter } from './types/query-types.js';
 export type { ProtocolsConfigureDescriptor, ProtocolDefinition, ProtocolTypes, ProtocolRuleSet, ProtocolsQueryFilter, ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply, ProtocolActionRule, ProtocolDeliveryStrategy, ProtocolKeyAgreement, ProtocolsQueryDescriptor, ProtocolRecordLimitDefinition, ProtocolSizeDefinition, ProtocolTagsDefinition, ProtocolTagSchema, ProtocolType, ProtocolUses } from './types/protocols-types.js';
-export { ProtocolRecordLimitStrategy } from './types/protocols-types.js';
 export type { DataEncodedRecordsWriteMessage, RecordsCountDescriptor, RecordsCountMessage, RecordsCountReply, RecordsDeleteMessage, RecordsFilter, RecordsQueryMessage, RecordsQueryReply, RecordsQueryReplyEntry, RecordsReadMessage, RecordsReadReply, RecordsSubscribeDescriptor, RecordsSubscribeMessage, RecordsSubscribeReply, RecordsWriteDescriptor, RecordsWriteTags, RecordsWriteTagValue, RecordsWriteMessage, RecordsWriteSignaturePayload, RecordsDeleteDescriptor, RecordsQueryDescriptor, RecordsReadDescriptor, RecordsSubscribeMessageOptions, RecordsWriteMessageOptions, InternalRecordsWriteMessage, RecordEvent, RecordsWriteTagsFilter } from './types/records-types.js';
 export type { GeneralJws, SignatureEntry } from './types/jws-types.js';
 export { authenticate } from './core/auth.js';
@@ -53,6 +52,7 @@ export { DwnError, DwnErrorCode } from './core/dwn-error.js';
 export type { DwnErrorInfo } from './core/dwn-error.js';
 export { DwnInterfaceName, DwnMethodName } from './enums/dwn-interface-method.js';
 export { Encoder } from './utils/encoder.js';
+export { assertValidSubtreeFilters, isSubtreeFilter } from './utils/filter.js';
 export { MessagesSubscribe } from './interfaces/messages-subscribe.js';
 export type { MessagesSubscribeOptions } from './interfaces/messages-subscribe.js';
 export { Encryption, ContentEncryptionAlgorithm, KeyAgreementAlgorithm, ROLE_AUDIENCE_DERIVATION_SCHEME, SEAL_DERIVATION_SCHEME } from './utils/encryption.js';
@@ -82,7 +82,7 @@ export type { MessagesReadOptions } from './interfaces/messages-read.js';
 export { MessagesQuery } from './interfaces/messages-query.js';
 export type { MessagesQueryOptions } from './interfaces/messages-query.js';
 export type { UnionMessageReply } from './core/message-reply.js';
-export type { MessageStore, MessageStoreLatestStateTransition, MessageStoreOptions, MessageStorePutResult } from './types/message-store.js';
+export type { MessageStore, MessageStoreLatestStateTransition, MessageStoreOptions, MessageStorePutResult, MessageStoreQueryOptions, RecordLimitOccupancy } from './types/message-store.js';
 export { Replication } from './utils/replication.js';
 export type { MessageInterface } from './types/message-interface.js';
 export { PermissionGrant } from './protocols/permission-grant.js';

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.
    *