@hydranium/protocol 1.0.0-next.148 → 1.0.0-next.155

package/src/client/data-session.ts

@@ -9,9 +9,9 @@
 
 import { type Disposable, Emitter, type Event } from 'vscode-jsonrpc';
 import { type Clock, SystemClock } from '../clock';
-import type { DataServerProtocol, DiagnosticOf, TransferDocumentDirtyChangedEvent } from '../data';
-import { SessionClosedError } from '../errors';
-import type { SnapshotVersion } from '../model-service/based-on';
+import type { DataServerProtocol, DiagnosticOf, TransferDocumentDirtyChangedEvent, TransferDocumentUpdatedEvent } from '../data';
+import { isConflictError, SessionClosedError } from '../errors';
+import { type BasedOn, isSnapshotVersion, type SnapshotVersion } from '../model-service/based-on';
 import { type ResolvedMessage, defineMessage, describeError, resolve } from '../messages/primitives';
 import type { OpenModelArgs } from '../model-server';
 import type { MaybePromise } from '../util';
@@ -21,7 +21,8 @@ import type { TransferElement } from '../transfer-element';
 
 /**
  * A session could not re-open a document it had open after its connection
- * dropped.
+ * dropped, and forgot it; or could not write it again for another reason than
+ * a conflict, and keeps its unsaved edits for the next restore.
  */
 export const DATA_SESSION_RESTORE_FAILED = defineMessage(
    'hydranium/protocol/data-session-restore-failed',
@@ -29,11 +30,12 @@ export const DATA_SESSION_RESTORE_FAILED = defineMessage(
 );
 
 /**
- * A session re-opened documents after its connection dropped whose version had
- * moved on since the session's last unsaved write to them: another client
- * edited them, even while the session was still connected, the server reverted
- * them to what is on disk, or the server restarted. The session's unsaved edits
- * may be gone.
+ * A session re-opened documents after its connection dropped and cannot put
+ * back what it wrote to them since their last save: another client changed
+ * them, even while the session was still connected; the session could not
+ * tell the text its writes started from, or lost another document written with
+ * them; or the write it sent again conflicted. The session's unsaved edits may
+ * be gone, and it no longer holds them.
  */
 export const DATA_SESSION_UNSAVED_LOST = defineMessage(
    'hydranium/protocol/data-session-unsaved-lost',
@@ -98,6 +100,39 @@ export type DataSessionDocument<
    TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
 > = TransferDocument<TTransfer, DiagnosticOf<TServer>>;
 
+/**
+ * What a {@link DataSession} keeps of a URI it wrote since the URI's last save,
+ * to write it again after a reconnect that lost it.
+ */
+export interface DataSessionUnsavedWrite<
+   TTransfer extends TransferElement,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
+> {
+   /**
+    * The {@link TransferDocument.textHash} of the text the first of these
+    * writes was based on. `undefined` when the session could not tell, for a
+    * write based on `'anything'` or on a version it could not read back, and
+    * such a write is never sent again: the session cannot tell another
+    * client's text from the text it wrote over.
+    */
+   readonly baseHash: string | undefined;
+   readonly answer: Pick<DataSessionDocument<TTransfer, TServer>, 'version' | 'textHash'>;
+   /**
+    * The call that made the last write, and for an `updateDocuments` call this
+    * URI's index in it. Records whose `updates` is the same object were
+    * written together and are sent again together, so a restore never applies
+    * part of a set.
+    */
+   readonly call:
+      | { readonly update: DataSessionUpdateArgs<TTransfer, TServer> }
+      | { readonly updates: DataSessionUpdatesArgs<TTransfer, TServer>; readonly index: number };
+}
+
+/** Where `write` stands in the `updateDocuments` call it was last written by; `0` for a single update. */
+function indexOf(write: DataSessionUnsavedWrite<TransferElement, DataServerProtocol<TransferElement>>): number {
+   return 'index' in write.call ? write.call.index : 0;
+}
+
 /**
  * What a {@link DataSession} needs from the connection that minted it.
  *
@@ -121,6 +156,19 @@ export interface DataSessionHost<TTransfer extends TransferElement, TServer exte
     * has open costs at most one repeat of a state the client already has.
     */
    forgetDirty?(uri: string): void;
+   /**
+    * Fires with each flip of a document's dirty state the server sends. A
+    * session drops the unsaved write it keeps of a document that turns
+    * clean; without this event it keeps it, and a restore after another
+    * client's save of the document can report the write lost.
+    */
+   readonly onDidChangeDirty?: Event<TransferDocumentDirtyChangedEvent>;
+   /**
+    * Fires with each update event the server sends. A session drops the
+    * unsaved write it keeps of a document another client wrote over; without
+    * this event it keeps it, and a restore reports the write lost.
+    */
+   readonly onDidUpdateDocument?: Event<TransferDocumentUpdatedEvent<TTransfer, DiagnosticOf<TServer>>>;
 }
 
 /**
@@ -199,11 +247,21 @@ export class DataSession<
     * it under the open that is still being made.
     */
    protected readonly openingUris = new Map<string, number>();
+   /** Per URI written since its last save, what {@link restore} needs to write it again. */
+   protected readonly unsavedWrites = new Map<string, DataSessionUnsavedWrite<TTransfer, TServer>>();
    /**
-    * Per URI written since its last save, the version the server answered this
-    * session's last write with; see {@link restore}.
+    * Per URI this session has open, the version and text hash of the last
+    * document one of its own calls was answered with, which spares the read a
+    * first unsaved write otherwise makes for its base; see {@link baseHashOf}.
     */
-   protected readonly unsavedWrites = new Map<string, SnapshotVersion>();
+   protected readonly lastAnswers = new Map<string, Pick<DataSessionDocument<TTransfer, TServer>, 'version' | 'textHash'>>();
+   /**
+    * Per URI this session has open, the version its last save of it was
+    * answered with; see {@link recordWrite}. Only a save sets it: an open
+    * answers at the version of a write still in flight as well, and that
+    * write is not saved.
+    */
+   protected readonly savedVersions = new Map<string, SnapshotVersion>();
    /** Per URI, this session's calls still in flight on it, which a close waits for. */
    protected readonly inFlight = new Map<string, Set<Promise<unknown>>>();
    /** This session's saves still in flight, which a host's exit waits for; see {@link hasSavesInFlight}. */
@@ -238,12 +296,19 @@ export class DataSession<
     * over a connection that is going away.
     */
    protected detached = false;
+   /** The subscription to the host's `onDidChangeDirty`, disposed with the session. */
+   protected readonly dirtySubscription?: Disposable;
+   /** The subscription to the host's `onDidUpdateDocument`, disposed with the session. */
+   protected readonly updateSubscription?: Disposable;
 
    constructor(
       readonly clientId: string,
       protected readonly host: DataSessionHost<TTransfer, TServer>,
       readonly label: string
-   ) {}
+   ) {
+      this.dirtySubscription = host.onDidChangeDirty?.(event => this.forgetSavedWrite(event));
+      this.updateSubscription = host.onDidUpdateDocument?.(event => this.forgetSupersededWrite(event));
+   }
 
    /**
     * The connected, READY server proxy once this session is registered on it,
@@ -323,6 +388,7 @@ export class DataSession<
       }
       this.openUris.add(uri);
       this.serverUris.set(uri, document.uri);
+      this.lastAnswers.set(uri, { version: document.version, textHash: document.textHash });
       // Keyed as the server keys its notifications, which may not be how the
       // caller spelled the URI.
       this.host.forgetDirty?.(document.uri);
@@ -344,6 +410,8 @@ export class DataSession<
       this.openUris.delete(args.uri);
       this.serverUris.delete(args.uri);
       this.unsavedWrites.delete(args.uri);
+      this.lastAnswers.delete(args.uri);
+      this.savedVersions.delete(args.uri);
       this.host.forgetDirty?.(serverUri);
       const server = await this.connected();
       await server.closeModelDocument({ ...args, clientId: this.clientId });
@@ -374,8 +442,10 @@ export class DataSession<
    updateDocument(args: DataSessionUpdateArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>> {
       return this.track([args.uri], async () => {
          const server = await this.connected();
+         const update = { ...args };
+         const baseHash = await this.baseHashOf(server, args.uri, args.basedOn);
          const document = await server.updateModelDocument({ ...args, clientId: this.clientId });
-         this.unsavedWrites.set(args.uri, document.version);
+         this.recordWrite(args.uri, document, baseHash, { update });
          return document;
       });
    }
@@ -389,9 +459,13 @@ export class DataSession<
       return this.track(
          args.updates.map(update => update.uri),
          async () => {
+            // One copy for the whole call: the copy's identity is what ties its
+            // records together.
+            const updates = { ...args, updates: args.updates.map(update => ({ ...update })) };
             const server = await this.connected();
+            const baseHashes = await Promise.all(args.updates.map(update => this.baseHashOf(server, update.uri, update.basedOn)));
             const documents = await server.updateModelDocuments({ ...args, clientId: this.clientId });
-            args.updates.forEach((update, i) => this.unsavedWrites.set(update.uri, documents[i].version));
+            args.updates.forEach((update, index) => this.recordWrite(update.uri, documents[index], baseHashes[index], { updates, index }));
             return documents;
          }
       );
@@ -401,8 +475,19 @@ export class DataSession<
    saveDocument(args: DataSessionSaveArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>> {
       const saving = this.track([args.uri], async () => {
          const server = await this.connected();
+         const unsaved = this.unsavedWrites.get(args.uri);
          const document = await server.saveModelDocument({ ...args, clientId: this.clientId });
-         this.unsavedWrites.delete(args.uri);
+         // A write that answered while the save ran made a record the save
+         // may not have persisted, which a restore still needs.
+         if (this.unsavedWrites.get(args.uri) === unsaved) {
+            this.unsavedWrites.delete(args.uri);
+         }
+         this.lastAnswers.set(args.uri, { version: document.version, textHash: document.textHash });
+         // The higher of two saves' answers, which may arrive out of order.
+         const saved = this.savedVersions.get(args.uri);
+         if (saved === undefined || document.version > saved) {
+            this.savedVersions.set(args.uri, document.version);
+         }
          return document;
       });
       this.savesInFlight.add(saving);
@@ -491,14 +576,22 @@ export class DataSession<
       this.openUris.clear();
       this.serverUris.clear();
       this.unsavedWrites.clear();
+      this.lastAnswers.clear();
+      this.savedVersions.clear();
       if (!this.disposed) {
          this.disposed = true;
          this.fireDispose();
       }
    }
 
-   /** Fire {@link onDidDispose} and dispose its emitter, so a second call fires nothing. */
+   /**
+    * Dispose {@link dirtySubscription} and {@link updateSubscription}, fire
+    * {@link onDidDispose} and dispose its emitter, so a second call fires
+    * nothing.
+    */
    protected fireDispose(): void {
+      this.dirtySubscription?.dispose();
+      this.updateSubscription?.dispose();
       this.disposeEmitter.fire(undefined);
       this.disposeEmitter.dispose();
    }
@@ -515,6 +608,56 @@ export class DataSession<
       }
    }
 
+   /**
+    * Drop the record in {@link unsavedWrites} of a document this session has
+    * open once the server says it turned clean: it holds no unsaved text
+    * then, and a record kept would have a restore report the write lost once
+    * another client's save changed the file.
+    *
+    * The server sends a flip only for a document someone watches, so a
+    * document the session writes without watching it keeps its record, and
+    * can still be reported lost that way.
+    */
+   protected forgetSavedWrite(event: TransferDocumentDirtyChangedEvent): void {
+      if (event.dirty) {
+         return;
+      }
+      // The flip names the server's key, which is not always the caller's
+      // spelling that the records are kept under.
+      for (const [uri, serverUri] of this.serverUris) {
+         if (serverUri === event.uri) {
+            this.unsavedWrites.delete(uri);
+         }
+      }
+   }
+
+   /**
+    * Drop the record in {@link unsavedWrites} of a document another client
+    * wrote over while the connection held: its write replaced the session's,
+    * so a restore has nothing of the session's to put back, and a record kept
+    * would have it report the write lost to the reconnect. A write superseded
+    * before its answer needs nothing: the answer names the other client's
+    * text, which the record then holds.
+    *
+    * Only a `'changed'` event from another client counts, and only where the
+    * document no longer holds the write: the session's own echo, and an
+    * integrity repair already in the write's answer, replaced nothing, and a
+    * `'rebuilt'` event carries no new text. Like {@link forgetSavedWrite}, it
+    * depends on the server sending the event, which it does only for a
+    * document someone watches.
+    */
+   protected forgetSupersededWrite(event: TransferDocumentUpdatedEvent<TTransfer, DiagnosticOf<TServer>>): void {
+      if (event.reason !== 'changed' || this.isOwnEcho(event.sourceClientId)) {
+         return;
+      }
+      for (const [uri, serverUri] of this.serverUris) {
+         const write = this.unsavedWrites.get(uri);
+         if (serverUri === event.document.uri && write && this.restoreOutcome(write, event.document) !== 'kept') {
+            this.unsavedWrites.delete(uri);
+         }
+      }
+   }
+
    /**
     * Register on `server`, and after a reconnect restore what the ended session
     * had. Calls issued meanwhile wait for this.
@@ -527,67 +670,258 @@ export class DataSession<
    }
 
    /**
-    * Re-open and re-watch every document the session had open, and tell the
-    * host which of them lost what the session wrote since their last save.
+    * Re-open and re-watch every document the session had open, write again
+    * what it wrote since their last save where the re-open lost it, and tell
+    * the host which of them lost it for good.
     *
-    * The unsaved text is not sent again. A document whose re-opened version is
-    * the one the session's last write was answered with still holds that
-    * write. Any other version means the text changed after that write:
-    * another client edited it, even while the session was still connected;
-    * the server reverted it to disk when the session's open closed as the
-    * document's last; or the server restarted and numbers versions afresh.
-    * Re-sending based on the write's own version then always conflicts, and
-    * based on the re-opened version it would overwrite whatever changed, so
-    * neither is done.
+    * Decided per document by the re-opened {@link TransferDocument.textHash},
+    * in {@link restoreOutcome}. Versions cannot decide a write: a revert moves
+    * the version on and a restarted server numbers afresh, so the version the
+    * last write was answered with never matches where a write is needed, and
+    * any other version may be another client's edit, which a write would
+    * overwrite.
     *
-    * No caller is waiting, so both outcomes go through the host: one report
+    * Only what the drop cost is reported: a write another client wrote over
+    * while the connection held has no record left by then, see
+    * {@link forgetSupersededWrite}.
+    *
+    * A write is sent again based on the re-opened version, as an ordinary
+    * write, so an edit arriving in between conflicts, and a conflict is not
+    * retried. Documents last written by one {@link updateDocuments} are sent
+    * again by one, and only when every one of them may be; a document that
+    * could not be re-opened blocks its set.
+    *
+    * No caller is waiting, so the outcomes go through the host: one report
     * naming every document whose unsaved text is gone, whose record is then
-    * dropped, and one per document that could not be re-opened, which is
-    * forgotten.
+    * dropped, and one per document that could not be re-opened or written
+    * again for another reason than a conflict. A document that could not be
+    * re-opened is forgotten; a failed write keeps its record, for the next
+    * restore to decide again.
     *
     * Each document's dirty state goes to the host too, read once the watch is
-    * in place: a flip while the connection was down, or between the re-open
-    * and the watch, reached no one, and the re-open's own answer misses the
-    * second.
+    * in place and any write is sent: a flip while the connection was down, or
+    * between the re-open and the watch, reached no one, and the re-open's own
+    * answer misses the second. Read before the write, it would tell the client
+    * a document is clean that the write is about to make dirty again.
     */
    protected async restore(server: RpcProxy<TServer>): Promise<void> {
-      const lost: string[] = [];
+      const writes = [...this.unsavedWrites];
+      // No write sent before the drop answers any more, and a restarted
+      // server numbers afresh, below the versions saved before it.
+      this.savedVersions.clear();
+      const reopened = new Map<string, DataSessionDocument<TTransfer, TServer>>();
       for (const uri of [...this.openUris]) {
          try {
             const document = await server.openModelDocument({ uri, clientId: this.clientId });
             await server.watchModelDocument({ uri, clientId: this.clientId });
             if (this.openUris.has(uri)) {
                this.serverUris.set(uri, document.uri);
+               this.lastAnswers.set(uri, { version: document.version, textHash: document.textHash });
             }
-            // A failed read leaves the client's dirty state as it was; the
-            // document is restored all the same.
-            const current = await server.getModelDocument({ uri }).catch(() => undefined);
-            if (current?.dirty !== undefined) {
-               try {
-                  this.host.restoreDirty?.({ uri: current.uri, dirty: current.dirty });
-               } catch {
-                  // The client's listener failed, not the restore: the server
-                  // has the document open and watched, so it stays restored.
-               }
-            }
-            const written = this.unsavedWrites.get(uri);
-            if (written !== undefined && written !== document.version) {
-               lost.push(uri);
-               this.unsavedWrites.delete(uri);
-            }
+            reopened.set(uri, document);
          } catch (error: unknown) {
+            // Its record goes with its set's, in `reapply`, which it blocks.
             this.openUris.delete(uri);
             this.serverUris.delete(uri);
-            this.unsavedWrites.delete(uri);
+            this.lastAnswers.delete(uri);
+            this.savedVersions.delete(uri);
             this.host.reportError?.(error, resolve(DATA_SESSION_RESTORE_FAILED, { uri, detail: describeError(error) }));
          }
       }
+      const sets = new Map<object, [string, DataSessionUnsavedWrite<TTransfer, TServer>][]>();
+      for (const [uri, write] of writes) {
+         const call = 'update' in write.call ? write.call.update : write.call.updates;
+         sets.set(call, [...(sets.get(call) ?? []), [uri, write]]);
+      }
+      const lost: string[] = [];
+      for (const members of sets.values()) {
+         lost.push(...(await this.reapply(server, members, reopened)));
+      }
+      for (const uri of reopened.keys()) {
+         if (!this.openUris.has(uri)) {
+            continue;
+         }
+         // A failed read leaves the client's dirty state as it was; the
+         // document is restored all the same.
+         const current = await server.getModelDocument({ uri }).catch(() => undefined);
+         if (current?.dirty !== undefined) {
+            try {
+               this.host.restoreDirty?.({ uri: current.uri, dirty: current.dirty });
+            } catch {
+               // The client's listener failed, not the restore: the server
+               // has the document open and watched, so it stays restored.
+            }
+         }
+      }
       if (lost.length > 0) {
          const reported = resolve(DATA_SESSION_UNSAVED_LOST, { uris: lost.join(', ') });
          this.host.reportError?.(new Error(reported.text), reported);
       }
    }
 
+   /**
+    * Whether the re-opened `document` still holds the session's unsaved
+    * `write` (`'kept'`), holds the text the write started from, so the write
+    * can be sent again (`'resend'`), or holds something else (`'lost'`).
+    *
+    * A document without a text hash comes from a server that sends none, and
+    * counts as kept only at the version the write was answered with.
+    */
+   protected restoreOutcome(
+      write: DataSessionUnsavedWrite<TTransfer, TServer>,
+      document: DataSessionDocument<TTransfer, TServer>
+   ): 'kept' | 'resend' | 'lost' {
+      if (document.textHash === undefined) {
+         return document.version === write.answer.version ? 'kept' : 'lost';
+      }
+      if (document.textHash === write.answer.textHash) {
+         return 'kept';
+      }
+      return write.baseHash !== undefined && document.textHash === write.baseHash ? 'resend' : 'lost';
+   }
+
+   /**
+    * Write again, in one call and based on their `reopened` versions, the
+    * `members` of one write call that the re-open lost, all or none. Returns
+    * the URIs whose unsaved text is gone, and drops their records, and the
+    * record of a member that could not be re-opened.
+    *
+    * A member whose record is no longer the one the restore started with was
+    * closed, saved or disposed meanwhile, and is left out: writing it would
+    * put back text its caller discarded.
+    */
+   protected async reapply(
+      server: RpcProxy<TServer>,
+      members: readonly [string, DataSessionUnsavedWrite<TTransfer, TServer>][],
+      reopened: ReadonlyMap<string, DataSessionDocument<TTransfer, TServer>>
+   ): Promise<string[]> {
+      const current = (uri: string, write: DataSessionUnsavedWrite<TTransfer, TServer>): boolean =>
+         !this.disposed && this.unsavedWrites.get(uri) === write;
+      const outcomes = members
+         .filter(([uri, write]) => current(uri, write))
+         .map(([uri, write]) => {
+            const document = reopened.get(uri);
+            return { uri, write, document, outcome: document ? this.restoreOutcome(write, document) : 'failed' };
+         });
+      // A restarted server numbers afresh: the answers to later writes follow
+      // on from the re-opened version, not from the one the record holds.
+      for (const { uri, write, document, outcome } of outcomes) {
+         if (outcome === 'kept' && document) {
+            this.unsavedWrites.set(uri, { ...write, answer: { version: document.version, textHash: document.textHash } });
+         }
+      }
+      // A document that could not be re-opened is forgotten, and was reported
+      // as such.
+      const lose = (): string[] => {
+         outcomes.filter(member => member.outcome !== 'kept').forEach(member => this.unsavedWrites.delete(member.uri));
+         return outcomes.filter(member => member.outcome === 'lost' || member.outcome === 'resend').map(member => member.uri);
+      };
+      if (outcomes.some(member => member.outcome === 'lost' || member.outcome === 'failed')) {
+         return lose();
+      }
+      // In the order of the call's updates, which is the order of its answers.
+      const resend = outcomes
+         .flatMap(({ uri, write, document, outcome }) =>
+            outcome === 'resend' && document ? [{ uri, write, basedOn: document.version }] : []
+         )
+         .sort((left, right) => indexOf(left.write) - indexOf(right.write));
+      if (resend.length === 0) {
+         return [];
+      }
+      let documents: DataSessionDocument<TTransfer, TServer>[];
+      try {
+         const { call } = resend[0].write;
+         if ('update' in call) {
+            documents = [await server.updateModelDocument({ ...call.update, basedOn: resend[0].basedOn, clientId: this.clientId })];
+         } else {
+            const basedOn = new Map(resend.map(member => [indexOf(member.write), member.basedOn]));
+            documents = await server.updateModelDocuments({
+               ...call.updates,
+               clientId: this.clientId,
+               updates: call.updates.updates.flatMap((update, index) => {
+                  const version = basedOn.get(index);
+                  return version === undefined ? [] : [{ ...update, basedOn: version }];
+               })
+            });
+         }
+      } catch (error: unknown) {
+         if (isConflictError(error)) {
+            return lose();
+         }
+         for (const { uri, write, basedOn } of resend) {
+            this.host.reportError?.(error, resolve(DATA_SESSION_RESTORE_FAILED, { uri, detail: describeError(error) }));
+            // Kept for the next restore, and numbered from the re-opened
+            // version, as the kept records are: a record numbered by a server
+            // that has since restarted would have later answers ignored.
+            if (current(uri, write)) {
+               this.unsavedWrites.set(uri, { ...write, answer: { ...write.answer, version: basedOn } });
+            }
+         }
+         return [];
+      }
+      resend.forEach((member, index) => {
+         if (current(member.uri, member.write)) {
+            // Recorded afresh, since the answer of a restarted server may be
+            // numbered below the one it replaces.
+            this.unsavedWrites.delete(member.uri);
+            this.recordWrite(member.uri, documents[index], member.write.baseHash, member.write.call);
+         }
+      });
+      return [];
+   }
+
+   /**
+    * The text hash of the version `basedOn` names for `uri`, for a write that
+    * starts the URI's record in {@link unsavedWrites}; `undefined` for any
+    * other write, whose record keeps the base it has.
+    *
+    * Taken from {@link lastAnswers} when that is at the version, otherwise
+    * read, and kept only when the read answers that version: a server's text
+    * changes only with its version, so the text at a version is the text the
+    * write, once it passes the gate, was applied to.
+    */
+   protected async baseHashOf(server: RpcProxy<TServer>, uri: string, basedOn: BasedOn): Promise<string | undefined> {
+      if (this.unsavedWrites.has(uri) || !isSnapshotVersion(basedOn)) {
+         return undefined;
+      }
+      const known = this.lastAnswers.get(uri);
+      if (known?.version === basedOn) {
+         return known.textHash;
+      }
+      const read = await server.getModelDocument({ uri }).catch(() => undefined);
+      return read?.version === basedOn ? read.textHash : undefined;
+   }
+
+   /**
+    * Record `document` as the answer to a write of `uri`, keeping the base of
+    * the URI's record if it has one. An answer numbered below the record's is
+    * ignored: two writes of `uri` in flight at once may answer out of order,
+    * and the record holds the one applied last.
+    *
+    * So is one numbered at or below the URI's entry in {@link savedVersions}.
+    * The save came after that write was applied, so the save persisted its
+    * text or a later write replaced it, and its answer carries the text as it
+    * was when sent, which a restore would report as lost.
+    */
+   protected recordWrite(
+      uri: string,
+      document: DataSessionDocument<TTransfer, TServer>,
+      baseHash: string | undefined,
+      call: DataSessionUnsavedWrite<TTransfer, TServer>['call']
+   ): void {
+      const answer = { version: document.version, textHash: document.textHash };
+      const kept = this.unsavedWrites.get(uri);
+      if (kept && answer.version < kept.answer.version) {
+         return;
+      }
+      const saved = this.savedVersions.get(uri);
+      if (saved !== undefined && answer.version <= saved) {
+         return;
+      }
+      this.unsavedWrites.set(uri, { baseHash: kept ? kept.baseHash : baseHash, answer, call });
+      this.lastAnswers.set(uri, answer);
+   }
+
    /** Run `call`, counted as in flight on each of `uris` until it settles. */
    protected track<T>(uris: readonly string[], call: () => Promise<T>): Promise<T> {
       const running = call();

package/src/transfer-document.ts

@@ -51,6 +51,18 @@ export interface TransferDocument<TTransfer extends TransferElement, TDiagnostic
     * watching the document.
     */
    dirty?: boolean;
+   /**
+    * What `textHash` makes of the text the server holds for this document
+    * when it sends it: set on every document a data server answers or sends
+    * that the server holds, and absent otherwise. Equal texts hash equal,
+    * whatever the version, so a client compares the text two snapshots hold,
+    * across a revert or a server restart that numbers versions afresh.
+    *
+    * Of the text alone. The data server's de-duplication fingerprint hashes the
+    * text or the transfer root together with the diagnostics, and changes with
+    * a diagnostic where this does not.
+    */
+   textHash?: string;
 }
 
 /**

package/src/util.ts

@@ -249,14 +249,23 @@ export function getAt<T = unknown>(obj: unknown, path: string[]): T | undefined
    return cur as T;
 }
 
+/**
+ * A stable, non-cryptographic digest of `text`, equal on every host for equal
+ * text: the `TransferDocument.textHash` a data server stamps, so a client can
+ * hash text of its own to compare. An array is read as its elements joined, so
+ * a large text is hashed in parts without concatenating it. It tells whether a
+ * text changed, not who could forge one.
+ */
+export function textHash(text: string | readonly string[]): string {
+   const { high, low } = cyrb53(typeof text === 'string' ? [text] : text);
+   return high.toString(16).padStart(8, '0') + low.toString(16).padStart(8, '0');
+}
+
 /**
  * The two 32-bit words cyrb53 ends on, each unsigned, for `parts` read as one
- * string. The 53-bit cyrb53 value is `2097151 & high` above `low`. It tells
- * whether a text changed, not who can forge one, and needs no `node:*` module,
- * so every host runs it. The parts are hashed in turn, so a caller never
- * concatenates a large text to hash it with others.
+ * string. It needs no `node:*` module, so every host runs it.
  */
-export function cyrb53(parts: readonly string[]): { readonly high: number; readonly low: number } {
+function cyrb53(parts: readonly string[]): { readonly high: number; readonly low: number } {
    let h1 = 0xdeadbeef;
    let h2 = 0x41c6ce57;
    for (const part of parts) {