@hydranium/data-server 1.0.0-next.27 → 1.0.0-next.270

package/src/data-server.ts

@@ -11,13 +11,20 @@ import {
    createRpcProxy,
    defineMessage,
    DisposableCollection,
+   HYDRANIUM_ERROR_CODES,
    isDocumentSource,
    isElementSource,
+   isResponseError,
    isSyntheticSource,
+   messageData,
    messageError,
    ReferenceSource,
+   SessionClosedError,
+   TIMED_OUT,
    type CloseModelArgs,
+   type HydraniumMessageData,
    type HydraniumResponseError,
+   type CanonicalUri,
    type Disposable,
    type ElementSource,
    type FindNextNameArgs,
@@ -29,10 +36,16 @@ import {
    type ReferenceContext,
    type ReferenceRequest,
    type ReferenceTarget,
+   type TransferModelSnapshot,
+   type ModelVersion,
+   type TextState,
    type Tracer,
    type TransferDiagnostic,
-   type TransferDocument,
-   type TransferElement
+   TransferDocument,
+   type TransferSavedDocument,
+   type TransferElement,
+   UNKNOWN_CLIENT_ID,
+   textHash
 } from '@hydranium/protocol';
 import {
    DATA_SERVER_DIAGNOSTICS_METHODS,
@@ -45,24 +58,29 @@ import {
    type StartProfilingArgs,
    type StopProfilingArgs,
    type WriteServerHeapSnapshotArgs,
+   type CloseSessionArgs,
+   type CreateModelDocumentArgs,
+   type CreateSessionArgs,
    type GetModelDocumentArgs,
    type GetProjectForUriArgs,
+   type TransferPersistDocumentArgs,
    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 { DOCUMENT_RELEASE_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 the
- * hop: an unwrapped throw inside an RPC handler reaches the client as a generic
- * internal error, which carries no code for a caller to switch on and no
- * envelope for a translating host to read.
+ * 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',
@@ -73,23 +91,54 @@ export const NO_ACTIVE_PROFILE = defineMessage(
  * 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 NO_ACTIVE_PROFILE_CODE = HYDRANIUM_ERROR_CODES.noActiveProfile;
 
 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',
+   'The model is still being processed; try again in a moment.'
+);
+
+/** See {@link NO_ACTIVE_PROFILE_CODE} for why this is separate from the catalogue code. */
+export const REFERENCE_SETTLE_TIMEOUT_CODE = HYDRANIUM_ERROR_CODES.referenceSettleTimeout;
+
+/** The wait's length rides in `data` as `elapsedMs`, for the code that reacts rather than the reader. */
+export const referenceSettleTimeoutError = (elapsedMs: number): ResponseError<HydraniumMessageData & { readonly elapsedMs: number }> =>
+   new ResponseError(REFERENCE_SETTLE_TIMEOUT_CODE, REFERENCE_SETTLE_TIMEOUT.format(), {
+      elapsedMs,
+      ...messageData(REFERENCE_SETTLE_TIMEOUT)
+   });
+
 import type { DataServerDiagnosticsProvider, DataServerProfileCapture } from './diagnostics-provider.js';
 import type {
-   ClientTextDocumentChangeEvent,
+   ClientSession,
+   ClientSessionWriteArgs,
    HydraniumLanguageServices,
    LogNameOptions,
+   AstDiagnostic,
+   AstDocument,
+   AstDocumentSavedEvent,
+   EncodedTransferDocument,
+   ModelDeletedEvent,
+   ModelDirtyChangedEvent,
    ModelService,
+   ModelUpdatedEvent,
    ProjectChangeEvent,
    ServerSharedServices,
+   SessionEndCause,
    TransferEncoder
 } from '@hydranium/core';
-import type { TextDocument } from 'vscode-languageserver-textdocument';
-import { type AstNode, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
-import type { CancellationToken, MessageConnection } from 'vscode-jsonrpc';
+import { type AstNode, DocumentState, UriUtils, type URI } from '@hydranium/langium';
+import { type MessageConnection, ResponseError } from 'vscode-jsonrpc';
 
 /**
  * Domain separator between text and diagnostics inputs of
@@ -100,34 +149,11 @@ import type { CancellationToken, MessageConnection } from 'vscode-jsonrpc';
 const FINGERPRINT_SEPARATOR = '\0';
 
 /**
- * Portable, non-cryptographic 64-bit fingerprint hash (cyrb53), returning a
- * 16-char hex digest.
- *
- * **A cryptographic hash via `node:crypto` is the wrong trade**: the
- * fingerprint only needs a stable signal that `(text, diagnostics)` changed
- * between emissions, and a `node:*` import would cost
- * `@hydranium/data-server` its browser-portability. Parts are fed
- * incrementally, char by char, so multi-MB document text is never
- * concatenated into one string.
+ * `LSPErrorCodes.ServerCancelled`, with which Langium's document wait rejects
+ * for a URI that has no document; `vscode-languageserver-protocol` is not a
+ * dependency of this package.
  */
-function fingerprintHash(parts: readonly string[]): string {
-   let h1 = 0xdeadbeef;
-   let h2 = 0x41c6ce57;
-   for (const part of parts) {
-      for (let i = 0; i < part.length; i++) {
-         const ch = part.charCodeAt(i);
-         h1 = Math.imul(h1 ^ ch, 2654435761);
-         h2 = Math.imul(h2 ^ ch, 1597334677);
-      }
-   }
-   h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
-   h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
-   h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
-   h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
-   const high = (h2 >>> 0).toString(16).padStart(8, '0');
-   const low = (h1 >>> 0).toString(16).padStart(8, '0');
-   return high + low;
-}
+const SERVER_CANCELLED = -32802;
 
 /**
  * Which observable state {@link DataServer.computeDocumentFingerprint} hashes to
@@ -140,26 +166,32 @@ function fingerprintHash(parts: readonly string[]): string {
  *   folded in on a cascade rebuild that leaves the document's own text
  *   untouched. Safe for any adopter whose AST extensions fold derived state
  *   into the transfer projection (the framework norm).
- * - `'text-diagnostics'` — the cheaper `getText()` + diagnostics hash. An
- *   opt-DOWN for adopters that fold no derived state and want to avoid the
- *   transfer-encode per phase event.
+ * - `'text-diagnostics'` — the cheaper parsed-text + diagnostics hash. An
+ *   opt-DOWN for adopters that fold no derived state and want to avoid
+ *   stringifying the transfer root per phase event.
  */
 export type FingerprintStrategy = 'transfer-document' | 'text-diagnostics';
 
-/** Hash a document's raw text + diagnostics — the `'text-diagnostics'` strategy. */
-function textDiagnosticsFingerprint(document: LangiumDocument): string {
-   return fingerprintHash([document.textDocument.getText(), FINGERPRINT_SEPARATOR, JSON.stringify(document.diagnostics ?? [])]);
+/**
+ * Hash `text`, the text the model was parsed from, + `model`'s diagnostics — the `'text-diagnostics'` strategy.
+ * The text comes from the root's ledger record or CST, as the document's own may have moved on,
+ * and a repair in place leaves the CST on the unrepaired text;
+ * a root built without a CST hashes as `'transfer-document'`.
+ * Absent diagnostics must hash apart from `[]`, as in {@link transferDocumentFingerprint}.
+ */
+function textDiagnosticsFingerprint(text: string | undefined, model: EncodedTransferDocument<TransferElement, unknown>['model']): string {
+   return text === undefined
+      ? transferDocumentFingerprint(model)
+      : textHash([text, FINGERPRINT_SEPARATOR, JSON.stringify(model.diagnostics ?? null)]);
 }
 
-/** Hash an encoded transfer document's root + diagnostics — the `'transfer-document'` strategy. */
-function transferDocumentFingerprint(transferDocument: Pick<TransferDocument<TransferElement, unknown>, 'root' | 'diagnostics'>): string {
-   // null, not undefined: `JSON.stringify(undefined)` yields undefined rather
-   // than a string, putting a non-string into the hash inputs.
-   return fingerprintHash([
-      JSON.stringify(transferDocument.root ?? null),
-      FINGERPRINT_SEPARATOR,
-      JSON.stringify(transferDocument.diagnostics)
-   ]);
+/**
+ * Hash an encoded model's root + diagnostics — the `'transfer-document'` strategy.
+ * Absent diagnostics must hash apart from `[]`: a client skipping a render on an
+ * equal hash would otherwise miss a validation that found nothing.
+ */
+function transferDocumentFingerprint(model: EncodedTransferDocument<TransferElement, unknown>['model']): string {
+   return textHash([JSON.stringify(model.root), FINGERPRINT_SEPARATOR, JSON.stringify(model.diagnostics ?? null)]);
 }
 /**
  * `logAfterMs` threshold passed to {@link Tracer.time} around
@@ -180,12 +212,13 @@ export interface DataServerOptions extends LogNameOptions {
     * (`DataClientProtocol.onDocumentUpdated`).
     *
     * **Subscription dispatch only** — distinct from the synchronous RPC
-    * response phase. The lifecycle reads/writes (`getModelDocument` /
-    * `updateModelDocument` / `saveModelDocument`) settle at the
-    * integrity-settled landmark (`IntegrityService.SettledState`); a
-    * read additionally upgrades to `Validated` per call when
-    * {@link GetModelDocumentArgs.includeDiagnostics} is set. This option
-    * controls only the async notification phase.
+    * response phase. A read (`getModelDocument`) settles at the
+    * integrity-settled landmark (`IntegrityService.SettledState`), or at
+    * `Validated` when {@link GetModelDocumentArgs.includeDiagnostics} is set.
+    * A write (`updateModelDocument` / `updateModelDocuments` /
+    * `saveModelDocument`) answers once its document is validated, as a
+    * session's write does. This option controls only the async notification
+    * phase.
     *
     * Default: `DocumentState.Validated` — validation is the last builder
     * phase and produces the full diagnostic set, so subscription events fired
@@ -226,6 +259,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
@@ -283,15 +332,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;
@@ -299,6 +353,41 @@ interface ResolvedDataServerOptions {
    readonly excludedMethods: readonly string[];
    /** Always resolved — to the caller's, or to the platform default. */
    readonly diagnostics: DataServerDiagnosticsProvider;
+   readonly referenceSettleTimeoutMs: number;
+}
+
+/**
+ * What a {@link DataServer} keeps per canonical URI, in the `protected`
+ * {@link DataServer.uriWatchRecords}. A record lives while it has a watcher
+ * or a release mark; {@link DataServer.pruneUriWatchRecord} enforces that on
+ * every path that removes either, so a record with no watcher has a release
+ * broadcast pending. Test the size of {@link DataServerUriWatchRecord.watchers}, not the
+ * record's presence, for "watched".
+ */
+export interface DataServerUriWatchRecord {
+   /** The client ids watching the URI; save, dirty and phase events go out only while it is non-empty, a pending release mark aside. */
+   readonly watchers: Set<string>;
+   /** Digest of the last emitted state, or of the state a first watch found; see {@link DataServer.dispatchPhaseEvent} for why it de-duplicates, {@link DataServer.computeDocumentFingerprint} for its inputs. */
+   fingerprint?: string;
+   /**
+    * The version {@link DataServerUriWatchRecord.fingerprint} was taken at; an
+    * event goes out when either moves. Not {@link DataServerUriWatchRecord.sentVersion}:
+    * a first watch sets this and sends nothing, so the next event at its
+    * version still carries the manager's attribution.
+    */
+   fingerprintVersion?: ModelVersion;
+   /** Set by {@link DataServer.subscribeToModelReleases} once a release happened: its broadcast, the next phase event, goes out even without a watcher. */
+   releaseBroadcastPending?: boolean;
+   /**
+    * The version of an open document the last event sent was built at. The
+    * version sent again goes out as `'rebuilt'` from no client: the manager
+    * counts a version delivered only once its `Validated` listeners ran, so a
+    * build cancelled after the subscription phase would send it as a change
+    * twice. Only while the store has the document open: without it, a
+    * document can keep one version through changes of its file, so its events
+    * keep the manager's attribution.
+    */
+   sentVersion?: number;
 }
 
 /**
@@ -322,13 +411,19 @@ interface ResolvedDataServerOptions {
  * adopters subclass ONLY when they need to decorate wire returns or
  * notifications. The usual adoption path is DI rebinds alone.
  *
+ * **`TTransfer` is not checked.** It declares the union of the transfer roots
+ * the workspace's languages produce. Which root a document has is known only
+ * at runtime, from its language, so a `TTransfer` missing a language compiles.
+ *
  * Lifecycle: the constructor registers framework request handlers (plus
  * 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 follows documents
+ * through `ModelService`'s events: at the configured phase, `onModelUpdated`
+ * dispatches per-document `clientProxy.onDocumentUpdated` for watched URIs and
+ * `onModelsBuilt` a single `clientProxy.onDocumentsBuilt` naming the batch's
+ * unwatched documents.
  *
  * The data-server requires the full {@link ServerSharedServices}
  * shape — `HydraniumTextDocuments` for client-attributed updates,
@@ -356,87 +451,30 @@ 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.
-    *
-    * 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.
-    */
-   protected readonly openedDocuments = new Map<string, Set<string>>();
-   /** 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();
+   /** This connection's {@link DataServerUriWatchRecord} per canonical URI; see there for when a record lives. */
+   protected readonly uriWatchRecords = new Map<string, DataServerUriWatchRecord>();
    /**
-    * 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.
+    * The live 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. A session leaves once it ends, so a
+    * connection that registers many over its life does not accumulate them.
     */
-   protected lastBuildUpdate?: { changed: readonly URI[]; deleted: readonly URI[] };
+   protected readonly clientSessions = new Map<string, ClientSession<AstNode, AstDiagnostic, TTransfer>>();
    /**
-    * Per-URI hash of the last emitted (text + diagnostics) state,
-    * used by {@link dispatchPhaseEvent} to suppress duplicate
-    * `onDocumentUpdated` notifications for rebuilds that produce no
-    * observable change since the last emit.
-    *
-    * Two scenarios routinely produce such rebuilds:
-    * 1. **Refresh-triggered rebuilds.** When a second client attaches to a
-    *    document already open in another client,
-    *    `HydraniumTextDocuments.refreshContent` fires `onDidChangeContent`
-    *    purely to re-trigger the build pipeline — the text and diagnostics
-    *    are identical to the prior emit.
-    * 2. **Cascade rebuilds with no diagnostic delta.** Langium rebuilds a
-    *    document when a dependency changes; if the rebuild produces the
-    *    same diagnostics, there is nothing new to communicate to subscribers.
-    *
-    * Without this filter, both scenarios reach subscribers as wire-side
-    * `'changed'` events. A subscriber that interprets `'changed'` as
-    * "another client wrote new content" and resets its in-memory root to
-    * the server view then misreads the spurious event as a concurrent
-    * third-party write and loses the user's edits.
-    *
-    * Initialised on {@link watchModelDocument} to the current
-    * document fingerprint so the FIRST phase event after a fresh
-    * subscription is also de-duplicated against the state subscribers
-    * obtained via `getModelDocument` — they do not need a redundant phase
-    * notification for the state they just fetched.
-    *
-    * Cleared in {@link unwatchModelDocument} when the last
-    * subscriber for a URI leaves so memory does not accumulate.
-    *
-    * Stored as a cyrb53 hex digest (16 chars per URI) rather than the raw
-    * text + diagnostics serialisation so the memory cost is constant in
-    * document size. See {@link computeDocumentFingerprint} for the inputs.
-    */
-   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
-    * {@link subscribeToTextDocumentCloses}) and consumed by
-    * {@link dispatchPhaseEvent}, which broadcasts the following rebuild's
-    * phase event even without a subscription — de-duplicated against
-    * {@link lastEmittedFingerprint} where an entry survives, so a close
-    * whose disk state equals the last emitted state stays silent.
+    * Typed client proxy — sends `data-server/on*` notifications back over the same wire.
+    * The proxy sends any `on[A-Z]*` name other than `onDidOpenConnection` and
+    * `onDidCloseConnection`, for which it returns its own events, so a subclass
+    * with notifications of its own narrows only the type:
+    * `declare protected readonly clientProxy: TheirClient`.
     */
-   protected readonly pendingRevertBroadcasts = new Set<string>();
+   protected readonly clientProxy: DataClientProtocol<TTransfer, TDiagnostic, TProject>;
+   protected readonly disposables = new DisposableCollection();
    protected readonly tracer: Tracer;
    /** The in-flight interactive profile capture, held between {@link startProfiling} and {@link stopProfiling}. */
    protected activeProfile?: DataServerProfileCapture;
@@ -445,27 +483,23 @@ 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
-    * carry LSP-shape diagnostics in their AstDocument (e.g. an adopter's LSP-shape diagnostic type)
-    * while the wire shape stays `TDiagnostic extends TransferDiagnostic`. The encoder's
-    * `astDocumentToTransferDocument` accepts both shapes (wire-shape or LSP-shape) and projects
-    * to wire shape on the return — see `TransferEncoder.astDocumentToTransferDocument`.
+    * Its documents carry the AST-layer {@link AstDiagnostic}, never the wire `TDiagnostic`:
+    * {@link encoder} converts one into the other on the way out.
     */
-   protected readonly modelService: ModelService<AstNode, unknown, TTransfer>;
+   protected readonly modelService: ModelService<AstNode, AstDiagnostic, TTransfer>;
 
    constructor(
       protected readonly connection: MessageConnection,
-      protected readonly services: ServerSharedServices<TProject>,
+      protected readonly services: ServerSharedServices<TProject, TDiagnostic>,
       options: DataServerOptions = {}
    ) {
       this.options = this.resolveOptions(options);
       this.tracer = this.services.Tracer.for(options.logName ?? 'DataServer').trace('instantiated');
       // DI-bound: adopters rebind `services.model.TransferEncoder` /
-      // `services.model.ModelService` with their own subclasses. Slot types use the
-      // framework upper bounds; the casts below narrow to this instance's generics.
+      // `services.model.ModelService` with their own subclasses.
       const { TransferEncoder: encoder, ModelService: modelService } = this.services.model;
       if (!encoder || !modelService) {
          throw new Error(
@@ -473,8 +507,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;
+      this.modelService = modelService;
       const excluded = new Set<string>(this.options.excludedMethods);
       const registeredMethods = [
          ...DATA_SERVER_PROTOCOL_METHODS,
@@ -490,38 +524,43 @@ 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.subscribeToDocumentBuilder();
+      this.disposables.push(this.modelService.onModelDeleted(event => this.dispatchDeleteEvent(event)));
+      this.subscribeToModelUpdates();
       this.subscribeToTextDocumentSaves();
-      this.subscribeToTextDocumentCloses();
+      this.subscribeToDirtyChanges();
+      this.subscribeToModelReleases();
       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 release grace. See `dispose`.
+      this.disposables.push(connection.onClose(() => this.dispose('lost')));
    }
 
    /**
     * Release everything the constructor wired up — the bound protocol
-    * 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.
+    * handlers and every listener — and clear {@link uriWatchRecords}, so a
+    * long-lived shared services bundle does not retain per-connection memory
+    * after the connection 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'` releases every document whose last open they close at once,
+    * and `'lost'`, the connection's own close, lets each wait out the release
+    * 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.
@@ -530,104 +569,148 @@ 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
+      // `onModelReleased` subscription would otherwise mark a release broadcast
+      // for a connection that is already gone.
       this.disposables.dispose();
-      this.closeOpenDocuments();
-      this.subscriptions.clear();
-      this.lastEmittedFingerprint.clear();
-      this.pendingRevertBroadcasts.clear();
+      for (const [clientId, session] of this.clientSessions) {
+         this.endSession(clientId, session, cause);
+      }
+      this.uriWatchRecords.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);
       }
-      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) };
+      const session = this.modelService.createSession(args.label, args.clientId, { resumeToken: args.resumeToken });
+      this.clientSessions.set(args.clientId, session);
+      // A session also ends without closeSession, as when a client registers
+      // again on another connection, and its watches and entry here would
+      // otherwise outlive it.
+      session.onDidDispose(cause => {
+         // A session class may report its end late, once a replacement holds
+         // the id here; the replacement's entry and watches stay.
+         if (this.clientSessions.get(args.clientId) !== session) {
+            return;
+         }
+         this.dropWatches(args.clientId);
+         this.clientSessions.delete(args.clientId);
+         this.tracer.debug(`Forget session ${args.clientId}: it ended as ${cause}`);
+      });
    }
 
-   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. */
+   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 {
+      this.dropWatches(clientId);
+      session.dispose(cause);
+   }
+
+   protected dropWatches(clientId: string): void {
+      for (const [uri, record] of this.uriWatchRecords) {
+         if (record.watchers.delete(clientId)) {
+            this.pruneUriWatchRecord(uri);
+         }
+      }
+   }
+
+   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.encodeDocument(astDocument));
    }
 
    /**
-    * Drop the recorded hold for `(uri, clientId)` so {@link dispose} does not
-    * close it a second time. Idempotent.
+    * 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 forgetOpenDocument(uri: string, clientId: string): void {
-      const holders = this.openedDocuments.get(uri);
-      if (!holders) {
-         return;
-      }
-      holders.delete(clientId);
-      if (holders.size === 0) {
-         this.openedDocuments.delete(uri);
+   protected toSessionWrite(request: Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>): ClientSessionWriteArgs<TTransfer> {
+      return { uri: request.uri, model: request.model, baseVersion: request.baseVersion };
+   }
+
+   /**
+    * 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, 'The client session is not 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.
-    *
-    * 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.
+    * 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.
     */
-   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>> {
+      try {
+         return 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;
       }
    }
 
+   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>> {
       // Smart dispatch: a warm document (already in LangiumDocuments) is
       // returned at its settle phase without a redundant build; a cold URI
@@ -640,18 +723,32 @@ export class DataServer<
       // unsubscribed caller that needs diagnostics inline passes
       // `includeDiagnostics: true` to settle at `Validated` instead.
       const state = args.includeDiagnostics ? DocumentState.Validated : undefined;
-      const astDocument = await this.modelService.ensureDocumentState(args.uri, state);
-      return this.encoder.astDocumentToTransferDocument(astDocument as never) as unknown as TransferDocument<TTransfer, TDiagnostic>;
+      try {
+         return this.encodeDocument(await this.modelService.ensureDocumentState(args.uri, state));
+      } catch (error: unknown) {
+         // The protocol answers a read of a URI with no document with an
+         // envelope that has no model.
+         if (this.isMissingDocument(error, args.uri)) {
+            return this.envelope(UriUtils.toUri(args.uri));
+         }
+         throw error;
+      }
    }
 
    async updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>> {
-      const astDocument = await this.modelService.update(args);
-      return this.encoder.astDocumentToTransferDocument(astDocument as never) as unknown as TransferDocument<TTransfer, TDiagnostic>;
+      const astDocument = await this.requireSession(args.clientId).update(this.toSessionWrite(args));
+      return this.encodeDocument(astDocument);
    }
 
-   async saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>> {
-      const astDocument = await this.modelService.save(args);
-      return this.encoder.astDocumentToTransferDocument(astDocument as never) as unknown as TransferDocument<TTransfer, TDiagnostic>;
+   async saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferSavedDocument<TTransfer, TDiagnostic>> {
+      const astDocument = await this.requireSession(args.clientId).save(this.toSessionWrite(args));
+      return { ...this.encodeDocument(astDocument), persisted: astDocument.persisted };
+   }
+
+   async persistModelDocument(args: TransferPersistDocumentArgs): Promise<TransferSavedDocument<TTransfer, TDiagnostic>> {
+      const version = await this.requireSession(args.clientId).persist({ uri: args.uri, baseVersion: args.baseVersion });
+      const astDocument = await this.modelService.ensureDocumentState(args.uri, this.services.workspace.DocumentBuilder.finalBuildState());
+      return { ...this.encodeDocument(astDocument), persisted: { version } };
    }
 
    /**
@@ -659,28 +756,25 @@ export class DataServer<
     * fan out to the wired `clientProxy.onDocumentUpdated`. The
     * bidirectional pattern means the event channel is the client
     * notification surface, not a returned handle — this method only
-    * registers the URI in the dispatch table.
+    * registers the watcher in {@link uriWatchRecords}.
     *
-    * Also baselines the per-URI emission fingerprint (see
-    * {@link lastEmittedFingerprint}) to the document's current state when
-    * the first watcher for the URI registers. This guarantees that any
-    * phase event firing immediately after the watch with no observable
-    * change is suppressed — watchers obtain initial state via
-    * `getModelDocument` (or {@link openModelDocument}) and do not need a
-    * redundant phase notification for that same state.
+    * Also baselines the URI's emission fingerprint (see
+    * {@link dispatchPhaseEvent}) to the document's current state when the
+    * first watcher for the URI registers. This guarantees that any phase event firing immediately after
+    * the watch with no observable change is suppressed — watchers obtain
+    * initial state via `getModelDocument` (or {@link openModelDocument}) and
+    * do not need a redundant phase notification for that same state.
     */
    async watchModelDocument(args: WatchModelDocumentArgs): Promise<void> {
       const uri = this.canonicalKey(args.uri);
-      let subscribers = this.subscriptions.get(uri);
-      if (!subscribers) {
-         subscribers = new Set();
-         this.subscriptions.set(uri, subscribers);
-      }
-      subscribers.add(args.clientId);
-      if (!this.lastEmittedFingerprint.has(uri)) {
-         const document = this.services.workspace.LangiumDocuments.getDocument(UriUtils.toUri(uri));
-         if (document) {
-            this.lastEmittedFingerprint.set(uri, this.computeDocumentFingerprint(document));
+      const record = this.uriWatchRecords.get(uri) ?? { watchers: new Set<string>() };
+      this.uriWatchRecords.set(uri, record);
+      record.watchers.add(args.clientId);
+      if (record.fingerprint === undefined) {
+         const document = this.modelService.getDocument(args.uri);
+         if (document && !this.services.workspace.ModelLedger.isPlaceholder(document.parseResult.value)) {
+            record.fingerprint = this.computeDocumentFingerprint(document.parseResult.value, this.encoder.toTransferDocument(document));
+            record.fingerprintVersion = this.services.workspace.ModelLedger.versionOf(document.parseResult.value);
          }
       }
    }
@@ -688,29 +782,41 @@ export class DataServer<
    /**
     * Remove a watch for `(uri, clientId)` previously created by
     * {@link watchModelDocument}. Idempotent — unwatching twice is a no-op.
-    * Dispatch for `uri` stops once no watchers remain, at which point the
-    * per-URI emission fingerprint is also cleared so the next first-watch
-    * re-baselines against the then-current document state rather than a
-    * stale snapshot from the previous watch.
+    * Dispatch for `uri` stops once no watchers remain, and the emission
+    * fingerprint goes with the last watcher (see {@link pruneUriWatchRecord}).
     */
    async unwatchModelDocument(args: WatchModelDocumentArgs): Promise<void> {
       const uri = this.canonicalKey(args.uri);
-      const subscribers = this.subscriptions.get(uri);
-      if (!subscribers) {
+      if (this.uriWatchRecords.get(uri)?.watchers.delete(args.clientId)) {
+         this.pruneUriWatchRecord(uri);
+      }
+   }
+
+   /**
+    * Drop what `uri` no longer needs: the
+    * {@link DataServerUriWatchRecord.fingerprint} once no client watches it,
+    * and the whole record once it holds no
+    * {@link DataServerUriWatchRecord.releaseBroadcastPending} mark either.
+    * Every path that removes a watcher or consumes a mark ends here.
+    */
+   protected pruneUriWatchRecord(uri: string): void {
+      const record = this.uriWatchRecords.get(uri);
+      if (!record || record.watchers.size > 0) {
          return;
       }
-      subscribers.delete(args.clientId);
-      if (subscribers.size === 0) {
-         this.subscriptions.delete(uri);
-         this.lastEmittedFingerprint.delete(uri);
+      if (record.releaseBroadcastPending) {
+         record.fingerprint = undefined;
+         record.fingerprintVersion = undefined;
+      } else {
+         this.uriWatchRecords.delete(uri);
       }
    }
 
    /**
-    * Canonicalise a URI string for use as a subscription / fingerprint
-    * map key, via the shared `DocumentUriPolicy`. Callers may send
-    * non-canonical URIs (drive-letter casing, percent-encoding differences,
-    * or a symlink path) over the wire; the dispatch side keys by
+    * Canonicalise a URI string for use as a {@link uriWatchRecords} key, via the
+    * shared `DocumentUriPolicy`. Callers may send non-canonical URIs
+    * (drive-letter casing, percent-encoding differences, or a symlink path)
+    * over the wire; the dispatch side keys by
     * `document.uri.toString()` from `LangiumDocuments`, so writer keys must
     * canonicalise to the same form or events silently fail to deliver.
     * Routing through the seam (rather than a bare `UriUtils.normalize`)
@@ -720,6 +826,7 @@ export class DataServer<
     * LSP head resolves.
     *
     * Adopters can still override for head-specific URI policy by subclassing.
+    * The result keys watches only; a document is looked up by its own URI.
     */
    protected canonicalKey(uri: string): string {
       return this.services.workspace.DocumentUriPolicy.canonicalUri(uri);
@@ -759,27 +866,60 @@ 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();
+      const linked = this.services.workspace.DocumentBuilder.waitUntil(DocumentState.Linked, waitUri);
+      if ((await this.services.Clock.raceTimer(linked, this.options.referenceSettleTimeoutMs)) !== TIMED_OUT) {
+         return;
+      }
+      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`);
+         return;
+      }
+      throw referenceSettleTimeoutError(elapsedMs);
+   }
+
+   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> {
+   async resolveReference<TElement extends TransferElement = TransferElement>(
+      ref: ReferenceRequest
+   ): Promise<ReferenceTarget<TElement> | undefined> {
+      await this.awaitReferencesLinked(ref.source);
       const resolved = this.resolveReferenceServices(ref.source).CandidateProvider.resolveCandidate(ref);
       if (!resolved) {
          return undefined;
       }
-      const element = this.encoder.toTransfer(resolved.node) as unknown as TTransfer;
-      return { ...resolved.candidate, element };
+      // `TElement` is the caller's claim about the target's type; nothing checks it.
+      return { ...resolved.candidate, element: this.encoder.toTransfer(resolved.node) as TElement };
    }
 
    async findNextName(args: FindNextNameArgs): Promise<string> {
@@ -789,15 +929,31 @@ 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);
       }
       if (tier === 'local') {
-         // Document-scoped uniqueness: the document root is the container.
-         const document = await this.modelService.ensureDocumentState(args.uri);
-         return document.root ? nameProvider.findNextName(args.type, args.proposal, document.root as AstNode) : args.proposal;
+         // Document-scoped uniqueness: the document root is the container. A
+         // URI with no document has nothing to collide with, like a document
+         // with no root.
+         try {
+            const document = await this.modelService.ensureDocumentState(args.uri);
+            return document.root ? nameProvider.findNextName(args.type, args.proposal, document.root) : args.proposal;
+         } catch (error: unknown) {
+            if (this.isMissingDocument(error, args.uri)) {
+               return args.proposal;
+            }
+            throw error;
+         }
       }
       const project = this.services.workspace.ProjectManager.getProject(uri);
       if (!project) {
@@ -834,67 +990,32 @@ export class DataServer<
    }
 
    /**
-    * Pick the language that owns a reference source, in order:
+    * Pick the language that owns a reference source: the registry's
+    * `getLanguageFor` over the source's declared language, URI and AST type,
+    * with an {@link isElementSource} routed by the document that holds the
+    * element (see {@link findElementDocumentUri}) before its type, and
+    * {@link fallbackReferenceLanguage}, adopter policy, last.
     *
-    * 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
-    *    single-language adopters never reach the steps below, and never pay
-    *    for them.
-    * 3. An {@link isElementSource} source carries no URI, so in a
-    *    multi-language workspace it is routed via the document that holds the
-    *    element (see {@link findElementDocumentUri}).
-    * 4. A source carrying an AST type is routed by that type when exactly one
-    *    registered grammar can produce it (see
-    *    {@link resolveReferenceLanguageByType}, over the registry's own type
-    *    index). This is what resolves a create-element flow's synthetic source
-    *    on a bare directory URI without asking the adopter.
-    * 5. Anything still unresolved falls to {@link fallbackReferenceLanguage},
-    *    which is adopter policy.
+    * An unregistered declared language falls through rather than failing: the
+    * id crosses the wire, so a client built against a head with one more
+    * grammar would otherwise lose queries the other signals answer.
     */
    protected resolveReferenceLanguage(source: ReferenceSource): HydraniumLanguageServices | undefined {
       const registry = this.services.ServiceRegistry;
-      // `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 ''".
-      const uri = isDocumentSource(source) || isSyntheticSource(source) ? UriUtils.toUri(source.uri) : undefined;
-      const byUri = uri && registry.getServicesFor(uri);
-      if (byUri) {
-         return byUri;
-      }
-      const all = registry.all;
-      if (all.length === 1) {
-         return all[0] as HydraniumLanguageServices;
-      }
       if (isElementSource(source)) {
-         const documentUri = this.findElementDocumentUri(source);
-         const byDocument = documentUri && registry.getServicesFor(documentUri);
-         if (byDocument) {
-            return byDocument;
-         }
+         // The index lookup runs only once the cheaper signals abstained.
+         return (
+            registry.getLanguageFor({}) ??
+            registry.getLanguageFor({ target: this.findElementDocumentUri(source), type: source.type }) ??
+            this.fallbackReferenceLanguage(source)
+         );
       }
-      const byType = this.resolveReferenceLanguageByType(source);
-      return byType ?? this.fallbackReferenceLanguage(source);
-   }
-
-   /**
-    * Route a reference source by the AST type it carries — a
-    * {@link isSyntheticSource}'s `type` (the transient node being created) or an
-    * {@link isElementSource}'s optional narrowing `type`.
-    *
-    * Answers only when EXACTLY ONE registered grammar can produce the type.
-    * Several can when the type comes from a grammar both import, and then the
-    * type genuinely does not identify a language — that is a fall-through to
-    * adopter policy, not a coin toss. Note this asks which grammar can *produce*
-    * the type, not which mentions it: a grammar that merely cross-references a
-    * type can never hold a node of it.
-    */
-   protected resolveReferenceLanguageByType(source: ReferenceSource): HydraniumLanguageServices | undefined {
-      const type = isSyntheticSource(source) ? source.type : isElementSource(source) ? source.type : undefined;
-      // The registry owns the type index — it is the one place that knows when
-      // the registered set changed, so unlike a private memo here it cannot go
-      // stale on a language registered after the first lookup.
-      return type ? this.services.ServiceRegistry.soleServicesByType(type) : undefined;
+      const hint = isSyntheticSource(source)
+         ? { languageId: source.language, target: source.uri, type: source.type }
+         : isDocumentSource(source)
+           ? { target: source.uri }
+           : {};
+      return registry.getLanguageFor(hint) ?? this.fallbackReferenceLanguage(source);
    }
 
    /**
@@ -904,15 +1025,14 @@ export class DataServer<
     * disambiguates names that repeat across types (honouring grammar
     * subtyping through `AstReflection.isSubtype`).
     *
-    * Only reached on the multi-language, name-based path (step 3 of
-    * {@link resolveReferenceLanguage}); single-language adopters return at
-    * step 2.
+    * Only reached in a multi-language workspace, once the declared language
+    * and the URI have abstained.
     *
     * Abstains when the name matches elements in more than one DOCUMENT — the
     * index spans every language and is filled in build order, so "the
-    * first match" would be file-watch order rather than an answer. Step 3
-    * then falls through to the type-based step 4, which abstains on ties
-    * in the same way, and finally to adopter policy.
+    * first match" would be file-watch order rather than an answer. Routing
+    * then falls through to the element's type, which abstains on ties in the
+    * same way, and finally to adopter policy.
     */
    protected findElementDocumentUri(source: ElementSource): URI | undefined {
       const matches = this.services.workspace.IndexManager.getElementsByName(source.name, source.type);
@@ -947,61 +1067,144 @@ export class DataServer<
    // Internal plumbing
    // ============================================================
 
+   /**
+    * Whether `error`, from waiting on `uri`'s document, means that `uri` has
+    * no document: a URI with neither a file nor text builds nothing, and
+    * Langium's wait after the build rejects for want of one, with a
+    * `ServerCancelled` response error. Any other failure, such as a read
+    * that fails before a document is registered, a cancelled wait or a
+    * `ReentrantWriteLockError`, is the caller's to see.
+    */
+   protected isMissingDocument(error: unknown, uri: string): boolean {
+      return isResponseError(error) && error.code === SERVER_CANCELLED && this.modelService.getDocument(uri) === undefined;
+   }
+
    /**
     * Build a {@link TransferDocument} envelope from the current document state,
     * delegating root + diagnostic encoding to {@link encoder} (see
-    * `TransferEncoder.toTransferDocument` for the walk).
-    *
-    * The encoder field's generic-map binding is widened to
-    * `Record<string, TransferElement>` at the framework-default level, and an
-    * adopter supplying a typed-overlay encoder narrows the runtime shape to
-    * its wire types. The cast on the return is where that invariant — the
-    * adopter's `TTransfer` matches its encoder's overlay — is asserted, at a
-    * single boundary point rather than spread across the callers.
+    * `TransferEncoder.toTransferDocument` for the walk). `fingerprint` is the
+    * caller's {@link computeDocumentFingerprint} of that same state, which
+    * spares hashing it twice.
     */
-   protected envelope(uri: URI): TransferDocument<TTransfer, TDiagnostic> {
+   protected envelope(uri: URI, fingerprint?: string): TransferDocument<TTransfer, TDiagnostic> {
       // Resolve through the model service's canonicalizing gateway rather than
       // reaching into `LangiumDocuments` directly, so a divergent (symlink) URI
       // still finds the document the build keys by its real path — and so the
       // data-server never has to remember to canonicalize this lookup itself.
       const document = this.modelService.getDocument(uri.toString());
-      if (!document) {
+      if (!document || this.services.workspace.ModelLedger.isPlaceholder(document.parseResult.value)) {
          // No document — a shaped envelope rather than a throw, so the caller
-         // decides policy at its own layer; `root` is optional on the envelope
+         // decides policy at its own layer; `model` 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[]
-         };
+         // override `envelope`. The builder's unparsed placeholder is no
+         // document either: its root parses no text.
+         return TransferDocument.absent<TTransfer, TDiagnostic>(uri.toString());
       }
-      return this.encoder.toTransferDocument<AstNode>(document) as unknown as TransferDocument<TTransfer, TDiagnostic>;
+      const encoded = this.encoder.toTransferDocument(document);
+      return this.withServerState(encoded, fingerprint ?? this.computeDocumentFingerprint(document.parseResult.value, encoded));
    }
 
    /**
-    * Subscribe one listener at the configured {@link DataServerOptions.subscriptionPhase}.
-    * The listener dispatches subscription events for every matching URI. A
-    * single listener (rather than one per subscription) keeps the cost flat
-    * regardless of subscriber count.
+    * The transfer document a request answers with for `astDocument`, its model
+    * hashed and the text stamped on it by {@link withServerState}. Every
+    * document a request answers with goes through here, so none goes out
+    * without them.
     */
-   protected subscribeToDocumentBuilder(): void {
-      this.disposables.push(
-         this.services.workspace.DocumentBuilder.onDocumentPhase(this.options.subscriptionPhase, (document, cancelToken) =>
-            this.dispatchPhaseEvent(document, cancelToken)
-         )
-      );
+   protected encodeDocument(astDocument: AstDocument<AstNode, AstDiagnostic>): TransferDocument<TTransfer, TDiagnostic> {
+      const encoded = this.encoder.astDocumentToTransferDocument(astDocument);
+      return this.withServerState(encoded, this.computeDocumentFingerprint(astDocument.root, encoded));
+   }
+
+   /**
+    * `encoded` with `hash` on its model and the text the server holds for it:
+    * the store's while it holds the document, the build's otherwise. The text
+    * is read when the document is sent rather than kept with the build: a save
+    * changes `text.dirty` without a rebuild, and the store's text moves on before
+    * the build that follows it.
+    */
+   protected withServerState(
+      encoded: EncodedTransferDocument<TransferElement, TDiagnostic>,
+      hash: string
+   ): TransferDocument<TTransfer, TDiagnostic> {
+      const text = this.services.workspace.TextDocuments.textState(encoded.uri) ?? this.builtTextState(encoded.uri);
+      if (text && text.version > encoded.model.version) {
+         this.tracer.withUri(encoded.uri).debug(`Send a model behind its text: model v${encoded.model.version} / text v${text.version}`);
+      }
+      return {
+         uri: encoded.uri,
+         // The encoder returns the structural base; `TTransfer` is the adopter's
+         // declaration of the roots its languages produce, and nothing checks it.
+         model: { ...encoded.model, hash } as TransferModelSnapshot<TTransfer, TDiagnostic>,
+         ...(text ? { text } : {})
+      };
+   }
+
+   /**
+    * The text a build read for a document the store never held, which is
+    * clean: the store holds every text a client gave it.
+    */
+   protected builtTextState(uri: string): TextState | undefined {
+      const textDocument = this.modelService.getDocument(uri)?.textDocument;
+      return textDocument && { version: textDocument.version, hash: textHash(textDocument.getText()), dirty: false };
+   }
+
+   /**
+    * Follow every document at the configured
+    * {@link DataServerOptions.subscriptionPhase}, once per connection rather
+    * than once per watch, so the cost stays flat in the number of watches.
+    */
+   protected subscribeToModelUpdates(): void {
+      const phase = this.options.subscriptionPhase;
+      this.disposables.push(this.modelService.onModelUpdated(event => this.dispatchPhaseEvent(event), { phase }));
+      // One message per build rather than one per document.
+      this.disposables.push(this.modelService.onModelsBuilt(event => this.dispatchBuiltEvent(event.uris), { phase }));
+   }
+
+   /**
+    * 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 watcher gate 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.
+    */
+   protected dispatchBuiltEvent(built: readonly CanonicalUri[]): void {
+      const uris = built.map(uri => this.canonicalKey(uri)).filter(uri => !this.uriWatchRecords.get(uri)?.watchers.size);
+      if (uris.length === 0) {
+         return;
+      }
+      this.tracer.debug(`Emit onDocumentsBuilt: ${uris.length} unwatched document(s)`);
+      this.clientProxy.onDocumentsBuilt({ uris });
    }
 
    /**
-    * Subscribe to the universal save event on `HydraniumTextDocuments` so a
-    * single `onDocumentSaved` wire notification fires for ANY save of a
-    * subscribed URI — regardless of whether the save originated from the
-    * data-server's RPC `saveModelDocument`, the LSP head's text-editor save,
-    * or any other client writing through `notifyDidSaveTextDocument`.
+    * Follow every save so a single `onDocumentSaved` wire notification fires
+    * for ANY save of a subscribed URI — regardless of whether the save
+    * originated from the data-server's RPC `saveModelDocument`, the LSP head's
+    * text-editor save, or any other client.
     *
-    * Architectural symmetry with {@link subscribeToDocumentBuilder}: every
+    * Architectural symmetry with {@link subscribeToModelUpdates}: every
     * subscribed client sees every state change to documents they care about,
     * regardless of which client triggered it. Firing `onDocumentSaved` only
     * from the data-server's own RPC path is a bug, not an optimisation: an
@@ -1009,41 +1212,114 @@ export class DataServer<
     * clients, which never clear their dirty state.
     */
    protected subscribeToTextDocumentSaves(): void {
-      this.disposables.push(this.services.workspace.TextDocuments.onDidSave(event => this.dispatchSaveEvent(event)));
+      this.disposables.push(this.modelService.onModelSaved(event => this.dispatchSaveEvent(event)));
+   }
+
+   /** Relay each change of a document's dirty state; see {@link dispatchDirtyEvent}. */
+   protected subscribeToDirtyChanges(): void {
+      this.disposables.push(this.modelService.onDirtyChanged(event => this.dispatchDirtyEvent(event)));
+   }
+
+   /**
+    * Send a dirty flip to the connection, gated on the URI's watchers as
+    * {@link dispatchSaveEvent} is: the answer at any one moment travels on
+    * every document sent, so a client that watches nothing reads it there.
+    */
+   protected dispatchDirtyEvent(event: ModelDirtyChangedEvent): void {
+      const uri = this.canonicalKey(event.uri);
+      if (this.uriWatchRecords.get(uri)?.watchers.size) {
+         this.clientProxy.onDocumentDirtyChanged({ uri, text: event.text });
+      }
    }
 
    /**
-    * 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, so {@link dispatchPhaseEvent}
+    * broadcasts the build that follows even without a watcher. By default
+    * that build reverts the document to its disk content, discarding unsaved
+    * in-session edits, and the last close typically also
+    * removed the last watcher: without the broadcast, a consumer that only
+    * ever fetches via `getModelDocument` keeps showing the discarded state.
+    * The broadcast is de-duplicated against the fingerprint while a watcher
+    * holds one, so a close whose disk state equals the last emitted state
+    * stays silent; with no watcher there is no fingerprint, and every release
+    * build is sent. The first build after the release consumes the mark, and
+    * goes out as the release unless it is stamped past the version a client
+    * opened the document at again: a client's write or an integrity repair
+    * that rides it keeps its author.
+    *
+    * A release, not the close itself: a document whose last client lost its
+    * connection is released only once the release 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;
+   protected subscribeToModelReleases(): void {
       this.disposables.push(
-         textDocuments.onDidClose(event => {
-            if (!textDocuments.isOpenInAnyClient(event.document.uri)) {
-               this.pendingRevertBroadcasts.add(this.canonicalKey(event.document.uri));
-            }
+         this.modelService.onModelReleased(event => {
+            const uri = this.canonicalKey(event.uri);
+            const record = this.uriWatchRecords.get(uri) ?? { watchers: new Set<string>() };
+            record.releaseBroadcastPending = true;
+            this.uriWatchRecords.set(uri, record);
+            this.tracer.withUri(uri).debug('Release marked: the first build after it is broadcast, watched or not');
          })
       );
    }
 
-   /** 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
-      // symlink path S); the subscription map and `dispatchPhaseEvent` key by the
-      // CANONICAL identity R. Canonicalize before both the gate and the envelope so
-      // a save of a symlinked file isn't silently dropped (and the envelope resolves
-      // the R-keyed document rather than missing into an empty one).
+   /**
+    * 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 watcher gate 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 release broadcast (see
+    * {@link subscribeToModelReleases}), where the same judgement was already made
+    * in the other direction: a transition that matters enough is delivered
+    * without a subscription.
+    *
+    * A deletion is announced before the build that follows it, so this goes
+    * out ahead of the `'rebuilt'` events for the dependents whose references
+    * the deletion just broke.
+    *
+    * The URI's fingerprint and release mark are dropped: they describe a
+    * document that no longer exists. A kept fingerprint is adopted as the
+    * baseline and suppresses the first emit after the file returns with its
+    * previous content.
+    *
+    * The watchers SURVIVE: a recreated file resumes delivering to them with no
+    * re-subscription, and a client that answers the deletion by closing
+    * releases the watch through `closeModelDocument` anyway.
+    */
+   protected dispatchDeleteEvent(event: ModelDeletedEvent): void {
+      const uri = this.canonicalKey(event.uri);
+      const record = this.uriWatchRecords.get(uri);
+      if (record) {
+         record.fingerprint = undefined;
+         record.fingerprintVersion = undefined;
+         record.releaseBroadcastPending = undefined;
+         record.sentVersion = undefined;
+         this.pruneUriWatchRecord(uri);
+      }
+      this.clientProxy.onDocumentDeleted({ uri });
+   }
+
+   /** Fan out a save event for the document's URI, gated on the URI's watchers. */
+   protected dispatchSaveEvent(event: AstDocumentSavedEvent<AstNode>): void {
       const uri = this.canonicalKey(event.document.uri);
-      if (!this.subscriptions.has(uri)) {
+      if (!this.uriWatchRecords.get(uri)?.watchers.size) {
          return;
       }
-      const response = this.envelope(UriUtils.toUri(uri));
+      const response = this.envelope(UriUtils.toUri(event.document.uri));
       const wireEvent: TransferDocumentSavedEvent<TTransfer, TDiagnostic> = {
          document: response,
-         sourceClientId: event.clientId
+         sourceClientId: event.sourceClientId
       };
       this.clientProxy.onDocumentSaved(wireEvent);
    }
@@ -1057,116 +1333,114 @@ export class DataServer<
     * out to multiple local subscribers with an `Emitter<T>` — the
     * framework deliberately does NOT promise multi-listener semantics.
     *
-    * The dispatch is guarded by two filters:
-    *   1. **Subscription map**: events for URIs no subscriber registered for
-    *      are NOT sent over the wire (bandwidth scales with subscribed URIs,
-    *      not phase events).
-    *   2. **Emission fingerprint**: events for rebuilds that produce no
-    *      observable change since the last emit are suppressed. See
-    *      {@link lastEmittedFingerprint} for the rationale.
+    * An event for a URI no client watches is NOT sent over the wire, so
+    * bandwidth scales with watched URIs rather than with phase events; a
+    * pending release mark is the exception (see
+    * {@link subscribeToModelReleases}).
+    *
+    * An event for a rebuild with no observable change since the last emit is
+    * suppressed against the URI's fingerprint and the version it was taken at;
+    * a new version with the same fingerprint goes out with the same
+    * `model.hash`, so a watcher still learns the version. Such rebuilds are routine: a
+    * second client attaching to an open document makes
+    * `HydraniumTextDocuments.refreshContent` fire `onDidChangeContent` purely
+    * to re-trigger the build, and Langium rebuilds a document when a
+    * dependency changes even if its diagnostics come out the same. Sent at a
+    * version this head has not sent, they reach watchers as `'changed'`, and a
+    * watcher that reads `'changed'` as another client's write and resets its
+    * root to the server view loses the user's edits. The first {@link watchModelDocument} baselines the
+    * fingerprint, so the first event after a watch is de-duplicated against
+    * the state the watcher just fetched; it goes with the last watcher, so the
+    * next first watch re-baselines rather than adopting a stale digest. A
+    * digest keeps its memory constant in document size; see
+    * {@link computeDocumentFingerprint} for the inputs.
     */
-   protected dispatchPhaseEvent(document: LangiumDocument, cancelToken: CancellationToken): void {
-      if (cancelToken.isCancellationRequested) {
-         // Build preempted by a concurrent write lock (or other cancel source) —
-         // the subscription event is stale by the time it would fire. Skip
-         // emission so RPC subscribers don't surface intermediate states.
-         // A pending revert mark is deliberately NOT consumed here: the
-         // follow-up build re-fires this phase and broadcasts then.
+   protected dispatchPhaseEvent(event: ModelUpdatedEvent<AstNode>): void {
+      const uri = this.canonicalKey(event.document.uri);
+      const record = this.uriWatchRecords.get(uri);
+      const afterRelease = record?.releaseBroadcastPending === true;
+      if (!record || (record.watchers.size === 0 && !afterRelease)) {
          return;
       }
-      const uri = document.uri.toString();
-      // Consume the last-close mark even when subscriptions exist — the
-      // regular dispatch below serves those watchers, and the mark's author
-      // attribution is more precise than the post-close `UNKNOWN_CLIENT_ID`
-      // the author lookup would yield.
-      const revertedOnClose = this.pendingRevertBroadcasts.delete(uri);
-      if (!this.subscriptions.has(uri) && !revertedOnClose) {
+      if (afterRelease) {
+         // Consumed even when watchers exist — the regular dispatch below
+         // serves them, and the mark's attribution is more precise than the
+         // post-close unknown client the manager's attribution would yield.
+         // With no watcher the record goes now, so the fingerprint written
+         // below lands on a detached record and the next first watch
+         // re-baselines instead of adopting it.
+         record.releaseBroadcastPending = undefined;
+         this.pruneUriWatchRecord(uri);
+      }
+      // The encoder reads the built document, which the event's holds for this
+      // synchronous run.
+      const document = this.modelService.getDocument(event.document.uri);
+      if (!document) {
          return;
       }
-      const fingerprint = this.computeDocumentFingerprint(document);
-      if (this.lastEmittedFingerprint.get(uri) === fingerprint) {
+      const fingerprint = this.computeDocumentFingerprint(document.parseResult.value, this.encoder.toTransferDocument(document));
+      const stamped = this.services.workspace.ModelLedger.versionOf(document.parseResult.value);
+      if (record.fingerprint === fingerprint && record.fingerprintVersion === stamped) {
          // A rebuild that produced no observable change since the last emit —
          // suppressed so RPC subscribers don't see a no-op broadcast. Logged at
          // debug so a *needed* re-broadcast wrongly suppressed by this dedup
          // (the failure mode the fingerprint strategy must avoid) is visible.
-         this.tracer.withUri(uri).debug(`Suppress onDocumentUpdated v${document.textDocument.version}: fingerprint unchanged`);
+         this.tracer.withUri(uri).debug(`Suppress onDocumentUpdated v${stamped}: fingerprint and version unchanged`);
          return;
       }
-      this.lastEmittedFingerprint.set(uri, fingerprint);
-      const event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic> = {
-         document: this.envelope(document.uri),
-         sourceClientId: revertedOnClose ? REVERT_ON_CLOSE_CLIENT_ID : this.resolveSourceClientId(document),
-         reason: this.resolveUpdateReason(document.uri)
+      record.fingerprint = fingerprint;
+      record.fingerprintVersion = stamped;
+      // The event's attribution, so this head names the same client as the
+      // in-process heads do for one build, except for a version this head
+      // already sent; see `DataServerUriWatchRecord.sentVersion`.
+      const version = this.modelService.isOpen(event.document.uri) ? document.textDocument.version : undefined;
+      const { reason, sourceClientId } =
+         version !== undefined && record.sentVersion === version
+            ? { reason: 'rebuilt' as const, sourceClientId: UNKNOWN_CLIENT_ID }
+            : event;
+      record.sentVersion = version;
+      // The stamp, not the live version: a write after the build's parse moves
+      // only the latter. At the opened version too, which a reopen with the
+      // released text keeps.
+      const openedVersion = afterRelease ? this.modelService.openedVersion(event.document.uri) : undefined;
+      const releaseBuild = afterRelease && (openedVersion === undefined || stamped <= openedVersion);
+      const wireEvent: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic> = {
+         document: this.envelope(document.uri, fingerprint),
+         sourceClientId: releaseBuild ? DOCUMENT_RELEASE_CLIENT_ID : sourceClientId,
+         reason
       };
+      const mark = afterRelease ? `, release mark: opened v${openedVersion ?? '-'}, attributed ${sourceClientId}` : '';
       this.tracer
          .withUri(uri)
-         .debug(`Emit onDocumentUpdated v${event.document.version} (reason=${event.reason}, sourceClientId=${event.sourceClientId})`);
-      this.clientProxy.onDocumentUpdated(event);
+         .debug(`Emit onDocumentUpdated v${stamped} (reason=${wireEvent.reason}, sourceClientId=${wireEvent.sourceClientId}${mark})`);
+      this.clientProxy.onDocumentUpdated(wireEvent);
    }
 
    /**
-    * Fingerprint of the document's observable state, used to de-dup
-    * `onDocumentUpdated` emissions. The {@link FingerprintStrategy} option
-    * selects what is hashed (default `'transfer-document'` — see the type), and
-    * {@link additionalFingerprintInputs} folds in any extra adopter signal.
+    * Fingerprint of the snapshot `root` and its encoding `encoded`, used to
+    * de-dup `onDocumentUpdated` emissions and sent as every document's
+    * `model.hash`, so it must not depend on the version or on live state. The
+    * {@link FingerprintStrategy} option selects what is hashed (default
+    * `'transfer-document'` — see the type).
     *
-    * The default `'transfer-document'` strategy goes through the encoder's
-    * {@link TransferEncoder.toTransferDocument}, which is cached per build —
-    * so within one phase event the fingerprint and the subsequently-emitted
-    * `envelope` share a single encode walk.
+    * {@link TransferEncoder.toTransferDocument} is cached per build, so within
+    * one phase event the fingerprint and the subsequently-emitted `envelope`
+    * share a single encode walk.
     *
     * Wrapped in {@link Tracer.time} against {@link FINGERPRINT_LOG_AFTER_MS}.
     */
-   protected computeDocumentFingerprint(document: LangiumDocument): string {
-      return this.tracer.withUri(document.uri.toString()).time(
-         'Compute fingerprint',
-         () => {
-            const base =
+   protected computeDocumentFingerprint(root: AstNode, encoded: EncodedTransferDocument<TransferElement, TDiagnostic>): string {
+      return this.tracer
+         .withUri(encoded.uri)
+         .time(
+            'Compute fingerprint',
+            () =>
                this.options.fingerprintStrategy === 'text-diagnostics'
-                  ? textDiagnosticsFingerprint(document)
-                  : transferDocumentFingerprint(this.encoder.toTransferDocument(document));
-            const extra = this.additionalFingerprintInputs(document);
-            return extra.length === 0 ? base : fingerprintHash([base, FINGERPRINT_SEPARATOR, ...extra.map(value => JSON.stringify(value))]);
-         },
-         'debug',
-         { logAfterMs: FINGERPRINT_LOG_AFTER_MS }
-      );
-   }
-
-   /**
-    * Extra inputs folded into {@link computeDocumentFingerprint} alongside the
-    * chosen {@link FingerprintStrategy}. Default: none. Override to contribute a
-    * signal that lives outside the document's text / root / diagnostics — each
-    * entry need only be stable across equivalent emissions and
-    * JSON-serialisable.
-    */
-   protected additionalFingerprintInputs(_document: LangiumDocument): readonly unknown[] {
-      return [];
-   }
-
-   /**
-    * 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.
-    */
-   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';
+                  ? textDiagnosticsFingerprint(this.services.workspace.ModelLedger.textOf(root), encoded.model)
+                  : transferDocumentFingerprint(encoded.model),
+            'debug',
+            { logAfterMs: FINGERPRINT_LOG_AFTER_MS }
+         );
    }
 
    /**
@@ -1212,20 +1486,6 @@ export class DataServer<
       }
    }
 
-   /**
-    * Resolve the wire-level `sourceClientId` for `document`'s events — the client
-    * that authored its current version, from the version-author history on
-    * `HydraniumTextDocuments`. The protocol-level counterpart of the internal
-    * `AstDocumentManager.getAuthor`: a framework-internal rebuild has no author,
-    * so this surfaces the {@link UNKNOWN_CLIENT_ID} presentation default. Adopters
-    * that rebuild through non-text-document channels override to derive a
-    * source id of their own.
-    */
-   protected resolveSourceClientId(document: LangiumDocument): string {
-      const author = this.services.workspace.TextDocuments.getAuthor(document.textDocument.uri, document.textDocument.version);
-      return author ?? UNKNOWN_CLIENT_ID;
-   }
-
    // --- Diagnostics (DataServerDiagnosticsProtocol) ---------------------------
    // Computed in THIS process: the data-server child holds the model store, so
    // these snapshots reflect the heap that actually carries the workspace
@@ -1287,11 +1547,11 @@ export class DataServer<
    /** Resolve a partial options object into a fully-defaulted form. */
    protected resolveOptions(partial: DataServerOptions): ResolvedDataServerOptions {
       const additionalMethods = partial.additionalMethods ?? [];
-      const builtIn = [...DATA_SERVER_PROTOCOL_METHODS, ...DATA_SERVER_DIAGNOSTICS_METHODS] as readonly string[];
+      const builtIn: readonly string[] = [...DATA_SERVER_PROTOCOL_METHODS, ...DATA_SERVER_DIAGNOSTICS_METHODS];
       const overlap = additionalMethods.filter(name => builtIn.includes(name));
       if (overlap.length > 0) {
          throw new Error(
-            `DataServer.additionalMethods overlaps with built-in data-server methods: ${overlap.join(', ')}. ` +
+            `DataServerOptions.additionalMethods overlaps with built-in data-server methods: ${overlap.join(', ')}. ` +
                'Adopter protocols must not redeclare framework method names; rename the adopter method or remove it from additionalMethods.'
          );
       }
@@ -1301,7 +1561,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
       };
    }
 }