@hydranium/data-server 1.0.0-next.18 → 1.0.0-next.181

package/lib/data-server.js

@@ -6,11 +6,43 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { createRpcProxy, DisposableCollection, isDocumentSource, isElementSource, isSyntheticSource, ReferenceSource } from '@hydranium/protocol';
+import { createRpcProxy, defineMessage, DisposableCollection, HYDRANIUM_ERROR_CODES, isDocumentSource, isElementSource, isSyntheticSource, messageData, messageError, ReferenceSource, SessionClosedError, TIMED_OUT, TransferDocument, UNKNOWN_CLIENT_ID, asSnapshotVersion, textHash } from '@hydranium/protocol';
 import { DATA_SERVER_DIAGNOSTICS_METHODS, DATA_SERVER_PROTOCOL_METHODS, DATA_SERVER_WIRE_PREFIX } from '@hydranium/protocol/data';
-import { REVERT_ON_CLOSE_CLIENT_ID, UNKNOWN_CLIENT_ID } from '@hydranium/core';
+import { REVERT_ON_CLOSE_CLIENT_ID } from '@hydranium/core';
 import { defaultDataServerDiagnostics } from './default-diagnostics.js';
+/**
+ * Raised when a profiling command arrives with no capture running.
+ *
+ * A `ResponseError` rather than a plain `Error` so the identity survives to the
+ * response boundary, which is where the message is rendered. An unwrapped throw
+ * reaches the client as a generic internal error instead: no code for a caller
+ * to switch on, and nothing for the boundary to render from.
+ */
+export const NO_ACTIVE_PROFILE = defineMessage('hydranium/data-server/no-active-profile', 'No profiling capture is active; call startProfiling first.');
+/**
+ * The JSON-RPC code, unrelated to the catalogue code above: this one is numeric,
+ * survives reconstruction and is what a caller switches on.
+ */
+export const NO_ACTIVE_PROFILE_CODE = HYDRANIUM_ERROR_CODES.noActiveProfile;
+export const noActiveProfileError = () => 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) => new ResponseError(REFERENCE_SETTLE_TIMEOUT_CODE, REFERENCE_SETTLE_TIMEOUT.format(), {
+    elapsedMs,
+    ...messageData(REFERENCE_SETTLE_TIMEOUT)
+});
 import { DocumentState, UriUtils } from '@hydranium/langium';
+import { ResponseError } from 'vscode-jsonrpc';
 /**
  * Domain separator between text and diagnostics inputs of
  * {@link DataServer.computeDocumentFingerprint}'s hash. A single NUL byte is
@@ -19,47 +51,21 @@ import { DocumentState, UriUtils } from '@hydranium/langium';
  */
 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) {
-    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;
+const resumableByModelService = new WeakMap();
 /** Hash a document's raw text + diagnostics — the `'text-diagnostics'` strategy. */
 function textDiagnosticsFingerprint(document) {
-    return fingerprintHash([document.textDocument.getText(), FINGERPRINT_SEPARATOR, JSON.stringify(document.diagnostics ?? [])]);
+    return textHash([document.textDocument.getText(), FINGERPRINT_SEPARATOR, JSON.stringify(document.diagnostics ?? [])]);
 }
 /** Hash an encoded transfer document's root + diagnostics — the `'transfer-document'` strategy. */
 function transferDocumentFingerprint(transferDocument) {
     // 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)
-    ]);
+    return textHash([JSON.stringify(transferDocument.root ?? null), FINGERPRINT_SEPARATOR, JSON.stringify(transferDocument.diagnostics)]);
 }
 /**
  * `logAfterMs` threshold passed to {@link Tracer.time} around
@@ -94,9 +100,11 @@ const FINGERPRINT_LOG_AFTER_MS = 5;
  * any names supplied via {@link DataServerOptions.additionalMethods}) and
  * builds the {@link DataClientProtocol} notification proxy on the same
  * connection in one {@link createRpcProxy} call (binding `this` as its
- * `localTarget`) under the configured namespace, and subscribes one
- * `DocumentBuilder.onDocumentPhase` listener per configured phase that
- * dispatches subscription events via `clientProxy.onDocumentUpdated`.
+ * `localTarget`) under the configured namespace, and subscribes two listeners
+ * at the configured phase: a `DocumentBuilder.onDocumentPhase` one dispatching
+ * per-document `clientProxy.onDocumentUpdated` for watched URIs, and a
+ * `DocumentBuilder.onBuildPhase` one dispatching a single
+ * `clientProxy.onDocumentsBuilt` naming the batch's unwatched documents.
  *
  * The data-server requires the full {@link ServerSharedServices}
  * shape — `HydraniumTextDocuments` for client-attributed updates,
@@ -121,85 +129,25 @@ export class DataServer {
      * extending rather than restate a value the framework may change.
      */
     static DEFAULT_OPTIONS = {
-        subscriptionPhase: DocumentState.Validated
+        subscriptionPhase: DocumentState.Validated,
+        referenceSettleTimeoutMs: 60_000
     };
     options;
-    /** Subscription bookkeeping: URI → set of clientIds that subscribed for that URI. */
-    subscriptions = new Map();
+    /** This connection's {@link DataServerUriWatchRecord} per canonical URI; see there for when a record lives. */
+    uriWatchRecords = new Map();
     /**
-     * Open-document bookkeeping: URI → set of clientIds that opened it over THIS
-     * connection.
+     * The client sessions this connection registered, by client id. A document
+     * request carrying one of these ids acts as that session; one carrying any
+     * other id fails.
      *
-     * Kept because the document store releases a client's hold only from an
-     * explicit close, and a client that dies without closing would otherwise keep
-     * the document open forever — resident, and with its last-close revert
-     * suppressed. The store has no notion of which connection a clientId reached
-     * it over, so the connection-scoped set has to live here; teaching it a client
-     * identity is the more robust and much larger alternative.
+     * Entries stay after {@link dispose} has ended their sessions, so a request
+     * still running from before the connection closed reaches the ended handle
+     * and fails with the session's own error.
      */
-    openedDocuments = new Map();
+    clientSessions = new Map();
     /** Typed client proxy — sends `data-server/on*` notifications back over the same wire. */
     clientProxy;
     disposables = new DisposableCollection();
-    /**
-     * Snapshot of the most recent `DocumentBuilder.onUpdate` event. Drives
-     * `reason` discrimination on outbound `onDocumentUpdated` notifications:
-     * a URI in the `changed` list emits `'changed'`, in `deleted` emits
-     * `'deleted'`, otherwise `'rebuilt'` (cascade rebuild from a dependent
-     * URI's change). The same mechanism `AstDocumentManager.onUpdate` uses on
-     * the LSP side, so reason fidelity stays consistent between heads.
-     */
-    lastBuildUpdate;
-    /**
-     * 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.
-     */
-    lastEmittedFingerprint = new Map();
-    /**
-     * 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.
-     */
-    pendingRevertBroadcasts = new Set();
     tracer;
     /** The in-flight interactive profile capture, held between {@link startProfiling} and {@link stopProfiling}. */
     activeProfile;
@@ -211,11 +159,8 @@ export class DataServer {
     encoder;
     /**
      * 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.
      */
     modelService;
     constructor(connection, services, options = {}) {
@@ -224,8 +169,7 @@ export class DataServer {
         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('DataServer requires `services.model.TransferEncoder` and `services.model.ModelService` to be bound. ' +
@@ -248,35 +192,42 @@ export class DataServer {
             methodNamespace: this.options.methodNamespace,
             localTarget: this,
             localMethods: registeredMethods,
-            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.disposables.push(this.services.workspace.DocumentBuilder.onUpdate((_changed, deleted) => this.dispatchDeleteEvents(deleted)));
         this.subscribeToDocumentBuilder();
         this.subscribeToTextDocumentSaves();
+        this.subscribeToDirtyChanges();
         this.subscribeToTextDocumentCloses();
         this.subscribeToProjectManager();
         // Self-register teardown so an adopter that keeps no reference to the
         // server still releases per-connection state, with no lifecycle hook of
-        // its own. See `dispose`.
-        this.disposables.push(connection.onClose(() => this.dispose()));
+        // its own. The client did not close anything itself, so its sessions end
+        // as lost and each document it was the last to have open waits out the
+        // store's revert grace. See `dispose`.
+        this.disposables.push(connection.onClose(() => this.dispose('lost')));
     }
     /**
      * 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.
-     *
-     * 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.
-     */
-    dispose() {
+     * 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. Runs by itself when the
+     * connection closes, so adopters who don't hold a reference still get
+     * per-connection cleanup; adopters that DO hold a reference may call
+     * `dispose()` directly for early teardown. The sessions end with `cause`:
+     * `'closed'` reverts every document whose last open they close at once,
+     * and `'lost'`, the connection's own close, lets each wait out the revert
+     * grace.
+     */
+    dispose(cause = 'closed') {
         this.disposed = true;
         // Release an in-flight interactive capture so the process-wide inspector
         // singleton is not left active after the connection closes.
@@ -285,97 +236,165 @@ export class DataServer {
             this.activeProfile = undefined;
             void capture.stop({}).catch(() => undefined);
         }
-        // AFTER `disposables.dispose()`, deliberately: closing a document fires
-        // `onDidClose`, and this server's own close listener would otherwise mark a
-        // revert broadcast for a connection that is already gone.
+        // AFTER `disposables.dispose()`, deliberately: ending a session releases
+        // each document it was the last to hold, and this server's own
+        // `onDidCloseLastOpen` listener would otherwise mark a revert broadcast
+        // for a connection that is already gone.
         this.disposables.dispose();
-        this.closeOpenDocuments();
-        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) {
-        // 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();
-            this.openedDocuments.set(args.uri, holders);
-        }
-        holders.add(args.clientId);
-        const document = await this.getModelDocument({ uri: args.uri });
-        // Project the authoritative client-facing version onto the open snapshot.
-        // `getModelDocument` encodes the freshly-built AST snapshot, whose version
-        // is the `LangiumDocument`'s own `textDocument.version`. That lags the
-        // multi-client synced version whenever the open seeded the synced document
-        // with a caller-supplied version id — and the synced version is what
-        // `ModelService.update`'s optimistic-concurrency gate compares
-        // `baseVersion` against, so reporting the snapshot's would make the
-        // caller's first tagged write self-conflict. A genuine concurrent edit
-        // still trips the gate and is reconciled by the caller's replay rather
-        // than predicted here.
-        return { ...document, version: this.services.workspace.TextDocuments.version(args.uri) };
-    }
-    async closeModelDocument(args) {
-        // 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);
+    // 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) {
+        // After teardown nothing would ever end a session registered now, and its
+        // id would stay taken for the life of the process.
+        if (this.disposed) {
+            throw new SessionClosedError(args.clientId);
+        }
+        const resumable = this.resumableSessions();
+        const previous = resumable.get(args.clientId);
+        if (previous && args.resumeToken !== undefined && previous.token === args.resumeToken) {
+            previous.end();
+        }
+        const session = this.modelService.createSession(args.label, args.clientId);
+        this.clientSessions.set(args.clientId, session);
+        if (args.resumeToken !== undefined) {
+            // Taken over by a client registering again after its connection
+            // dropped, so the old session ends as lost: the documents it was the
+            // last to have open wait out the grace, and the new session's opens
+            // find their unsaved text.
+            resumable.set(args.clientId, { token: args.resumeToken, end: () => this.endSession(args.clientId, session, 'lost') });
+        }
     }
     /**
-     * Drop the recorded hold for `(uri, clientId)` so {@link dispose} does not
-     * close it a second time. Idempotent.
+     * End a session this connection registered. The ended handle stays in
+     * {@link clientSessions}, as it does after {@link dispose}, so a request for
+     * the id still arriving fails with the ended session's own error.
      */
-    forgetOpenDocument(uri, clientId) {
-        const holders = this.openedDocuments.get(uri);
-        if (!holders) {
-            return;
+    async closeSession(args) {
+        const session = this.clientSessions.get(args.clientId);
+        if (session) {
+            this.endSession(args.clientId, session);
         }
-        holders.delete(clientId);
-        if (holders.size === 0) {
-            this.openedDocuments.delete(uri);
+    }
+    /** End `session`, registered here under `clientId`, with `cause`, and drop its watches on this connection. */
+    endSession(clientId, session, cause = 'closed') {
+        for (const [uri, record] of this.uriWatchRecords) {
+            if (record.watchers.delete(clientId)) {
+                this.pruneUriWatchRecord(uri);
+            }
         }
+        session.dispose(cause);
     }
     /**
-     * Close every document still open over this connection, for the clients that
-     * opened it here.
+     * The resumable sessions of this services tree, by client id, across all of
+     * its data connections: a client resumes on another connection than the one
+     * that registered it. An entry leaves when its session ends, by any path, so
+     * it keeps no ended connection alive.
      *
-     * 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.
+     * A takeover by resume token ends the old session even when its connection
+     * is still alive, so two clients that shared an id and its token would end
+     * each other's sessions. And the token is a guard against colliding with a
+     * session the server has not yet seen end, not a secret: the wire carries no
+     * authentication, and a peer that learns the token can end the session.
+     */
+    resumableSessions() {
+        let sessions = resumableByModelService.get(this.modelService);
+        if (!sessions) {
+            const created = new Map();
+            // Subscribed once per services tree, and never disposed: it lives as
+            // long as the text store it listens to.
+            this.services.workspace.TextDocuments.onDidCloseSession(event => created.delete(event.clientId));
+            resumableByModelService.set(this.modelService, created);
+            sessions = created;
+        }
+        return sessions;
+    }
+    async createModelDocument(args) {
+        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) {
+        const astDocuments = await this.requireSession(args.clientId).updateAll({
+            updates: args.updates.map(update => this.toSessionWrite(update))
+        });
+        return astDocuments.map(astDocument => this.encodeDocument(astDocument));
+    }
+    /**
+     * 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.
+     */
+    toSessionWrite(request) {
+        return { uri: request.uri, model: request.model, basedOn: request.basedOn };
+    }
+    /**
+     * The session this connection registered under `clientId`, which every
+     * document request acts as. An id that is not one fails with the
+     * closed-session code: opening or writing under it would leave an open that
+     * no session end ever closes.
+     */
+    requireSession(clientId) {
+        const session = this.clientSessions.get(clientId);
+        if (!session) {
+            throw new SessionClosedError(clientId, 'The client session was never registered on this connection.');
+        }
+        return session;
+    }
+    async openModelDocument(args) {
+        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));
+    }
+    /**
+     * The snapshot a session's open or create answers with. When the read
+     * fails, `rollback` undoes the open this call made before the failure is
+     * rethrown: the caller sees no open, so nothing on its side would ever close
+     * it.
      *
-     * Runs from {@link dispose}, which is synchronous, so each close is fired and
-     * its failure swallowed — a teardown must not reject, and a URI whose close
-     * fails is no worse off than it was before this drain existed.
+     * Versioned with the store's shared version rather than the snapshot's own:
+     * the built document's `textDocument.version` lags the store's whenever the
+     * store assigned the version, and the store's is what a write's `basedOn` is
+     * compared against, so reporting the snapshot's would make the caller's
+     * first based-on write conflict with itself.
      */
-    closeOpenDocuments() {
-        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);
-            }
+    async openedSnapshot(uri, rollback) {
+        let document;
+        try {
+            document = await this.getModelDocument({ uri });
         }
+        catch (error) {
+            // The open's failure is the one the caller needs, not the cleanup's.
+            await rollback?.().catch(() => undefined);
+            throw error;
+        }
+        // Stamped again with the version, in one step: a write landing after the
+        // read would otherwise pair its version with the read's text hash.
+        return this.withServerState({ ...document, version: asSnapshotVersion(this.services.workspace.TextDocuments.version(uri)) });
+    }
+    async closeModelDocument(args) {
+        // 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) {
         // Smart dispatch: a warm document (already in LangiumDocuments) is
@@ -389,72 +408,88 @@ 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);
+        try {
+            return this.encodeDocument(await this.modelService.ensureDocumentState(args.uri, state));
+        }
+        catch (error) {
+            // The protocol answers a read of a URI with no document with an
+            // envelope that has no root.
+            if (this.isMissingDocument(error, args.uri)) {
+                return this.envelope(UriUtils.toUri(args.uri));
+            }
+            throw error;
+        }
     }
     async updateModelDocument(args) {
-        const astDocument = await this.modelService.update(args);
-        return this.encoder.astDocumentToTransferDocument(astDocument);
+        const astDocument = await this.requireSession(args.clientId).update(this.toSessionWrite(args));
+        return this.encodeDocument(astDocument);
     }
     async saveModelDocument(args) {
-        const astDocument = await this.modelService.save(args);
-        return this.encoder.astDocumentToTransferDocument(astDocument);
+        const astDocument = await this.requireSession(args.clientId).save(this.toSessionWrite(args));
+        return this.encodeDocument(astDocument);
     }
     /**
      * Record a watch for `(uri, clientId)`. Subsequent phase events on `uri`
      * 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) {
         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 record = this.uriWatchRecords.get(uri) ?? { watchers: new Set() };
+        this.uriWatchRecords.set(uri, record);
+        record.watchers.add(args.clientId);
+        if (record.fingerprint === undefined) {
             const document = this.services.workspace.LangiumDocuments.getDocument(UriUtils.toUri(uri));
             if (document) {
-                this.lastEmittedFingerprint.set(uri, this.computeDocumentFingerprint(document));
+                record.fingerprint = this.computeDocumentFingerprint(document);
             }
         }
     }
     /**
      * 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) {
         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.revertPending} mark either. Every path
+     * that removes a watcher or consumes a mark ends here.
+     */
+    pruneUriWatchRecord(uri) {
+        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.revertPending) {
+            record.fingerprint = 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`)
@@ -498,20 +533,50 @@ export class DataServer {
     // Resolve the language's reference services from each request's source
     // (see resolveReferenceServices) and delegate.
     // ============================================================
-    async findReferenceCandidates(ctx) {
-        // 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}.
+     */
+    async awaitReferencesLinked(source) {
+        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) {
+        await this.awaitReferencesLinked(ctx.source);
         return this.resolveReferenceServices(ctx.source).CandidateProvider.find(ctx);
     }
     async resolveReference(ref) {
+        await this.awaitReferencesLinked(ref.source);
         const resolved = this.resolveReferenceServices(ref.source).CandidateProvider.resolveCandidate(ref);
         if (!resolved) {
             return undefined;
@@ -526,15 +591,32 @@ 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) : 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) {
+                if (this.isMissingDocument(error, args.uri)) {
+                    return args.proposal;
+                }
+                throw error;
+            }
         }
         const project = this.services.workspace.ProjectManager.getProject(uri);
         if (!project) {
@@ -569,6 +651,9 @@ export class DataServer {
     /**
      * Pick the language that owns a reference source, in order:
      *
+     * 0. A {@link isSyntheticSource} naming its own `language` routes there.
+     *    First because every step below infers, and an inference must not
+     *    override a caller that has said which grammar it means.
      * 1. A URI-bearing source ({@link isDocumentSource}/{@link isSyntheticSource})
      *    whose URI resolves to a registered language routes by URI.
      * 2. A single-language workspace always routes to that one language — so
@@ -587,6 +672,15 @@ export class DataServer {
      */
     resolveReferenceLanguage(source) {
         const registry = this.services.ServiceRegistry;
+        if (isSyntheticSource(source) && source.language !== undefined) {
+            const declared = registry.getServicesById(source.language);
+            if (declared) {
+                return declared;
+            }
+            // Falling through on an UNREGISTERED id rather than failing: the id
+            // crosses the wire, so a client built against a head with one more
+            // grammar would otherwise lose queries the steps below can answer.
+        }
         // `getServicesFor` (non-throwing, one ladder walk) gates the URI lookup:
         // an extensionless / unregistered URI falls through to the steps below
         // rather than throwing "no services for the extension ''".
@@ -675,6 +769,17 @@ 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.
+     */
+    isMissingDocument(error, uri) {
+        return error instanceof ResponseError && 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
@@ -698,14 +803,34 @@ export class DataServer {
             // decides policy at its own layer; `root` is optional on the envelope
             // so the compiler forces that decision. Adopters preferring to throw
             // override `envelope`.
-            return {
-                uri: uri.toString(),
-                version: 0,
-                root: undefined,
-                diagnostics: []
-            };
+            return TransferDocument.absent(uri.toString());
         }
-        return this.encoder.toTransferDocument(document);
+        return this.withServerState(this.encoder.toTransferDocument(document));
+    }
+    /**
+     * The transfer document a request answers with for `astDocument`, the
+     * store's current `dirty` and `textHash` stamped on it by
+     * {@link withServerState}. Every document a request answers with goes
+     * through here, so none goes out without the stamp.
+     */
+    encodeDocument(astDocument) {
+        return this.withServerState(this.encoder.astDocumentToTransferDocument(astDocument));
+    }
+    /**
+     * `document` with the store's current {@link TransferDocument.dirty} and
+     * the {@link TransferDocument.textHash} of the text the server holds for
+     * it: the store's text while a client has it open, the build's otherwise.
+     * Both are read when the document is sent rather than kept with the build:
+     * a save changes `dirty` without a rebuild, and the store's text moves on
+     * before the build that follows it.
+     */
+    withServerState(document) {
+        const text = (this.services.workspace.TextDocuments.get(document.uri) ?? this.modelService.getDocument(document.uri)?.textDocument)?.getText();
+        return {
+            ...document,
+            dirty: this.services.workspace.TextDocuments.isDirty(document.uri),
+            ...(text === undefined ? {} : { textHash: textHash(text) })
+        };
     }
     /**
      * Subscribe one listener at the configured {@link DataServerOptions.subscriptionPhase}.
@@ -715,6 +840,56 @@ export class DataServer {
      */
     subscribeToDocumentBuilder() {
         this.disposables.push(this.services.workspace.DocumentBuilder.onDocumentPhase(this.options.subscriptionPhase, (document, cancelToken) => this.dispatchPhaseEvent(document, cancelToken)));
+        // The BUILD-phase hook, not the per-document one: this notification is one
+        // message per build rather than one per document, and Langium hands the
+        // whole batch over here. It also does not fire for a cancelled build,
+        // which is what the per-document dispatch has to check by hand.
+        this.disposables.push(this.services.workspace.DocumentBuilder.onBuildPhase(this.options.subscriptionPhase, built => this.dispatchBuiltEvent(built)));
+    }
+    /**
+     * Report the documents that reached {@link DataServerOptions.subscriptionPhase}
+     * and that NOBODY on this
+     * connection is watching — the ones a client was not told about through
+     * {@link dispatchPhaseEvent}, which is gated per URI.
+     *
+     * **The gap this closes is the one no other source can observe.** A document
+     * the client watches, it hears about already. A file changed on disk, the
+     * host's own filesystem watcher reports — and on a browser host, where the
+     * workspace lives behind this head, an external change cannot happen at all.
+     * What is left, and what nothing outside the server can see, is a document
+     * rebuilt because something it DEPENDS ON changed: its file never changed, so
+     * a filesystem watcher is silent by construction, and it has no subscriber, so
+     * the update channel is silent by design. A consumer displaying data derived
+     * from that document — a tree label, a decorator — otherwise goes stale with
+     * no signal from any source, and repairs itself the moment someone opens the
+     * file to investigate, which is what makes it expensive to diagnose later.
+     *
+     * Payload-free on purpose: URIs only, so a client re-reads what it displays
+     * rather than being handed transfer documents it did not ask for. That is the
+     * property the 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.
+     *
+     * The URI is canonicalised for the same reason {@link uriWatchRecords} is keyed
+     * that way, and is untested for the same reason as its twin in
+     * {@link dispatchDeleteEvents}: the builder reports URIs out of its own
+     * store, so a non-canonical one cannot be produced without a fixture
+     * asserting a shape the real system never emits.
+     */
+    dispatchBuiltEvent(built) {
+        const uris = built
+            .map(document => this.canonicalKey(document.uri.toString()))
+            .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
@@ -733,29 +908,107 @@ export class DataServer {
     subscribeToTextDocumentSaves() {
         this.disposables.push(this.services.workspace.TextDocuments.onDidSave(event => this.dispatchSaveEvent(event)));
     }
+    /** Relay each change of a document's dirty state; see {@link dispatchDirtyEvent}. */
+    subscribeToDirtyChanges() {
+        this.disposables.push(this.services.workspace.TextDocuments.onDidChangeDirty(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.
+     */
+    dispatchDirtyEvent(event) {
+        const uri = this.canonicalKey(event.uri);
+        if (this.uriWatchRecords.get(uri)?.watchers.size) {
+            this.clientProxy.onDocumentDirtyChanged({ uri, dirty: event.dirty });
+        }
+    }
     /**
-     * Mark the last-close transition per URI (see
-     * {@link pendingRevertBroadcasts}). The listener consults
-     * `isOpenInAnyClient` AFTER the store decremented the closing client's
-     * hold, so a `false` answer means this close was the last one.
+     * Mark each document the store releases after its last close, so
+     * {@link dispatchPhaseEvent} broadcasts the following rebuild even without
+     * a watcher. The store rebuilds such a document from 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 revert
+     * is sent.
+     *
+     * A release, not the close itself: a document whose last client lost its
+     * connection is released only once the revert grace runs out, or when
+     * another client opens it meanwhile, and not at all when a client lost
+     * from it opens it again within its own grace.
      */
     subscribeToTextDocumentCloses() {
-        const textDocuments = this.services.workspace.TextDocuments;
-        this.disposables.push(textDocuments.onDidClose(event => {
-            if (!textDocuments.isOpenInAnyClient(event.document.uri)) {
-                this.pendingRevertBroadcasts.add(this.canonicalKey(event.document.uri));
-            }
+        this.disposables.push(this.services.workspace.TextDocuments.onDidCloseLastOpen(event => {
+            const uri = this.canonicalKey(event.uri);
+            const record = this.uriWatchRecords.get(uri) ?? { watchers: new Set() };
+            record.revertPending = true;
+            this.uriWatchRecords.set(uri, record);
         }));
     }
-    /** Fan out a save event for the document's URI, gated by the subscription map. */
+    /**
+     * 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 last-close revert broadcast (see
+     * {@link subscribeToTextDocumentCloses}), where the same judgement was already made
+     * in the other direction: a transition that matters enough is delivered
+     * without a subscription.
+     *
+     * Runs from the `DocumentBuilder.onUpdate` listener rather than from a phase
+     * listener, which is the only place a deletion is observable: `update`
+     * removes the document before deriving the rebuild set, so it is never built.
+     * That ordering also puts this notification ahead of the `'rebuilt'` events
+     * for the dependents whose references the deletion just broke.
+     *
+     * The `deleted` list arrives already expanded to concrete document URIs —
+     * `deleteDocuments` resolves a directory URI to the documents beneath it — so
+     * no caller has to handle a directory here.
+     *
+     * The URI's fingerprint and revert 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.
+     */
+    dispatchDeleteEvents(deleted) {
+        for (const removed of deleted) {
+            const uri = this.canonicalKey(removed.toString());
+            const record = this.uriWatchRecords.get(uri);
+            if (record) {
+                record.fingerprint = undefined;
+                record.revertPending = 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. */
     dispatchSaveEvent(event) {
         // 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
+        // symlink path S); `uriWatchRecords` 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).
         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));
@@ -774,13 +1027,25 @@ 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 revert mark is the exception (see
+     * {@link subscribeToTextDocumentCloses}).
+     *
+     * An event for a rebuild with no observable change since the last emit is
+     * suppressed against the URI's fingerprint. 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.
      */
     dispatchPhaseEvent(document, cancelToken) {
         if (cancelToken.isCancellationRequested) {
@@ -792,16 +1057,23 @@ export class DataServer {
             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) {
+        const record = this.uriWatchRecords.get(uri);
+        const revertedOnClose = record?.revertPending === true;
+        if (!record || (record.watchers.size === 0 && !revertedOnClose)) {
             return;
         }
+        if (revertedOnClose) {
+            // 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.revertPending = undefined;
+            this.pruneUriWatchRecord(uri);
+        }
         const fingerprint = this.computeDocumentFingerprint(document);
-        if (this.lastEmittedFingerprint.get(uri) === fingerprint) {
+        if (record.fingerprint === fingerprint) {
             // 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
@@ -809,11 +1081,19 @@ export class DataServer {
             this.tracer.withUri(uri).debug(`Suppress onDocumentUpdated v${document.textDocument.version}: fingerprint unchanged`);
             return;
         }
-        this.lastEmittedFingerprint.set(uri, fingerprint);
+        record.fingerprint = fingerprint;
+        // The manager'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.services.workspace.AstDocumentManager.isOpen(uri) ? document.textDocument.version : undefined;
+        const { reason, sourceClientId } = version !== undefined && record.sentVersion === version
+            ? { reason: 'rebuilt', sourceClientId: UNKNOWN_CLIENT_ID }
+            : this.services.workspace.AstDocumentManager.attributeUpdate(document);
+        record.sentVersion = version;
         const event = {
             document: this.envelope(document.uri),
-            sourceClientId: revertedOnClose ? REVERT_ON_CLOSE_CLIENT_ID : this.resolveSourceClientId(document),
-            reason: this.resolveUpdateReason(document.uri)
+            sourceClientId: revertedOnClose ? REVERT_ON_CLOSE_CLIENT_ID : sourceClientId,
+            reason
         };
         this.tracer
             .withUri(uri)
@@ -839,7 +1119,7 @@ export class DataServer {
                 ? 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))]);
+            return extra.length === 0 ? base : textHash([base, FINGERPRINT_SEPARATOR, ...extra.map(value => JSON.stringify(value))]);
         }, 'debug', { logAfterMs: FINGERPRINT_LOG_AFTER_MS });
     }
     /**
@@ -852,30 +1132,6 @@ export class DataServer {
     additionalFingerprintInputs(_document) {
         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.
-     */
-    resolveUpdateReason(uri) {
-        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';
-    }
     /**
      * Subscribe to the project tier's change channel and re-fan registry
      * diffs into per-project wire notifications. The internal
@@ -917,19 +1173,6 @@ export class DataServer {
             this.clientProxy.onProjectsChanged({ project: entry.snapshot, reason: 'removed' });
         }
     }
-    /**
-     * 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.
-     */
-    resolveSourceClientId(document) {
-        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
@@ -967,7 +1210,7 @@ export class DataServer {
     }
     async stopProfiling(args) {
         if (!this.activeProfile) {
-            throw new Error('No profiling capture is active; call startProfiling first.');
+            throw noActiveProfileError();
         }
         const capture = this.activeProfile;
         this.activeProfile = undefined;
@@ -996,7 +1239,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
         };
     }
 }