@enbox/dwn-sdk-js 0.4.0 → 0.4.1

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

@@ -0,0 +1,127 @@
+import type { GenericMessage } from './message-types.js';
+import type { PermissionGrant } from '../protocols/permission-grant.js';
+import type { ProtocolDefinition } from './protocols-types.js';
+import type { RecordsWrite } from '../interfaces/records-write.js';
+import type { RecordsWriteMessage } from './records-types.js';
+
+/**
+ * The single narrow surface through which validation logic reads state.
+ *
+ * Every validation-time state read performed during message admission routes through this
+ * interface, so the replay basis (initial writes ∪ latest states ∪ tombstones ∪ protocol-config
+ * history ∪ permission records) provably stays closed under admission's read set. Validation
+ * modules (`core/protocol-authorization*`, `protocols/permissions*`) are lint-banned from
+ * importing `MessageStore` directly; a new protocol-engine feature that needs new state must add
+ * a reader method here.
+ */
+export interface ValidationStateReader {
+  /**
+   * Fetches a record's initial `RecordsWrite` by entry ID, parsed.
+   * @returns the initial write, or `undefined` when no message carries the entry ID.
+   */
+  fetchInitialRecordsWrite(tenant: string, recordId: string): Promise<RecordsWrite | undefined>;
+
+  /**
+   * Fetches a record's initial write from among all of the record's writes.
+   * @returns the initial write message, or `undefined` when the record has no messages at all.
+   * @throws {DwnError} with `RecordsWriteGetInitialWriteNotFound` when writes exist for the
+   *         record but none of them is the initial write.
+   */
+  fetchInitialWrite(tenant: string, recordId: string): Promise<RecordsWriteMessage | undefined>;
+
+  /**
+   * Constructs the chain of existing records from the root to the given
+   * descendant, each represented by its initial `RecordsWrite`.
+   * @returns the chain root-first; an empty array when `descendantRecordId` is `undefined`.
+   * @throws {DwnError} with `ProtocolAuthorizationParentNotFoundConstructingRecordChain` when any
+   *         link in the chain is missing.
+   */
+  constructRecordChain(tenant: string, descendantRecordId: string | undefined): Promise<RecordsWriteMessage[]>;
+
+  /**
+   * Fetches the immediate parent record for protocolPath/contextId verification.
+   *
+   * Queries the latest-state write first — the fast path that excludes deleted parents. If no
+   * latest write exists, a retained initial write is sufficient for immutable parent facts
+   * (protocolPath/contextId) provided no local tombstone exists for that record.
+   * @returns the parent write, or `undefined` when the parent is absent (or deleted).
+   */
+  fetchParentRecord(input: {
+    tenant: string;
+    parentProtocolUri: string;
+    parentId: string;
+  }): Promise<RecordsWriteMessage | undefined>;
+
+  /**
+   * Checks whether a role record matching the invoked-role selector exists.
+   * Filter-only — role validation never reads record data. The latest-state match is the fast
+   * path. If no latest match exists, a retained initial role write is sufficient for immutable
+   * role facts (recipient/path/context) provided no local tombstone exists for that role record.
+   */
+  hasMatchingRoleRecord(input: {
+    tenant: string;
+    protocol: string;
+    protocolPath: string;
+    recipient: string;
+    contextIdPrefix?: string;
+  }): Promise<boolean>;
+
+  /**
+   * Queries the latest-state role records matching the given
+   * selector, used to reject duplicate role assignments to the same recipient. Filter-only.
+   */
+  queryLatestRoleRecords(input: {
+    tenant: string;
+    protocol: string;
+    protocolPath: string;
+    recipient: string;
+    contextIdPrefix?: string;
+  }): Promise<RecordsWriteMessage[]>;
+
+  /**
+   * Fetches the permission grant with the given record ID, with its scope parsed from grant data.
+   * @throws {DwnError} with `GrantAuthorizationGrantMissing` when the grant does not exist.
+   */
+  fetchGrant(tenant: string, permissionGrantId: string): Promise<PermissionGrant>;
+
+  /**
+   * Fetches the oldest latest-state revocation record for the given permission grant, if any.
+   * Grant activity checks compare the oldest revocation timestamp to the incoming message timestamp.
+   */
+  fetchOldestGrantRevocation(tenant: string, permissionGrantId: string): Promise<GenericMessage | undefined>;
+
+  /**
+   * Fetches the newest `RecordsWrite` associated with a record, used to authorize `Messages.Read`
+   * access to `RecordsDelete` messages by projecting the delete back to the deleted record's
+   * protocol scope.
+   * @throws {DwnError} with `RecordsWriteGetNewestWriteRecordNotFound` when no write exists.
+   */
+  fetchNewestRecordsWrite(tenant: string, recordId: string): Promise<RecordsWriteMessage>;
+
+  /**
+   * Fetches the protocol definition for the given protocol URI.
+   * When `messageTimestamp` is provided, returns the definition active at that point in time —
+   * the `ProtocolsConfigure` with the greatest `messageTimestamp` that is <= the given timestamp,
+   * read from retained config history. When not provided, returns the latest definition.
+   * Core protocol definitions are returned from the registry without a store read.
+   * @throws {DwnError} with `ProtocolAuthorizationProtocolNotFound` when no definition exists.
+   */
+  fetchProtocolDefinition(tenant: string, protocolUri: string, messageTimestamp?: string): Promise<ProtocolDefinition>;
+
+  /**
+   * Fetches the latest `$squash: true` record at a protocol path within the parent context.
+   * This is the temporal floor used by the squash backstop.
+   */
+  fetchLatestSquashRecordAtScope(input: {
+    tenant: string;
+    protocol: string;
+    protocolPath: string;
+    contextIdPrefix?: string;
+  }): Promise<RecordsWriteMessage | undefined>;
+
+  /**
+   * Checks whether the data with the given CID is present in the `DataStore` for the given record.
+   * This is the prior-data integrity check for dataless non-initial writes.
+   */
+  hasStoredData(tenant: string, recordId: string, dataCid: string): Promise<boolean>;
+}

package/src/utils/messages.ts

@@ -1,11 +1,15 @@
 import type { CoreProtocolRegistry } from '../core/core-protocol.js';
 import type { Filter } from '../types/query-types.js';
+import type { GenericMessage } from '../types/message-types.js';
 import type { MessagesFilter } from '../types/messages-types.js';
 
 import { FilterUtility } from './filter.js';
 import { normalizeProtocolUrl } from './url.js';
+import { Records } from './records.js';
 import { isEmptyObject, removeUndefinedProperties } from '@enbox/common';
 
+type StoredMessageWithEncodedData = GenericMessage & { encodedData?: string };
+
 
 /**
  * Class containing Messages related utility methods.
@@ -95,6 +99,22 @@ export class Messages {
     return messagesQueryFilters;
   }
 
+  /**
+   * Returns a copy of a RecordsWrite message without inline encodedData, and the
+   * detached encodedData value for wire surfaces that carry data beside the message.
+   */
+  public static detachEncodedData(message: GenericMessage): { message: GenericMessage; encodedData?: string } {
+    if (!Records.isRecordsWrite(message) || !Messages.hasEncodedData(message)) {
+      return { message };
+    }
+
+    const messageWithoutEncodedData: StoredMessageWithEncodedData = { ...message };
+    const { encodedData } = messageWithoutEncodedData;
+    delete messageWithoutEncodedData.encodedData;
+
+    return { message: messageWithoutEncodedData, encodedData };
+  }
+
   /**
    * Converts an external-facing filter model into an internal-facing filer model used by data store.
    */
@@ -132,4 +152,8 @@ export class Messages {
 
     return filterCopy;
   }
-}
+
+  private static hasEncodedData(message: GenericMessage): message is StoredMessageWithEncodedData {
+    return 'encodedData' in message && typeof message.encodedData === 'string';
+  }
+}

package/src/utils/record-limit-occupancy.ts

@@ -0,0 +1,377 @@
+import type { MessageStore } from '../types/message-store.js';
+import type { ProtocolRecordLimitDefinition } from '../types/protocols-types.js';
+import type { RecordsWriteMessage } from '../types/records-types.js';
+import type { ValidationStateReader } from '../types/validation-state-reader.js';
+import type { Filter, PaginationCursor } from '../types/query-types.js';
+import type { MessageSort, Pagination } from '../types/message-types.js';
+
+import { FilterUtility } from './filter.js';
+import { getRuleSetAtPath } from './protocols.js';
+import { lexicographicalCompare } from './string.js';
+import { ProtocolRecordLimitStrategy } from '../types/protocols-types.js';
+import { Records } from './records.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';
+
+type RecordLimitOccupancyDependencies = {
+  messageStore: MessageStore;
+  validationStateReader: ValidationStateReader;
+};
+
+type RecordLimitOccupancyQueryInput = RecordLimitOccupancyDependencies & {
+  tenant: string;
+  filters: Filter[];
+  messageTimestamp: string;
+  messageSort?: MessageSort;
+  pagination?: Pagination;
+};
+
+type RecordLimitScope = {
+  protocol: string;
+  protocolPath: string;
+  parentContextId: string;
+};
+
+type RecordLimitFilterResolution = {
+  projectedFilters: Filter[];
+};
+
+/**
+ * Queries records with bounded `$recordLimit` occupancy projection when every limited filter targets one concrete scope.
+ *
+ * Broad filters keep the store's native query path. Projecting those without a store-level grouping primitive would require
+ * scanning the full matching set, which is worse than leaving them unprojected until a bounded broad-query strategy exists.
+ */
+export async function queryRecordsWithRecordLimitOccupancy(
+  input: RecordLimitOccupancyQueryInput
+): Promise<{ messages: RecordsWriteMessage[]; cursor?: PaginationCursor }> {
+  const filterResolution = await resolveRecordLimitFilters(input);
+  if (filterResolution === undefined) {
+    const { messages, cursor } = await input.messageStore.query(input.tenant, input.filters, input.messageSort, input.pagination);
+    return { messages: messages.filter(Records.isRecordsWrite), cursor };
+  }
+
+  if (filterResolution.projectedFilters.length === 0) {
+    return { messages: [] };
+  }
+
+  const { messages, cursor } = await input.messageStore.query(
+    input.tenant,
+    filterResolution.projectedFilters,
+    input.messageSort,
+    input.pagination
+  );
+
+  return { messages: messages.filter(Records.isRecordsWrite), cursor };
+}
+
+/**
+ * Counts records with bounded `$recordLimit` occupancy projection when every limited filter targets one concrete scope.
+ */
+export async function countRecordsWithRecordLimitOccupancy(input: Omit<RecordLimitOccupancyQueryInput, 'pagination'>): Promise<number> {
+  const filterResolution = await resolveRecordLimitFilters(input);
+  if (filterResolution === undefined) {
+    return input.messageStore.count(input.tenant, input.filters, input.messageSort);
+  }
+
+  if (filterResolution.projectedFilters.length === 0) {
+    return 0;
+  }
+
+  return input.messageStore.count(input.tenant, filterResolution.projectedFilters, input.messageSort);
+}
+
+/**
+ * Returns true when the latest RecordsWrite is visible under the `$recordLimit` projection.
+ */
+export async function isRecordLimitOccupant(input: RecordLimitOccupancyDependencies & {
+  tenant: string;
+  message: RecordsWriteMessage;
+  messageTimestamp: string;
+}): Promise<boolean> {
+  const recordLimit = await getRecordLimitForMessage({
+    messageStore           : input.messageStore,
+    validationStateReader  : input.validationStateReader,
+    tenant                 : input.tenant,
+    message                : input.message,
+    messageTimestamp       : input.messageTimestamp,
+    recordLimitDefinitions : new Map(),
+  });
+
+  if (recordLimit === undefined) {
+    return true;
+  }
+
+  const occupantRecordIds = await findOccupantRecordIds({
+    messageStore : input.messageStore,
+    tenant       : input.tenant,
+    scope        : getRecordLimitScope(input.message),
+    recordLimit,
+  });
+
+  return occupantRecordIds.has(input.message.recordId);
+}
+
+async function resolveRecordLimitFilters(
+  input: Omit<RecordLimitOccupancyQueryInput, 'pagination'>
+): Promise<RecordLimitFilterResolution | undefined> {
+  const recordLimitDefinitions = new Map<string, ProtocolRecordLimitDefinition | undefined>();
+  const projectedFilters: Filter[] = [];
+  let projectionApplied = false;
+
+  for (const filter of input.filters) {
+    const recordLimit = await getRecordLimitForFilter({
+      messageStore          : input.messageStore,
+      validationStateReader : input.validationStateReader,
+      tenant                : input.tenant,
+      filter,
+      messageTimestamp      : input.messageTimestamp,
+      recordLimitDefinitions,
+    });
+
+    if (recordLimit === undefined) {
+      projectedFilters.push(filter);
+      continue;
+    }
+
+    const scope = getRecordLimitScopeFromFilter(filter);
+    if (scope === undefined) {
+      return undefined;
+    }
+
+    const occupantRecordIds = await findOccupantRecordIds({
+      messageStore : input.messageStore,
+      tenant       : input.tenant,
+      scope,
+      recordLimit,
+    });
+
+    const projectedFilter = buildProjectedFilter(filter, occupantRecordIds);
+    if (projectedFilter !== undefined) {
+      projectedFilters.push(projectedFilter);
+    }
+    projectionApplied = true;
+  }
+
+  return projectionApplied ? { projectedFilters } : undefined;
+}
+
+async function getRecordLimitForMessage(input: RecordLimitOccupancyDependencies & {
+  tenant: string;
+  message: RecordsWriteMessage;
+  messageTimestamp: string;
+  recordLimitDefinitions: Map<string, ProtocolRecordLimitDefinition | undefined>;
+}): Promise<ProtocolRecordLimitDefinition | undefined> {
+  const { protocol, protocolPath } = input.message.descriptor;
+  if (protocol === undefined || protocolPath === undefined) {
+    return undefined;
+  }
+
+  return getRecordLimit({
+    validationStateReader  : input.validationStateReader,
+    tenant                 : input.tenant,
+    protocol,
+    protocolPath,
+    messageTimestamp       : input.messageTimestamp,
+    recordLimitDefinitions : input.recordLimitDefinitions,
+  });
+}
+
+async function getRecordLimitForFilter(input: RecordLimitOccupancyDependencies & {
+  tenant: string;
+  filter: Filter;
+  messageTimestamp: string;
+  recordLimitDefinitions: Map<string, ProtocolRecordLimitDefinition | undefined>;
+}): Promise<ProtocolRecordLimitDefinition | undefined> {
+  if (input.filter.interface !== DwnInterfaceName.Records ||
+    input.filter.method !== DwnMethodName.Write ||
+    input.filter.isLatestBaseState !== true
+  ) {
+    return undefined;
+  }
+
+  const { protocol, protocolPath } = input.filter;
+  if (typeof protocol !== 'string' || typeof protocolPath !== 'string') {
+    return undefined;
+  }
+
+  return getRecordLimit({
+    validationStateReader  : input.validationStateReader,
+    tenant                 : input.tenant,
+    protocol,
+    protocolPath,
+    messageTimestamp       : input.messageTimestamp,
+    recordLimitDefinitions : input.recordLimitDefinitions,
+  });
+}
+
+async function getRecordLimit(input: {
+  validationStateReader: ValidationStateReader;
+  tenant: string;
+  protocol: string;
+  protocolPath: string;
+  messageTimestamp: string;
+  recordLimitDefinitions: Map<string, ProtocolRecordLimitDefinition | undefined>;
+}): Promise<ProtocolRecordLimitDefinition | undefined> {
+  const key = `${input.protocol}\u0000${input.protocolPath}`;
+  if (!input.recordLimitDefinitions.has(key)) {
+    let protocolDefinition;
+    try {
+      protocolDefinition = await input.validationStateReader.fetchProtocolDefinition(
+        input.tenant,
+        input.protocol,
+        input.messageTimestamp,
+      );
+    } catch (error) {
+      if (error instanceof DwnError && error.code === DwnErrorCode.ProtocolAuthorizationProtocolNotFound) {
+        input.recordLimitDefinitions.set(key, undefined);
+        return undefined;
+      }
+      throw error;
+    }
+
+    const ruleSet = getRuleSetAtPath(input.protocolPath, protocolDefinition.structure);
+    const recordLimit = ruleSet?.$recordLimit;
+    input.recordLimitDefinitions.set(
+      key,
+      recordLimit?.strategy === ProtocolRecordLimitStrategy.Reject ? recordLimit : undefined
+    );
+  }
+
+  return input.recordLimitDefinitions.get(key);
+}
+
+async function findOccupantRecordIds(input: {
+  messageStore: MessageStore;
+  tenant: string;
+  scope: RecordLimitScope;
+  recordLimit: ProtocolRecordLimitDefinition;
+}): Promise<Set<string>> {
+  const scopeFilter = buildRecordLimitScopeFilter(input.scope);
+  const messageSort = { dateCreated: SortDirection.Ascending };
+  const { messages: firstPage } = await input.messageStore.query(
+    input.tenant,
+    [scopeFilter],
+    messageSort,
+    { limit: input.recordLimit.max }
+  );
+  const firstPageCandidates = firstPage.filter(Records.isRecordsWrite);
+  if (firstPageCandidates.length === 0) {
+    return new Set();
+  }
+
+  const boundaryDateCreated = firstPageCandidates.at(-1)!.descriptor.dateCreated;
+  const beforeBoundary = firstPageCandidates.filter(
+    (message): boolean => message.descriptor.dateCreated < boundaryDateCreated
+  );
+  let boundaryCandidates = firstPageCandidates.filter(
+    (message): boolean => message.descriptor.dateCreated === boundaryDateCreated
+  );
+
+  if (firstPageCandidates.length === input.recordLimit.max) {
+    const { messages } = await input.messageStore.query(
+      input.tenant,
+      [{ ...scopeFilter, dateCreated: boundaryDateCreated }],
+      messageSort
+    );
+    boundaryCandidates = messages.filter(Records.isRecordsWrite);
+  }
+
+  boundaryCandidates.sort(compareRecordLimitCandidates);
+
+  const rankedCandidates = [
+    ...beforeBoundary,
+    ...boundaryCandidates,
+  ];
+
+  return new Set(
+    rankedCandidates
+      .slice(0, input.recordLimit.max)
+      .map((message): string => message.recordId)
+  );
+}
+
+function buildRecordLimitScopeFilter(scope: RecordLimitScope): Filter {
+  const filter: Filter = {
+    interface         : DwnInterfaceName.Records,
+    method            : DwnMethodName.Write,
+    isLatestBaseState : true,
+    protocol          : scope.protocol,
+    protocolPath      : scope.protocolPath,
+  };
+
+  if (scope.parentContextId !== '') {
+    filter.contextId = FilterUtility.constructPrefixFilterAsRangeFilter(scope.parentContextId);
+  }
+
+  return filter;
+}
+
+function getRecordLimitScopeFromFilter(filter: Filter): RecordLimitScope | undefined {
+  const { protocol, protocolPath } = filter;
+  if (typeof protocol !== 'string' || typeof protocolPath !== 'string') {
+    return undefined;
+  }
+
+  if (!protocolPath.includes('/')) {
+    return { protocol, protocolPath, parentContextId: '' };
+  }
+
+  const parentContextId = getExactParentContextIdFromFilter(filter);
+  if (parentContextId === undefined) {
+    return undefined;
+  }
+
+  return { protocol, protocolPath, parentContextId };
+}
+
+function getRecordLimitScope(message: RecordsWriteMessage): RecordLimitScope {
+  return {
+    protocol        : message.descriptor.protocol,
+    protocolPath    : message.descriptor.protocolPath,
+    parentContextId : Records.getParentContextFromOfContextId(message.contextId) ?? '',
+  };
+}
+
+function getExactParentContextIdFromFilter(filter: Filter): string | undefined {
+  const { contextId } = filter;
+  if (contextId === undefined || !FilterUtility.isRangeFilter(contextId)) {
+    return undefined;
+  }
+
+  if (typeof contextId.gte !== 'string' || contextId.lt !== `${contextId.gte}\uffff`) {
+    return undefined;
+  }
+
+  return contextId.gte;
+}
+
+function buildProjectedFilter(filter: Filter, occupantRecordIds: Set<string>): Filter | undefined {
+  let projectedRecordIds = Array.from(occupantRecordIds);
+  const existingRecordIdFilter = filter.recordId;
+  if (typeof existingRecordIdFilter === 'string') {
+    projectedRecordIds = occupantRecordIds.has(existingRecordIdFilter) ? [existingRecordIdFilter] : [];
+  } else if (Array.isArray(existingRecordIdFilter)) {
+    projectedRecordIds = existingRecordIdFilter
+      .filter((recordId): recordId is string => typeof recordId === 'string' && occupantRecordIds.has(recordId));
+  }
+
+  if (projectedRecordIds.length === 0) {
+    return undefined;
+  }
+
+  return {
+    ...filter,
+    recordId: projectedRecordIds,
+  };
+}
+
+function compareRecordLimitCandidates(left: RecordsWriteMessage, right: RecordsWriteMessage): number {
+  const dateComparison = lexicographicalCompare(left.descriptor.dateCreated, right.descriptor.dateCreated);
+  if (dateComparison !== 0) {
+    return dateComparison;
+  }
+
+  return lexicographicalCompare(left.recordId, right.recordId);
+}

package/src/utils/records.ts

@@ -36,6 +36,26 @@ export class Records {
     return isRecordsWrite;
   }
 
+  /**
+   * Gets the newest `RecordsWrite` from the given message set.
+   */
+  public static async getNewestRecordsWrite(messages: GenericMessage[]): Promise<RecordsWriteMessage | undefined> {
+    const recordsWriteMessages = messages.filter(Records.isRecordsWrite);
+    const newestRecordsWrite = await Message.getNewestMessage(recordsWriteMessages);
+    return newestRecordsWrite as RecordsWriteMessage | undefined;
+  }
+
+  /**
+   * Gets the newest `RecordsDelete` from the given message set.
+   */
+  public static async getNewestRecordsDelete(messages: GenericMessage[]): Promise<RecordsDeleteMessage | undefined> {
+    const recordsDeleteMessages = messages.filter((message): message is RecordsDeleteMessage =>
+      message.descriptor.interface === DwnInterfaceName.Records && message.descriptor.method === DwnMethodName.Delete
+    );
+    const newestRecordsDelete = await Message.getNewestMessage(recordsDeleteMessages);
+    return newestRecordsDelete as RecordsDeleteMessage | undefined;
+  }
+
   /**
    * Decrypts the encrypted data in a message reply.
    *
@@ -285,6 +305,35 @@ export class Records {
     return filterCopy;
   }
 
+  /**
+   * Nested protocol-path queries must pin one parent context. Otherwise the same
+   * protocol type is read across every parent instance.
+   */
+  public static validateNestedProtocolPathQueryScope(
+    filter: RecordsFilter,
+    errorCode: DwnErrorCode,
+    operationName: string,
+  ): void {
+    const { contextId, protocolPath } = filter;
+    if (!protocolPath?.includes('/')) {
+      return;
+    }
+
+    const expectedParentDepth = protocolPath.split('/').length - 1;
+    const contextIdSegments = contextId?.split('/');
+    if (
+      contextIdSegments?.length === expectedParentDepth &&
+      contextIdSegments.every(segment => segment.length > 0)
+    ) {
+      return;
+    }
+
+    throw new DwnError(
+      errorCode,
+      `${operationName} for nested protocol path '${protocolPath}' must include the direct parent contextId in the filter`
+    );
+  }
+
 
   public static isStartsWithFilter(filter: RecordsWriteTagsFilter): filter is StartsWithFilter {
     return typeof filter === 'object' && ('startsWith' in filter && typeof filter.startsWith === 'string');
@@ -530,25 +579,32 @@ export class Records {
   }
 
   /**
-   * Checks if the given RecordsDelete message can be performed against a record with the given newest existing state.
+   * Checks whether the given `RecordsDelete` is beaten by an existing tombstone for the record,
+   * per the tombstone lattice. A tombstone displaces any `RecordsWrite` regardless of timestamp
+   * (delete-wins). Among competing tombstones one canonical winner stands on every replica:
+   * a prune beats a plain delete regardless of timestamp — the cascade is a side effect, and a
+   * plain-newer winner would leave replicas that ran the cascade diverged from those that never
+   * would — and within the same class the newest tombstone wins, with `Message.isNewer`'s
+   * (messageTimestamp, CID) total order picking the same winner everywhere. Admission and
+   * resumable-task replay must share this predicate: state can advance between acceptance and
+   * replay, and replay must never admit a delete that admission would now reject.
    */
-  public static canPerformDeleteAgainstRecord(deleteToBePerformed: RecordsDeleteMessage, newestExistingMessage: GenericMessage | undefined): boolean {
-    if (newestExistingMessage === undefined) {
+  public static async isDeleteBeatenByExistingTombstone(
+    deleteToBePerformed: RecordsDeleteMessage,
+    newestExistingMessage: GenericMessage
+  ): Promise<boolean> {
+    if (newestExistingMessage.descriptor.method !== DwnMethodName.Delete) {
       return false;
     }
 
-    // can't perform delete if:
-    // attempting to delete on an already deleted record; or
-    // attempting to prune on an already pruned record;
-    if (newestExistingMessage.descriptor.method === DwnMethodName.Delete) {
-      if (deleteToBePerformed.descriptor.prune !== true) {
-        return false;
-      } else if ((newestExistingMessage as RecordsDeleteMessage).descriptor.prune === true) {
-        return false;
-      }
+    const incomingIsPrune = deleteToBePerformed.descriptor.prune === true;
+    const existingIsPrune = (newestExistingMessage as RecordsDeleteMessage).descriptor.prune === true;
+    if (incomingIsPrune !== existingIsPrune) {
+      return existingIsPrune;
     }
 
-    return true;
+    const incomingDeleteIsNewest = await Message.isNewer(deleteToBePerformed, newestExistingMessage);
+    return !incomingDeleteIsNewest;
   }
 
   /**