@hydranium/protocol 1.0.0-next.32 → 1.0.0-next.321

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

@@ -10,16 +10,29 @@
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
 import type { Project } from '../project';
-import type { TransferDocument } from '../transfer-document';
+import type { TransferCreatedDocument, TransferDocument, TransferSavedDocument, TransferWatchedDocument } from '../transfer-document';
 import type { CloseModelArgs, FindNextNameArgs, OpenModelArgs, ReferenceContext, ReferenceRequest } from '../model-server';
 import type { ReferenceCandidate, ReferenceTarget } from '../model-service/reference-candidate';
-import type { ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from './events';
 import type {
+   ProjectsChangedEvent,
+   TransferDocumentDeletedEvent,
+   TransferDocumentDirtyChangedEvent,
+   TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
+   TransferDocumentUpdatedEvent
+} from './events';
+import type {
+   CloseSessionArgs,
+   CreateModelDocumentArgs,
+   CreateSessionArgs,
    GetModelDocumentArgs,
    GetProjectForUriArgs,
+   TransferDeleteDocumentArgs,
+   TransferPersistDocumentArgs,
    TransferSaveDocumentArgs,
    WatchModelDocumentArgs,
-   TransferUpdateDocumentArgs
+   TransferUpdateDocumentArgs,
+   TransferUpdateDocumentsArgs
 } from './requests';
 
 /**
@@ -40,35 +53,77 @@ import type {
  */
 export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
    /**
-    * Open a document for an editor session and return its current state.
-    * Registers `(uri, clientId)` with the multi-client document manager
-    * (so concurrent editors share one built document) and returns the
-    * document at the server's configured target phase — the same shape
-    * {@link getModelDocument} returns, except that `version` is taken from
-    * the text-document store so the caller's first `baseVersion` write
-    * cannot self-conflict. Idempotent in registration terms: opening an
-    * already-open document refreshes the client registration. Note it does
-    * NOT avoid a rebuild — a second client attaching triggers
-    * `refreshContent`, which fires a change event, so mounting a form on a
-    * document already open in a text editor rebuilds it.
+    * Register `args.clientId` as a client session owned by this connection.
+    * Rejects with a `DuplicateClientIdError` code when the id is live anywhere
+    * in the server process, and with a `ReservedClientIdError` code when the
+    * framework reserves it.
+    *
+    * A request carrying a registered id acts as that session: it writes only
+    * what the session has open, failing with a `DocumentNotOpenError` code
+    * otherwise, and opens nothing implicitly; its open reads the file and takes
+    * no `languageId`, `version` or `text` seed. The session ends with
+    * {@link closeSession} or when the connection closes, and either closes
+    * every document it has open.
     *
-    * The default `DataServer` impl delegates to `ModelService.open` then
-    * reads the built state. Pair with {@link watchModelDocument} to receive
-    * subsequent build-phase events (open returns a one-shot snapshot;
-    * later validation diagnostics arrive on the watch channel).
+    * A registration carrying the `resumeToken` an earlier registration of the
+    * same id carried ends that session first, from any connection, so a client
+    * whose connection dropped can register again before the server notices.
+    */
+   createSession(args: CreateSessionArgs): Promise<void>;
+
+   /**
+    * End a session this connection registered: close every document it has
+    * open, drop its watches, and free its id. A no-op for an id this
+    * connection did not register.
     */
-   openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+   closeSession(args: CloseSessionArgs): Promise<void>;
 
    /**
-    * Close an editor session for `(uri, clientId)`. Counterpart to
-    * {@link openModelDocument}; the underlying document stays built until
-    * every registered client has closed. The default `DataServer` impl
-    * delegates to `ModelService.close` and ALSO releases any watch for the
-    * same `(uri, clientId)` (closing a session frees its own watch — a
-    * forgotten {@link unwatchModelDocument} would otherwise leak dispatch;
-    * the implicit unwatch is idempotent). `watchModelDocument` is NOT
-    * coupled the other way: opening does not force a watch, so a snapshot
-    * reader can open without streaming.
+    * Create a document with `args.text`, open for the session, and return it
+    * as {@link openModelDocument} does, with the version the create made in
+    * `created`. The answer is read after the create, so it can already hold
+    * another client's write or an integrity repair; a write based on
+    * `created.version` then conflicts. It reaches disk with the first save.
+    * Fails when the file exists or any client has the URI open, and with a
+    * `SessionClosedError` code when `args.clientId` is not a session
+    * registered on this connection.
+    */
+   createModelDocument(args: CreateModelDocumentArgs): Promise<TransferCreatedDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Write several documents the session has open, all or none: a conflict or
+    * a document not open fails the whole set before any text applies.
+    * Resolves to the documents in the order given. Only for a session
+    * registered on this connection.
+    */
+   updateModelDocuments(args: TransferUpdateDocumentsArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>[]>;
+
+   /**
+    * Open a document for the client session `clientId` and return its current
+    * state. `clientId` must be a session this connection registered with
+    * {@link createSession}; any other id fails with the closed-session code,
+    * as every document request here does. The document is read from disk
+    * unless a client has it open already, so the request carries no
+    * `languageId`, `version` or `text` seed. Returns the document at
+    * the server's configured target phase, as {@link getModelDocument} does.
+    * A repeat open changes nothing.
+    *
+    * Pair with {@link watchModelDocument} to receive subsequent build-phase
+    * events (open returns a one-shot snapshot; later validation diagnostics
+    * arrive on the watch channel).
+    */
+   openModelDocument(args: Pick<OpenModelArgs, 'uri' | 'clientId' | 'options'>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Close the session's open of `uri`. Counterpart to
+    * {@link openModelDocument}; the document stays open until every client
+    * has closed it, and then the server releases it, by default reverting it
+    * to disk. The default
+    * `DataServer` impl ALSO releases any watch for the same
+    * `(uri, clientId)` (a forgotten {@link unwatchModelDocument} would
+    * otherwise leak dispatch; the implicit unwatch is idempotent).
+    * `watchModelDocument` is NOT coupled the other way: opening does not force
+    * a watch, so a snapshot reader can open without streaming.
     */
    closeModelDocument(args: CloseModelArgs): Promise<void>;
 
@@ -81,34 +136,69 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
    getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
 
    /**
-    * Update a document's content. The response carries the latest built
-    * state including diagnostics; callers observe convergence via that
-    * response.
+    * Update a document's content as the session `clientId`, which must have
+    * it open. The response carries the latest built state including
+    * diagnostics; callers observe convergence via that response.
     */
    updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
 
    /**
-    * Persist a document to disk. The response is the post-save document
-    * state (matches the file on disk). Save semantics depend on the
-    * filesystem-provider wiring; rejection paths surface as awaited
+    * Write a document as the session `clientId`, which must have it open, and
+    * persist it to disk. The response is the build of the text written, with
+    * its version in `persisted`, sent once the language client has answered
+    * the push of that text, applied or refused, or a server-side bound on
+    * that wait passes; it does not wait again for a push that wait already
+    * gave up on and the client has not answered since. Save semantics depend
+    * on the filesystem-provider wiring; rejection paths surface as awaited
     * promise rejections.
     */
-   saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+   saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Persist the text the server holds for a document the session `clientId`
+    * has open, as it is: no update and no serialisation, so another client's
+    * unsaved text keeps its formatting. `baseVersion` is checked in the step
+    * that takes the text, so text that moved on fails with a `ConflictError`
+    * code. The saved event names this session, whoever wrote the text.
+    * Answers after the same language-client wait as {@link saveModelDocument},
+    * with the document's latest build, read after that wait, so another
+    * session's write during it shows; `persisted` carries the version written.
+    */
+   persistModelDocument(args: TransferPersistDocumentArgs): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Delete a document the session `clientId` has open, at once: its file,
+    * then the document, as a deletion a file watcher reports removes it. Every
+    * session's open of it closes and every client hears
+    * {@link DocumentClientProtocol.onDocumentDeleted} naming this session; the
+    * session's own watch is released, as {@link closeModelDocument} releases
+    * it. `baseVersion` is checked in the step that marks the document for
+    * deletion, so text that moved on fails with a `ConflictError` code. A file
+    * already gone deletes only the document; a file that cannot be removed
+    * fails the call and changes nothing. Resolves once the build that removes
+    * the document has run; a read then answers the URI without a model, unless
+    * an editor still has it open, whose buffer the document is built from.
+    */
+   deleteModelDocument(args: TransferDeleteDocumentArgs): Promise<void>;
 
    /**
     * Start watching `(uri, clientId)`. The server starts dispatching
     * {@link DocumentClientProtocol.onDocumentUpdated} on the paired wire
     * for every build-phase event on `uri`.
     *
-    * Returns `Promise<void>` — the bidirectional pattern means the event
-    * channel is the client interface, not a returned handle. Callers fan
-    * out a single inbound `onDocumentUpdated` to multiple local listeners
-    * with their own `Emitter<T>` (matching Theia's pattern). Pair every
-    * `watchModelDocument` with {@link unwatchModelDocument} when no longer
-    * needed; the server holds the watch record until the matching unwatch
-    * lands.
+    * Answers with the key the watch's events name the document by, whether
+    * a document exists, taken once the watch is in place and the document
+    * is loaded as a read loads it, the text held at that moment, and the
+    * position of the last update or deletion event sent as of it, so an event
+    * the client heard while the watch was in flight tells by its own position
+    * whether it is newer than the answer. No handle: the event channel is the
+    * client interface. Callers fan out a single inbound `onDocumentUpdated` to
+    * multiple local listeners with their own `Emitter<T>` (matching Theia's
+    * pattern). Pair every `watchModelDocument` with
+    * {@link unwatchModelDocument} when no longer needed; the server holds the
+    * watch record until the matching unwatch lands.
     */
-   watchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
+   watchModelDocument(args: WatchModelDocumentArgs): Promise<TransferWatchedDocument>;
 
    /**
     * Stop watching `(uri, clientId)` previously started by
@@ -194,6 +284,22 @@ export interface DataServerProtocol<
 >
    extends DocumentServerProtocol<TTransfer, TDiagnostic>, ProjectServerProtocol<TProject> {}
 
+/**
+ * The diagnostic shape a server answers with, read back off its own
+ * declaration.
+ *
+ * This is what lets a client tier stay generic over the server alone and still
+ * describe what it hands back. Both parameters must be inferred: naming
+ * {@link TransferElement} for the transfer instead fails to match while that
+ * parameter is still generic, and a default declared against the constraint
+ * then stops satisfying it.
+ */
+export type DiagnosticOf<TServer> =
+   TServer extends DocumentServerProtocol<infer _TTransfer, infer TDiagnostic> ? TDiagnostic : TransferDiagnostic;
+
+/** The project shape a server answers with, read back off its own declaration. */
+export type ProjectOf<TServer> = TServer extends ProjectServerProtocol<infer TProject> ? TProject : Project;
+
 /**
  * Cross-reference / naming slice of the server surface — scope-aware
  * queries that resolve against the language's reference services. NOT part
@@ -204,11 +310,11 @@ export interface DataServerProtocol<
  * source/URI (an `ElementSource` with no URI resolves to the sole
  * registered language; a multi-language workspace overrides).
  *
- * Generic over the transfer root type only — the resolution result
- * ({@link ReferenceTarget}) carries the resolved node's encoded subtree;
- * candidates and names are diagnostic-free.
+ * Not generic over a server's root type: {@link resolveReference} answers with
+ * a node a reference names, which is no document root, and candidates and
+ * names are diagnostic-free.
  */
-export interface ReferenceServerProtocol<TTransfer extends TransferElement> {
+export interface ReferenceServerProtocol {
    /**
     * List the reference candidates reachable for the property named in `ctx`
     * from its (possibly synthetic) source. Backed by the language's
@@ -221,8 +327,13 @@ export interface ReferenceServerProtocol<TTransfer extends TransferElement> {
     * target's document URI, display fields, and the resolved node's encoded
     * transfer subtree. Resolves via the language's reference services;
     * `undefined` when the reference does not resolve.
+    *
+    * `TElement` is the caller's claim about the target node's type; nothing
+    * checks it, so leave it at the default unless the reference names one type.
     */
-   resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined>;
+   resolveReference<TElement extends TransferElement = TransferElement>(
+      ref: ReferenceRequest
+   ): Promise<ReferenceTarget<TElement> | undefined>;
 
    /**
     * Compute the next free name for a new element of `args.type` based on
@@ -262,6 +373,39 @@ export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiag
     * codepath, not a subscription codepath).
     */
    onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+
+   /**
+    * Delivered when a subscribed document's text starts or stops differing
+    * from its file, as the server last knew it. Gated like
+    * {@link onDocumentSaved}; the answer at any one moment is the `dirty` of
+    * the documents the server sends. After a reconnect, a `DataSession`
+    * delivers here the answer of each document it restored, when that differs
+    * from the last this client was told: the flips while the connection was
+    * down reached no one.
+    */
+   onDocumentDirtyChanged(event: TransferDocumentDirtyChangedEvent): void;
+
+   /**
+    * Delivered when a document's backing file was removed. Separate from
+    * {@link onDocumentUpdated} for the same reason as {@link onDocumentSaved},
+    * and more strongly: there is no built state to deliver, and the build-phase
+    * path cannot report a deletion at all.
+    *
+    * Ungated, because on a browser host — where the workspace lives behind the
+    * head — no other source can observe a file disappearing. Recipients that
+    * only care about their own documents filter by URI.
+    */
+   onDocumentDeleted(event: TransferDocumentDeletedEvent): void;
+
+   /**
+    * Delivered once per build, naming the documents that reached the
+    * subscription phase and that
+    * nobody on this connection watches — chiefly the ones rebuilt as a cascade
+    * from a dependency's change, which no filesystem watcher can see because
+    * their own files did not change. The complement of
+    * {@link onDocumentUpdated}; carries URIs and no documents.
+    */
+   onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void;
 }
 
 /**

package/src/data/events.ts

@@ -10,30 +10,36 @@
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
 import type { Project } from '../project';
-import type { TransferDocument } from '../transfer-document';
+import type { TextState, TransferDocument } from '../transfer-document';
 
 /**
  * Why an update event fired. Subscribers filter on reason for behaviour
  * decisions (e.g. dirty-flag handling, undo-history grouping, telemetry):
  *
- * - `'changed'` — the URI appeared in `DocumentBuilder.onUpdate`'s
- *   `changed` list. The framework's underlying primitive is "this URI was
- *   passed to `documentBuilder.update(changed, deleted)`", which spans
- *   `didChange` text-document events, `notifyDidChangeTextDocument` calls,
- *   and any programmatic `documentBuilder.update([uri], [])` invocation.
- *   The name matches Langium's own `changed` parameter — it's vague-on-
- *   purpose because the underlying primitive is.
- * - `'rebuilt'` — the URI was rebuilt as a cascade from another URI's
- *   build (dependency graph re-derivation), without itself being passed to
- *   `documentBuilder.update`. The complement of `'changed'`.
+ * - `'changed'` — the server's first update event for the document's current
+ *   version: its content changed since the last one. A write whose build a
+ *   later write cancelled is still `'changed'` in the build that takes over.
+ * - `'rebuilt'` — a later event for a version the server already delivered,
+ *   whether or not any client watched it then: something the document depends
+ *   on changed, or the document was built again with the same content. The
+ *   complement of `'changed'`.
  * - `'saved'` — emitted by adopters that synthesise a unified update stream
  *   from both `onDocumentUpdated` and `onDocumentSaved`. The framework's own
  *   `dispatchPhaseEvent` does NOT emit `'saved'` — saves take the dedicated
  *   `DataClientProtocol.onDocumentSaved` channel.
- * - `'deleted'` — the URI appeared in `DocumentBuilder.onUpdate`'s
- *   `deleted` list. The backing file was removed.
+ *
+ * The version rule needs a version the server keeps and builds that validate.
+ * For a document no client has opened, or when rebuilds do not validate,
+ * `'changed'` means the URI was passed to `DocumentBuilder.update` for this
+ * build. A document that a validating build skips is `'changed'` every time.
+ *
+ * Deletion is deliberately NOT a member. An update event carries a built
+ * document, which a deleted one has none of, and the phase-driven path that
+ * produces these events never runs for a deleted URI — the builder drops the
+ * document before deriving the rebuild set. It travels as
+ * {@link TransferDocumentDeletedEvent} on its own channel instead.
  */
-export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved' | 'deleted';
+export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved';
 
 /**
  * Delivered on the data-server when a document's content (or existence)
@@ -47,9 +53,21 @@ export interface TransferDocumentUpdatedEvent<
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
    document: TransferDocument<TTransfer, TDiagnostic>;
-   /** Stable identifier of the client that triggered the update. */
+   /**
+    * The client whose write this event echoes: the author of the version on a
+    * `'changed'`, and the unknown-client id on a `'rebuilt'`, which echoes no
+    * write. A recipient compares it against its own id to recognise its echo.
+    * The build that follows a document's release names the release id
+    * instead.
+    */
    sourceClientId: string;
    reason: TransferDocumentUpdateReason;
+   /**
+    * The position of this event among the update and deletion events the
+    * server sent on this connection, which a watch's answer carries as of
+    * the moment it was taken: a greater one was sent later.
+    */
+   sequence: number;
 }
 
 /** Callback shape for `DataClientProtocol.onDocumentUpdated`. */
@@ -60,8 +78,8 @@ export type TransferDocumentUpdatedListener<
 
 /**
  * Delivered on the data-server when a document was persisted to disk via
- * `DataServerProtocol.saveModelDocument`. Distinct from
- * {@link TransferDocumentUpdatedEvent}: subscribers that only care about
+ * `DataServerProtocol.saveModelDocument` or `persistModelDocument`. Distinct
+ * from {@link TransferDocumentUpdatedEvent}: subscribers that only care about
  * persistence (external sync, editor "saved" indicators, dirty-flag
  * clear) listen for this event family instead of filtering an update
  * stream for `reason: 'saved'`.
@@ -77,10 +95,11 @@ export interface TransferDocumentSavedEvent<
 > {
    document: TransferDocument<TTransfer, TDiagnostic>;
    /**
-    * The client whose `saveModelDocument` call produced this. Every subscriber
-    * receives the event including the originator, which already had the same
-    * state as the RPC response — compare against your own id to drop the echo
-    * rather than re-rendering from it.
+    * The client whose `saveModelDocument` or `persistModelDocument` call
+    * produced this, also when another client wrote the persisted text. Every
+    * subscriber receives the event including the originator, which already had
+    * the same state as the RPC response — compare against your own id to drop
+    * the echo rather than re-rendering from it.
     */
    sourceClientId: string;
 }
@@ -91,6 +110,109 @@ export type TransferDocumentSavedListener<
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > = (event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>) => void;
 
+/**
+ * Delivered on the data-server when a watched document's text starts or stops
+ * differing from its file, as the server last knew the file. The current
+ * answer rides on every transfer document the server sends as `text.dirty`;
+ * this carries only its changes, so a client that follows it needs no rebuild
+ * to learn of a save.
+ */
+export interface TransferDocumentDirtyChangedEvent {
+   /** Canonical URI, keyed as the subscription is. */
+   readonly uri: string;
+   /**
+    * The text the answer was decided on. It is sent before that text is
+    * built, so a `text.version` ahead of the model a client holds means an
+    * update at this version or a later one follows. Absent when the document
+    * no longer exists, or when the build that follows its release failed.
+    */
+   readonly text?: TextState;
+}
+
+/** Callback shape for `DataClientProtocol.onDocumentDirtyChanged`. */
+export type TransferDocumentDirtyChangedListener = (event: TransferDocumentDirtyChangedEvent) => void;
+
+/**
+ * Delivered on the data-server when a document's backing file was removed.
+ * Carries no document, and cannot: the state a
+ * {@link TransferDocumentUpdatedEvent} would have to carry no longer exists by
+ * the time anyone can be told. That is also why deletion is not a `reason` on
+ * the update stream — `DocumentBuilder.update` drops the document before
+ * deriving the rebuild set, so the phase-driven path that produces update
+ * events never runs for it.
+ *
+ * **Delivered for EVERY document, not only watched ones**, unlike
+ * `onDocumentUpdated` and `onDocumentSaved`. The test that decides which
+ * channels are gated is whether any OTHER source can observe the fact on the
+ * least capable host: a browser-hosted client's workspace lives behind the
+ * head, so nothing there can see a file disappear, and gating the notification
+ * would leave it blind. (A Theia frontend's filesystem watcher would cover it,
+ * which is why this is a host argument and not a structure-versus-content one.)
+ * A watcher is told about its own document's deletion here too, the update
+ * channel being silent for deletions by construction. Filter on {@link uri} if
+ * the receiver only cares about documents it opened.
+ *
+ * A watch survives the deletion, so a file that comes back resumes delivering
+ * `onDocumentUpdated` to the same subscribers with no re-subscription. A
+ * client that responds by closing its editor releases the watch through
+ * `closeModelDocument` as usual, and `deleteModelDocument` releases the
+ * deleting session's own.
+ */
+export interface TransferDocumentDeletedEvent {
+   /** Canonical URI of the removed document, keyed as the subscription is. */
+   readonly uri: string;
+   /**
+    * The session whose `deleteModelDocument` removed the file, so it can tell
+    * its own deletion from another's; the unknown-client id for a file
+    * removed outside any session, as a file watcher reports one, and for one
+    * a `DataConnection` found gone after a reconnect, which no event named.
+    */
+   readonly sourceClientId: string;
+   /**
+    * The position of this event among the update and deletion events the
+    * server sent on this connection, as on an update; absent on a deletion a
+    * `DataConnection` found after a reconnect, which the server never sent.
+    */
+   readonly sequence?: number;
+}
+
+/** Callback shape for `DataClientProtocol.onDocumentDeleted`. */
+export type TransferDocumentDeletedListener = (event: TransferDocumentDeletedEvent) => void;
+
+/**
+ * Delivered on the data-server once per build, naming the documents that reached
+ * the configured subscription phase (`DataServerOptions.subscriptionPhase`,
+ * `Validated` by default) and that NO client on the connection is watching. Not
+ * the integrity-settled landmark, which is a different point and a different
+ * word in this framework.
+ *
+ * The complement of {@link TransferDocumentUpdatedEvent}, which is gated per
+ * URI: together the two cover every document a build touched. This one exists
+ * for the case no source outside the server can observe — a document rebuilt
+ * because something it DEPENDS ON changed. Its own file never changed, so a
+ * filesystem watcher cannot see it, and it has no subscriber, so the update
+ * channel does not report it. A consumer showing data derived from such a
+ * document (a tree label, a decorator) would otherwise hold a stale value with
+ * nothing to invalidate it.
+ *
+ * Carries URIs and no documents: a recipient re-reads what it displays, through
+ * `getModelDocument` or its own request. That keeps the bandwidth property the
+ * per-URI subscription exists for, without gating the message.
+ *
+ * Not sent when the set is empty, which is the normal case while editing — the
+ * document being edited is watched by its own editor and therefore excluded.
+ * Workspace initialisation sends nothing either: it does not build to the
+ * subscription phase. The largest message a workspace can produce is therefore
+ * a whole-workspace rebuild at that phase, which is one message of URIs.
+ */
+export interface TransferDocumentsBuiltEvent {
+   /** Canonical URIs, keyed as subscriptions are. Never empty. */
+   readonly uris: readonly string[];
+}
+
+/** Callback shape for `DataClientProtocol.onDocumentsBuilt`. */
+export type TransferDocumentsBuiltListener = (event: TransferDocumentsBuiltEvent) => void;
+
 /**
  * Why a project-change event fired. `added` — the project was newly
  * registered (descriptor discovered); `updated` — the project's

package/src/data/requests.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { TransferSaveArgs, TransferUpdateArgs } from '../model-service/args';
+import type { BaseVersion } from '../model-service/base-version';
 
 /** Get the current state of a single document. The server returns the latest built version. */
 export interface GetModelDocumentArgs {
@@ -41,24 +41,90 @@ export interface GetProjectForUriArgs {
 }
 
 /**
- * Update a document's content. Wire-side projection of the facade's
- * {@link TransferUpdateArgs}; structurally identical so the data-server RPC
- * handler can forward straight to the in-process `ModelService.update`
- * without an args mapping.
+ * Update a document the session `clientId` has open. Generic over `TTransfer`
+ * so adopters parameterise the structured shape against their grammar's
+ * transfer-model overlay; passing a string is always allowed.
  */
-export type TransferUpdateDocumentArgs<TTransfer> = TransferUpdateArgs<TTransfer>;
+export interface TransferUpdateDocumentArgs<TTransfer> {
+   /** Document URI. */
+   uri: string;
+   /** The id of a live session registered on this connection. */
+   clientId: string;
+   /** The whole structured model root, or its serialised textual form. */
+   model: TTransfer | string;
+   /**
+    * What this write was authored against. A `ModelVersion` is compared
+    * against the server's current text-document version for `uri` and throws
+    * `ConflictError` on mismatch; `'any'` writes unconditionally.
+    *
+    * **Required so that an ungated write is a decision rather than an
+    * omission.** An optional gate is indistinguishable from a forgotten one at
+    * the call site, and a file of twenty writes hides the one that lost the
+    * field. Nothing else here can see that, since the defect is an absence.
+    */
+   baseVersion: BaseVersion;
+}
+
+/** Update a document the session `clientId` has open, then persist it to disk. */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- save names its own args; it adds no field to update's
+export interface TransferSaveDocumentArgs<TTransfer> extends TransferUpdateDocumentArgs<TTransfer> {}
+
+/** Persist the text the server holds for a document the session `clientId` has open, without writing a model. */
+export type TransferPersistDocumentArgs = Omit<TransferUpdateDocumentArgs<never>, 'model'>;
+
+/** Delete a document the session `clientId` has open: its file, then the document. */
+export type TransferDeleteDocumentArgs = Omit<TransferUpdateDocumentArgs<never>, 'model'>;
+
+/** Register a client session on the connection. */
+export interface CreateSessionArgs {
+   /** The session's id, minted by the client; unique in the server process while the session is live. */
+   clientId: string;
+   /** What the participant is; kept as the server session's `label`. */
+   label?: string;
+   /**
+    * A token the client keeps for the session's lifetime. It is no secret: the
+    * wire carries no authentication. A later `createSession` for the same id
+    * carrying the same token, from any connection, ends the session it names
+    * and registers the id afresh, so a client whose connection dropped before
+    * the server noticed can register again. Without it the id stays refused
+    * until the server notices.
+    */
+   resumeToken?: string;
+}
 
-/** Persist a document to disk. Wire-side projection of {@link TransferSaveArgs}. */
-export type TransferSaveDocumentArgs<TTransfer> = TransferSaveArgs<TTransfer>;
+/** End a client session registered on the connection. */
+export interface CloseSessionArgs {
+   clientId: string;
+}
+
+/** Create a document that exists nowhere yet, open for the session creating it. */
+export interface CreateModelDocumentArgs {
+   uri: string;
+   /** The id of a live session registered on this connection. */
+   clientId: string;
+   /** The document's initial content; it reaches disk with the first save. */
+   text: string;
+}
+
+/**
+ * Write several documents a session has open, all or none. `clientId` is on
+ * the set rather than on each update: an id per update would allow a set
+ * mixing clients, which the server would have to refuse.
+ */
+export interface TransferUpdateDocumentsArgs<TTransfer> {
+   /** The id of a live session registered on this connection. */
+   clientId: string;
+   updates: Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>[];
+}
 
 /**
  * Identifies a per-document watch on the data server. Shared by both
  * `watchModelDocument` and `unwatchModelDocument` — the `(uri, clientId)`
  * pair is the watch key, so unwatching names the same watch that was
  * started. The `clientId` identifies the originator the same way it does
- * on facade-side mutations (`TransferUpdateArgs.clientId`,
- * `TransferSaveArgs.clientId`): it keys the per-`(uri, clientId)` watch
- * bucket so multiple watchers on the same wire stay distinct, AND it lets
+ * on the document writes (`TransferUpdateDocumentArgs.clientId`,
+ * `TransferSaveDocumentArgs.clientId`): it keys the per-`(uri, clientId)`
+ * watch bucket so multiple watchers on the same wire stay distinct, AND it lets
  * each watcher recognise its own echo on inbound `onDocumentUpdated` events
  * (the wire shape's `sourceClientId` carries the originating mutation's
  * `clientId`).