@enbox/dwn-sdk-js 0.4.16 → 0.4.17

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.
@@ -865,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

package/src/types/message-store.ts

@@ -6,6 +6,29 @@ export interface MessageStoreOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Read-time `$recordLimit` occupancy policy for one concrete protocol path.
+ *
+ * Stores partition matching latest RecordsWrites by `parentId`, rank each
+ * partition by `dateCreated` then `recordId` ascending, and apply `max`
+ * before the caller's filters, sort, and pagination.
+ */
+export type RecordLimitOccupancy = {
+  protocol: string;
+  protocolPath: string;
+  /**
+   * Root of the candidate context subtree. An exact-record request supplies
+   * its direct-parent context here so sibling candidates still consume slots.
+   * Omitted for root protocol paths.
+   */
+  contextId?: string;
+  max: number;
+};
+
+export interface MessageStoreQueryOptions extends MessageStoreOptions {
+  recordLimit?: RecordLimitOccupancy;
+}
+
 /**
  * Result of a {@link MessageStore.put} operation.
  */
@@ -98,7 +121,7 @@ export interface MessageStore {
     filters: Filter[],
     messageSort?: MessageSort,
     pagination?: Pagination,
-    options?: MessageStoreOptions
+    options?: MessageStoreQueryOptions
   ): Promise<{ messages: GenericMessage[], cursor?: PaginationCursor}>;
 
   /**
@@ -109,7 +132,7 @@ export interface MessageStore {
     tenant: string,
     filters: Filter[],
     messageSort?: MessageSort,
-    options?: MessageStoreOptions
+    options?: MessageStoreQueryOptions
   ): Promise<number>;
 
   /**

package/src/types/protocols-types.ts

@@ -149,33 +149,15 @@ export type ProtocolSizeDefinition = {
 };
 
 /**
- * Supported strategies for handling writes that would exceed a `$recordLimit`.
- */
-export enum ProtocolRecordLimitStrategy {
-  /** Reject the incoming write with an error. The author must delete old records first. */
-  Reject = 'reject',
-  /** Automatically delete the oldest record(s) (by `dateCreated`) to make room for the new one. */
-  PurgeOldest = 'purgeOldest',
-}
-
-/**
- * Limits the number of records at a given protocol path within the same parent context.
+ * Limits the visible records at a given protocol path within the same parent context.
  *
- * For root-level records, the count is across the entire protocol for the tenant.
- * For nested records, the count is scoped to the parent record's context.
- *
- * Only initial writes (new records) count toward the limit; updates to existing records do not.
+ * Root-level records form one group for the protocol path. Nested records are grouped by
+ * direct parent context. Occupants are selected deterministically at read time; valid writes
+ * outside the visible population remain stored and may become visible later.
  */
 export type ProtocolRecordLimitDefinition = {
-  /** Maximum number of records allowed at this path within the same parent context. Must be >= 1. */
+  /** Maximum number of visible records at this path within the same parent context. Must be >= 1. */
   max: number;
-
-  /**
-   * Strategy when the limit is reached.
-   * Currently only `'reject'` is implemented. Future strategies (e.g. `'purgeOldest'`)
-   * are defined in the wire format but not yet enforced.
-   */
-  strategy: ProtocolRecordLimitStrategy | `${ProtocolRecordLimitStrategy}` | (string & {});
 };
 
 /**
@@ -287,9 +269,8 @@ export type ProtocolRuleSet = {
   $tags?: ProtocolTagsDefinition;
 
   /**
-   * If $recordLimit is set, the number of records at this protocol path within the same
-   * parent context is constrained. When the limit is reached, the `strategy` determines
-   * whether the write is rejected or the oldest record is purged.
+   * If `$recordLimit` is set, reads expose at most `max` records at this protocol path
+   * within each direct parent context.
    */
   $recordLimit?: ProtocolRecordLimitDefinition;
 

package/src/types/query-types.ts

@@ -37,7 +37,15 @@ export type StartsWithFilter = {
   startsWith: string;
 };
 
-export type FilterValue = EqualFilter | OneOfFilter | RangeFilter;
+/**
+ * Selects one hierarchical path and every proper `/`-delimited descendant.
+ * Supported only for the `contextId` and `protocolPath` indexes.
+ */
+export type SubtreeFilter = {
+  subtree: string;
+};
+
+export type FilterValue = EqualFilter | OneOfFilter | RangeFilter | SubtreeFilter;
 
 export type Filter = {
   [property: string]: FilterValue;
@@ -58,4 +66,4 @@ export type RangeCriterion = {
 export type PaginationCursor = {
   messageCid: string;
   value: string | number;
-};
+};

package/src/types/records-types.ts

@@ -154,7 +154,8 @@ export type RecordsFilter = {
   published?: boolean;
 
   /**
-   * When given all Records message under the context of the given `contextId` will be returned.
+   * Selects the exact context and its proper `/`-delimited descendants.
+   * Prefix-sharing sibling contexts are excluded.
    */
   contextId?: string;
   schema?: string;

package/src/utils/filter.ts

@@ -1,4 +1,30 @@
-import type { EqualFilter, Filter, FilterValue, KeyValues, OneOfFilter, RangeCriterion, RangeFilter, RangeValue } from '../types/query-types.js';
+import type { EqualFilter, Filter, FilterValue, KeyValues, OneOfFilter, RangeCriterion, RangeFilter, RangeValue, SubtreeFilter } from '../types/query-types.js';
+
+const SUBTREE_FILTER_PROPERTIES = new Set(['contextId', 'protocolPath']);
+
+/** Returns whether the value is a well-formed hierarchical subtree filter. */
+export function isSubtreeFilter(filter: FilterValue): filter is SubtreeFilter {
+  return typeof filter === 'object' &&
+    filter !== null &&
+    !Array.isArray(filter) &&
+    Object.keys(filter).length === 1 &&
+    typeof (filter as Partial<SubtreeFilter>).subtree === 'string';
+}
+
+/**
+ * Rejects subtree filters for indexes without hierarchical path semantics.
+ *
+ * @throws {TypeError} If a subtree filter targets an index other than `contextId` or `protocolPath`.
+ */
+export function assertValidSubtreeFilters(filters: Filter[]): void {
+  for (const filter of filters) {
+    for (const property in filter) {
+      if (isSubtreeFilter(filter[property]) && !SUBTREE_FILTER_PROPERTIES.has(property)) {
+        throw new TypeError(`SubtreeFilter is not supported for index '${property}'.`);
+      }
+    }
+  }
+}
 
 /**
  * A Utility class to help match indexes against filters.
@@ -84,7 +110,9 @@ export class FilterUtility {
         if (this.matchOneOf(filterValue, indexValue)) {
           return true;
         }
-      } else if (this.matchRange(filterValue, indexValue as RangeValue)) {
+      } else if (isSubtreeFilter(filterValue) && this.matchesSubtree(filterValue.subtree, indexValue)) {
+        return true;
+      } else if (this.isRangeFilter(filterValue) && this.matchRange(filterValue, indexValue as RangeValue)) {
         // `filterValue` is a `RangeFilter`
         // range filters cannot range over booleans
         return true;
@@ -181,6 +209,15 @@ export class FilterUtility {
     };
   }
 
+  /**
+   * Returns whether a candidate is the selected hierarchical path or one of
+   * its proper `/`-delimited descendants.
+   */
+  static matchesSubtree(subtree: string, candidate: unknown): candidate is string {
+    return typeof candidate === 'string' &&
+      (candidate === subtree || candidate.startsWith(`${subtree}/`));
+  }
+
 }
 
 export class FilterSelector {
@@ -238,4 +275,4 @@ export class FilterSelector {
     singlePropertyFilter[firstRemainingProperty] = filter[firstRemainingProperty];
     return singlePropertyFilter;
   }
-}
+}

package/src/utils/grant-key-coverage.ts

@@ -1,6 +1,7 @@
 import type { PermissionScope, RecordsPermissionScope } from '../types/permission-types.js';
 import type { ProtocolDefinition, ProtocolRuleSet } from '../types/protocols-types.js';
 
+import { FilterUtility } from './filter.js';
 import { KeyDerivationScheme } from './hd-key.js';
 import { ProtocolAction } from '../types/protocols-types.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
@@ -171,7 +172,7 @@ function readGrantKeyScopeCoversDeliveredScope(input: {
     return false;
   }
 
-  if (isBoundaryAwareSubtree(grantProtocolPath, deliveredProtocolPath)) {
+  if (FilterUtility.matchesSubtree(grantProtocolPath, deliveredProtocolPath)) {
     return true;
   }
 
@@ -206,7 +207,7 @@ function writeGrantKeyScopeCoversDeliveredScope(input: {
     return true;
   }
 
-  return isBoundaryAwareSubtree(grantProtocolPath, deliveredProtocolPath);
+  return FilterUtility.matchesSubtree(grantProtocolPath, deliveredProtocolPath);
 }
 
 function getGrantKeyReadRolePathsForScope(protocolDefinition: ProtocolDefinition, scopeProtocolPath: string): string[] {
@@ -257,7 +258,7 @@ function collectReadRolePaths(protocolDefinition: ProtocolDefinition, ruleSet: P
 
 function getGrantKeyRolePathsCoveredByScope(protocolDefinition: ProtocolDefinition, scopeProtocolPath?: string): string[] {
   return collectRolePaths(protocolDefinition, protocolDefinition.structure as ProtocolRuleSet)
-    .filter((rolePath) => scopeProtocolPath === undefined || isBoundaryAwareSubtree(scopeProtocolPath, rolePath));
+    .filter((rolePath) => scopeProtocolPath === undefined || FilterUtility.matchesSubtree(scopeProtocolPath, rolePath));
 }
 
 function collectRolePaths(protocolDefinition: ProtocolDefinition, ruleSet: ProtocolRuleSet, parentPath: string[] = []): string[] {
@@ -285,10 +286,6 @@ function isGrantKeyLocalRolePath(protocolDefinition: ProtocolDefinition, protoco
   return ruleSet?.$role === true && ruleSet.$keyAgreement !== undefined;
 }
 
-function isBoundaryAwareSubtree(scopePath: string, candidatePath: string): boolean {
-  return `${candidatePath}/`.startsWith(`${scopePath}/`);
-}
-
 function getGrantKeyScopeCacheKey(scope: GrantKeyProtocolPathScope): string {
   return JSON.stringify([scope.protocol, scope.protocolPath]);
 }

package/src/utils/messages.ts

@@ -196,26 +196,16 @@ export class Messages {
       delete filterCopy.dateUpdated;
     }
 
-    // Convert protocolPathPrefix into a protocolPath range filter.
-    // The range gte: prefix, lt: prefix + '/\uffff' matches:
-    //   - exact: 'post' (prefix itself)
-    //   - children: 'post/attachment', 'post/comment', etc.
-    //   - NOT siblings: 'poster', 'postfix' (excluded because '/' < any alphanumeric)
+    // Convert protocolPathPrefix into a segment-aware protocolPath subtree filter.
     if (protocolPathPrefix !== undefined) {
       delete (filterCopy as any).protocolPathPrefix;
-      filterCopy.protocolPath = {
-        gte : protocolPathPrefix,
-        lt  : protocolPathPrefix + '/\uffff',
-      };
+      filterCopy.protocolPath = { subtree: protocolPathPrefix };
     }
 
-    // Convert contextIdPrefix into a contextId range filter (same pattern).
+    // Convert contextIdPrefix into the same segment-aware subtree filter.
     if (contextIdPrefix !== undefined) {
       delete (filterCopy as any).contextIdPrefix;
-      filterCopy.contextId = {
-        gte : contextIdPrefix,
-        lt  : contextIdPrefix + '/\uffff',
-      };
+      filterCopy.contextId = { subtree: contextIdPrefix };
     }
 
     return filterCopy;

package/src/utils/permission-scope.ts

@@ -1,3 +1,5 @@
+import { FilterUtility } from './filter.js';
+
 /**
  * Minimal protocol-bound scope shape used by permission grant authorization.
  *
@@ -38,22 +40,13 @@ export class PermissionScopeMatcher {
     }
 
     if (scope.protocolPath !== undefined) {
-      return PermissionScopeMatcher.matchesSubtree(scope.protocolPath, target.protocolPath);
+      return FilterUtility.matchesSubtree(scope.protocolPath, target.protocolPath);
     }
 
     if (scope.contextId !== undefined) {
-      return PermissionScopeMatcher.matchesContextId(scope.contextId, target.contextId);
+      return FilterUtility.matchesSubtree(scope.contextId, target.contextId);
     }
 
     return true;
   }
-
-  private static matchesContextId(scopeContextId: string, candidateContextId: unknown): boolean {
-    return PermissionScopeMatcher.matchesSubtree(scopeContextId, candidateContextId);
-  }
-
-  private static matchesSubtree(scopeValue: string, candidateValue: unknown): boolean {
-    return typeof candidateValue === 'string' &&
-      (candidateValue === scopeValue || candidateValue.startsWith(scopeValue + '/'));
-  }
 }