@hydranium/protocol 1.0.0-next.24 → 1.0.0-next.241

package/lib/client/data-session.js

@@ -8,78 +8,190 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DataSession = void 0;
-const data_1 = require("../data");
-const rpc_1 = require("../rpc");
+exports.DataSession = exports.DATA_SESSION_UNSAVED_LOST = exports.DATA_SESSION_ANSWER_WITHOUT_MODEL = exports.DATA_SESSION_RESTORE_FAILED = void 0;
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+const clock_1 = require("../clock");
+const errors_1 = require("../errors");
+const base_version_1 = require("../model-service/base-version");
+const primitives_1 = require("../messages/primitives");
+const random_uuid_1 = require("../random-uuid");
 /**
- * The host-invariant half of talking to the data head: everything above
- * {@link DataPort} that would otherwise be re-derived by every host
- * adapter.
+ * A session could not re-open a document it had open after its connection
+ * 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.
+ */
+exports.DATA_SESSION_RESTORE_FAILED = (0, primitives_1.defineMessage)('hydranium/protocol/data-session-restore-failed', 'Could not restore {uri} after reconnecting to the data server: {detail}');
+/** A write or open of `{uri}` that the data server answered without a model. */
+exports.DATA_SESSION_ANSWER_WITHOUT_MODEL = (0, primitives_1.defineMessage)('hydranium/protocol/data-session-answer-without-model', 'The data server answered a write of {uri} without a model; the session counts that answer as older than every version.');
+/**
+ * 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.
+ */
+exports.DATA_SESSION_UNSAVED_LOST = (0, primitives_1.defineMessage)('hydranium/protocol/data-session-unsaved-lost', 'Unsaved changes to {uris} may have been lost when the connection to the data server dropped.');
+/** Where `write` stands in the `updateDocuments` call it was last written by; `0` for a single update. */
+function indexOf(write) {
+    return 'index' in write.call ? write.call.index : 0;
+}
+/**
+ * One participant on a data connection: a properties panel, a tree, a form
+ * editor. The client side of a server client session, registered over the
+ * wire under {@link clientId}.
+ *
+ * The session writes only what it has open: the server refuses its update or
+ * save of a document it has not opened with a `DocumentNotOpenError` code.
+ * Every call waits for the registration, so the first can be issued at once.
  *
- * Three jobs, and deliberately no fourth:
+ * Every document operation stamps {@link clientId} itself. A caller that
+ * passed its own could pass another participant's, and the server would
+ * attribute the write and close the document accordingly.
  *
- * 1. **Build the typed proxy** over the port's connection, with the framework's
- *    wire prefix and its drift-proof client-method allowlist.
- * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
- *    across concurrent callers. A socket client can connect before the
- *    workspace walk finishes, and an early request is then answered correctly
- *    from an empty registry, which reads as a broken project tier rather than
- *    as a race.
- * 3. **Own the reconnect policy**, by dropping its connection generation when
- *    the port disposes and building a fresh one on the next request.
+ * {@link closeDocument} and {@link dispose} first wait, up to
+ * {@link settleBeforeCloseMs}, for this session's calls still in flight on the
+ * URI, or on any URI for `dispose`: a save sent just before its close would
+ * otherwise reach the server after it, and fail as not open.
  *
- * It does **not** wrap the protocol methods; callers reach them through
- * {@link connected}. The one exception is {@link openDocument}, which exists
- * because the open/watch *order* is silently wrong the other way round — see
- * its own doc.
+ * After the connection drops, the session registers again under the same id,
+ * re-opens and re-watches what it had open, tells the client of their dirty
+ * state where it changed, and reports the documents whose unsaved edits did
+ * not survive; see {@link restore}. The connection does this at
+ * once for a session with documents open, and again once any later connection
+ * is ready, so a reconnect that failed is not left to the session's own next
+ * call; any session's next call does it too.
  *
- * Generic over the transfer root so this file names no grammar. An adopter
- * binds the concrete root (or the union of them, for a multi-grammar head) at
- * its own edge.
+ * Generic over the transfer root so this file names no grammar.
+ *
+ * `TServer` is bound to a server answering with ITS OWN diagnostic shape, read
+ * back off the parameter being bound. Simplifying that to
+ * `DataServerProtocol<TTransfer>` compiles and costs the wrappers their
+ * return type: every call through `TServer` would resolve against that looser
+ * bound, so an adopter's diagnostics would come back as the framework's and
+ * the document would have to be cast on the way out.
  */
 class DataSession {
-    port;
-    client;
-    methodNamespace;
-    /** The current generation, or `undefined` before the first request / after a teardown. */
-    generation;
+    clientId;
+    host;
+    label;
+    /**
+     * How long {@link closeDocument} and {@link dispose} wait for this session's
+     * calls in flight before closing 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.
+     */
+    settleBeforeCloseMs = 10_000;
+    /**
+     * The clock {@link settleBeforeCloseMs} runs on. {@link DataSessionHost}
+     * carries no {@link Clock}, so a subclass replaces this field as it
+     * replaces the bound.
+     */
+    clock = new clock_1.SystemClock();
+    /** URIs this session has open, re-opened after a reconnect. */
+    openUris = new Set();
+    /**
+     * Per URI in {@link openUris}, the URI the server's last answer to its open
+     * or re-open named. The server keys its notifications by it, and so does
+     * the host's record of what its client was told.
+     */
+    serverUris = new Map();
+    /**
+     * Per URI, how many 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.
+     */
+    openingUris = new Map();
+    /** Per URI written since its last save, what {@link restore} needs to write it again. */
+    unsavedWrites = new Map();
+    /**
+     * Per URI this session has open, the text 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}.
+     */
+    lastAnswers = new Map();
+    /**
+     * Per URI this session has open, the text version its last save or persist
+     * of it wrote, as its answer's `persisted` says; see {@link recordWrite}.
+     * Not the answer's model version, which can carry a write that landed
+     * after the text was taken. Only those set it: an open answers at the
+     * version of a write still in flight as well, and that write is not saved.
+     */
+    savedVersions = new Map();
+    /** Per URI, this session's calls still in flight on it, which a close waits for. */
+    inFlight = new Map();
+    /** This session's saves still in flight, which a host's exit waits for; see {@link hasSavesInFlight}. */
+    savesInFlight = new Set();
+    disposeEmitter = new vscode_jsonrpc_1.Emitter();
+    /**
+     * Fires once when the session ends, by {@link dispose} or {@link detach}, as
+     * soon as it rejects further calls and before any close is sent. For a
+     * session its connection created, the connection's listener runs first, so
+     * the id is free again on that connection by the time any other listener
+     * runs; the server still holds it until the close arrives, and refuses a new
+     * session under it until then.
+     *
+     * A listener subscribed once the session has ended is never called, so a
+     * late subscriber checks {@link isDisposed} first.
+     */
+    onDidDispose = this.disposeEmitter.event;
+    /**
+     * Sent with every registration, so the server lets this session register
+     * its id again while the dropped connection's session is still live there:
+     * a server that has not yet noticed the drop would otherwise refuse the id
+     * as a duplicate until it does.
+     */
+    resumeToken = (0, random_uuid_1.randomUuid)();
+    /** The proxy the session is registered on; another one means the connection was replaced. */
+    registeredOn;
+    registration;
     disposed = false;
-    portDisposeListener;
-    constructor(port, client, options = {}) {
-        this.port = port;
-        this.client = client;
-        this.methodNamespace = options.methodNamespace ?? data_1.DATA_SERVER_WIRE_PREFIX;
-        this.portDisposeListener = this.port.onDispose(() => this.dropGeneration());
-    }
-    /** The identity every request is made under — the port's, not a second one. */
-    get clientId() {
-        return this.port.clientId;
+    /**
+     * Disposed through {@link detach} rather than {@link dispose}, so nothing may
+     * be sent. Folding it into {@link disposed} would send the session's close
+     * over a connection that is going away.
+     */
+    detached = false;
+    /** The subscription to the host's `onDidChangeDirty`, disposed with the session. */
+    dirtySubscription;
+    /** The subscription to the host's `onDidUpdateDocument`, disposed with the session. */
+    updateSubscription;
+    constructor(clientId, host, label) {
+        this.clientId = clientId;
+        this.host = host;
+        this.label = label;
+        this.dirtySubscription = host.onDidChangeDirty?.(event => this.forgetSavedWrite(event));
+        this.updateSubscription = host.onDidUpdateDocument?.(event => this.forgetSupersededWrite(event));
     }
     /**
-     * The connected, READY server proxy.
-     *
-     * Returns the proxy rather than `void` on purpose. A reconnect replaces the
-     * proxy, so a caller that cached one from an earlier call would go on
-     * addressing a dead connection with no error — handing it back per call
-     * makes the stale reference unrepresentable.
-     *
-     * Concurrent callers share one readiness promise, so `waitForReady` is
-     * awaited once per generation and not once per caller.
+     * The connected, READY server proxy once this session is registered on it,
+     * for protocol methods this session does not wrap. The proxy stamps
+     * nothing: pass this session's {@link clientId} to any method that carries
+     * one.
      */
     async connected() {
-        if (this.disposed) {
-            throw new Error('DataSession is disposed');
-        }
-        const generation = this.currentGeneration();
-        if (!generation.ready) {
-            generation.ready = this.awaitReady(generation);
+        // `async` so a disposed session REJECTS rather than throwing
+        // synchronously: the connection's own `connected` rejects, and a caller
+        // reaching for `.catch` on one of them would not catch the other.
+        this.assertLive();
+        const server = await this.host.connected();
+        // Again after the wait: a session disposed meanwhile must not register,
+        // since its dispose found nothing registered to end.
+        this.assertLive();
+        if (this.registeredOn !== server) {
+            const reconnected = this.registeredOn !== undefined;
+            this.registeredOn = server;
+            this.registration = this.register(server, reconnected);
         }
-        await generation.ready;
-        return generation.server;
+        await this.registration;
+        // And after the registration: a call waiting on it has not reached the
+        // wire, and sent now it would land after the session's close.
+        this.assertLive();
+        return server;
     }
     /**
-     * Open `uri` for editing and start watching it, in that order, returning
-     * the opened snapshot.
+     * Open `args.uri` for editing and start watching it, in that order,
+     * returning the opened snapshot.
      *
      * **The order is the whole reason this method exists.**
      * `watchModelDocument` baselines its dedup fingerprint from the *current*
@@ -87,30 +199,176 @@ class DataSession {
      * baseline, and the first phase event after the open arrives as a spurious
      * `'changed'` — which a widget that resets its in-memory root to the server
      * view misreads as a concurrent third-party write, losing whatever the user
-     * had typed. Nothing about the wrong order fails loudly, so it is encoded
-     * here rather than documented and re-derived.
+     * had typed.
      *
-     * Note that the returned snapshot's empty `diagnostics` does not mean
-     * valid: `open` settles at the integrity landmark, not at validation.
+     * Note that the returned snapshot's model usually has no `diagnostics`:
+     * `open` settles at the integrity landmark, not at validation.
      * Validity arrives asynchronously on `onDocumentUpdated`, or synchronously
      * from `getModelDocument({ includeDiagnostics: true })`.
      */
-    async openDocument(uri) {
-        const server = await this.connected();
-        const document = await server.openModelDocument({ uri, clientId: this.clientId });
-        await server.watchModelDocument({ uri, clientId: this.clientId });
+    openDocument(args) {
+        return this.trackOpen(args.uri, async () => {
+            const server = await this.connected();
+            return this.watchOpened(server, args.uri, await server.openModelDocument({ ...args, clientId: this.clientId }));
+        });
+    }
+    /**
+     * Create a document that exists nowhere yet, open and watched for this
+     * session; it reaches disk with the first {@link saveDocument}. The server
+     * refuses a URI that exists on disk or that any client has open.
+     */
+    createDocument(args) {
+        return this.trackOpen(args.uri, async () => {
+            const server = await this.connected();
+            return this.watchOpened(server, args.uri, await server.createModelDocument({ ...args, clientId: this.clientId }));
+        });
+    }
+    /**
+     * Watch a document this session just opened, and record it as open. A
+     * failed watch closes it again: the caller sees a failed open and so would
+     * never close it.
+     */
+    async watchOpened(server, uri, document) {
+        try {
+            await server.watchModelDocument({ uri, clientId: this.clientId });
+        }
+        catch (error) {
+            await server.closeModelDocument({ uri, clientId: this.clientId }).catch(() => undefined);
+            throw error;
+        }
+        this.openUris.add(uri);
+        this.serverUris.set(uri, document.uri);
+        this.recordText(uri, document);
+        // Keyed as the server keys its notifications, which may not be how the
+        // caller spelled the URI.
+        this.host.forgetDirty?.(document.uri);
         return document;
     }
     /**
-     * Close `uri`. The server unwatches implicitly, so this is the dual of
-     * {@link openDocument} and needs no separate unwatch.
+     * Close `args.uri`, once this session's calls on it have settled or
+     * {@link settleBeforeCloseMs} has passed. The server unwatches implicitly,
+     * so this is the dual of {@link openDocument} and needs no separate unwatch.
      */
-    async closeDocument(uri) {
+    async closeDocument(args) {
+        this.assertLive();
+        await this.settle(this.inFlight.get(args.uri));
+        // Forgotten before the close is sent, so a reconnect in between does not
+        // re-open a document the caller has closed; after the wait, so an open
+        // of it that was still in flight does not record it again.
+        const serverUri = this.serverUris.get(args.uri) ?? args.uri;
+        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({ uri, clientId: this.clientId });
+        await server.closeModelDocument({ ...args, clientId: this.clientId });
+    }
+    /**
+     * Open `args.uri`, run `fn` with the opened snapshot, and close it once
+     * `fn` settles, whether it returned or threw. A URI this session already
+     * had open, or is still opening through another call, stays open: the close
+     * undoes only the open this call made.
+     */
+    async withOpenDocument(args, fn) {
+        const alreadyOpen = this.openUris.has(args.uri) || this.openingUris.has(args.uri);
+        const document = await this.openDocument(args);
+        try {
+            return await fn(document);
+        }
+        finally {
+            if (!alreadyOpen && !this.disposed) {
+                await this.closeDocument({ uri: args.uri });
+            }
+        }
+    }
+    /** Write `args.model` back as this session. The session must have `args.uri` open. */
+    updateDocument(args) {
+        return this.track([args.uri], async () => {
+            const server = await this.connected();
+            const update = { ...args };
+            const baseHash = await this.baseHashOf(server, args.uri, args.baseVersion);
+            const document = await server.updateModelDocument({ ...args, clientId: this.clientId });
+            this.recordWrite(args.uri, document, baseHash, { update });
+            return document;
+        });
+    }
+    /**
+     * Write several documents this session has open, all or none: the server
+     * refuses the whole set, before any text applies, when one is stale or not
+     * open. Resolves to the documents in the order given.
+     */
+    updateDocuments(args) {
+        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.baseVersion)));
+            const documents = await server.updateModelDocuments({ ...args, clientId: this.clientId });
+            args.updates.forEach((update, index) => this.recordWrite(update.uri, documents[index], baseHashes[index], { updates, index }));
+            return documents;
+        });
+    }
+    /** Persist `args.model` to disk as this session. The session must have `args.uri` open. */
+    saveDocument(args) {
+        return this.trackSave(args.uri, server => server.saveModelDocument({ ...args, clientId: this.clientId }));
+    }
+    /**
+     * Persist the text the server holds for `args.uri` as this session, with no
+     * model of its own. The session must have `args.uri` open.
+     */
+    persistDocument(args) {
+        return this.trackSave(args.uri, server => server.persistModelDocument({ ...args, clientId: this.clientId }));
+    }
+    /** Run a save or persist of `uri` and record what it answered as saved. */
+    trackSave(uri, send) {
+        const saving = this.track([uri], async () => {
+            const server = await this.connected();
+            const document = await send(server);
+            // Kept only when its last answer is newer than the text written. Kept
+            // whenever it changed while the save ran, a record the save covered
+            // survives, and a restore then reports it lost.
+            const unsaved = this.unsavedWrites.get(uri);
+            if (unsaved && unsaved.answer.version <= document.persisted.version) {
+                this.unsavedWrites.delete(uri);
+            }
+            this.recordText(uri, document);
+            // The higher of two saves' answers, which may arrive out of order.
+            const saved = this.savedVersions.get(uri);
+            if (saved === undefined || document.persisted.version > saved) {
+                this.savedVersions.set(uri, document.persisted.version);
+            }
+            return document;
+        });
+        this.savesInFlight.add(saving);
+        const done = () => this.savesInFlight.delete(saving);
+        saving.then(done, done);
+        return saving;
+    }
+    /** Whether the session has ended, by {@link dispose} or {@link detach}. */
+    get isDisposed() {
+        return this.disposed;
+    }
+    /**
+     * Whether a save of this session has not answered yet. Synchronous, for a
+     * host whose exit veto must decide within the tick, such as Theia's
+     * `onWillStop`.
+     */
+    get hasSavesInFlight() {
+        return this.savesInFlight.size > 0;
     }
     /**
-     * Whether `event.sourceClientId` identifies this session's own write.
+     * Resolves once the saves in flight now have answered, or
+     * {@link settleBeforeCloseMs} has passed. Never rejects: a failed save has
+     * answered too.
+     */
+    whenSavesSettled() {
+        return this.settle(this.savesInFlight);
+    }
+    /**
+     * Whether `sourceClientId` identifies this session's own write.
      *
      * Every watcher needs this and the check is one comparison, so getting it
      * wrong is cheap to do and expensive to find: an unfiltered echo looks
@@ -119,60 +377,437 @@ class DataSession {
     isOwnEcho(sourceClientId) {
         return sourceClientId === this.clientId;
     }
-    /** Tear down the current connection and stop tracking the port. Idempotent. */
+    /**
+     * End the session: detach it from the connection at once, and once its
+     * calls in flight have settled or {@link settleBeforeCloseMs} has passed,
+     * end it on the server, which closes everything it has open. Idempotent,
+     * and leaves the connection usable by its other sessions.
+     *
+     * Every later call rejects, and so does a call made earlier in the same
+     * tick, which has not reached the wire yet and is never sent. The server
+     * close is not awaited, because a `Disposable` cannot be; a close that fails
+     * leaves the session to the server's connection-close cleanup.
+     */
     dispose() {
         if (this.disposed) {
             return;
         }
         this.disposed = true;
-        this.portDisposeListener.dispose();
-        this.dropGeneration();
-    }
-    /** The live generation, building one if there is none. */
-    currentGeneration() {
-        if (this.generation) {
-            return this.generation;
-        }
-        const connection = this.port.connect();
-        // Rejection is reported here rather than left to float: an unhandled
-        // rejection on a connection promise is the failure mode that reads as
-        // "the model is empty" instead of "the transport never opened".
-        connection.catch((error) => this.port.reportError(error, 'connecting to the data server'));
-        const server = (0, rpc_1.createRpcProxy)(connection, {
-            methodNamespace: this.methodNamespace,
-            localTarget: this.client,
-            localMethods: data_1.DATA_CLIENT_PROTOCOL_METHODS
-        });
-        this.generation = { connection, server };
-        return this.generation;
+        this.fireDispose();
+        const pending = [...this.inFlight.values()].flatMap(calls => [...calls]);
+        void (async () => {
+            await this.settle(pending);
+            await this.registration;
+            // The proxy the session registered on, never a fresh connection: a
+            // connection that dropped already ended the session on the server.
+            if (!this.detached && this.registeredOn) {
+                await this.registeredOn.closeSession({ clientId: this.clientId });
+            }
+        })().catch(() => undefined);
     }
-    /** Await the connection and the server's startup gate for one generation. */
-    async awaitReady(generation) {
+    /**
+     * Come off the connection because it is going away.
+     *
+     * Sends nothing, unlike {@link dispose}: the server ends every session on a
+     * connection it sees close, and the close would travel over the very
+     * connection being disposed.
+     *
+     * Public because the connection calls it; anyone else ends a session with
+     * {@link dispose}. It fires {@link onDidDispose} only if the session has not
+     * already ended, and after {@link dispose} it still cancels the close that
+     * dispose has not sent yet.
+     */
+    detach() {
+        this.detached = true;
+        this.openUris.clear();
+        this.serverUris.clear();
+        this.unsavedWrites.clear();
+        this.lastAnswers.clear();
+        this.savedVersions.clear();
+        if (!this.disposed) {
+            this.disposed = true;
+            this.fireDispose();
+        }
+    }
+    /**
+     * Dispose {@link dirtySubscription} and {@link updateSubscription}, fire
+     * {@link onDidDispose} and dispose its emitter, so a second call fires
+     * nothing.
+     */
+    fireDispose() {
+        this.dirtySubscription?.dispose();
+        this.updateSubscription?.dispose();
+        this.disposeEmitter.fire(undefined);
+        this.disposeEmitter.dispose();
+    }
+    /**
+     * Register again and restore now, after the connection dropped, instead of
+     * on the next call. A no-op for a session with nothing open, which the next
+     * call restores anyway, and for one already registered on the current
+     * connection. A failure is retried on the connection's next ready
+     * generation; a call before then meets it again.
+     */
+    reconnect() {
+        if (!this.disposed && this.openUris.size > 0) {
+            this.connected().catch(() => undefined);
+        }
+    }
+    /**
+     * 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.
+     */
+    forgetSavedWrite(event) {
+        if (event.text?.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.
+     */
+    forgetSupersededWrite(event) {
+        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.
+     */
+    async register(server, reconnected) {
+        await server.createSession({ clientId: this.clientId, label: this.label, resumeToken: this.resumeToken });
+        if (reconnected) {
+            await this.restore(server);
+        }
+    }
+    /**
+     * 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.
+     *
+     * Decided per document by the re-opened document's `text.hash`,
+     * 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.
+     *
+     * 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 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 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.
+     */
+    async restore(server) {
+        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();
+        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.recordText(uri, document);
+                }
+                reopened.set(uri, document);
+            }
+            catch (error) {
+                // Its record goes with its set's, in `reapply`, which it blocks.
+                this.openUris.delete(uri);
+                this.serverUris.delete(uri);
+                this.lastAnswers.delete(uri);
+                this.savedVersions.delete(uri);
+                this.host.reportError?.(error, (0, primitives_1.resolve)(exports.DATA_SESSION_RESTORE_FAILED, { uri, detail: (0, primitives_1.describeError)(error) }));
+            }
+        }
+        const sets = new Map();
+        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 = [];
+        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, 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 (current?.text !== undefined) {
+                try {
+                    this.host.restoreDirty?.({ uri: current.uri, text: current.text });
+                }
+                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 = (0, primitives_1.resolve)(exports.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 `text` comes from a server that sends none, and
+     * counts as kept only at the version the write was answered with. One
+     * without a model has no version to send the write again on.
+     */
+    restoreOutcome(write, document) {
+        if (document.text === undefined) {
+            return document.model?.version === write.answer.version ? 'kept' : 'lost';
+        }
+        if (document.text.hash === write.answer.hash) {
+            return 'kept';
+        }
+        return document.model && write.baseHash !== undefined && document.text.hash === 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.
+     */
+    async reapply(server, members, reopened) {
+        const current = (uri, write) => !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: this.answerOf(uri, document) });
+            }
+        }
+        // A document that could not be re-opened is forgotten, and was reported
+        // as such.
+        const lose = () => {
+            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?.model ? [{ uri, write, baseVersion: document.model.version }] : [])
+            .sort((left, right) => indexOf(left.write) - indexOf(right.write));
+        if (resend.length === 0) {
+            return [];
+        }
+        let documents;
         try {
-            await generation.connection;
-            await generation.server.waitForReady();
+            const { call } = resend[0].write;
+            if ('update' in call) {
+                documents = [await server.updateModelDocument({ ...call.update, baseVersion: resend[0].baseVersion, clientId: this.clientId })];
+            }
+            else {
+                const baseVersion = new Map(resend.map(member => [indexOf(member.write), member.baseVersion]));
+                documents = await server.updateModelDocuments({
+                    ...call.updates,
+                    clientId: this.clientId,
+                    updates: call.updates.updates.flatMap((update, index) => {
+                        const version = baseVersion.get(index);
+                        return version === undefined ? [] : [{ ...update, baseVersion: version }];
+                    })
+                });
+            }
         }
         catch (error) {
-            // Drop the generation so the next request retries rather than
-            // re-awaiting a settled rejection forever.
-            if (this.generation === generation) {
-                this.generation = undefined;
+            if ((0, errors_1.isConflictError)(error)) {
+                return lose();
             }
-            this.port.reportError(error, 'waiting for the data server to become ready');
-            throw error;
+            for (const { uri, write, baseVersion } of resend) {
+                this.host.reportError?.(error, (0, primitives_1.resolve)(exports.DATA_SESSION_RESTORE_FAILED, { uri, detail: (0, primitives_1.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: baseVersion } });
+                }
+            }
+            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 [];
     }
     /**
-     * Discard the current generation, disposing its connection if it opened.
-     * The next {@link connected} builds a fresh one.
+     * The text hash of the version `baseVersion` 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.
      */
-    dropGeneration() {
-        const generation = this.generation;
-        this.generation = undefined;
-        if (!generation) {
+    async baseHashOf(server, uri, baseVersion) {
+        if (this.unsavedWrites.has(uri) || !(0, base_version_1.isModelVersion)(baseVersion)) {
+            return undefined;
+        }
+        const known = this.lastAnswers.get(uri);
+        if (known?.version === baseVersion) {
+            return known.hash;
+        }
+        const read = await server.getModelDocument({ uri }).catch(() => undefined);
+        return read?.text?.version === baseVersion ? read.text.hash : 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.
+     */
+    recordWrite(uri, document, baseHash, call) {
+        const answer = this.answerOf(uri, document);
+        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;
         }
-        generation.connection.then(connection => connection.dispose()).catch(() => undefined);
+        this.unsavedWrites.set(uri, { baseHash: kept ? kept.baseHash : baseHash, answer, call });
+        this.recordText(uri, document);
+    }
+    /**
+     * What {@link DataSessionUnsavedWrite.answer} keeps of `document`. Every write
+     * and open answers with a model; one without is reported and counted older
+     * than every version, so it never replaces a real answer.
+     */
+    answerOf(uri, document) {
+        if (!document.model) {
+            const reported = (0, primitives_1.resolve)(exports.DATA_SESSION_ANSWER_WITHOUT_MODEL, { uri });
+            this.host.reportError?.(new Error(reported.text), reported);
+            return { version: base_version_1.UNRECORDED_VERSION, hash: document.text?.hash };
+        }
+        return { version: document.model.version, hash: document.text?.hash };
+    }
+    /** Keep `document`'s text in {@link lastAnswers}, or forget it for a server that sends none. */
+    recordText(uri, document) {
+        if (document.text) {
+            this.lastAnswers.set(uri, document.text);
+        }
+        else {
+            this.lastAnswers.delete(uri);
+        }
+    }
+    /** Run `call`, counted as in flight on each of `uris` until it settles. */
+    track(uris, call) {
+        const running = call();
+        for (const uri of uris) {
+            this.inFlight.set(uri, (this.inFlight.get(uri) ?? new Set()).add(running));
+        }
+        const done = () => uris.forEach(uri => this.inFlight.get(uri)?.delete(running));
+        running.then(done, done);
+        return running;
+    }
+    /** {@link track} an open of `uri`, counted in {@link openingUris} until it settles. */
+    trackOpen(uri, call) {
+        this.openingUris.set(uri, (this.openingUris.get(uri) ?? 0) + 1);
+        const done = () => {
+            const remaining = (this.openingUris.get(uri) ?? 1) - 1;
+            if (remaining > 0) {
+                this.openingUris.set(uri, remaining);
+            }
+            else {
+                this.openingUris.delete(uri);
+            }
+        };
+        const running = this.track([uri], call);
+        running.then(done, done);
+        return running;
+    }
+    /** Wait until `calls` have settled, or {@link settleBeforeCloseMs} has passed. */
+    async settle(calls) {
+        const pending = [...(calls ?? [])];
+        if (pending.length === 0) {
+            return;
+        }
+        await this.clock.raceTimer(Promise.allSettled(pending), this.settleBeforeCloseMs);
+    }
+    assertLive() {
+        if (this.disposed) {
+            throw new errors_1.SessionClosedError(this.clientId);
+        }
     }
 }
 exports.DataSession = DataSession;