@hydranium/protocol 1.0.0-next.35 → 1.0.0-next.350

package/lib/client/data-session.d.ts

@@ -6,92 +6,363 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import type { MessageConnection } from 'vscode-jsonrpc';
-import { type DataClientProtocol, type DataServerProtocol } from '../data';
-import { type RpcProxy } from '../rpc';
-import type { TransferDocument } from '../transfer-document';
+import { type Disposable, Emitter, type Event } from 'vscode-jsonrpc';
+import { type Clock } from '../clock';
+import type { DataServerProtocol, DiagnosticOf, TransferDocumentDeletedEvent, TransferDocumentDirtyChangedEvent, TransferDocumentUpdatedEvent } from '../data';
+import type { Logger } from '../logger';
+import { type BaseVersion, type ModelVersion } from '../model-service/base-version';
+import { type ResolvedMessage } from '../messages/primitives';
+import { PendingWorkTracker } from '../pending-work-tracker';
+import type { MaybePromise } from '../util';
+import type { RpcProxy } from '../rpc';
+import type { TextState, TransferCreatedDocument, TransferDocument, TransferSavedDocument } from '../transfer-document';
 import type { TransferElement } from '../transfer-element';
-import type { DataPort } from './data-port';
 /**
- * The transport never opened. A complete sentence rather than a fragment: a
- * fragment is nested inside a sentence the framework does not own, so no
- * translator controls the whole and the composition cannot be made to read
- * correctly in every language.
+ * 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.
  */
-export declare const DATA_SERVER_CONNECT_FAILED: import("../messages/primitives").MessageDefinition<"Could not connect to the data server: {detail}">;
-export declare const DATA_SERVER_NOT_READY: import("../messages/primitives").MessageDefinition<"The data server did not become ready: {detail}">;
-/** Options for {@link DataSession}. */
-export interface DataSessionOptions {
-    /**
-     * Wire namespace the server is addressed under. Defaults to the
-     * framework's {@link DATA_SERVER_WIRE_PREFIX}, which is what an unmodified
-     * `DataServer` binds. Override only alongside the server's own
-     * `methodNamespace` option — a mismatch turns every request into
-     * "Unhandled method" rather than failing at wire-up.
-     */
-    readonly methodNamespace?: string;
+export declare const DATA_SESSION_RESTORE_FAILED: import("../messages/primitives").MessageDefinition<"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. */
+export declare const DATA_SESSION_ANSWER_WITHOUT_MODEL: import("../messages/primitives").MessageDefinition<"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.
+ */
+export declare const DATA_SESSION_UNSAVED_LOST: import("../messages/primitives").MessageDefinition<"Unsaved changes to {uris} may have been lost when the connection to the data server dropped.">;
+/**
+ * What one of `TServer`'s document methods takes, minus the `clientId` a
+ * {@link DataSession} stamps itself.
+ *
+ * Read off the SERVER's signature, not off the framework's own arg type: an
+ * adopter server widens these, and a wrapper declared against the narrow
+ * shape rejects the extra field on a fresh object literal, so that call
+ * cannot go through a session at all.
+ */
+export type DataSessionArgs<TMethod extends (args: never) => unknown> = Omit<Parameters<TMethod>[0], 'clientId'>;
+/**
+ * Open a document through a session; the session supplies `clientId`. Only the
+ * 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, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = 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<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['createModelDocument']>;
+/** Close a document through a session; the session supplies `clientId`. */
+export type DataSessionCloseArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['closeModelDocument']>;
+/** Update a document through a session; the session supplies `clientId`. */
+export type DataSessionUpdateArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['updateModelDocument']>;
+/** Update several documents at once through a session; the session supplies `clientId`. */
+export type DataSessionUpdatesArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['updateModelDocuments']>;
+/** Persist a document through a session; the session supplies `clientId`. */
+export type DataSessionSaveArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['saveModelDocument']>;
+/** Persist the text the server holds through a session; the session supplies `clientId`. */
+export type DataSessionPersistArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['persistModelDocument']>;
+/** Delete a document through a session; the session supplies `clientId`. */
+export type DataSessionDeleteArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['deleteModelDocument']>;
+/** The document a session hands back, carrying its server's diagnostic shape. */
+export type DataSessionDocument<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = TransferDocument<TTransfer, DiagnosticOf<TServer>>;
+/**
+ * What a {@link DataSession} keeps of a URI it wrote since the URI's last save,
+ * to write it again after a reconnect that lost it.
+ */
+export interface DataSessionUnsavedWrite<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> {
+    /**
+     * The `text.hash` of the text the first of these writes was based on.
+     * `undefined` when the session could not tell, for a write based on
+     * `'any'` or on a version it could not read back, and such a write is
+     * never sent again: the session cannot tell another client's text from the
+     * text it wrote over.
+     */
+    readonly baseHash: string | undefined;
+    /**
+     * The model version the last of these writes was answered with, which
+     * orders its answers, and the `text.hash` of that answer.
+     */
+    readonly answer: {
+        readonly version: ModelVersion;
+        readonly hash?: string;
+    };
+    /**
+     * The call that made the last write, and for an `updateDocuments` call this
+     * URI's index in it. Records whose `updates` is the same object were
+     * written together and are sent again together, so a restore never applies
+     * part of a set.
+     */
+    readonly call: {
+        readonly update: DataSessionUpdateArgs<TTransfer, TServer>;
+    } | {
+        readonly updates: DataSessionUpdatesArgs<TTransfer, TServer>;
+        readonly index: number;
+    };
 }
-/** One connection generation: its connection, its proxy, and its readiness. */
-interface Generation<TTransfer extends TransferElement> {
-    readonly connection: Promise<MessageConnection>;
-    readonly server: RpcProxy<DataServerProtocol<TTransfer>>;
-    /** Set on first use; the shared readiness gate for this generation. */
-    ready?: Promise<void>;
+/**
+ * One open of a URI by a {@link DataSession}, from the answer to its open,
+ * create or re-open until a close or a deletion ends it. A call records its
+ * answer only while the open it was sent under is still the URI's: checking
+ * that the URI is open accepts an answer from before a close or deletion
+ * once the URI is open again.
+ */
+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;
+}
+/**
+ * One open or create of a URI by a {@link DataSession}, from its call until it
+ * settles. A close of the URI while it is under way marks it: it then records
+ * 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<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>;
 }
 /**
- * The host-invariant half of talking to the data head: everything above
- * {@link DataPort} that would otherwise be re-derived by every host
- * adapter.
+ * What a {@link DataSession} needs from the connection that minted it.
  *
- * Three jobs, and deliberately no fourth:
+ * Narrower than the connection itself so the dependency points one way:
+ * `DataConnection` constructs sessions, and nothing here imports it back.
+ */
+export interface DataSessionHost<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>>> {
+    /** The connected, READY proxy of the current connection; a new object after each reconnect. */
+    connected(): Promise<RpcProxy<TServer>>;
+    /** Surface a failure no caller is waiting on, such as restoring a document after a reconnect. */
+    reportError?(error: unknown, reported: ResolvedMessage): void;
+    /**
+     * Tell the connection's client the dirty state a restore read, unless it
+     * 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
+     * close leaves nothing to restore. Forgetting a URI another session still
+     * has open costs at most one repeat of a state the client already has.
+     */
+    forgetDirty?(uri: string): void;
+    /**
+     * Fires with each flip of a document's dirty state the server sends. A
+     * session drops the unsaved write it keeps of a document that turns
+     * clean; without this event it keeps it, and a restore after another
+     * client's save of the document can report the write lost.
+     */
+    readonly onDidChangeDirty?: Event<TransferDocumentDirtyChangedEvent>;
+    /**
+     * Fires with each update event the server sends. A session drops the
+     * unsaved write it keeps of a document another client wrote over; without
+     * this event it keeps it, and a restore reports the write lost.
+     */
+    readonly onDidUpdateDocument?: Event<TransferDocumentUpdatedEvent<TTransfer, DiagnosticOf<TServer>>>;
+    /**
+     * 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.
+     */
+    readonly onDidDeleteDocument?: Event<TransferDocumentDeletedEvent>;
+    /** Where the session logs the documents it forgets as gone. */
+    readonly logger?: Logger;
+}
+/**
+ * Builds the session `DataConnection.createSession` hands out, for an adopter
+ * that extends {@link DataSession}. The connection has minted `clientId` and
+ * checked it by then.
+ */
+export type DataSessionFactory<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>>> = (clientId: string, host: DataSessionHost<TTransfer, TServer>, label: string) => DataSession<TTransfer, TServer>;
+/**
+ * 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.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * {@link closeDocument}, {@link deleteDocument} 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. An open or
+ * create of a URI called while a close or delete of it is under way is sent
+ * once that has answered, so the server takes them in the order they were
+ * called.
  *
- * 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.
+ * 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.
+ *
+ * `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.
  */
-export declare class DataSession<TTransfer extends TransferElement> {
-    protected readonly port: DataPort;
-    protected readonly client: DataClientProtocol<TTransfer>;
-    protected readonly methodNamespace: string;
-    /** The current generation, or `undefined` before the first request / after a teardown. */
-    protected generation?: Generation<TTransfer>;
-    protected disposed: boolean;
-    protected readonly portDisposeListener: {
-        dispose(): void;
-    };
-    constructor(port: DataPort, client: DataClientProtocol<TTransfer>, options?: DataSessionOptions);
-    /** The identity every request is made under — the port's, not a second one. */
-    get clientId(): string;
+export declare class DataSession<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> implements Disposable {
+    readonly clientId: string;
+    protected readonly host: DataSessionHost<TTransfer, TServer>;
+    readonly label: string;
     /**
-     * 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.
+     * How long {@link closeDocument}, {@link deleteDocument} and {@link dispose}
+     * wait for this session's calls in flight before going on anyway. Long,
+     * 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;
+    /**
+     * How long {@link whenWritesSettled} waits before going on anyway: well past
+     * the server's bound on the language-client settle it runs before answering
+     * an update. The update itself has no bound, so a server slower than that is
+     * taken as lost.
+     */
+    protected readonly settleWritesMs: number;
+    /**
+     * The clock {@link settleBeforeCloseMs} runs on. {@link DataSessionHost}
+     * carries no {@link Clock}, so a subclass replaces this field as it
+     * replaces the bound.
+     */
+    protected readonly clock: Clock;
+    /** URIs this session has open, re-opened after a reconnect. */
+    protected readonly openUris: Set<string>;
+    /**
+     * Per URI in {@link openUris}, or whose open answered and whose watch is
+     * still under way, the open it is under. A repeat open keeps it, as the
+     * server keeps its earlier open.
+     */
+    protected readonly opens: 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: 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}.
+     */
+    protected readonly endings: Map<string, Promise<unknown>>;
+    /** Per URI written since its last save, what {@link restore} needs to write it again. */
+    protected readonly unsavedWrites: Map<string, DataSessionUnsavedWrite<TTransfer, TServer>>;
+    /**
+     * 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}.
+     */
+    protected readonly lastAnswers: Map<string, TextState>;
+    /**
+     * 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.
+     */
+    protected readonly savedVersions: Map<string, number>;
+    /**
+     * URIs this session created whose whole text is still its own and unsaved,
+     * even with no write recorded: no save, clean flip, other client's write or
+     * reported loss has come since the create, its answer included; see
+     * {@link forgetGoneDocument}.
+     */
+    protected readonly createdUris: Set<string>;
+    /** Per URI, this session's calls still in flight on it, which a close or delete waits for. */
+    protected readonly inFlight: Map<string, PendingWorkTracker>;
+    /** This session's saves, persists and deletes still in flight, which a host's exit waits for; see {@link hasSavesInFlight}. */
+    protected readonly savesInFlight: PendingWorkTracker;
+    /** This session's updates still in flight, which a page's unload guard and save account for; see {@link hasWritesInFlight}. */
+    protected readonly writesInFlight: PendingWorkTracker;
+    protected readonly disposeEmitter: Emitter<void>;
+    /**
+     * 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.
      *
-     * Concurrent callers share one readiness promise, so `waitForReady` is
-     * awaited once per generation and not once per caller.
+     * A listener subscribed once the session has ended is never called, so a
+     * late subscriber checks {@link isDisposed} first.
      */
-    connected(): Promise<RpcProxy<DataServerProtocol<TTransfer>>>;
+    readonly onDidDispose: Event<void>;
     /**
-     * Open `uri` for editing and start watching it, in that order, returning
-     * the opened snapshot.
+     * 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.
+     */
+    protected readonly resumeToken: string;
+    /** The proxy the session is registered on; another one means the connection was replaced. */
+    protected registeredOn?: RpcProxy<TServer>;
+    protected registration?: Promise<void>;
+    protected disposed: boolean;
+    /**
+     * 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.
+     */
+    protected detached: boolean;
+    /**
+     * 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: 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. */
+    protected readonly updateSubscription?: Disposable;
+    /** The subscription to the host's `onDidDeleteDocument`, disposed with the session. */
+    protected readonly deletionSubscription?: Disposable;
+    /** The host's logger, or one that logs nothing. */
+    protected readonly logger: Logger;
+    constructor(clientId: string, host: DataSessionHost<TTransfer, TServer>, label: string);
+    /**
+     * 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.
+     */
+    connected(): Promise<RpcProxy<TServer>>;
+    /**
+     * 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*
@@ -99,39 +370,363 @@ export declare class DataSession<TTransfer extends TransferElement> {
      * 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 })`.
      */
-    openDocument(uri: string): Promise<TransferDocument<TTransfer>>;
+    openDocument(args: DataSessionOpenArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>>;
     /**
-     * Close `uri`. The server unwatches implicitly, so this is the dual of
-     * {@link openDocument} and needs no separate unwatch.
+     * 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. The answer
+     * names the version the create made in `created`, which a write of what
+     * this session created is based on: the answered model can already be
+     * another client's write or an integrity repair.
      */
-    closeDocument(uri: string): Promise<void>;
+    createDocument(args: DataSessionCreateArgs<TTransfer, TServer>): Promise<TransferCreatedDocument<TTransfer, DiagnosticOf<TServer>>>;
     /**
-     * Whether `event.sourceClientId` identifies this session's own write.
+     * Send `open` and watch what it answered, again for as long as a deletion
+     * heard while the watch is under way closes that open: sent after the
+     * deletion, the open fails as an open of a gone file does, or opens the
+     * file that is back. `created` reads the version the create made off the
+     * answered document, or none for an open; see {@link watchOpened} for the
+     * mark it puts in {@link createdUris}.
+     *
+     * An `opening` a close marked answers with the document, recording nothing
+     * and sending nothing again; one it marked before the open answered is
+     * undone, since the server may have taken the close first. A failed watch
+     * is undone too: the caller sees a failed open, and so would never close it.
+     */
+    protected openAndWatch<TDocument extends DataSessionDocument<TTransfer, TServer>>(uri: string, opening: DataSessionOpening<TTransfer, TServer>, created: (document: TDocument) => ModelVersion | undefined, open: (server: RpcProxy<TServer>) => Promise<TDocument>): Promise<TDocument>;
+    /**
+     * Watch a document this session just opened, and record it as open.
+     * Answers `undefined`, recording nothing, when a deletion heard while the
+     * watch is under way has ended the open already, and the document,
+     * recording nothing, when a close has. A failed watch rejects with the open
+     * still recorded, for its caller to undo, see {@link undoOpen}.
+     *
+     * A document created at `createdVersion` is marked in {@link createdUris}
+     * while its text is still at that version: a version past it is another's,
+     * a write or a repair, as a changed event would have said. Marked before the
+     * watch, so an event heard while it is under way clears the mark for good,
+     * and checked again against the text the watch answered, which an event
+     * sent before the watch was in place moved on unheard. The restore's
+     * re-open is the one other point the session learns of the text without
+     * hearing the events between, and checks the mark the same way. An answer
+     * without text leaves the mark as it is, at every one of the three.
+     */
+    protected watchOpened<TDocument extends DataSessionDocument<TTransfer, TServer>>(server: RpcProxy<TServer>, uri: string, document: TDocument, createdVersion?: ModelVersion): Promise<TDocument | undefined>;
+    /**
+     * 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.
+     */
+    closeDocument(args: DataSessionCloseArgs<TTransfer, TServer>): Promise<void>;
+    /**
+     * Close `uri` again after `opening` failed or was closed while under way,
+     * and drop what it recorded, unless the session still relies on the open,
+     * see {@link hasOpen}: the server holds one open per session and URI, so
+     * the close would end that one too.
+     */
+    protected undoOpen(server: RpcProxy<TServer>, uri: string, opening: DataSessionOpening<TTransfer, TServer>): Promise<void>;
+    /** Drop everything this session keeps of `uri`, which it no longer has open. */
+    protected forgetDocument(uri: string): void;
+    /**
+     * Whether this session has `uri` open, or has an open of it under way that
+     * no close has marked, other than `except`. A marked open records nothing,
+     * so nothing can rely on it.
+     */
+    protected hasOpen(uri: string, except?: DataSessionOpening<TTransfer, TServer>): boolean;
+    /**
+     * 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.
+     */
+    withOpenDocument<T>(args: DataSessionOpenArgs<TTransfer, TServer>, fn: (document: DataSessionDocument<TTransfer, TServer>) => MaybePromise<T>): Promise<T>;
+    /** Write `args.model` back as this session. The session must have `args.uri` open. */
+    updateDocument(args: DataSessionUpdateArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>>;
+    /**
+     * 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: DataSessionUpdatesArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>[]>;
+    /** Persist `args.model` to disk as this session. The session must have `args.uri` open. */
+    saveDocument(args: DataSessionSaveArgs<TTransfer, TServer>): Promise<TransferSavedDocument<TTransfer, DiagnosticOf<TServer>>>;
+    /**
+     * 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: DataSessionPersistArgs<TTransfer, TServer>): Promise<TransferSavedDocument<TTransfer, DiagnosticOf<TServer>>>;
+    /**
+     * Delete `args.uri` as this session, at once: its file, then the document.
+     * The session must have `args.uri` open. Sent once this session's calls in
+     * flight on the URI have settled, as {@link closeDocument} is, and counted
+     * in {@link hasSavesInFlight} until it answers.
+     *
+     * The session forgets the document once the delete has succeeded: on
+     * hearing its own deletion, which the server sends before it answers, or
+     * on the answer, for a client that hears no deletions. A refused delete
+     * leaves the document open, as the server does.
+     */
+    deleteDocument(args: DataSessionDeleteArgs<TTransfer, TServer>): Promise<void>;
+    /** Run a save or persist of `uri` and record what it answered as saved. */
+    protected trackSave(uri: string, send: (server: RpcProxy<TServer>) => Promise<TransferSavedDocument<TTransfer, DiagnosticOf<TServer>>>): Promise<TransferSavedDocument<TTransfer, DiagnosticOf<TServer>>>;
+    /** Whether the session has ended, by {@link dispose} or {@link detach}. */
+    get isDisposed(): boolean;
+    /**
+     * Whether a save, persist or delete 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(): boolean;
+    /**
+     * Resolves once the saves in flight now have answered, or
+     * {@link settleBeforeCloseMs} has passed. Never rejects: a failed save has
+     * answered too.
+     */
+    whenSavesSettled(): Promise<void>;
+    /**
+     * Whether an update of this session, one a restore sends again included,
+     * has not answered yet. The server answers once an editor on the language
+     * client holds the text, so a page that reads unsaved work from its editor
+     * guards a reload on this too. Synchronous, for an unload guard that must
+     * decide within the tick.
+     */
+    get hasWritesInFlight(): boolean;
+    /**
+     * Resolves to `true` once the updates in flight now have answered, so a
+     * save of the editor's documents started after it includes them, or to
+     * `false` once {@link settleWritesMs} has passed first. An update sent while
+     * it waits is not waited for. Never rejects.
+     */
+    whenWritesSettled(): Promise<boolean>;
+    /**
+     * 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
      * exactly like a concurrent third-party edit.
      */
     isOwnEcho(sourceClientId: string): boolean;
-    /** 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(): void;
-    /** The live generation, building one if there is none. */
-    protected currentGeneration(): Generation<TTransfer>;
-    /** Await the connection and the server's startup gate for one generation. */
-    protected awaitReady(generation: Generation<TTransfer>): Promise<void>;
     /**
-     * Discard the current generation, disposing its connection if it opened.
-     * The next {@link connected} builds a fresh one.
+     * 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(): void;
+    /**
+     * Dispose {@link dirtySubscription}, {@link updateSubscription} and
+     * {@link deletionSubscription}, fire {@link onDidDispose} and dispose its
+     * emitter, so a second call fires nothing.
+     */
+    protected fireDispose(): void;
+    /**
+     * 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(): void;
+    /**
+     * Drop the record in {@link unsavedWrites} of a document this session has
+     * open once the server says it turned clean, and its mark in
+     * {@link createdUris}: it holds no unsaved text then, and a record kept
+     * would have a restore report the write lost once another client's save
+     * changed the file.
+     *
+     * The server sends a flip only for a document someone watches, so a
+     * document the session writes without watching it keeps its record, and
+     * can still be reported lost that way.
+     */
+    protected forgetSavedWrite(event: TransferDocumentDirtyChangedEvent): void;
+    /**
+     * 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.
+     *
+     * The mark in {@link createdUris} goes on any such event: the unsaved text
+     * is then the other client's, and a record still kept reports the
+     * session's own.
+     */
+    protected forgetSupersededWrite(event: TransferDocumentUpdatedEvent<TTransfer, DiagnosticOf<TServer>>): void;
+    /**
+     * Forget a document whose file was deleted, which closed this session's
+     * open. At once rather than after the calls in flight settle, which would
+     * 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. 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
+     * drop the text.
+     */
+    protected forgetDeletedDocument(event: TransferDocumentDeletedEvent): void;
+    /**
+     * {@link forgetDocument} a document that is gone, logging any unsaved text
+     * it drops, written or created; returns whether it dropped some.
+     */
+    protected forgetGoneDocument(uri: string): boolean;
+    /**
+     * Register on `server`, and after a reconnect restore what the ended session
+     * had. Calls issued meanwhile wait for this.
+     */
+    protected register(server: RpcProxy<TServer>, reconnected: boolean): Promise<void>;
+    /**
+     * 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
+     * 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, 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
+     * 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. 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 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
+     * between the re-open and the watch, reached no one, and the re-open's own
+     * answer misses the second. Read before the write, it would tell the client
+     * a document is clean that the write is about to make dirty again.
+     */
+    protected restore(server: RpcProxy<TServer>): Promise<void>;
+    /**
+     * 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.
+     */
+    protected restoreOutcome(write: DataSessionUnsavedWrite<TTransfer, TServer>, document: DataSessionDocument<TTransfer, TServer>): 'kept' | '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. A set in {@link brokenSets} is
+     * not written again.
+     */
+    protected reapply(server: RpcProxy<TServer>, members: readonly [string, DataSessionUnsavedWrite<TTransfer, TServer>][], reopened: ReadonlyMap<string, DataSessionDocument<TTransfer, TServer>>): Promise<string[]>;
+    /**
+     * 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.
+     */
+    protected baseHashOf(server: RpcProxy<TServer>, uri: string, baseVersion: BaseVersion): Promise<string | undefined>;
+    /**
+     * Record `document` as the answer to a write of `uri` sent under `open`,
+     * keeping the base of the URI's record if it has one. An answer sent under
+     * no open, or under one that has ended, is ignored. So is one numbered below
+     * the record's: two writes of `uri` in flight at once may answer out of
+     * order, and the record holds the one applied last.
+     *
+     * So is one numbered at or below the URI's entry in {@link savedVersions}.
+     * The save came after that write was applied, so the save persisted its
+     * text or a later write replaced it, and its answer carries the text as it
+     * was when sent, which a restore would report as lost.
+     */
+    protected recordWrite(uri: string, open: DataSessionOpen<TTransfer, TServer> | undefined, document: DataSessionDocument<TTransfer, TServer>, baseHash: string | undefined, call: DataSessionUnsavedWrite<TTransfer, TServer>['call']): void;
+    /**
+     * 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.
+     */
+    protected answerOf(uri: string, document: DataSessionDocument<TTransfer, TServer>): DataSessionUnsavedWrite<TTransfer, TServer>['answer'];
+    /** Keep `document`'s text in {@link lastAnswers}, or forget it for a server that sends none. */
+    protected recordText(uri: string, document: DataSessionDocument<TTransfer, TServer>): void;
+    /** Run `call`, counted as in flight on each of `uris` until it settles. */
+    protected track<T>(uris: readonly string[], call: () => Promise<T>): Promise<T>;
+    /** {@link track} an update of `uris`, counted in {@link writesInFlight} too. */
+    protected trackWrite<T>(uris: readonly string[], call: () => Promise<T>): Promise<T>;
+    /**
+     * {@link track} an open of `uri`, kept in {@link openings} until it settles,
+     * and sent once the closes and deletes of `uri` called before it have
+     * answered.
+     */
+    protected trackOpen<T>(uri: string, options: DataSessionOpenOptions<TTransfer, TServer>, call: (opening: DataSessionOpening<TTransfer, TServer>) => Promise<T>): Promise<T>;
+    /**
+     * Run `end`, a close or delete of `uri`, kept in {@link endings} until it
+     * and every earlier one of `uri` have settled.
      */
-    protected dropGeneration(): void;
+    protected trackEnding(uri: string, end: () => Promise<void>): Promise<void>;
+    /** Wait until the work `trackers` hold now has settled, or {@link settleBeforeCloseMs} has passed. */
+    protected settle(trackers: Iterable<PendingWorkTracker | undefined>): Promise<void>;
+    protected assertLive(): void;
 }
-export {};
 //# sourceMappingURL=data-session.d.ts.map