@hydranium/protocol 1.0.0-next.285 → 1.0.0-next.288

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,
@@ -20,7 +21,6 @@ import { isConflictError, SessionClosedError } from '../errors';
 import type { Logger } from '../logger';
 import { type BaseVersion, isModelVersion, type ModelVersion, type TextVersion, UNRECORDED_VERSION } from '../model-service/base-version';
 import { type ResolvedMessage, defineMessage, describeError, resolve } from '../messages/primitives';
-import type { OpenModelArgs } from '../model-server';
 import { NoopLogger } from '../noop-logger';
 import { randomUuid } from '../random-uuid';
 import type { MaybePromise } from '../util';
@@ -70,15 +70,24 @@ export type DataSessionArgs<TMethod extends (args: never) => unknown> = Omit<Par
 
 /**
  * Open a document through a session; the session supplies `clientId`. Only the
- * URI and the open's options: a session's open reads the file, and the server
- * ignores the `languageId`, `version` and `text` seeds of `OpenModelArgs`, so
- * accepting them here would let a caller believe they took effect.
+ * URI and the open's options, read off the server's signature: the server
+ * ignores the `languageId`, `version` and `text` seeds of `OpenModelArgs`, and
+ * a field an adopter adds never reaches the server session's open, so
+ * accepting either would let a caller believe it took effect.
  */
 export type DataSessionOpenArgs<
    TTransfer extends TransferElement,
-   // oxlint-disable-next-line no-unused-vars -- TServer validates its own diagnostic constraint; Oxlint does not count that use.
    TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
-> = Pick<OpenModelArgs, 'uri' | 'options'>;
+> = Pick<Parameters<TServer['openModelDocument']>[0], 'uri' | ('options' & keyof Parameters<TServer['openModelDocument']>[0])>;
+
+/**
+ * The options an open through a session passes to `TServer`, `undefined` when
+ * it passed none; only `undefined` for a server whose open takes none.
+ */
+export type DataSessionOpenOptions<
+   TTransfer extends TransferElement,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
+> = DataSessionOpenArgs<TTransfer, TServer>['options' & keyof DataSessionOpenArgs<TTransfer, TServer>] | undefined;
 
 /** Create a document through a session; the session supplies `clientId`. */
 export type DataSessionCreateArgs<
@@ -167,9 +176,18 @@ export interface DataSessionUnsavedWrite<
  * that the URI is open accepts an answer from before a close or deletion
  * once the URI is open again.
  */
-export interface DataSessionOpen {
+export interface DataSessionOpen<
+   TTransfer extends TransferElement,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
+> {
    /** The URI the open's answer named, which the server keys its notifications by. */
    readonly serverUri: string;
+   /**
+    * The options the server opened under, which a re-open after a reconnect
+    * passes again: those of the earliest open of the URI under way when the
+    * first answered, since the server keeps the open that arrives first.
+    */
+   readonly options: DataSessionOpenOptions<TTransfer, TServer>;
    /** Whether a deletion ended the open, which an open still watching sends again; a close does not. */
    deleted: boolean;
 }
@@ -180,9 +198,14 @@ export interface DataSessionOpen {
  * nothing and is not sent again, so the close stands. Without the mark, a
  * deletion during its watch has it sent again after the close.
  */
-export interface DataSessionOpening {
+export interface DataSessionOpening<
+   TTransfer extends TransferElement,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
+> {
    /** Whether a close of the URI came while this open was under way. */
    closed: boolean;
+   /** The options the open was sent with; none for a create. */
+   readonly options: DataSessionOpenOptions<TTransfer, TServer>;
 }
 
 /** Where `write` stands in the `updateDocuments` call it was last written by; `0` for a single update. */
@@ -190,6 +213,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 +234,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 +264,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. */
@@ -310,13 +345,13 @@ export class DataSession<
     * still under way, the open it is under. A repeat open keeps it, as the
     * server keeps its earlier open.
     */
-   protected readonly opens = new Map<string, DataSessionOpen>();
+   protected readonly opens = new Map<string, DataSessionOpen<TTransfer, TServer>>();
    /**
     * Per URI, the opens of it this session has under way. Such a URI counts
     * as open for {@link withOpenDocument}, which would otherwise close it
     * under the open that is still being made.
     */
-   protected readonly openings = new Map<string, Set<DataSessionOpening>>();
+   protected readonly openings = new Map<string, Set<DataSessionOpening<TTransfer, TServer>>>();
    /**
     * Per URI, the closes and deletes of it this session has under way, which
     * an open or create called meanwhile waits for; see {@link trackEnding}.
@@ -379,6 +414,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. */
@@ -444,7 +486,7 @@ export class DataSession<
     * from `getModelDocument({ includeDiagnostics: true })`.
     */
    openDocument(args: DataSessionOpenArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>> {
-      return this.trackOpen(args.uri, opening =>
+      return this.trackOpen(args.uri, args.options, opening =>
          this.openAndWatch(args.uri, opening, false, server => server.openModelDocument({ ...args, clientId: this.clientId }))
       );
    }
@@ -455,7 +497,7 @@ export class DataSession<
     * refuses a URI that exists on disk or that any client has open.
     */
    createDocument(args: DataSessionCreateArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>> {
-      return this.trackOpen(args.uri, opening =>
+      return this.trackOpen(args.uri, undefined, opening =>
          this.openAndWatch(args.uri, opening, true, server => server.createModelDocument({ ...args, clientId: this.clientId }))
       );
    }
@@ -475,7 +517,7 @@ export class DataSession<
     */
    protected async openAndWatch(
       uri: string,
-      opening: DataSessionOpening,
+      opening: DataSessionOpening<TTransfer, TServer>,
       created: boolean,
       open: (server: RpcProxy<TServer>) => Promise<DataSessionDocument<TTransfer, TServer>>
    ): Promise<DataSessionDocument<TTransfer, TServer>> {
@@ -516,7 +558,14 @@ export class DataSession<
    ): Promise<DataSessionDocument<TTransfer, TServer> | undefined> {
       // Recorded before the watch, so a deletion heard while it is under way
       // finds this open, which the server made before the deletion.
-      const open = this.opens.get(uri) ?? { serverUri: document.uri, deleted: false };
+      // Under the options of the earliest open still under way, which the
+      // server took first; one that failed is gone from `openings` by now,
+      // as the connection handles each answer in a task of its own.
+      const open = this.opens.get(uri) ?? {
+         serverUri: document.uri,
+         deleted: false,
+         options: [...(this.openings.get(uri) ?? [])].find(opening => !opening.closed)?.options
+      };
       this.opens.set(uri, open);
       await server.watchModelDocument({ uri, clientId: this.clientId });
       if (this.opens.get(uri) !== open) {
@@ -562,7 +611,7 @@ export class DataSession<
     * see {@link hasOpen}: the server holds one open per session and URI, so
     * the close would end that one too.
     */
-   protected async undoOpen(server: RpcProxy<TServer>, uri: string, opening: DataSessionOpening): Promise<void> {
+   protected async undoOpen(server: RpcProxy<TServer>, uri: string, opening: DataSessionOpening<TTransfer, TServer>): Promise<void> {
       if (this.hasOpen(uri, opening)) {
          return;
       }
@@ -588,7 +637,7 @@ export class DataSession<
     * no close has marked, other than `except`. A marked open records nothing,
     * so nothing can rely on it.
     */
-   protected hasOpen(uri: string, except?: DataSessionOpening): boolean {
+   protected hasOpen(uri: string, except?: DataSessionOpening<TTransfer, TServer>): boolean {
       return this.openUris.has(uri) || [...(this.openings.get(uri) ?? [])].some(opening => opening !== except && !opening.closed);
    }
 
@@ -918,7 +967,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
@@ -935,7 +987,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);
@@ -969,9 +1032,10 @@ export class DataSession<
    }
 
    /**
-    * 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.
+    * Re-open, each under the options its {@link DataSessionOpen} holds, 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.
     *
     * Decided per document by the re-opened document's `text.hash`,
     * in {@link restoreOutcome}. Versions cannot decide a write: a revert moves
@@ -988,7 +1052,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
@@ -998,8 +1062,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,7 +1089,11 @@ export class DataSession<
             continue;
          }
          try {
-            const document = await server.openModelDocument({ uri, clientId: this.clientId });
+            const options = this.opens.get(uri)?.options;
+            const document = await server.openModelDocument({ uri, clientId: this.clientId, options });
+            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.
@@ -1030,13 +1103,16 @@ export class DataSession<
             // Recorded before the watch, so a deletion heard while it is under
             // way finds the re-open under the URI it answered with, which a
             // restarted server may key differently.
-            this.opens.set(uri, { serverUri: document.uri, deleted: false });
+            this.opens.set(uri, { serverUri: document.uri, deleted: false, options });
             await server.watchModelDocument({ uri, clientId: this.clientId }).catch(async (error: unknown) => {
                // Closed, or the server holds the re-open until the session
                // ends; no other call relies on it while the restore runs.
                await server.closeModelDocument({ uri, clientId: this.clientId }).catch(() => undefined);
                throw error;
             });
+            if (this.disposed) {
+               return;
+            }
             if (this.openUris.has(uri)) {
                this.recordText(uri, document);
             }
@@ -1045,22 +1121,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.
@@ -1074,11 +1170,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)) {
@@ -1087,6 +1186,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)) {
@@ -1140,7 +1242,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>,
@@ -1172,7 +1275,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.
@@ -1265,7 +1368,7 @@ export class DataSession<
     */
    protected recordWrite(
       uri: string,
-      open: DataSessionOpen | undefined,
+      open: DataSessionOpen<TTransfer, TServer> | undefined,
       document: DataSessionDocument<TTransfer, TServer>,
       baseHash: string | undefined,
       call: DataSessionUnsavedWrite<TTransfer, TServer>['call']
@@ -1329,9 +1432,13 @@ export class DataSession<
     * and sent once the closes and deletes of `uri` called before it have
     * answered.
     */
-   protected trackOpen<T>(uri: string, call: (opening: DataSessionOpening) => Promise<T>): Promise<T> {
-      const opening: DataSessionOpening = { closed: false };
-      const openings = this.openings.get(uri) ?? new Set<DataSessionOpening>();
+   protected trackOpen<T>(
+      uri: string,
+      options: DataSessionOpenOptions<TTransfer, TServer>,
+      call: (opening: DataSessionOpening<TTransfer, TServer>) => Promise<T>
+   ): Promise<T> {
+      const opening: DataSessionOpening<TTransfer, TServer> = { closed: false, options };
+      const openings = this.openings.get(uri) ?? new Set<DataSessionOpening<TTransfer, TServer>>();
       this.openings.set(uri, openings.add(opening));
       const done = (): void => {
          openings.delete(opening);

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 {
@@ -183,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

package/src/data/events.ts

@@ -62,6 +62,12 @@ export interface TransferDocumentUpdatedEvent<
     */
    sourceClientId: string;
    reason: TransferDocumentUpdateReason;
+   /**
+    * The position of this event among the update and deletion events the
+    * server sent on this connection, which a watch's answer carries as of
+    * the moment it was taken: a greater one was sent later.
+    */
+   sequence: number;
 }
 
 /** Callback shape for `DataClientProtocol.onDocumentUpdated`. */
@@ -158,9 +164,16 @@ export interface TransferDocumentDeletedEvent {
    /**
     * The session whose `deleteModelDocument` removed the file, so it can tell
     * its own deletion from another's; the unknown-client id for a file
-    * removed outside any session, as a file watcher reports one.
+    * removed outside any session, as a file watcher reports one, and for one
+    * a `DataConnection` found gone after a reconnect, which no event named.
     */
    readonly sourceClientId: string;
+   /**
+    * The position of this event among the update and deletion events the
+    * server sent on this connection, as on an update; absent on a deletion a
+    * `DataConnection` found after a reconnect, which the server never sent.
+    */
+   readonly sequence?: number;
 }
 
 /** Callback shape for `DataClientProtocol.onDocumentDeleted`. */

package/src/transfer-document.ts

@@ -98,6 +98,16 @@ export type TransferSavedDocument<TTransfer extends TransferElement, TDiagnostic
    persisted: { version: TextVersion };
 };
 
+/** What a watch answers, once it is in place. */
+export interface TransferWatchedDocument {
+   /** The key the watch's events name the document by, which a symlinked URI does not spell. */
+   readonly uri: string;
+   /** Whether a document exists there; one the server fails to load counts, only a missing one does not. */
+   readonly exists: boolean;
+   /** The position of the last update or deletion event sent before `exists` was taken; an event past it was sent after. */
+   readonly sequence: number;
+}
+
 export namespace TransferDocument {
    /**
     * Whether the server had this document. Branch on it where absence is an