@hydranium/data-server 1.0.0-next.12 → 1.0.0-next.123

package/src/data-server.ts

@@ -9,12 +9,16 @@
 
 import {
    createRpcProxy,
+   defineMessage,
    DisposableCollection,
    isDocumentSource,
    isElementSource,
    isSyntheticSource,
+   messageError,
    ReferenceSource,
+   SessionClosedError,
    type CloseModelArgs,
+   type HydraniumResponseError,
    type Disposable,
    type ElementSource,
    type FindNextNameArgs,
@@ -28,8 +32,9 @@ import {
    type ReferenceTarget,
    type Tracer,
    type TransferDiagnostic,
-   type TransferDocument,
-   type TransferElement
+   TransferDocument,
+   type TransferElement,
+   asSnapshotVersion
 } from '@hydranium/protocol';
 import {
    DATA_SERVER_DIAGNOSTICS_METHODS,
@@ -42,24 +47,73 @@ import {
    type StartProfilingArgs,
    type StopProfilingArgs,
    type WriteServerHeapSnapshotArgs,
+   type CloseSessionArgs,
+   type CreateModelDocumentArgs,
+   type CreateSessionArgs,
    type GetModelDocumentArgs,
    type GetProjectForUriArgs,
    type TransferSaveDocumentArgs,
    type WatchModelDocumentArgs,
    type TransferDocumentSavedEvent,
    type TransferDocumentUpdatedEvent,
-   type TransferUpdateDocumentArgs
+   type TransferUpdateDocumentArgs,
+   type TransferUpdateDocumentsArgs
 } from '@hydranium/protocol/data';
 import { REVERT_ON_CLOSE_CLIENT_ID, UNKNOWN_CLIENT_ID } from '@hydranium/core';
 import { defaultDataServerDiagnostics } from './default-diagnostics.js';
+
+/**
+ * Raised when a profiling command arrives with no capture running.
+ *
+ * A `ResponseError` rather than a plain `Error` so the identity survives to the
+ * response boundary, which is where the message is rendered. An unwrapped throw
+ * reaches the client as a generic internal error instead: no code for a caller
+ * to switch on, and nothing for the boundary to render from.
+ */
+export const NO_ACTIVE_PROFILE = defineMessage(
+   'hydranium/data-server/no-active-profile',
+   'No profiling capture is active; call startProfiling first.'
+);
+
+/**
+ * The JSON-RPC code, unrelated to the catalogue code above: this one is numeric,
+ * survives reconstruction and is what a caller switches on.
+ */
+export const NO_ACTIVE_PROFILE_CODE = 1002;
+
+export const noActiveProfileError = (): HydraniumResponseError => messageError(NO_ACTIVE_PROFILE_CODE, NO_ACTIVE_PROFILE);
+
+/**
+ * Raised when a reference question's wait for the build exceeds
+ * {@link DataServerOptions.referenceSettleTimeoutMs}.
+ *
+ * A `ResponseError` because a class name does not cross RPC: without the code a
+ * wire client cannot tell a wedged build from a reference that resolves to
+ * nothing, which is the distinction the wait exists to keep.
+ */
+export const REFERENCE_SETTLE_TIMEOUT = defineMessage(
+   'hydranium/data-server/reference-settle-timeout',
+   'Timed out after {elapsedMs}ms waiting for the build to settle before answering a reference query.'
+);
+
+/** See {@link NO_ACTIVE_PROFILE_CODE} for why this is separate from the catalogue code. */
+export const REFERENCE_SETTLE_TIMEOUT_CODE = 1003;
+
+export const referenceSettleTimeoutError = (elapsedMs: number): HydraniumResponseError =>
+   messageError(REFERENCE_SETTLE_TIMEOUT_CODE, REFERENCE_SETTLE_TIMEOUT, { elapsedMs });
+
 import type { DataServerDiagnosticsProvider, DataServerProfileCapture } from './diagnostics-provider.js';
 import type {
+   ClientSession,
+   ClientSessionWriteArgs,
    ClientTextDocumentChangeEvent,
    HydraniumLanguageServices,
    LogNameOptions,
+   AstDiagnostic,
    ModelService,
    ProjectChangeEvent,
    ServerSharedServices,
+   SessionEndCause,
    TransferEncoder
 } from '@hydranium/core';
 import type { TextDocument } from 'vscode-languageserver-textdocument';
@@ -104,6 +158,18 @@ function fingerprintHash(parts: readonly string[]): string {
    return high + low;
 }
 
+/**
+ * A session a data connection registered with a resume token, and how to end
+ * it from another connection. See {@link DataServer.resumableSessions}.
+ */
+export interface ResumableSession {
+   readonly token: string;
+   /** End the session as its connection closing would. */
+   readonly end: () => void;
+}
+
+const resumableByModelService = new WeakMap<object, Map<string, ResumableSession>>();
+
 /**
  * Which observable state {@link DataServer.computeDocumentFingerprint} hashes to
  * de-dup `onDocumentUpdated` emissions.
@@ -201,6 +267,22 @@ export interface DataServerOptions extends LogNameOptions {
     */
    readonly fingerprintStrategy?: FingerprintStrategy;
 
+   /**
+    * How long a reference question waits for the build to reach `Linked` before
+    * failing with {@link REFERENCE_SETTLE_TIMEOUT_CODE}. Bounded because the
+    * wait resolves off a build-phase notification, so a build cancelled below
+    * `Linked` with nothing after it leaves the request unanswered for the life
+    * of the server.
+    *
+    * Expiry rejects rather than reading the index anyway: the unsettled index
+    * is what the wait keeps the caller away from, so falling through to it on a
+    * slow build reinstates the fault — and on a name proposal persists it.
+    *
+    * Default {@link DataServer.DEFAULT_OPTIONS}, sized for a cold workspace
+    * still reaching `Linked` for the first time.
+    */
+   readonly referenceSettleTimeoutMs?: number;
+
    /**
     * Wire-method namespace for both inbound request handlers and the
     * outbound notification client proxy. Defaults to
@@ -258,15 +340,20 @@ export interface DataServerOptions extends LogNameOptions {
     * When supplied, every inbound data-server RPC is timed into this collector
     * (via the `createRpcProxy` binding) and exposed through
     * {@link DataServerDiagnosticsProtocol.getLatency}. A head that also runs an
-    * LSP connection can pass the SAME collector to
-    * `instrumentLspConnection(connection, latency)` so one report covers both
-    * heads. Absent by default (no timing overhead).
+    * LSP connection can pass the SAME collector through `lspLatencyOptions` to
+    * that connection, so one report covers both heads. Absent by default (no
+    * timing overhead).
     */
    readonly latency?: LatencyCollector;
 }
 
-/** Fully-resolved variant — every field set, used internally after merging defaults. */
-interface ResolvedDataServerOptions {
+/**
+ * Fully-resolved variant of {@link DataServerOptions} — every field set, after
+ * merging defaults. Returned by the `protected`
+ * {@link DataServer.resolveOptions} and held on {@link DataServer.options}, so
+ * an adopter changing how defaults resolve has to name it.
+ */
+export interface ResolvedDataServerOptions {
    readonly subscriptionPhase: DocumentState;
    readonly fingerprintStrategy: FingerprintStrategy;
    readonly methodNamespace: string;
@@ -274,6 +361,7 @@ interface ResolvedDataServerOptions {
    readonly excludedMethods: readonly string[];
    /** Always resolved — to the caller's, or to the platform default. */
    readonly diagnostics: DataServerDiagnosticsProvider;
+   readonly referenceSettleTimeoutMs: number;
 }
 
 /**
@@ -301,9 +389,11 @@ interface ResolvedDataServerOptions {
  * any names supplied via {@link DataServerOptions.additionalMethods}) and
  * builds the {@link DataClientProtocol} notification proxy on the same
  * connection in one {@link createRpcProxy} call (binding `this` as its
- * `localTarget`) under the configured namespace, and subscribes one
- * `DocumentBuilder.onDocumentPhase` listener per configured phase that
- * dispatches subscription events via `clientProxy.onDocumentUpdated`.
+ * `localTarget`) under the configured namespace, and subscribes two listeners
+ * at the configured phase: a `DocumentBuilder.onDocumentPhase` one dispatching
+ * per-document `clientProxy.onDocumentUpdated` for watched URIs, and a
+ * `DocumentBuilder.onBuildPhase` one dispatching a single
+ * `clientProxy.onDocumentsBuilt` naming the batch's unwatched documents.
  *
  * The data-server requires the full {@link ServerSharedServices}
  * shape — `HydraniumTextDocuments` for client-attributed updates,
@@ -331,35 +421,36 @@ export class DataServer<
     * Framework defaults, exposed so an adopter can spread them when
     * extending rather than restate a value the framework may change.
     */
-   static readonly DEFAULT_OPTIONS: Required<Pick<DataServerOptions, 'subscriptionPhase'>> = {
-      subscriptionPhase: DocumentState.Validated
+   static readonly DEFAULT_OPTIONS: Required<Pick<DataServerOptions, 'subscriptionPhase' | 'referenceSettleTimeoutMs'>> = {
+      subscriptionPhase: DocumentState.Validated,
+      referenceSettleTimeoutMs: 60_000
    };
 
    protected readonly options: ResolvedDataServerOptions;
    /** Subscription bookkeeping: URI → set of clientIds that subscribed for that URI. */
    protected readonly subscriptions = new Map<string, Set<string>>();
    /**
-    * Open-document bookkeeping: URI → set of clientIds that opened it over THIS
-    * connection.
+    * The client sessions this connection registered, by client id. A document
+    * request carrying one of these ids acts as that session; one carrying any
+    * other id fails.
     *
-    * Kept because the document store releases a client's hold only from an
-    * explicit close, and a client that dies without closing would otherwise keep
-    * the document open forever — resident, and with its last-close revert
-    * suppressed. The store has no notion of which connection a clientId reached
-    * it over, so the connection-scoped set has to live here; teaching it a client
-    * identity is the more robust and much larger alternative.
+    * Entries stay after {@link dispose} has ended their sessions, so a request
+    * still running from before the connection closed reaches the ended handle
+    * and fails with the session's own error.
     */
-   protected readonly openedDocuments = new Map<string, Set<string>>();
+   protected readonly clientSessions = new Map<string, ClientSession<AstNode, AstDiagnostic, TTransfer>>();
    /** Typed client proxy — sends `data-server/on*` notifications back over the same wire. */
    protected readonly clientProxy: DataClientProtocol<TTransfer, TDiagnostic, TProject>;
    protected readonly disposables = new DisposableCollection();
    /**
     * Snapshot of the most recent `DocumentBuilder.onUpdate` event. Drives
     * `reason` discrimination on outbound `onDocumentUpdated` notifications:
-    * a URI in the `changed` list emits `'changed'`, in `deleted` emits
-    * `'deleted'`, otherwise `'rebuilt'` (cascade rebuild from a dependent
-    * URI's change). The same mechanism `AstDocumentManager.onUpdate` uses on
-    * the LSP side, so reason fidelity stays consistent between heads.
+    * a URI in the `changed` list emits `'changed'`, otherwise `'rebuilt'`
+    * (cascade rebuild from a dependent URI's change). The same mechanism
+    * `AstDocumentManager.onUpdate` uses on the LSP side, so reason fidelity
+    * stays consistent between heads. The `deleted` half is read by
+    * {@link dispatchDeleteEvents} rather than by the reason discrimination,
+    * a deletion travelling on its own channel.
     */
    protected lastBuildUpdate?: { changed: readonly URI[]; deleted: readonly URI[] };
    /**
@@ -399,12 +490,12 @@ export class DataServer<
     */
    protected readonly lastEmittedFingerprint = new Map<string, string>();
    /**
-    * URIs whose LAST client just closed. The update handler rebuilds such a
-    * document from its disk content (discarding unsaved in-session edits),
-    * but {@link dispatchPhaseEvent} gates on the subscription map — and the
-    * last close typically also removed the last watcher, so consumers that
-    * only ever fetch via `getModelDocument` would keep showing the
-    * discarded state forever. Marked on the last-close transition (see
+    * URIs the text store just released after their last close. The store
+    * rebuilds such a document from its disk content (discarding unsaved
+    * in-session edits), but {@link dispatchPhaseEvent} gates on the
+    * subscription map — and the last close typically also removed the last
+    * watcher, so consumers that only ever fetch via `getModelDocument` would
+    * keep showing the discarded state forever. Marked on the release (see
     * {@link subscribeToTextDocumentCloses}) and consumed by
     * {@link dispatchPhaseEvent}, which broadcasts the following rebuild's
     * phase event even without a subscription — de-duplicated against
@@ -420,7 +511,7 @@ export class DataServer<
    /** Per-method RPC latency collector, when the head opted in via {@link DataServerOptions.latency}. */
    protected readonly latency?: LatencyCollector;
    /** Encoder pulled from DI. Adopters rebind `services.model.TransferEncoder` to a typed-overlay subclass. */
-   protected readonly encoder: TransferEncoder<unknown, TDiagnostic>;
+   protected readonly encoder: TransferEncoder<TDiagnostic>;
    /**
     * In-process workspace facade — the lifecycle delegate `get` / `update` / `save` go through.
     * The facade's AstDocument diagnostic shape is intentionally typed `unknown` here: adopters
@@ -429,7 +520,7 @@ export class DataServer<
     * `astDocumentToTransferDocument` accepts both shapes (wire-shape or LSP-shape) and projects
     * to wire shape on the return — see `TransferEncoder.astDocumentToTransferDocument`.
     */
-   protected readonly modelService: ModelService<AstNode, unknown, TTransfer>;
+   protected readonly modelService: ModelService<AstNode, AstDiagnostic, TTransfer>;
 
    constructor(
       protected readonly connection: MessageConnection,
@@ -448,8 +539,8 @@ export class DataServer<
                'Did you compose `createServerSharedModule(ctx)` into your shared module?'
          );
       }
-      this.encoder = encoder as TransferEncoder<unknown, TDiagnostic>;
-      this.modelService = modelService as ModelService<AstNode, unknown, TTransfer>;
+      this.encoder = encoder as TransferEncoder<TDiagnostic>;
+      this.modelService = modelService as ModelService<AstNode, AstDiagnostic, TTransfer>;
       const excluded = new Set<string>(this.options.excludedMethods);
       const registeredMethods = [
          ...DATA_SERVER_PROTOCOL_METHODS,
@@ -465,11 +556,16 @@ export class DataServer<
          methodNamespace: this.options.methodNamespace,
          localTarget: this,
          localMethods: registeredMethods as readonly (keyof this & string)[],
-         latency: this.latency
+         latency: this.latency,
+         // Bound at the chokepoint rather than per handler, so an adopter's
+         // `additionalMethods` are rendered on the same terms as the
+         // framework's own rejections.
+         renderErrorMessage: error => this.services.MessageRenderer.renderError(error)
       });
       this.disposables.push(
          this.services.workspace.DocumentBuilder.onUpdate((changed, deleted) => {
             this.lastBuildUpdate = { changed, deleted };
+            this.dispatchDeleteEvents(deleted);
          })
       );
       this.subscribeToDocumentBuilder();
@@ -478,8 +574,10 @@ export class DataServer<
       this.subscribeToProjectManager();
       // Self-register teardown so an adopter that keeps no reference to the
       // server still releases per-connection state, with no lifecycle hook of
-      // its own. See `dispose`.
-      this.disposables.push(connection.onClose(() => this.dispose()));
+      // its own. The client did not close anything itself, so its sessions end
+      // as lost and each document it was the last to have open waits out the
+      // store's revert grace. See `dispose`.
+      this.disposables.push(connection.onClose(() => this.dispose('lost')));
    }
 
    /**
@@ -487,16 +585,19 @@ export class DataServer<
     * handlers and every listener — and clear the subscription map and the
     * per-URI emission-fingerprint cache, so a long-lived shared services
     * bundle does not retain per-connection memory after the connection
-    * closes. Also closes every document still open over this connection (see
-    * {@link closeOpenDocuments}), which is the SHARED store's state rather than
-    * this server's and so outlives the connection unless released here.
+    * closes. Also ends every session this connection registered, which closes
+    * every document it has open: the SHARED store's state rather than this
+    * server's, which outlives the connection unless released here.
     *
-    * Idempotent: subsequent calls are no-ops. Self-fires on
-    * `connection.onClose` so adopters who don't hold a reference still
-    * get per-connection cleanup; adopters that DO hold a reference may
-    * call `dispose()` directly for early teardown.
+    * Idempotent: subsequent calls are no-ops. Runs by itself when the
+    * connection closes, so adopters who don't hold a reference still get
+    * per-connection cleanup; adopters that DO hold a reference may call
+    * `dispose()` directly for early teardown. The sessions end with `cause`:
+    * `'closed'` reverts every document whose last open they close at once,
+    * and `'lost'`, the connection's own close, lets each wait out the revert
+    * grace.
     */
-   dispose(): void {
+   dispose(cause: SessionEndCause = 'closed'): void {
       this.disposed = true;
       // Release an in-flight interactive capture so the process-wide inspector
       // singleton is not left active after the connection closes.
@@ -505,102 +606,184 @@ export class DataServer<
          this.activeProfile = undefined;
          void capture.stop({}).catch(() => undefined);
       }
-      // AFTER `disposables.dispose()`, deliberately: closing a document fires
-      // `onDidClose`, and this server's own close listener would otherwise mark a
-      // revert broadcast for a connection that is already gone.
+      // AFTER `disposables.dispose()`, deliberately: ending a session releases
+      // each document it was the last to hold, and this server's own
+      // `onDidCloseLastOpen` listener would otherwise mark a revert broadcast
+      // for a connection that is already gone.
       this.disposables.dispose();
-      this.closeOpenDocuments();
+      for (const [clientId, session] of this.clientSessions) {
+         this.endSession(clientId, session, cause);
+      }
       this.subscriptions.clear();
       this.lastEmittedFingerprint.clear();
       this.pendingRevertBroadcasts.clear();
    }
 
    // ============================================================
-   // DataServerProtocol implementation — delegates to ModelService.
+   // DataServerProtocol implementation
    // ============================================================
    //
-   // The lifecycle methods (`get` / `update` / `save` / `ready`) forward
-   // straight to `ModelService` and encode the returned `AstDocument` on
-   // the wire boundary via `encoder.astDocumentToTransferDocument`.
-   // Adopters customising lifecycle behaviour (normalisation, supersession,
-   // settled-phase choice, etc.) override on the ModelService subclass —
-   // no override on DataServer is needed.
-
-   async openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>> {
-      // Register the editor session (idempotent — `ModelService.open` refreshes
-      // an already-open document rather than re-opening), then return the built
-      // state at the configured target phase. The one-shot snapshot; subsequent
-      // build-phase events arrive via `watchModelDocument`.
-      await this.modelService.open(args);
-      // Record the hold so `dispose` can release it for a client that never
-      // closes. Keyed by the URI as given, because that is what `close` takes.
-      let holders = this.openedDocuments.get(args.uri);
-      if (!holders) {
-         holders = new Set<string>();
-         this.openedDocuments.set(args.uri, holders);
+   // Reads go to `ModelService`; a request that opens or writes a document
+   // goes to the session this connection registered under its `clientId`.
+   // Each answer is encoded on the wire boundary via
+   // `encoder.astDocumentToTransferDocument`. To change how documents are
+   // read, override on the ModelService subclass; to change how they are
+   // written, on the session class the bound `ClientSessionFactory` builds.
+
+   async createSession(args: CreateSessionArgs): Promise<void> {
+      // After teardown nothing would ever end a session registered now, and its
+      // id would stay taken for the life of the process.
+      if (this.disposed) {
+         throw new SessionClosedError(args.clientId);
+      }
+      const resumable = this.resumableSessions();
+      const previous = resumable.get(args.clientId);
+      if (previous && args.resumeToken !== undefined && previous.token === args.resumeToken) {
+         previous.end();
+      }
+      const session = this.modelService.createSession(args.label, args.clientId);
+      this.clientSessions.set(args.clientId, session);
+      if (args.resumeToken !== undefined) {
+         // Taken over by a client registering again after its connection
+         // dropped, so the old session ends as lost: the documents it was the
+         // last to have open wait out the grace, and the new session's opens
+         // find their unsaved text.
+         resumable.set(args.clientId, { token: args.resumeToken, end: () => this.endSession(args.clientId, session, 'lost') });
       }
-      holders.add(args.clientId);
-      const document = await this.getModelDocument({ uri: args.uri });
-      // Project the authoritative client-facing version onto the open snapshot.
-      // `getModelDocument` encodes the freshly-built AST snapshot, whose version
-      // is the `LangiumDocument`'s own `textDocument.version`. That lags the
-      // multi-client synced version whenever the open seeded the synced document
-      // with a caller-supplied version id — and the synced version is what
-      // `ModelService.update`'s optimistic-concurrency gate compares
-      // `baseVersion` against, so reporting the snapshot's would make the
-      // caller's first tagged write self-conflict. A genuine concurrent edit
-      // still trips the gate and is reconciled by the caller's replay rather
-      // than predicted here.
-      return { ...document, version: this.services.workspace.TextDocuments.version(args.uri) };
    }
 
-   async closeModelDocument(args: CloseModelArgs): Promise<void> {
-      // Closing a session also releases its watch for (uri, clientId) — a
-      // forgotten unwatch would otherwise leak phase-event dispatch until the
-      // connection closes. Idempotent: a close without a prior watch is a no-op.
-      await this.unwatchModelDocument({ uri: args.uri, clientId: args.clientId });
-      this.forgetOpenDocument(args.uri, args.clientId);
-      await this.modelService.close(args);
+   /**
+    * End a session this connection registered. The ended handle stays in
+    * {@link clientSessions}, as it does after {@link dispose}, so a request for
+    * the id still arriving fails with the ended session's own error.
+    */
+   async closeSession(args: CloseSessionArgs): Promise<void> {
+      const session = this.clientSessions.get(args.clientId);
+      if (session) {
+         this.endSession(args.clientId, session);
+      }
+   }
+
+   /** End `session`, registered here under `clientId`, with `cause`, and drop its watches on this connection. */
+   protected endSession(
+      clientId: string,
+      session: ClientSession<AstNode, AstDiagnostic, TTransfer>,
+      cause: SessionEndCause = 'closed'
+   ): void {
+      for (const [uri, watchers] of this.subscriptions) {
+         if (watchers.delete(clientId) && watchers.size === 0) {
+            this.subscriptions.delete(uri);
+            this.lastEmittedFingerprint.delete(uri);
+         }
+      }
+      session.dispose(cause);
    }
 
    /**
-    * Drop the recorded hold for `(uri, clientId)` so {@link dispose} does not
-    * close it a second time. Idempotent.
+    * The resumable sessions of this services tree, by client id, across all of
+    * its data connections: a client resumes on another connection than the one
+    * that registered it. An entry leaves when its session ends, by any path, so
+    * it keeps no ended connection alive.
+    *
+    * A takeover by resume token ends the old session even when its connection
+    * is still alive, so two clients that shared an id and its token would end
+    * each other's sessions. And the token is a guard against colliding with a
+    * session the server has not yet seen end, not a secret: the wire carries no
+    * authentication, and a peer that learns the token can end the session.
     */
-   protected forgetOpenDocument(uri: string, clientId: string): void {
-      const holders = this.openedDocuments.get(uri);
-      if (!holders) {
-         return;
+   protected resumableSessions(): Map<string, ResumableSession> {
+      let sessions = resumableByModelService.get(this.modelService);
+      if (!sessions) {
+         const created = new Map<string, ResumableSession>();
+         // Subscribed once per services tree, and never disposed: it lives as
+         // long as the text store it listens to.
+         this.services.workspace.TextDocuments.onDidCloseSession(event => created.delete(event.clientId));
+         resumableByModelService.set(this.modelService, created);
+         sessions = created;
       }
-      holders.delete(clientId);
-      if (holders.size === 0) {
-         this.openedDocuments.delete(uri);
+      return sessions;
+   }
+
+   async createModelDocument(args: CreateModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>> {
+      const session = this.requireSession(args.clientId);
+      await session.create(args.uri, args.text);
+      return this.openedSnapshot(args.uri, () => session.close(args.uri));
+   }
+
+   async updateModelDocuments(args: TransferUpdateDocumentsArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>[]> {
+      const astDocuments = await this.requireSession(args.clientId).updateAll({
+         updates: args.updates.map(update => this.toSessionWrite(update))
+      });
+      return astDocuments.map(
+         astDocument =>
+            this.encoder.astDocumentToTransferDocument(astDocument as never) as unknown as TransferDocument<TTransfer, TDiagnostic>
+      );
+   }
+
+   /**
+    * The session write a wire write request carries. Only the fields a session
+    * takes: a field an adopter adds to a request reaches the session only
+    * through an override of this.
+    */
+   protected toSessionWrite(request: Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>): ClientSessionWriteArgs<TTransfer> {
+      return { uri: request.uri, model: request.model, basedOn: request.basedOn };
+   }
+
+   /**
+    * The session this connection registered under `clientId`, which every
+    * document request acts as. An id that is not one fails with the
+    * closed-session code: opening or writing under it would leave an open that
+    * no session end ever closes.
+    */
+   protected requireSession(clientId: string): ClientSession<AstNode, AstDiagnostic, TTransfer> {
+      const session = this.clientSessions.get(clientId);
+      if (!session) {
+         throw new SessionClosedError(clientId, `Client session ${clientId} was never registered on this connection`);
       }
+      return session;
+   }
+
+   async openModelDocument(args: Pick<OpenModelArgs, 'uri' | 'clientId' | 'options'>): Promise<TransferDocument<TTransfer, TDiagnostic>> {
+      const session = this.requireSession(args.clientId);
+      const wasOpen = this.services.workspace.TextDocuments.isOpenInClient(args.uri, args.clientId);
+      await session.open(args.uri, args.options);
+      // A repeat open keeps the earlier one, which is still in use.
+      return this.openedSnapshot(args.uri, wasOpen ? undefined : () => session.close(args.uri));
    }
 
    /**
-    * Close every document still open over this connection, for the clients that
-    * opened it here.
-    *
-    * The document store releases a per-URI hold only from an explicit close, so
-    * without this a client that dies mid-session keeps its documents open for the
-    * lifetime of the process: `isOpenInAnyClient` stays true, the document stays
-    * resident, and the last-close revert never runs. A long-lived multi-client
-    * head is the configuration where a dead client is normal rather than
-    * exceptional, so the leak accumulates there.
+    * The snapshot a session's open or create answers with. When the read
+    * fails, `rollback` undoes the open this call made before the failure is
+    * rethrown: the caller sees no open, so nothing on its side would ever close
+    * it.
     *
-    * Runs from {@link dispose}, which is synchronous, so each close is fired and
-    * its failure swallowed — a teardown must not reject, and a URI whose close
-    * fails is no worse off than it was before this drain existed.
+    * Versioned with the store's shared version rather than the snapshot's own:
+    * the built document's `textDocument.version` lags the store's whenever the
+    * store assigned the version, and the store's is what a write's `basedOn` is
+    * compared against, so reporting the snapshot's would make the caller's
+    * first based-on write conflict with itself.
     */
-   protected closeOpenDocuments(): void {
-      const held = [...this.openedDocuments];
-      this.openedDocuments.clear();
-      for (const [uri, clientIds] of held) {
-         for (const clientId of clientIds) {
-            void Promise.resolve(this.modelService.close({ uri, clientId })).catch(() => undefined);
-         }
+   protected async openedSnapshot(uri: string, rollback?: () => Promise<void>): Promise<TransferDocument<TTransfer, TDiagnostic>> {
+      let document: TransferDocument<TTransfer, TDiagnostic>;
+      try {
+         document = await this.getModelDocument({ uri });
+      } catch (error: unknown) {
+         // The open's failure is the one the caller needs, not the cleanup's.
+         await rollback?.().catch(() => undefined);
+         throw error;
       }
+      return { ...document, version: asSnapshotVersion(this.services.workspace.TextDocuments.version(uri)) };
+   }
+
+   async closeModelDocument(args: CloseModelArgs): Promise<void> {
+      // Through the handle, so a close under an ended session fails as that
+      // session's calls do, and a session class's own close is honoured.
+      const session = this.requireSession(args.clientId);
+      // Closing also releases the watch for (uri, clientId) — a forgotten
+      // unwatch would otherwise leak phase-event dispatch until the connection
+      // closes. Idempotent: a close without a prior watch is a no-op.
+      await this.unwatchModelDocument({ uri: args.uri, clientId: args.clientId });
+      await session.close(args.uri);
    }
 
    async getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>> {
@@ -620,12 +803,12 @@ export class DataServer<
    }
 
    async updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>> {
-      const astDocument = await this.modelService.update(args);
+      const astDocument = await this.requireSession(args.clientId).update(this.toSessionWrite(args));
       return this.encoder.astDocumentToTransferDocument(astDocument as never) as unknown as TransferDocument<TTransfer, TDiagnostic>;
    }
 
    async saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>> {
-      const astDocument = await this.modelService.save(args);
+      const astDocument = await this.requireSession(args.clientId).save(this.toSessionWrite(args));
       return this.encoder.astDocumentToTransferDocument(astDocument as never) as unknown as TransferDocument<TTransfer, TDiagnostic>;
    }
 
@@ -734,21 +917,59 @@ export class DataServer<
    // (see resolveReferenceServices) and delegate.
    // ============================================================
 
-   async findReferenceCandidates(ctx: ReferenceContext): Promise<ReferenceCandidate[]> {
-      // Candidates are derived from resolved cross-references, so the relevant document(s) must
-      // have finished the Linked phase — otherwise a query issued right after a model update races
-      // the asynchronous rebuild and returns stale candidates. Wait the source document
-      // specifically, but ONLY when a document is actually loaded at that URI: a synthetic source
-      // can address a URI with no document (a directory URI, typically), and a per-URI `waitUntil`
-      // there throws "No document found". Fall back to a global Linked settle, matching the
-      // id-based ElementSource (no URI) path.
-      const uri = isDocumentSource(ctx.source) || isSyntheticSource(ctx.source) ? UriUtils.toUri(ctx.source.uri) : undefined;
+   /**
+    * Settle the build before a reference question is answered from the index.
+    *
+    * A query issued right after a model update otherwise races the rebuild and
+    * reads an index missing the symbols it asks about. The cost is not confined
+    * to this call: a scope built inside that window is cached, and the build's
+    * remaining documents link against it.
+    *
+    * Waits the source document specifically, but ONLY when one is loaded at
+    * that URI: a synthetic source can address a URI with no document (a
+    * directory URI, typically), where a per-URI `waitUntil` throws "No document
+    * found". Falls back to a global settle, matching the id-based
+    * `ElementSource` path.
+    *
+    * Bounded by {@link DataServerOptions.referenceSettleTimeoutMs}.
+    */
+   protected async awaitReferencesLinked(source: ReferenceSource): Promise<void> {
+      const uri = isDocumentSource(source) || isSyntheticSource(source) ? UriUtils.toUri(source.uri) : undefined;
       const waitUri = uri && this.services.workspace.LangiumDocuments.hasDocument(uri) ? uri : undefined;
-      await this.services.workspace.DocumentBuilder.waitUntil(DocumentState.Linked, waitUri);
+      const stopwatch = this.services.Clock.stopwatch();
+      let timer: Disposable | undefined;
+      const timeout = new Promise<void>((resolve, reject) => {
+         timer = this.services.Clock.setTimer(() => {
+            const elapsedMs = Math.round(stopwatch.elapsedMs);
+            // A per-URI wait resolves off a document-phase notification, so a
+            // missed one strands a wait on a document that HAS reached the
+            // phase. Re-read before failing; the workspace-wide wait has no
+            // equivalent reading and can only reject.
+            const document = waitUri ? this.services.workspace.LangiumDocuments.getDocument(waitUri) : undefined;
+            if (waitUri && document && document.state >= DocumentState.Linked) {
+               this.tracer
+                  .withUri(waitUri.toString())
+                  .warn(`Missed the 'Linked' notification after ${elapsedMs}ms; the document already reached it`);
+               resolve();
+               return;
+            }
+            reject(referenceSettleTimeoutError(elapsedMs));
+         }, this.options.referenceSettleTimeoutMs);
+      });
+      try {
+         await Promise.race([this.services.workspace.DocumentBuilder.waitUntil(DocumentState.Linked, waitUri), timeout]);
+      } finally {
+         timer?.dispose();
+      }
+   }
+
+   async findReferenceCandidates(ctx: ReferenceContext): Promise<ReferenceCandidate[]> {
+      await this.awaitReferencesLinked(ctx.source);
       return this.resolveReferenceServices(ctx.source).CandidateProvider.find(ctx);
    }
 
    async resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined> {
+      await this.awaitReferencesLinked(ref.source);
       const resolved = this.resolveReferenceServices(ref.source).CandidateProvider.resolveCandidate(ref);
       if (!resolved) {
          return undefined;
@@ -764,7 +985,14 @@ export class DataServer<
       // synthetic source — and the create-element flow driving this method is
       // the one that produces directory URIs, on which a bare
       // `getServices(uri)` throws while `findReferenceCandidates` succeeds.
-      const nameProvider = this.resolveReferenceServices(ReferenceSource.synthetic(args.uri, args.type)).NameProvider;
+      const source = ReferenceSource.synthetic(args.uri, args.type, args.language);
+      // Mid-rebuild the names of documents not yet re-indexed are absent from
+      // the taken set, and the caller PERSISTS what it is handed. Nothing
+      // reserves the answer either, so a name is free of the collisions the
+      // index knows about and of nothing else — two callers racing get the same
+      // proposal, which only uniqueness at the write can catch.
+      await this.awaitReferencesLinked(source);
+      const nameProvider = this.resolveReferenceServices(source).NameProvider;
       const tier = args.tier ?? 'project';
       if (tier === 'public') {
          return nameProvider.findNextProjectQualifiedName(args.type, args.proposal);
@@ -811,6 +1039,9 @@ export class DataServer<
    /**
     * Pick the language that owns a reference source, in order:
     *
+    * 0. A {@link isSyntheticSource} naming its own `language` routes there.
+    *    First because every step below infers, and an inference must not
+    *    override a caller that has said which grammar it means.
     * 1. A URI-bearing source ({@link isDocumentSource}/{@link isSyntheticSource})
     *    whose URI resolves to a registered language routes by URI.
     * 2. A single-language workspace always routes to that one language — so
@@ -829,6 +1060,15 @@ export class DataServer<
     */
    protected resolveReferenceLanguage(source: ReferenceSource): HydraniumLanguageServices | undefined {
       const registry = this.services.ServiceRegistry;
+      if (isSyntheticSource(source) && source.language !== undefined) {
+         const declared = registry.getServicesById(source.language);
+         if (declared) {
+            return declared;
+         }
+         // Falling through on an UNREGISTERED id rather than failing: the id
+         // crosses the wire, so a client built against a head with one more
+         // grammar would otherwise lose queries the steps below can answer.
+      }
       // `getServicesFor` (non-throwing, one ladder walk) gates the URI lookup:
       // an extensionless / unregistered URI falls through to the steps below
       // rather than throwing "no services for the extension ''".
@@ -945,14 +1185,9 @@ export class DataServer<
          // decides policy at its own layer; `root` is optional on the envelope
          // so the compiler forces that decision. Adopters preferring to throw
          // override `envelope`.
-         return {
-            uri: uri.toString(),
-            version: 0,
-            root: undefined,
-            diagnostics: [] as TDiagnostic[]
-         };
+         return TransferDocument.absent<TTransfer, TDiagnostic>(uri.toString());
       }
-      return this.encoder.toTransferDocument<AstNode>(document) as unknown as TransferDocument<TTransfer, TDiagnostic>;
+      return this.encoder.toTransferDocument(document) as unknown as TransferDocument<TTransfer, TDiagnostic>;
    }
 
    /**
@@ -967,6 +1202,57 @@ export class DataServer<
             this.dispatchPhaseEvent(document, cancelToken)
          )
       );
+      // The BUILD-phase hook, not the per-document one: this notification is one
+      // message per build rather than one per document, and Langium hands the
+      // whole batch over here. It also does not fire for a cancelled build,
+      // which is what the per-document dispatch has to check by hand.
+      this.disposables.push(
+         this.services.workspace.DocumentBuilder.onBuildPhase(this.options.subscriptionPhase, built => this.dispatchBuiltEvent(built))
+      );
+   }
+
+   /**
+    * Report the documents that reached {@link DataServerOptions.subscriptionPhase}
+    * and that NOBODY on this
+    * connection is watching — the ones a client was not told about through
+    * {@link dispatchPhaseEvent}, which is gated per URI.
+    *
+    * **The gap this closes is the one no other source can observe.** A document
+    * the client watches, it hears about already. A file changed on disk, the
+    * host's own filesystem watcher reports — and on a browser host, where the
+    * workspace lives behind this head, an external change cannot happen at all.
+    * What is left, and what nothing outside the server can see, is a document
+    * rebuilt because something it DEPENDS ON changed: its file never changed, so
+    * a filesystem watcher is silent by construction, and it has no subscriber, so
+    * the update channel is silent by design. A consumer displaying data derived
+    * from that document — a tree label, a decorator — otherwise goes stale with
+    * no signal from any source, and repairs itself the moment someone opens the
+    * file to investigate, which is what makes it expensive to diagnose later.
+    *
+    * Payload-free on purpose: URIs only, so a client re-reads what it displays
+    * rather than being handed transfer documents it did not ask for. That is the
+    * property the subscription map protects, and it is preserved here by
+    * carrying no document rather than by gating the message.
+    *
+    * Quiet in the common case. Editing a document that an editor has open leaves
+    * that URI watched and therefore out of this set, so a build with no
+    * dependents produces nothing at all, and workspace initialisation produces
+    * nothing because it does not build to this phase. The ceiling is a
+    * whole-workspace rebuild at the subscription phase: one message, URIs only.
+    *
+    * The URI is canonicalised for the same reason the subscription map is keyed
+    * that way, and is untested for the same reason as its twin in
+    * {@link dispatchDeleteEvents}: the builder reports URIs out of its own
+    * store, so a non-canonical one cannot be produced without a fixture
+    * asserting a shape the real system never emits.
+    */
+   protected dispatchBuiltEvent(built: readonly LangiumDocument[]): void {
+      const uris = built.map(document => this.canonicalKey(document.uri.toString())).filter(uri => !this.subscriptions.has(uri));
+      if (uris.length === 0) {
+         return;
+      }
+      this.tracer.debug(`Emit onDocumentsBuilt: ${uris.length} unwatched document(s)`);
+      this.clientProxy.onDocumentsBuilt({ uris });
    }
 
    /**
@@ -988,22 +1274,71 @@ export class DataServer<
    }
 
    /**
-    * Mark the last-close transition per URI (see
-    * {@link pendingRevertBroadcasts}). The listener consults
-    * `isOpenInAnyClient` AFTER the store decremented the closing client's
-    * hold, so a `false` answer means this close was the last one.
+    * Mark each document the store releases after its last close (see
+    * {@link pendingRevertBroadcasts}). A release, not the close itself: a
+    * document whose last client lost its connection is released only once
+    * the revert grace runs out, or when another client opens it meanwhile, and
+    * not at all when a client lost from it opens it again within its own
+    * grace.
     */
    protected subscribeToTextDocumentCloses(): void {
-      const textDocuments = this.services.workspace.TextDocuments;
       this.disposables.push(
-         textDocuments.onDidClose(event => {
-            if (!textDocuments.isOpenInAnyClient(event.document.uri)) {
-               this.pendingRevertBroadcasts.add(this.canonicalKey(event.document.uri));
-            }
+         this.services.workspace.TextDocuments.onDidCloseLastOpen(event => {
+            this.pendingRevertBroadcasts.add(this.canonicalKey(event.uri));
          })
       );
    }
 
+   /**
+    * Fan out a deletion for each removed URI, to EVERY client on the connection
+    * rather than only to the ones watching that URI.
+    *
+    * **Deliberately ungated, where {@link dispatchPhaseEvent} and
+    * {@link dispatchSaveEvent} are gated.** Those two carry a built document and
+    * fire on every build, so the subscription map is what keeps bandwidth
+    * proportional to what a client asked for. A deletion is neither: it is one
+    * URI, it is rare, and it reports the workspace's STRUCTURE rather than a
+    * document's content. Gating it forces any consumer that displays the
+    * workspace — a model tree, a file decorator — to learn about disappearances
+    * from a filesystem watcher instead, which a client hosted in a browser has
+    * no way to run: its workspace lives behind the head. A client that does not
+    * care filters on the URI, which costs it a comparison.
+    *
+    * The precedent is the last-close revert broadcast (see
+    * {@link pendingRevertBroadcasts}), where the same judgement was already made
+    * in the other direction: a transition that matters enough is delivered
+    * without a subscription.
+    *
+    * Runs from the `DocumentBuilder.onUpdate` listener rather than from a phase
+    * listener, which is the only place a deletion is observable: `update`
+    * removes the document before deriving the rebuild set, so it is never built.
+    * That ordering also puts this notification ahead of the `'rebuilt'` events
+    * for the dependents whose references the deletion just broke.
+    *
+    * The `deleted` list arrives already expanded to concrete document URIs —
+    * `deleteDocuments` resolves a directory URI to the documents beneath it — so
+    * no caller has to handle a directory here.
+    *
+    * Per-URI derived state is dropped for the same reason it is dropped
+    * anywhere: it describes a document that no longer exists.
+    * {@link lastEmittedFingerprint} in particular can outlive its subscriptions
+    * through the last-close revert path — left behind, it is adopted as the
+    * baseline by the next {@link watchModelDocument} and suppresses the first
+    * emit after the file returns with its previous content.
+    *
+    * The subscription itself SURVIVES: a recreated file resumes delivering to
+    * the same watchers with no re-subscription, and a client that answers the
+    * deletion by closing releases the watch through `closeModelDocument` anyway.
+    */
+   protected dispatchDeleteEvents(deleted: readonly URI[]): void {
+      for (const removed of deleted) {
+         const uri = this.canonicalKey(removed.toString());
+         this.lastEmittedFingerprint.delete(uri);
+         this.pendingRevertBroadcasts.delete(uri);
+         this.clientProxy.onDocumentDeleted({ uri });
+      }
+   }
+
    /** Fan out a save event for the document's URI, gated by the subscription map. */
    protected dispatchSaveEvent(event: ClientTextDocumentChangeEvent<TextDocument>): void {
       // The save event arrives under the CLIENT URI the text store keys by (e.g. a
@@ -1122,26 +1457,19 @@ export class DataServer<
    /**
     * Discriminate the reason for a phase-event-driven update notification.
     * Uses the most recent `DocumentBuilder.onUpdate` snapshot:
-    * - URI in the `deleted` list → `'deleted'`
     * - URI in the `changed` list → `'changed'` (the URI was passed to
     *   `documentBuilder.update(changed, deleted)`, which spans `didChange`
     *   text-document events and programmatic `update([uri], [])` calls).
     * - Otherwise → `'rebuilt'` (cascade re-derivation: this URI was rebuilt
     *   because something it depends on changed; its own text wasn't flagged).
     *
-    * `'saved'` is NOT emitted from this code path — saves take the dedicated
-    * `DataClientProtocol.onDocumentSaved` channel; adopters that want a
-    * unified update stream synthesise `'saved'` in their bridge layer.
+    * `'saved'` is NOT emitted here — saves take the dedicated
+    * `DataClientProtocol.onDocumentSaved` channel, and adopters wanting a
+    * unified stream synthesise it in their bridge layer. A deletion is not a
+    * reason at all; see {@link dispatchDeleteEvents}.
     */
    protected resolveUpdateReason(uri: URI): TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>['reason'] {
-      const last = this.lastBuildUpdate;
-      if (last?.deleted.some(deleted => UriUtils.equals(deleted, uri))) {
-         return 'deleted';
-      }
-      if (last?.changed.some(changed => UriUtils.equals(changed, uri))) {
-         return 'changed';
-      }
-      return 'rebuilt';
+      return this.lastBuildUpdate?.changed.some(changed => UriUtils.equals(changed, uri)) ? 'changed' : 'rebuilt';
    }
 
    /**
@@ -1243,7 +1571,7 @@ export class DataServer<
 
    async stopProfiling(args: StopProfilingArgs): Promise<string> {
       if (!this.activeProfile) {
-         throw new Error('No profiling capture is active; call startProfiling first.');
+         throw noActiveProfileError();
       }
       const capture = this.activeProfile;
       this.activeProfile = undefined;
@@ -1276,7 +1604,8 @@ export class DataServer<
          methodNamespace: partial.methodNamespace ?? DATA_SERVER_WIRE_PREFIX,
          additionalMethods,
          excludedMethods: partial.excludedMethods ?? [],
-         diagnostics: partial.diagnostics ?? defaultDataServerDiagnostics()
+         diagnostics: partial.diagnostics ?? defaultDataServerDiagnostics(),
+         referenceSettleTimeoutMs: partial.referenceSettleTimeoutMs ?? DataServer.DEFAULT_OPTIONS.referenceSettleTimeoutMs
       };
    }
 }