@enbox/dwn-sdk-js 0.4.15 → 0.4.17

package/src/core/protocol-authorization-validation.ts

@@ -5,13 +5,13 @@ import type { ValidationStateReader } from '../types/validation-state-reader.js'
 import type { ProtocolActionRule, ProtocolDefinition, ProtocolRuleSet, ProtocolType, ProtocolTypes } from '../types/protocols-types.js';
 
 import { KeyDerivationScheme } from '../utils/hd-key.js';
+import { ProtocolAction } from '../types/protocols-types.js';
 import { Records } from '../utils/records.js';
 import { validateProtocolTags } from '../utils/protocol-tags.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
 import { Encryption, ROLE_AUDIENCE_DERIVATION_SCHEME } from '../utils/encryption.js';
 import { ENCRYPTION_PROTOCOL_GRANT_KEY_PATH, ENCRYPTION_PROTOCOL_URI } from './constants.js';
 import { getRoleAudienceContextId, getRuleSetAtPath, getTypeName, parseCrossProtocolRef } from '../utils/protocols.js';
-import { ProtocolAction, ProtocolRecordLimitStrategy } from '../types/protocols-types.js';
 
 type ResolvedRoleAudience = {
   contextId: string;
@@ -526,38 +526,6 @@ export async function verifyAsRoleRecordIfNeeded(
   }
 }
 
-/**
- * Verifies that the `$recordLimit` strategy is supported for a new record creation.
- *
- * This check only applies to initial writes (new records). Updates to existing records do not
- * affect record-limit occupancy. The supported `reject` strategy admits every candidate and
- * projects the visible occupant set at read time, so validation stays independent of arrival order.
- *
- * @throws {DwnError} with `ProtocolAuthorizationRecordLimitStrategyNotImplemented` if strategy is not implemented.
- */
-export async function verifyRecordLimit(
-  incomingMessage: RecordsWrite,
-  ruleSet: ProtocolRuleSet,
-): Promise<void> {
-  if (ruleSet.$recordLimit === undefined) {
-    return;
-  }
-
-  // Only initial writes can introduce a new record-limit candidate.
-  const isInitialWrite = await incomingMessage.isInitialWrite();
-  if (!isInitialWrite) {
-    return;
-  }
-
-  const { strategy } = ruleSet.$recordLimit;
-  if (strategy !== ProtocolRecordLimitStrategy.Reject) {
-    throw new DwnError(
-      DwnErrorCode.ProtocolAuthorizationRecordLimitStrategyNotImplemented,
-      `record limit strategy '${strategy}' is not yet implemented.`
-    );
-  }
-}
-
 /**
  * Verifies that a `RecordsWrite` with `squash: true` is eligible:
  * 1. The protocol rule set at the record's `protocolPath` must have `$squash: true`.

package/src/core/protocol-authorization.ts

@@ -19,7 +19,6 @@ import {
   verifyAsRoleRecordIfNeeded,
   verifyImmutability,
   verifyProtocolPathAndContextId,
-  verifyRecordLimit,
   verifySizeLimit,
   verifySquashEligibility,
   verifyTagsIfNeeded,
@@ -88,9 +87,6 @@ export class ProtocolAuthorization {
     // Verify squash eligibility — ensure squash writes are at $squash: true paths and are initial writes
     await verifySquashEligibility(incomingMessage, ruleSet);
 
-    // Verify record count limit
-    await verifyRecordLimit(incomingMessage, ruleSet);
-
     return ruleSet;
   }
 
@@ -142,9 +138,6 @@ export class ProtocolAuthorization {
     verifyTagsIfNeeded(incomingMessage, ruleSet);
     await verifySquashEligibility(incomingMessage, ruleSet);
     ProtocolAuthorization.verifyStoredInitialWriteCreateAction(tenant, incomingMessage, ruleSet);
-
-    // `verifyRecordLimit()` is intentionally not replayed here. It only checks strategy
-    // support for new record candidates; read-time occupancy projection decides visibility.
   }
 
   /**

package/src/core/validation-state-reader.ts

@@ -8,7 +8,6 @@ import type { DataEncodedRecordsWriteMessage, RecordsWriteMessage } from '../typ
 import type { ProtocolDefinition, ProtocolsConfigureMessage } from '../types/protocols-types.js';
 
 import { ENCRYPTION_CONTROL_AUDIENCE_PATH } from './constants.js';
-import { FilterUtility } from '../utils/filter.js';
 import { PermissionGrant } from '../protocols/permission-grant.js';
 import { PermissionsProtocol } from '../protocols/permissions.js';
 import { RecordsWrite } from '../interfaces/records-write.js';
@@ -313,7 +312,7 @@ export class StoreValidationStateReader implements ValidationStateReader {
     };
 
     if (input.contextIdPrefix !== undefined) {
-      filter.contextId = FilterUtility.constructPrefixFilterAsRangeFilter(input.contextIdPrefix);
+      filter.contextId = { subtree: input.contextIdPrefix };
     }
 
     const { messages } = await this.messageStore.query(
@@ -370,7 +369,7 @@ export class StoreValidationStateReader implements ValidationStateReader {
     }
 
     if (input.contextIdPrefix !== undefined) {
-      filter.contextId = FilterUtility.constructPrefixFilterAsRangeFilter(input.contextIdPrefix);
+      filter.contextId = { subtree: input.contextIdPrefix };
     }
 
     return filter;

package/src/handlers/messages-query.ts

@@ -1,4 +1,4 @@
-import type { EventLogEntry, ProgressGapInfo, ReplicationFeedReader } from '../types/subscriptions.js';
+import type { EventLogEntry, ProgressGapInfo } from '../types/subscriptions.js';
 import type { Filter, KeyValues } from '../types/query-types.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { MessagesFilter, MessagesQueryMessage, MessagesQueryReply, MessagesQueryReplyEntry } from '../types/messages-types.js';
@@ -31,7 +31,7 @@ export class MessagesQueryHandler implements MethodHandler {
       return messageReplyFromError(e, 401);
     }
 
-    const replicationFeedReader = MessagesQueryHandler.asReplicationFeedReader(this.deps.messageStore);
+    const replicationFeedReader = Replication.asFeedReader(this.deps.messageStore);
     if (replicationFeedReader === undefined) {
       return {
         status: {
@@ -56,7 +56,7 @@ export class MessagesQueryHandler implements MethodHandler {
         drained : result.drained,
       };
 
-      const fingerprintScopes = MessagesQueryHandler.computeFingerprintScopes(message.descriptor.filters);
+      const fingerprintScopes = Messages.computeFingerprintScopes(message.descriptor.filters);
       if (fingerprintScopes !== undefined) {
         reply.fingerprint = await replicationFeedReader.fingerprint(tenant, fingerprintScopes);
       }
@@ -87,18 +87,6 @@ export class MessagesQueryHandler implements MethodHandler {
     });
   }
 
-  private static asReplicationFeedReader(candidate: unknown): ReplicationFeedReader | undefined {
-    const partial = candidate as Partial<ReplicationFeedReader>;
-    if (
-      typeof partial.logRead === 'function' &&
-      typeof partial.logBounds === 'function' &&
-      typeof partial.fingerprint === 'function' &&
-      typeof partial.epoch === 'function'
-    ) {
-      return partial as ReplicationFeedReader;
-    }
-  }
-
   private static convertFilters(filters: MessagesFilter[], deps: HandlerDependencies): Filter[] | undefined {
     if (filters.length === 0) {
       return undefined;
@@ -155,32 +143,6 @@ export class MessagesQueryHandler implements MethodHandler {
     return indexes.isLatestBaseState === true || indexes.isLatestBaseState === 'true';
   }
 
-  private static computeFingerprintScopes(filters: MessagesFilter[]): string[] | undefined {
-    if (filters.length === 0) {
-      return [Replication.globalDomain];
-    }
-
-    const protocols = new Set<string>();
-    for (const filter of filters) {
-      const keys = Object.keys(filter);
-      if (keys.length !== 1 || typeof filter.protocol !== 'string') {
-        return undefined;
-      }
-
-      protocols.add(filter.protocol);
-    }
-
-    const scopes: string[] = [];
-    for (const protocol of protocols) {
-      scopes.push(
-        Replication.protocolDomain(protocol),
-        ...Replication.taggedCoreProtocolDomains(protocol, protocols),
-      );
-    }
-
-    return scopes;
-  }
-
   private static getProgressGapInfo(error: DwnError): ProgressGapInfo | undefined {
     const gapInfo = (error as DwnError & { gapInfo?: ProgressGapInfo }).gapInfo;
     return gapInfo;

package/src/handlers/messages-subscribe.ts

@@ -1,7 +1,7 @@
 import type { PermissionGrant } from '../protocols/permission-grant.js';
-import type { EventSubscription, ProgressGapInfo, SubscriptionEvent, SubscriptionListener, SubscriptionMessage } from '../types/subscriptions.js';
+import type { EventSubscription, ProgressGapInfo, ProgressToken, ReplicationFeedReader, SubscriptionEvent, SubscriptionListener, SubscriptionMessage } from '../types/subscriptions.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
-import type { MessagesSubscribeMessage, MessagesSubscribeReply } from '../types/messages-types.js';
+import type { MessagesFilter, MessagesSubscribeMessage, MessagesSubscribeReply } from '../types/messages-types.js';
 
 import { authenticate } from '../core/auth.js';
 import { Message } from '../core/message.js';
@@ -9,6 +9,7 @@ import { messageReplyFromError } from '../core/message-reply.js';
 import { Messages } from '../utils/messages.js';
 import { MessagesGrantAuthorization } from '../core/messages-grant-authorization.js';
 import { MessagesSubscribe } from '../interfaces/messages-subscribe.js';
+import { Replication } from '../utils/replication.js';
 import { Time } from '../utils/time.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
@@ -79,10 +80,20 @@ export class MessagesSubscribeHandler implements MethodHandler {
       });
       await guardedHandler.setSubscription(subscription);
 
-      return {
+      const reply: MessagesSubscribeReply = {
         status: { code: 200, detail: 'OK' },
         subscription,
       };
+      try {
+        await MessagesSubscribeHandler.attachFeedSnapshot(reply, tenant, filters, this.deps);
+      } catch {
+        // Best-effort enrichment: the subscription is live and correct
+        // without the snapshot — consumers feature-detect the fields. A
+        // failure reply here would orphan the just-installed listener, since
+        // close handles are registered only from successful replies.
+      }
+
+      return reply;
     } catch (error) {
       if (error instanceof DwnError && error.code === DwnErrorCode.EventLogProgressGap) {
         const gapInfo = (error as any).gapInfo as ProgressGapInfo | undefined;
@@ -95,6 +106,59 @@ export class MessagesSubscribeHandler implements MethodHandler {
     }
   }
 
+  /**
+   * Attaches the replication feed's `head` token and scope `fingerprint` to a
+   * successful subscribe reply, when the message store exposes the feed.
+   *
+   * Ordering is load-bearing: both values are observed AFTER the subscription
+   * became active, so every event past `head` is either replayable from it or
+   * already flowing on the live stream — a caller that verifies `fingerprint`
+   * against its local feed may adopt `head` as a checkpoint without a delivery
+   * gap. The head is captured before the fingerprint, mirroring MessagesQuery's
+   * cursor-then-fingerprint order: an event landing between the two captures
+   * makes the fingerprint read ahead of the head, which a consumer observes as
+   * a mismatch (one redundant reconcile), never as a silently skipped event.
+   */
+  private static async attachFeedSnapshot(
+    reply: MessagesSubscribeReply,
+    tenant: string,
+    filters: MessagesFilter[],
+    deps: HandlerDependencies,
+  ): Promise<void> {
+    const feedReader = Replication.asFeedReader(deps.messageStore);
+    if (feedReader === undefined) {
+      return;
+    }
+
+    // Build the complete snapshot before attaching anything: a partial
+    // snapshot (a head without its fingerprint) would read to consumers as
+    // a fingerprint-less server rather than as a failed capture.
+    const bounds = await feedReader.logBounds(tenant);
+    const head = bounds?.latest ?? await MessagesSubscribeHandler.buildAnchorToken(tenant, feedReader);
+
+    const fingerprintScopes = Messages.computeFingerprintScopes(filters);
+    const fingerprint = fingerprintScopes === undefined
+      ? undefined
+      : await feedReader.fingerprint(tenant, fingerprintScopes);
+
+    reply.head = head;
+    if (fingerprint !== undefined) {
+      reply.fingerprint = fingerprint;
+    }
+  }
+
+  /** Builds the position-zero anchor token for a tenant log with no events. */
+  private static async buildAnchorToken(
+    tenant: string,
+    feedReader: ReplicationFeedReader,
+  ): Promise<ProgressToken> {
+    return {
+      streamId : await Replication.deriveStreamId(tenant),
+      epoch    : await feedReader.epoch(),
+      position : '0',
+    };
+  }
+
   private static async authorizeMessagesSubscribe(
     tenant: string,
     messagesSubscribe: MessagesSubscribe,

package/src/handlers/records-count.ts

@@ -1,4 +1,5 @@
 import type { Filter } from '../types/query-types.js';
+import type { RecordLimitOccupancy } from '../types/message-store.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { RecordsCountMessage, RecordsCountReply } from '../types/records-types.js';
 
@@ -10,7 +11,11 @@ import { ProtocolAuthorization } from '../core/protocol-authorization.js';
 import { Records } from '../utils/records.js';
 import { RecordsCount } from '../interfaces/records-count.js';
 import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
-import { countRecordsWithRecordLimitOccupancy, queryRecordsWithRecordLimitOccupancy } from '../utils/record-limit-occupancy.js';
+import {
+  countRecordsWithRecordLimitOccupancy,
+  queryRecordsWithRecordLimitOccupancy,
+  resolveRecordLimitOccupancy,
+} from '../utils/record-limit-occupancy.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 
 export class RecordsCountHandler implements MethodHandler {
@@ -71,7 +76,8 @@ export class RecordsCountHandler implements MethodHandler {
       isLatestBaseState : true
     };
 
-    return this.countProjectedRecords(tenant, recordsCount, [countFilter]);
+    const recordLimit = await this.resolveRecordLimit(tenant, recordsCount);
+    return this.countProjectedRecords(tenant, [countFilter], recordLimit);
   }
 
   private async countRecordsAsOwnerDelegate(
@@ -142,13 +148,16 @@ export class RecordsCountHandler implements MethodHandler {
     return this.countProjectedRecordsForRequester(tenant, recordsCount, requester, [filter]);
   }
 
-  private async countProjectedRecords(tenant: string, recordsCount: RecordsCount, filters: Filter[]): Promise<number> {
+  private async countProjectedRecords(
+    tenant: string,
+    filters: Filter[],
+    recordLimit: RecordLimitOccupancy | undefined,
+  ): Promise<number> {
     const totalCount = await countRecordsWithRecordLimitOccupancy({
-      messageStore          : this.deps.messageStore,
-      validationStateReader : this.deps.validationStateReader,
+      messageStore: this.deps.messageStore,
       tenant,
       filters,
-      messageTimestamp      : recordsCount.message.descriptor.messageTimestamp,
+      recordLimit,
     });
 
     const audienceFilters = EncryptionControl.buildAudienceRecordFilters(filters);
@@ -178,23 +187,23 @@ export class RecordsCountHandler implements MethodHandler {
     requester: string | undefined,
     filters: Filter[],
   ): Promise<number> {
+    const recordLimit = await this.resolveRecordLimit(tenant, recordsCount);
     const controlFilters = Records.buildControlRecordsFilters(filters);
     if (controlFilters.length === 0) {
-      return this.countProjectedRecords(tenant, recordsCount, filters);
+      return this.countProjectedRecords(tenant, filters, recordLimit);
     }
 
-    const totalCount = await this.countProjectedRecords(tenant, recordsCount, filters);
-    const controlCount = await this.countProjectedRecords(tenant, recordsCount, controlFilters);
+    const totalCount = await this.countProjectedRecords(tenant, filters, recordLimit);
+    const controlCount = await this.countProjectedRecords(tenant, controlFilters, recordLimit);
     if (controlCount === 0) {
       return totalCount;
     }
 
     const { messages } = await queryRecordsWithRecordLimitOccupancy({
-      messageStore          : this.deps.messageStore,
-      validationStateReader : this.deps.validationStateReader,
+      messageStore : this.deps.messageStore,
       tenant,
-      filters               : controlFilters,
-      messageTimestamp      : recordsCount.message.descriptor.messageTimestamp,
+      filters      : controlFilters,
+      recordLimit,
     });
     const projectedMessages = await EncryptionControl.projectCurrentAudienceRecords({
       messageStore         : this.deps.messageStore,
@@ -212,6 +221,18 @@ export class RecordsCountHandler implements MethodHandler {
     return totalCount - controlCount + visibleMessages.length;
   }
 
+  private async resolveRecordLimit(
+    tenant: string,
+    recordsCount: RecordsCount,
+  ): Promise<RecordLimitOccupancy | undefined> {
+    return resolveRecordLimitOccupancy({
+      validationStateReader : this.deps.validationStateReader,
+      tenant,
+      recordsFilter         : recordsCount.message.descriptor.filter,
+      messageTimestamp      : recordsCount.message.descriptor.messageTimestamp,
+    });
+  }
+
   private static buildPublishedRecordsFilter(recordsCount: RecordsCount): Filter {
     const { filter } = recordsCount.message.descriptor;
     return {

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';