@enbox/dwn-sdk-js 0.4.10 → 0.4.12

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

@@ -13,7 +13,7 @@ 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, MessageStoreOptions, MessageStorePutResult } from '../types/message-store.js';
+import type { MessageStore, MessageStoreLatestStateTransition, MessageStoreOptions, MessageStorePutResult } from '../types/message-store.js';
 
 import * as block from 'multiformats/block';
 import * as cbor from '@ipld/dag-cbor';
@@ -441,6 +441,140 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
     });
   }
 
+  async commitLatestState(
+    tenant: string,
+    transition: MessageStoreLatestStateTransition,
+    options?: MessageStoreOptions
+  ): Promise<MessageStorePutResult> {
+    options?.signal?.throwIfAborted();
+
+    const partitions = await executeUnlessAborted(this.partitions(), options?.signal);
+    const index = await executeUnlessAborted(this.index(), options?.signal);
+
+    const { message, indexes } = transition.put;
+    const encodedMessageBlock = await executeUnlessAborted(block.encode({ value: message, codec: cbor, hasher: sha256 }), options?.signal);
+    const messageCid = Cid.parseCid(await Message.getCid(message)).toString();
+
+    // Validate and encode the retained replacements before entering the write lock.
+    const retains: { messageCid: string, message: GenericMessage, indexes: KeyValues, blockBytes: Uint8Array }[] = [];
+    for (const retain of transition.retains ?? []) {
+      const computedMessageCid = Cid.parseCid(await Message.getCid(retain.message)).toString();
+      const normalizedMessageCid = Cid.parseCid(retain.messageCid).toString();
+      if (computedMessageCid !== normalizedMessageCid) {
+        throw new DwnError(
+          DwnErrorCode.MessageStoreUpdateMessageAndIndexesCidMismatch,
+          `replacement message CID ${computedMessageCid} does not match target CID ${normalizedMessageCid}`
+        );
+      }
+
+      const encodedRetainBlock = await executeUnlessAborted(block.encode({ value: retain.message, codec: cbor, hasher: sha256 }), options?.signal);
+      retains.push({
+        messageCid : normalizedMessageCid,
+        message    : retain.message,
+        indexes    : retain.indexes,
+        blockBytes : encodedRetainBlock.bytes,
+      });
+    }
+    const deleteCids = (transition.deletes ?? []).map((cidString): string => CID.parse(cidString).toString());
+
+    return this.withTenantWriteLock(tenant, async () => {
+      options?.signal?.throwIfAborted();
+
+      const tenantBlocks = await partitions.blocks.partition(tenant);
+      const tenantLog = await partitions.log.partition(tenant);
+      const tenantCidToSeq = await partitions.cidToSeq.partition(tenant);
+
+      const operations: LevelWrapperBatchOperation<string>[] = [];
+      const fingerprintFolds: { messageCid: string, scopes: string[] }[] = [];
+
+      // The new message insert. A duplicate inserts nothing but still applies the retains and
+      // deletes below, so replaying a transition heals one that previously stopped mid-plan.
+      const existingSeq = await tenantCidToSeq.get(messageCid, options);
+      const inserted = existingSeq === undefined;
+      let seq = 0n;
+      if (inserted) {
+        const head = await this.getHead(partitions, tenant);
+        seq = head + 1n;
+        const fingerprintScopes = Replication.computeFingerprintScopes(message, indexes);
+
+        const logEntry: LogEntryValue = {
+          seq: seq.toString(),
+          messageCid,
+          indexes,
+          fingerprintScopes,
+        };
+
+        operations.push(
+          tenantBlocks.createOperation({ type: 'put', key: messageCid, value: encodedMessageBlock.bytes }) as unknown as LevelWrapperBatchOperation<string>,
+          ...await index.createPutOperations(tenant, messageCid, indexes),
+          tenantLog.createOperation({ type: 'put', key: Replication.encodePositionKey(seq), value: JSON.stringify(logEntry) }),
+          tenantCidToSeq.createOperation({ type: 'put', key: messageCid, value: seq.toString() }),
+          partitions.heads.createOperation({ type: 'put', key: tenant, value: seq.toString() }),
+        );
+        fingerprintFolds.push({ messageCid, scopes: fingerprintScopes });
+      }
+
+      // Retained displaced writes: same-CID in-place replacement, exactly as `updateMessageAndIndexes`.
+      for (const retain of retains) {
+        const { entry, positionKey } = await this.getLogEntryForMutation(
+          partitions, tenant, retain.messageCid, DwnErrorCode.MessageStoreUpdateMessageAndIndexesMessageNotFound
+        );
+        Replication.assertFingerprintScopesUntouched(entry.fingerprintScopes, retain.message, retain.messageCid, retain.indexes);
+
+        const updatedEntry: LogEntryValue = { ...entry, indexes: retain.indexes };
+        operations.push(
+          tenantBlocks.createOperation({ type: 'put', key: retain.messageCid, value: retain.blockBytes }) as unknown as LevelWrapperBatchOperation<string>,
+          ...await index.createDeleteOperations(tenant, retain.messageCid),
+          ...await index.createPutOperations(tenant, retain.messageCid, retain.indexes),
+          tenantLog.createOperation({ type: 'put', key: positionKey, value: JSON.stringify(updatedEntry) }),
+        );
+      }
+
+      // Non-retained displaced rows: full removal, exactly as `delete`. Absent rows are no-ops.
+      for (const deleteCid of deleteCids) {
+        const seqString = await tenantCidToSeq.get(deleteCid, options);
+        if (seqString === undefined) {
+          continue;
+        }
+
+        const positionKey = Replication.encodePositionKey(BigInt(seqString));
+        const serializedEntry = await tenantLog.get(positionKey);
+        if (serializedEntry === undefined) {
+          throw new DwnError(
+            DwnErrorCode.MessageStoreDeleteLogEntryMissing,
+            `cid index for tenant ${tenant} points to missing log entry at seq ${seqString} (CID ${deleteCid})`
+          );
+        }
+
+        const entry = JSON.parse(serializedEntry) as LogEntryValue;
+        operations.push(
+          tenantBlocks.createOperation({ type: 'del', key: deleteCid }) as unknown as LevelWrapperBatchOperation<string>,
+          ...await index.createDeleteOperations(tenant, deleteCid),
+          tenantLog.createOperation({ type: 'del', key: positionKey }),
+          tenantCidToSeq.createOperation({ type: 'del', key: deleteCid }),
+        );
+        fingerprintFolds.push({ messageCid: deleteCid, scopes: entry.fingerprintScopes });
+      }
+
+      operations.push(...await this.createFingerprintFoldOperationsForMessages(partitions, tenant, fingerprintFolds));
+
+      if (operations.length > 0) {
+        await partitions.root.batch(operations);
+      }
+
+      if (!inserted) {
+        return { status: 'duplicate' as const };
+      }
+
+      this.publishWake(tenant, seq);
+
+      return {
+        status   : 'inserted' as const,
+        position : await this.buildToken(tenant, seq, messageCid),
+      };
+    });
+  }
+
   async updateIndexes(
     tenant: string,
     messageCid: string,
@@ -907,12 +1041,33 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
     messageCid: string,
     scopes: string[],
   ): Promise<LevelWrapperBatchOperation<string>[]> {
-    const contribution = await Replication.hashMessageCid(messageCid);
-    const tenantFingerprints = await partitions.fingerprints.partition(tenant);
+    return this.createFingerprintFoldOperationsForMessages(partitions, tenant, [{ messageCid, scopes }]);
+  }
 
+  /**
+   * Creates the batch operations that fold multiple messages' contributions into their fingerprint
+   * domains. Contributions targeting the same domain are XOR-combined before the single
+   * read-fold-write per domain — concatenating per-message fold operations into one batch would
+   * let the last write to a shared domain silently discard the earlier folds.
+   */
+  private async createFingerprintFoldOperationsForMessages(
+    partitions: StorePartitions,
+    tenant: string,
+    folds: { messageCid: string, scopes: string[] }[],
+  ): Promise<LevelWrapperBatchOperation<string>[]> {
+    const combinedContributionByKey = new Map<string, Uint8Array>();
+    for (const { messageCid, scopes } of folds) {
+      const contribution = await Replication.hashMessageCid(messageCid);
+      for (const scope of scopes) {
+        const key = MessageStoreLevel.fingerprintKey(scope);
+        const combined = combinedContributionByKey.get(key);
+        combinedContributionByKey.set(key, combined === undefined ? contribution : Replication.xorFingerprint(combined, contribution));
+      }
+    }
+
+    const tenantFingerprints = await partitions.fingerprints.partition(tenant);
     const operations: LevelWrapperBatchOperation<string>[] = [];
-    for (const scope of scopes) {
-      const key = MessageStoreLevel.fingerprintKey(scope);
+    for (const [key, contribution] of combinedContributionByKey) {
       const storedHex = await tenantFingerprints.get(key);
       const current = storedHex === undefined ? Replication.emptyFingerprint() : Replication.hexToFingerprint(storedHex);
       const folded = Replication.xorFingerprint(current, contribution);

package/src/store/storage-controller.ts

@@ -1,8 +1,8 @@
 import type { DataStore } from '../types/data-store.js';
-import type { Filter } from '../types/query-types.js';
 import type { GenericMessage } from '../types/message-types.js';
-import type { MessageStore } from '../types/message-store.js';
 import type { ProgressToken } from '../types/subscriptions.js';
+import type { Filter, KeyValues } from '../types/query-types.js';
+import type { MessageStore, MessageStorePutResult } from '../types/message-store.js';
 import type { RecordsDeleteMessage, RecordsWriteMessage } from '../types/records-types.js';
 
 import { DwnConstant } from '../core/dwn-constant.js';
@@ -80,7 +80,12 @@ export class StorageController {
     // tombstones carry no visibility facts in their descriptors, so the retained write is the
     // durable source of truth for later prune/replay/replication index reconstruction.
     const indexes = recordsDelete.constructIndexes(initialWrite, newestPreDeleteWrite);
-    const { position } = await this.messageStore.put(tenant, message, indexes);
+
+    // store the tombstone and displace every other message for this record in one atomic commit,
+    // retaining the writes needed for replay and future tombstone visibility
+    const { position } = await StorageController.commitLatestStateTransition(
+      tenant, existingMessages, { message, indexes }, [newestPreDeleteWrite], this.messageStore, this.dataStore
+    );
 
     if (message.descriptor.prune) {
       // purge/hard-delete all descendant records. Cascade is intentionally protocol-agnostic:
@@ -92,11 +97,6 @@ export class StorageController {
       );
     }
 
-    // displace every other message for this record, retaining the writes needed for replay and future tombstone visibility
-    await StorageController.deleteDisplacedMessagesAndRetainWrites(
-      tenant, existingMessages, message, this.messageStore, this.dataStore, [newestPreDeleteWrite]
-    );
-
     return { position };
   }
 
@@ -285,56 +285,70 @@ export class StorageController {
   }
 
   /**
-   * Deletes all messages in `existingMessages` that the `retainedMessage` displaces, while keeping
-   * the initial write and the caller-supplied writes as non-latest state for future replay and
-   * tombstone visibility reconstruction. Displacement is deliberately NOT a timestamp comparison:
-   * a RecordsDelete displaces even a newer RecordsWrite (delete-wins convergence), and on
-   * resumable-task replay the retained message itself is back in `existingMessages` and must
-   * survive — so membership is decided by CID.
+   * Stores the new latest message and displaces every other message in `existingMessages` as ONE
+   * atomic message-store commit: the initial write and the caller-supplied writes are retained as
+   * non-latest state for future replay and tombstone visibility reconstruction, and the remaining
+   * displaced messages are deleted. Readers can never observe an intermediate state where both the
+   * new message and a displaced message carry latest-state indexes.
+   *
+   * Displacement is deliberately NOT a timestamp comparison: a RecordsDelete displaces even a
+   * newer RecordsWrite (delete-wins convergence), and on resumable-task replay the new message
+   * itself is back in `existingMessages` and must survive — so membership is decided by CID.
+   *
+   * Displaced messages' unreferenced data is deleted from the data store only AFTER the commit:
+   * a crash in between leaves at most an orphaned data blob, never a live row whose data is gone.
    */
-  public static async deleteDisplacedMessagesAndRetainWrites(
+  public static async commitLatestStateTransition(
     tenant: string,
     existingMessages: GenericMessage[],
-    retainedMessage: GenericMessage,
+    newMessage: { message: GenericMessage, indexes: KeyValues },
+    additionalRetainedRecordsWrites: RecordsWriteMessage[],
     messageStore: MessageStore,
     dataStore: DataStore,
-    additionalRetainedRecordsWrites: RecordsWriteMessage[],
-  ): Promise<void> {
-    const retainedMessageCid = await Message.getCid(retainedMessage);
+  ): Promise<MessageStorePutResult> {
+    const newMessageCid = await Message.getCid(newMessage.message);
     const additionalRetainedRecordsWriteCids = new Set<string>();
     for (const retainedRecordsWrite of additionalRetainedRecordsWrites) {
       additionalRetainedRecordsWriteCids.add(await Message.getCid(retainedRecordsWrite));
     }
 
     // NOTE: under normal operation, there should only be at most two existing records per `recordId` (initial + a potential subsequent write/delete),
-    // but the DWN may crash before `delete()` is called below, so we use a loop as a tactic to clean up lingering data as needed
+    // but the plan-then-commit shape below heals any lingering rows a previous partial application left behind.
+    const retains: { messageCid: string, message: GenericMessage, indexes: KeyValues }[] = [];
+    const deletes: string[] = [];
+    const displacedMessages: GenericMessage[] = [];
     for (const message of existingMessages) {
       const messageCid = await Message.getCid(message);
-      const messageIsDisplaced = messageCid !== retainedMessageCid;
-      if (messageIsDisplaced) {
-        // the easiest implementation here is delete each old messages
-        // and re-create it with the right index (isLatestBaseState = 'false') if the message is a retained write,
-        // but there is room for better/more efficient implementation here
-
-        await StorageController.deleteFromDataStoreIfNeeded(dataStore, tenant, message, retainedMessage);
-
-        // Retained writes must stay in the message store and state index so future deletes and
-        // replicas can reconstruct tombstone visibility, but they must no longer be latest state.
-        const shouldKeepAsNonLatestWrite =
-          await RecordsWrite.isInitialWrite(message) ||
-          additionalRetainedRecordsWriteCids.has(messageCid);
-        if (shouldKeepAsNonLatestWrite) {
-          const retainedRecordsWriteMessage = StorageController.stripInlineData(message as RecordsWriteMessage);
-          const existingRecordsWrite = await RecordsWrite.parse(retainedRecordsWriteMessage);
-          const isLatestBaseState = false;
-          const indexes = await existingRecordsWrite.constructIndexes(isLatestBaseState);
-          await messageStore.updateMessageAndIndexes(tenant, messageCid, retainedRecordsWriteMessage, indexes);
-        } else {
-          // delete message from message store
-          await messageStore.delete(tenant, messageCid);
-        }
+      const messageIsDisplaced = messageCid !== newMessageCid;
+      if (!messageIsDisplaced) {
+        continue;
+      }
+
+      displacedMessages.push(message);
+
+      // Retained writes must stay in the message store and state index so future deletes and
+      // replicas can reconstruct tombstone visibility, but they must no longer be latest state.
+      const shouldKeepAsNonLatestWrite =
+        await RecordsWrite.isInitialWrite(message) ||
+        additionalRetainedRecordsWriteCids.has(messageCid);
+      if (shouldKeepAsNonLatestWrite) {
+        const retainedRecordsWriteMessage = StorageController.stripInlineData(message as RecordsWriteMessage);
+        const existingRecordsWrite = await RecordsWrite.parse(retainedRecordsWriteMessage);
+        const isLatestBaseState = false;
+        const indexes = await existingRecordsWrite.constructIndexes(isLatestBaseState);
+        retains.push({ messageCid, message: retainedRecordsWriteMessage, indexes });
+      } else {
+        deletes.push(messageCid);
       }
     }
+
+    const putResult = await messageStore.commitLatestState(tenant, { put: newMessage, retains, deletes });
+
+    for (const message of displacedMessages) {
+      await StorageController.deleteFromDataStoreIfNeeded(dataStore, tenant, message, newMessage.message);
+    }
+
+    return putResult;
   }
 
   private static stripInlineData(message: RecordsWriteMessage): RecordsWriteMessage {

package/src/types/message-store.ts

@@ -24,6 +24,28 @@ export type MessageStorePutResult = {
   position?: ProgressToken;
 };
 
+/**
+ * A latest-state transition applied by {@link MessageStore.commitLatestState}: the insert of a new
+ * message together with the displacement of the messages it supersedes.
+ */
+export type MessageStoreLatestStateTransition = {
+  /**
+   * The new message to insert, with its insert-time indexes.
+   */
+  put: { message: GenericMessage; indexes: KeyValues };
+
+  /**
+   * Displaced writes retained as non-latest state: same-CID in-place replacements
+   * (same row, same log sequence) applied with the insert.
+   */
+  retains?: { messageCid: string; message: GenericMessage; indexes: KeyValues }[];
+
+  /**
+   * Message CIDs of displaced messages that are not retained, deleted with the insert.
+   */
+  deletes?: string[];
+};
+
 export interface MessageStore {
   /**
    * opens a connection to the underlying store
@@ -46,6 +68,21 @@ export interface MessageStore {
     options?: MessageStoreOptions
   ): Promise<MessageStorePutResult>;
 
+  /**
+   * Atomically inserts a new message and displaces the messages it supersedes: retained writes are
+   * replaced in place with their demoted state, and the remaining displaced rows are deleted, all
+   * in one commit. Readers can never observe an intermediate state where both the new message and
+   * a displaced message carry latest-state indexes.
+   *
+   * When the new message already exists, returns `duplicate` and still applies the retains and
+   * deletes, so replaying a transition heals one that was only partially planned before a crash.
+   */
+  commitLatestState(
+    tenant: string,
+    transition: MessageStoreLatestStateTransition,
+    options?: MessageStoreOptions
+  ): Promise<MessageStorePutResult>;
+
   /**
    * Fetches a single message by `cid` from the underlying store.
    * Returns `undefined` no message was found.

package/src/utils/initial-write-attachment.ts

@@ -0,0 +1,64 @@
+import type { MessageStore } from '../types/message-store.js';
+import type { RecordsQueryReplyEntry } from '../types/records-types.js';
+
+import { DwnErrorCode } from '../core/dwn-error.js';
+import { Messages } from './messages.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
+
+/**
+ * Attaches each returned update's retained initial write, resolved for the whole result page in
+ * one batched lookup by the stable identity `entryId === recordId` — unlike the mutable
+ * latest-state index, that identity holds at every point of the record's lifecycle.
+ *
+ * An update whose initial write is genuinely missing (store corruption) is omitted with a
+ * warning rather than failing the whole reply.
+ */
+export async function attachInitialWrites(input: {
+  messageStore: MessageStore;
+  tenant: string;
+  recordsWrites: RecordsQueryReplyEntry[];
+  operationName: 'RecordsQuery' | 'RecordsSubscribe';
+}): Promise<RecordsQueryReplyEntry[]> {
+  const updateRecordIds = new Set<string>();
+  const initialWriteState = new Map<RecordsQueryReplyEntry, boolean>();
+  for (const recordsWrite of input.recordsWrites) {
+    const isInitialWrite = await RecordsWrite.isInitialWrite(recordsWrite);
+    initialWriteState.set(recordsWrite, isInitialWrite);
+    if (!isInitialWrite) {
+      updateRecordIds.add(recordsWrite.recordId);
+    }
+  }
+
+  if (updateRecordIds.size === 0) {
+    return input.recordsWrites;
+  }
+
+  const initialWriteByRecordId = new Map<string, RecordsQueryReplyEntry>();
+  const { messages } = await input.messageStore.query(input.tenant, [{ entryId: [...updateRecordIds] }]);
+  for (const message of messages) {
+    const initialWrite = message as RecordsQueryReplyEntry;
+    initialWriteByRecordId.set(initialWrite.recordId, initialWrite);
+  }
+
+  const completeRecordsWrites: RecordsQueryReplyEntry[] = [];
+  for (const recordsWrite of input.recordsWrites) {
+    if (initialWriteState.get(recordsWrite) === true) {
+      completeRecordsWrites.push(recordsWrite);
+      continue;
+    }
+
+    const storedInitialWrite = initialWriteByRecordId.get(recordsWrite.recordId);
+    if (storedInitialWrite === undefined) {
+      console.warn(
+        `${DwnErrorCode.RecordsWriteGetInitialWriteNotFound}: ` +
+        `${input.operationName} skipped record ${recordsWrite.recordId}`,
+      );
+      continue;
+    }
+
+    const { message: initialWrite } = Messages.detachEncodedData(storedInitialWrite);
+    completeRecordsWrites.push({ ...recordsWrite, initialWrite: initialWrite as RecordsQueryReplyEntry });
+  }
+
+  return completeRecordsWrites;
+}