@hydranium/protocol 1.0.0-next.284 → 1.0.0-next.287

package/src/client/data-connection.ts

@@ -8,7 +8,7 @@
  ********************************************************************************/
 
 import { Disposable, Emitter, type Event } from 'vscode-jsonrpc';
-import { FRAMEWORK_CLIENT_IDS } from '../client-ids';
+import { FRAMEWORK_CLIENT_IDS, UNKNOWN_CLIENT_ID } from '../client-ids';
 import {
    DATA_CLIENT_PROTOCOL_METHODS,
    DATA_SERVER_WIRE_PREFIX,
@@ -20,6 +20,7 @@ import {
    type TransferDocumentDirtyChangedEvent,
    type TransferDocumentUpdatedEvent
 } from '../data';
+import type { TransferWatchedDocument } from '../transfer-document';
 import { DuplicateClientIdError, ReservedClientIdError } from '../errors';
 import type { Logger } from '../logger';
 import { defineMessage, describeError, describeErrorWithStack, resolve } from '../messages/primitives';
@@ -49,6 +50,31 @@ export const DATA_CONNECTION_SESSION_RESTORE_FAILED = defineMessage(
    'Could not restore a session after reconnecting to the data server: {detail}'
 );
 
+/**
+ * A watch {@link DataConnection.watchDocument} keeps, with what the client last
+ * heard of its document: a reconnect whose watch answers that no document
+ * exists tells the client of a deletion only where it had heard one did.
+ */
+export interface DataConnectionWatch {
+   /** The URI as the caller named it, which the watch is sent under. */
+   readonly uri: string;
+   /** The key a watch of it last answered with, which events name; absent until one answered. */
+   readonly serverUri?: string;
+   /** Whether the client last heard that the document exists. */
+   readonly exists: boolean;
+}
+
+/** What an event heard while a watch was in flight said of its document, and the event's position. */
+export interface DataConnectionHeardEvent {
+   readonly exists: boolean;
+   readonly sequence: number;
+}
+
+/** Whether the document exists, by the newer of a watch's answer and an event heard while the watch was in flight. */
+function existsAfter(heard: DataConnectionHeardEvent | undefined, answer: TransferWatchedDocument): boolean {
+   return heard !== undefined && heard.sequence > answer.sequence ? heard.exists : answer.exists;
+}
+
 /** Options for {@link DataConnection}. */
 export interface DataConnectionOptions<
    TTransfer extends TransferElement = TransferElement,
@@ -143,11 +169,11 @@ export class DataConnection<
    /** Backs each session's {@link DataSessionHost.onDidDeleteDocument}. */
    protected readonly documentDeletedEmitter = new Emitter<TransferDocumentDeletedEvent>();
    /**
-    * Per id {@link watchDocument} watches under, the URI it watches, which
+    * Per id {@link watchDocument} watches under, the watch, which
     * {@link generationReady} sends again to every later generation until the
     * watch's handle is disposed.
     */
-   protected readonly watches = new Map<string, string>();
+   protected readonly watches = new Map<string, DataConnectionWatch>();
    /**
     * Per id, the URI of a watch whose handle was disposed with no ready
     * generation to unwatch on. {@link generationReady} sends the unwatch to the
@@ -155,6 +181,19 @@ export class DataConnection<
     * watches were sent leaves them on a connection the port may hand back.
     */
    protected readonly pendingUnwatches = new Map<string, string>();
+   /**
+    * The keys of the deletions the current generation's reconnect told the
+    * client of, so a URI several sessions and watches follow is told once.
+    */
+   protected readonly toldDeletions = new Set<string>();
+   /**
+    * One map per watch in flight, keyed by document, of what the last event
+    * heard since the watch was sent said of its existence, and the event's
+    * position. The server may take the answer before an event goes out, so
+    * an event heard in flight wins over the answer where its position is
+    * past the one the answer carries.
+    */
+   protected readonly heardInFlight = new Set<Map<string, DataConnectionHeardEvent>>();
    /** The port's logger, or one that logs nothing. */
    protected readonly logger: Logger;
    /** Backs {@link onDidReconnect}. */
@@ -230,6 +269,8 @@ export class DataConnection<
             connected: () => this.connected(),
             reportError: (error, reported) => this.reportError(error, reported),
             restoreDirty: event => this.restoreDirty(event),
+            // Without it the session reports the unsaved text it loses.
+            restoreDeletion: this.hearsDeletions ? event => this.restoreDeletion(event) : undefined,
             forgetDirty: uri => this.dirtyStates.delete(uri),
             onDidChangeDirty: this.dirtyChangedEmitter.event,
             onDidUpdateDocument: this.documentUpdatedEmitter.event,
@@ -255,22 +296,28 @@ export class DataConnection<
     * for as long as the caller follows it. The watch runs under an id of its
     * own, `label` plus `#` plus a random UUID, and needs no session: a session
     * closing the document would also end its own watch of it. Every later
-    * connection that becomes ready gets the watch again. Disposing the handle
-    * unwatches.
+    * connection that becomes ready gets the watch again, and tells the client
+    * of a deletion while it was down. Disposing the handle unwatches.
     */
    async watchDocument(uri: string, label = 'watch'): Promise<Disposable> {
       const clientId = `${label}#${randomUuid()}`;
       const server = await this.connected();
       // Kept only from here: kept during the wait, a generation that became
       // ready meanwhile would send the watch a second time.
-      this.watches.set(clientId, uri);
+      this.watches.set(clientId, { uri, exists: false });
+      const heard = new Map<string, DataConnectionHeardEvent>();
+      this.heardInFlight.add(heard);
+      let answer: TransferWatchedDocument;
       try {
-         await server.watchModelDocument({ uri, clientId });
+         answer = await server.watchModelDocument({ uri, clientId });
       } catch (error: unknown) {
          this.watches.delete(clientId);
          throw error;
+      } finally {
+         this.heardInFlight.delete(heard);
       }
       this.logger.debug(`Watch ${uri} as ${clientId}`);
+      this.watches.set(clientId, { uri, serverUri: answer.uri, exists: existsAfter(heard.get(answer.uri), answer) });
       return Disposable.create(() => {
          if (!this.watches.delete(clientId)) {
             return;
@@ -307,9 +354,9 @@ export class DataConnection<
     */
    protected override localTarget(): TClient {
       const client = this.client as unknown as Record<string, unknown>;
-      const hearsDirty = typeof client.onDocumentDirtyChanged === 'function';
-      const hearsUpdates = typeof client.onDocumentUpdated === 'function';
-      const hearsDeletions = typeof client.onDocumentDeleted === 'function';
+      const hearsDirty = this.bindsClientMethod('onDocumentDirtyChanged');
+      const hearsUpdates = this.bindsClientMethod('onDocumentUpdated');
+      const hearsDeletions = this.hearsDeletions;
       if (!hearsDirty && !hearsUpdates && !hearsDeletions) {
          return this.client;
       }
@@ -329,6 +376,9 @@ export class DataConnection<
       if (hearsUpdates) {
          const forward = target.onDocumentUpdated as (event: TransferDocumentUpdatedEvent<TTransfer, DiagnosticOf<TServer>>) => void;
          target.onDocumentUpdated = (event: TransferDocumentUpdatedEvent<TTransfer, DiagnosticOf<TServer>>): void => {
+            if (event.document.model) {
+               this.markWatches(event.document.uri, true, event.sequence);
+            }
             this.documentUpdatedEmitter.fire(event);
             forward(event);
          };
@@ -336,6 +386,10 @@ export class DataConnection<
       if (hearsDeletions) {
          const forward = target.onDocumentDeleted as (event: TransferDocumentDeletedEvent) => void;
          target.onDocumentDeleted = (event: TransferDocumentDeletedEvent): void => {
+            // Held gone, so a reconnect tells the client of it no second time.
+            // A server sending no position has its deletion count as sent
+            // before any answer.
+            this.markWatches(event.uri, false, event.sequence ?? 0);
             this.documentDeletedEmitter.fire(event);
             forward(event);
          };
@@ -343,6 +397,50 @@ export class DataConnection<
       return target as unknown as TClient;
    }
 
+   /**
+    * Whether the client binds `onDocumentDeleted`. Without it no deletion
+    * reaches the client or the sessions, the server's or one a reconnect
+    * found, and a session's restore reports what a gone document took.
+    */
+   protected get hearsDeletions(): boolean {
+      return this.bindsClientMethod('onDocumentDeleted');
+   }
+
+   /** Whether `name` is among the methods bound for the client, and the client implements it. */
+   protected bindsClientMethod(name: string): boolean {
+      const client = this.client as unknown as Record<string, unknown>;
+      return (this.clientMethods as readonly string[]).includes(name) && typeof client[name] === 'function';
+   }
+
+   /**
+    * Hand the client a deletion a session's restore or a watch sent again
+    * found, which no event brought while the connection was down, unless
+    * {@link toldDeletions} says this generation told it already. The sessions
+    * do not hear it: each finds what it lost in its own restore.
+    */
+   protected restoreDeletion(event: TransferDocumentDeletedEvent): void {
+      if (this.toldDeletions.has(event.uri)) {
+         return;
+      }
+      this.toldDeletions.add(event.uri);
+      const client = this.client as unknown as Pick<DataClientProtocol<TTransfer>, 'onDocumentDeleted'>;
+      client.onDocumentDeleted(event);
+   }
+
+   /**
+    * Record in every watch whose answer named `uri` whether the document
+    * exists, and in {@link heardInFlight} for the watches not answered yet,
+    * with the event's position.
+    */
+   protected markWatches(uri: string, exists: boolean, sequence: number): void {
+      this.watches.forEach((watch, clientId) => {
+         if (watch.serverUri === uri) {
+            this.watches.set(clientId, { ...watch, exists });
+         }
+      });
+      this.heardInFlight.forEach(heard => heard.set(uri, { exists, sequence }));
+   }
+
    /**
     * Hand a dirty state a restore read to the client, unless it is what
     * {@link dirtyStates} says the client was last told; a URI it holds
@@ -357,8 +455,10 @@ export class DataConnection<
    /** Record `event` in {@link dirtyStates} and hand it to the client. */
    protected deliverDirty(event: TransferDocumentDirtyChangedEvent): void {
       this.dirtyStates.set(event.uri, event.text?.dirty ?? false);
-      const client = this.client as unknown as Partial<Pick<DataClientProtocol<TTransfer>, 'onDocumentDirtyChanged'>>;
-      client.onDocumentDirtyChanged?.(event);
+      if (this.bindsClientMethod('onDocumentDirtyChanged')) {
+         const client = this.client as unknown as Pick<DataClientProtocol<TTransfer>, 'onDocumentDirtyChanged'>;
+         client.onDocumentDirtyChanged(event);
+      }
    }
 
    /**
@@ -414,8 +514,9 @@ export class DataConnection<
     */
    protected override generationReady(generation: RpcConnectionGeneration<TServer>): void {
       super.generationReady(generation);
+      this.toldDeletions.clear();
       this.reconnectSessions();
-      this.watches.forEach((uri, clientId) => this.watchAgain(generation, clientId, uri));
+      this.watches.forEach((watch, clientId) => this.watchAgain(generation, clientId, watch.uri));
       this.pendingUnwatches.forEach((uri, clientId) => this.unwatch(generation, clientId, uri));
       this.pendingUnwatches.clear();
       if (this.readyBefore) {
@@ -438,41 +539,58 @@ export class DataConnection<
     * `generation` is still current: otherwise the next generation sends it
     * again.
     *
-    * Once the watch is in place, the document's dirty state is read and goes
-    * through {@link restoreDirty}, as a session's restore does: a flip while
-    * the connection was down reached no one.
+    * A document the client last heard exists that the watch's answer says
+    * is gone goes to the client as a deletion; once the watch is in place,
+    * the document's dirty state is read and goes through
+    * {@link restoreDirty}, as a session's restore does. Neither reached
+    * anyone while the connection was down.
     */
    protected watchAgain(generation: RpcConnectionGeneration<TServer>, clientId: string, uri: string): void {
-      generation.server.watchModelDocument({ uri, clientId }).then(
-         () => {
-            if (!this.watches.has(clientId)) {
-               return;
-            }
-            this.logger.debug(`Watch ${uri} again as ${clientId}`);
-            generation.server.getModelDocument({ uri }).then(
-               current => {
-                  if (current.text && this.watches.has(clientId)) {
-                     try {
-                        this.restoreDirty({ uri: current.uri, text: current.text });
-                     } catch {
-                        // The client's listener failed, not the watch, which stays kept.
-                     }
+      const heard = new Map<string, DataConnectionHeardEvent>();
+      this.heardInFlight.add(heard);
+      generation.server
+         .watchModelDocument({ uri, clientId })
+         .finally(() => this.heardInFlight.delete(heard))
+         .then(
+            answer => {
+               const known = this.watches.get(clientId);
+               if (!known) {
+                  return;
+               }
+               this.logger.debug(`Watch ${uri} again as ${clientId}`);
+               const exists = existsAfter(heard.get(answer.uri), answer);
+               this.watches.set(clientId, { uri, serverUri: answer.uri, exists });
+               if (known.exists && !exists && this.hearsDeletions) {
+                  try {
+                     this.restoreDeletion({ uri: answer.uri, sourceClientId: UNKNOWN_CLIENT_ID });
+                  } catch {
+                     // The client's listener failed, not the watch, which stays kept.
                   }
-               },
-               () => undefined
-            );
-         },
-         (error: unknown) => {
-            if (!this.watches.has(clientId)) {
-               return;
-            }
-            if (this.generation !== generation) {
-               this.logger.debug(`Watch of ${uri} as ${clientId} cut short by a lost connection; the next one sends it again`);
-               return;
+               }
+               generation.server.getModelDocument({ uri }).then(
+                  current => {
+                     if (current.text && this.watches.has(clientId)) {
+                        try {
+                           this.restoreDirty({ uri: current.uri, text: current.text });
+                        } catch {
+                           // The client's listener failed, not the watch, which stays kept.
+                        }
+                     }
+                  },
+                  () => undefined
+               );
+            },
+            (error: unknown) => {
+               if (!this.watches.has(clientId)) {
+                  return;
+               }
+               if (this.generation !== generation) {
+                  this.logger.debug(`Watch of ${uri} as ${clientId} cut short by a lost connection; the next one sends it again`);
+                  return;
+               }
+               this.reportError(error, resolve(DATA_CONNECTION_WATCH_RESTORE_FAILED, { uri, detail: describeError(error) }));
             }
-            this.reportError(error, resolve(DATA_CONNECTION_WATCH_RESTORE_FAILED, { uri, detail: describeError(error) }));
-         }
-      );
+         );
    }
 
    /**

package/src/client/data-events.ts

@@ -59,7 +59,11 @@ export class DataEvents<
    readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>> = this.documentSavedEmitter.event;
    /** A watched document's text started or stopped differing from its file. */
    readonly onDidChangeDocumentDirty: Event<TransferDocumentDirtyChangedEvent> = this.documentDirtyChangedEmitter.event;
-   /** A document's backing file was removed, watched or not. Any watch survives. */
+   /**
+    * A document's backing file was removed, watched or not. Any watch
+    * survives. After a reconnect, also a document a session had open or a
+    * watch followed that went while the connection was down.
+    */
    readonly onDidDeleteDocument: Event<TransferDocumentDeletedEvent> = this.documentDeletedEmitter.event;
    /** Documents built that nobody watches — re-read anything derived from them. */
    readonly onDidBuildDocuments: Event<TransferDocumentsBuiltEvent> = this.documentsBuiltEmitter.event;

package/src/client/data-session.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { type Disposable, Emitter, type Event } from 'vscode-jsonrpc';
+import { UNKNOWN_CLIENT_ID } from '../client-ids';
 import { type Clock, SystemClock } from '../clock';
 import type {
    DataServerProtocol,
@@ -190,6 +191,11 @@ function indexOf(write: DataSessionUnsavedWrite<TransferElement, DataServerProto
    return 'index' in write.call ? write.call.index : 0;
 }
 
+/** The call `write` was last written by, which a restore writes again as one set. */
+function setOf(write: DataSessionUnsavedWrite<TransferElement, DataServerProtocol<TransferElement>>): object {
+   return 'update' in write.call ? write.call.update : write.call.updates;
+}
+
 /**
  * What a {@link DataSession} needs from the connection that minted it.
  *
@@ -206,6 +212,13 @@ export interface DataSessionHost<TTransfer extends TransferElement, TServer exte
     * is what the client was last told of the URI since the URI's last open.
     */
    restoreDirty?(event: TransferDocumentDirtyChangedEvent): void;
+   /**
+    * Tell the connection's client of a document a restore found gone, whose
+    * deletion reached no one while the connection was down, as the server
+    * tells it of a deletion over a live connection. Without it, the restore
+    * reports the unsaved text such a document took with it as lost.
+    */
+   restoreDeletion?(event: TransferDocumentDeletedEvent): void;
    /**
     * Forget what the client was told of `uri`'s dirty state: an open just
     * made answered its caller afresh, and the client heard none of it, or a
@@ -229,7 +242,7 @@ export interface DataSessionHost<TTransfer extends TransferElement, TServer exte
    /**
     * Fires with each deletion the server sends. A session forgets a document
     * whose file was deleted; without this event it keeps it as open until a
-    * restore finds it gone, and reports its unsaved text lost only then.
+    * restore finds it gone.
     */
    readonly onDidDeleteDocument?: Event<TransferDocumentDeletedEvent>;
    /** Where the session logs the documents it forgets as gone. */
@@ -292,8 +305,9 @@ export class DataSession<
    /**
     * How long {@link closeDocument}, {@link deleteDocument} and {@link dispose}
     * wait for this session's calls in flight before going on anyway. Long,
-    * because the wait only runs out when a call hangs, and a close sent while
-    * a save is still running fails that save.
+    * because a close sent while a save is still writing fails that save. It
+    * need not outlast the server's language-client settle after the write,
+    * which a close does not fail.
     */
    protected readonly settleBeforeCloseMs: number = 10_000;
    /**
@@ -378,6 +392,13 @@ export class DataSession<
     * over a connection that is going away.
     */
    protected detached = false;
+   /**
+    * Write sets, keyed as a restore groups them, that lost a document to
+    * another client's deletion. A restore cannot write such a set again
+    * whole, so it writes none of it. Weak, so a set goes once no write
+    * record holds it.
+    */
+   protected readonly brokenSets = new WeakSet<object>();
    /** 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. */
@@ -917,7 +938,10 @@ export class DataSession<
     * let a restore re-open the file that is gone. Unwatched rather than
     * closed: the server keeps the watch, and a close could end a re-open of a
     * re-created file still in flight. Unsaved writes are logged, not
-    * reported: the client hears the deletion too.
+    * reported: the client hears the deletion too. A document this session
+    * created and never saved, deleted by no session, is reported as well: a
+    * drop released it. An unsaved write breaks the set it was written with,
+    * see {@link brokenSets}.
     *
     * This session's own deletion is neither unwatched nor logged as dropping
     * unsaved text: its delete released the watch, and its caller chose to
@@ -934,7 +958,18 @@ export class DataSession<
             this.forgetDocument(uri);
             continue;
          }
+         const write = this.unsavedWrites.get(uri);
+         if (write) {
+            this.brokenSets.add(setOf(write));
+         }
+         // Never saved, so no file a watcher could see removed: a deletion
+         // naming no session is the release of the text a drop left behind.
+         const released = this.createdUris.has(uri) && event.sourceClientId === UNKNOWN_CLIENT_ID;
          this.forgetGoneDocument(uri);
+         if (released) {
+            const reported = resolve(DATA_SESSION_UNSAVED_LOST, { uris: uri });
+            this.host.reportError?.(new Error(reported.text), reported);
+         }
          this.connected()
             .then(server => server.unwatchModelDocument({ uri, clientId: this.clientId }))
             .catch(() => undefined);
@@ -987,7 +1022,7 @@ export class DataSession<
     * 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.
+    * could not be re-opened, or that another client deleted, 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
@@ -997,8 +1032,13 @@ export class DataSession<
     * restore to decide again. A document closed while the restore runs, or
     * whose file is deleted then, is neither restored nor reported. One gone
     * while the connection was down, which the server reads back without a
-    * model, is forgotten, and goes into the report of lost unsaved text when
-    * the session wrote it since its last save, or created it and never saved it.
+    * model, is forgotten, and its deletion goes to the host as the deletion
+    * no event brought; unsaved text it took with it is logged, as for a
+    * deletion heard live, and reported as well for a document the session
+    * created and never saved, which the drop released. A host that cannot
+    * tell the client has the unsaved text of either reported. Once the session
+    * is disposed, its caller has ended it, and the restore returns at its
+    * next await: nothing more goes to the server or the host.
     *
     * Each document's dirty state goes to the host too, read once the watch is
     * in place and any write is sent: a flip while the connection was down, or
@@ -1020,6 +1060,9 @@ export class DataSession<
          }
          try {
             const document = await server.openModelDocument({ uri, clientId: this.clientId });
+            if (this.disposed) {
+               return;
+            }
             if (!this.openUris.has(uri)) {
                // Forgotten while it re-opened. A close of the caller's would
                // follow, but a deletion sends none.
@@ -1036,6 +1079,9 @@ export class DataSession<
                await server.closeModelDocument({ uri, clientId: this.clientId }).catch(() => undefined);
                throw error;
             });
+            if (this.disposed) {
+               return;
+            }
             if (this.openUris.has(uri)) {
                this.recordText(uri, document);
             }
@@ -1044,22 +1090,42 @@ export class DataSession<
             // Gone while the connection was down, which no deletion told the
             // session of: the server answers a read of it without a model.
             const read = await server.getModelDocument({ uri }).catch(() => undefined);
+            if (this.disposed) {
+               return;
+            }
             // Forgotten meanwhile, so nothing is lost.
             if (!this.openUris.has(uri)) {
                continue;
             }
             if (read && !read.model) {
-               // No deletion reached the client either, so unsaved text the
-               // document took with it is reported, as a drop's other losses are.
                const write = this.unsavedWrites.get(uri);
-               if (this.forgetGoneDocument(uri)) {
-                  lost.push(uri);
-               }
+               // Named as the client last heard it, by the open's answer.
+               const serverUri = this.opens.get(uri)?.serverUri ?? uri;
+               // Never saved, so the drop released it and no one deleted it.
+               const created = this.createdUris.has(uri);
+               const unsaved = this.forgetGoneDocument(uri);
                // Kept for `reapply`, where it blocks its set as a document
                // that could not be re-opened does, and goes.
                if (write) {
                   this.unsavedWrites.set(uri, write);
                }
+               if (!this.host.restoreDeletion) {
+                  // No client hears of the deletion, so the loss is reported.
+                  if (unsaved) {
+                     lost.push(uri);
+                  }
+                  continue;
+               }
+               // The client hears of the deletion, so unsaved text is logged,
+               // as for one heard live; the drop's release is reported too.
+               if (created) {
+                  lost.push(uri);
+               }
+               try {
+                  this.host.restoreDeletion({ uri: serverUri, sourceClientId: UNKNOWN_CLIENT_ID });
+               } catch {
+                  // The client's listener failed, not the restore.
+               }
                continue;
             }
             // Its record goes with its set's, in `reapply`, which it blocks.
@@ -1073,11 +1139,14 @@ export class DataSession<
       }
       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 set = setOf(write);
+         sets.set(set, [...(sets.get(set) ?? []), [uri, write]]);
       }
       for (const members of sets.values()) {
          lost.push(...(await this.reapply(server, members, reopened)));
+         if (this.disposed) {
+            return;
+         }
       }
       for (const uri of reopened.keys()) {
          if (!this.openUris.has(uri)) {
@@ -1086,6 +1155,9 @@ export class DataSession<
          // A failed read, or one without text, 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 (this.disposed) {
+            return;
+         }
          // Again after the read: one closed or deleted meanwhile has no
          // state to tell.
          if (current?.text !== undefined && this.openUris.has(uri)) {
@@ -1139,7 +1211,8 @@ export class DataSession<
     *
     * 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.
+    * put back text its caller discarded. A set in {@link brokenSets} is
+    * not written again.
     */
    protected async reapply(
       server: RpcProxy<TServer>,
@@ -1171,7 +1244,7 @@ export class DataSession<
          });
          return gone.filter(member => member.outcome === 'lost' || member.outcome === 'resend').map(member => member.uri);
       };
-      if (outcomes.some(member => member.outcome === 'lost' || member.outcome === 'failed')) {
+      if (this.brokenSets.has(setOf(members[0][1])) || 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.

package/src/data/data-server-protocol.ts

@@ -10,7 +10,7 @@
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
 import type { Project } from '../project';
-import type { TransferDocument, TransferSavedDocument } from '../transfer-document';
+import type { TransferDocument, TransferSavedDocument, TransferWatchedDocument } from '../transfer-document';
 import type { CloseModelArgs, FindNextNameArgs, OpenModelArgs, ReferenceContext, ReferenceRequest } from '../model-server';
 import type { ReferenceCandidate, ReferenceTarget } from '../model-service/reference-candidate';
 import type {
@@ -141,10 +141,13 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
 
    /**
     * Write a document as the session `clientId`, which must have it open, and
-    * persist it to disk. The response is the latest build of the document,
-    * with the version of the text written in `persisted`. Save semantics
-    * depend on the filesystem-provider wiring; rejection paths surface as
-    * awaited promise rejections.
+    * persist it to disk. The response is the build of the text written, with
+    * its version in `persisted`, sent once the language client has answered
+    * the push of that text, applied or refused, or a server-side bound on
+    * that wait passes; it does not wait again for a push that wait already
+    * gave up on and the client has not answered since. Save semantics depend
+    * on the filesystem-provider wiring; rejection paths surface as awaited
+    * promise rejections.
     */
    saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
 
@@ -154,7 +157,9 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
     * unsaved text keeps its formatting. `baseVersion` is checked in the step
     * that takes the text, so text that moved on fails with a `ConflictError`
     * code. The saved event names this session, whoever wrote the text.
-    * Responds as {@link saveModelDocument} does.
+    * Answers after the same language-client wait as {@link saveModelDocument},
+    * with the document's latest build, read after that wait, so another
+    * session's write during it shows; `persisted` carries the version written.
     */
    persistModelDocument(args: TransferPersistDocumentArgs): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
 
@@ -178,15 +183,19 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
     * {@link DocumentClientProtocol.onDocumentUpdated} on the paired wire
     * for every build-phase event on `uri`.
     *
-    * Returns `Promise<void>` — the bidirectional pattern means the event
-    * channel is the client interface, not a returned handle. Callers fan
-    * out a single inbound `onDocumentUpdated` to multiple local listeners
-    * with their own `Emitter<T>` (matching Theia's pattern). Pair every
-    * `watchModelDocument` with {@link unwatchModelDocument} when no longer
-    * needed; the server holds the watch record until the matching unwatch
-    * lands.
+    * Answers with the key the watch's events name the document by, whether
+    * a document exists, taken once the watch is in place and the document
+    * is loaded as a read loads it, and the position of the last update or
+    * deletion event sent as of that moment, so an event the client heard
+    * while the watch was in flight tells by its own position whether it is
+    * newer than the answer. No handle: the event channel is the client
+    * interface. Callers fan out a single inbound `onDocumentUpdated` to
+    * multiple local listeners with their own `Emitter<T>` (matching Theia's
+    * pattern). Pair every `watchModelDocument` with
+    * {@link unwatchModelDocument} when no longer needed; the server holds the
+    * watch record until the matching unwatch lands.
     */
-   watchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
+   watchModelDocument(args: WatchModelDocumentArgs): Promise<TransferWatchedDocument>;
 
    /**
     * Stop watching `(uri, clientId)` previously started by