@hydranium/core 1.0.0-next.114 → 1.0.0-next.117

package/src/documents/client-session-registry.ts

@@ -0,0 +1,211 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type CanonicalUri, FRAMEWORK_CLIENT_IDS } from '@hydranium/protocol';
+import { Emitter, type Event } from 'vscode-languageserver';
+import { INTEGRITY_CLIENT_ID } from '../langium/integrity/integrity-rule.js';
+import { DuplicateClientIdError, SessionClosedError } from './client-session-errors.js';
+
+/**
+ * What a client session states about one of its opens, kept per
+ * `(session, uri)` for as long as that open lasts.
+ *
+ * Any object type: an adopter declares the fields its own open path reads and
+ * passes that type as a session's `TOpenOptions`. Stored per open rather than
+ * per document, so two sessions opening one document with different options
+ * each keep their own.
+ */
+export type OpenOptions = object;
+
+/**
+ * `'closing'` covers the span in which a session's opens are being closed. The
+ * id is still taken then, and the session can open nothing more, so an open
+ * issued from a close listener cannot outlive the session that made it.
+ */
+export type ClientSessionState = 'live' | 'closing';
+
+/** Delivered by {@link ClientSessionRegistry.onDidCloseSession}. */
+export interface ClientSessionClosedEvent {
+   readonly clientId: string;
+}
+
+/**
+ * The ids no client session may be started under: the wire's well-known ids and
+ * the integrity author. Each names a framework participant rather than a
+ * client, and a session holding one would have its writes read as that
+ * participant's.
+ */
+export const RESERVED_CLIENT_IDS: readonly string[] = [...FRAMEWORK_CLIENT_IDS, INTEGRITY_CLIENT_ID];
+
+/**
+ * Which client has which document open, and which client ids are registered
+ * sessions — the open facts every head shares, composed by
+ * `HydraniumTextDocuments`.
+ *
+ * Opens are recorded for every client id, registered or not. An id that was
+ * never registered is a client that predates sessions and writes through the
+ * flat `clientId` calls; its opens are tracked exactly as a session's are, and
+ * only the session table ignores it. Requiring registration before an open
+ * would refuse every such client.
+ *
+ * One open per `(client, uri)`, with no reference count: a repeat open changes
+ * nothing, and one close ends it.
+ *
+ * Pure bookkeeping. Closing a document is the store's job, because a close has
+ * to reach the text store and its listeners; the store asks this class what to
+ * close and records each close here.
+ */
+export class ClientSessionRegistry {
+   protected readonly sessions = new Map<string, ClientSessionState>();
+   protected readonly clientsByUri = new Map<CanonicalUri, Set<string>>();
+   /** Each client's opens, with the options it opened them with. */
+   protected readonly opensByClient = new Map<string, Map<CanonicalUri, OpenOptions | undefined>>();
+   protected readonly reservedIds: ReadonlySet<string> = new Set(RESERVED_CLIENT_IDS);
+   protected readonly sessionClosedEmitter = new Emitter<ClientSessionClosedEvent>();
+
+   /** Fires once a session has been removed from the table, after all its opens closed. */
+   get onDidCloseSession(): Event<ClientSessionClosedEvent> {
+      return this.sessionClosedEmitter.event;
+   }
+
+   /**
+    * Enter `clientId` in the session table.
+    *
+    * Throws {@link DuplicateClientIdError} when the id is live anywhere in the
+    * process: reserved, registered (including by a session that is still
+    * closing), or holding opens as a client that is not a session. The last
+    * matters because the id is the author label and the echo key, and a
+    * session sharing one with another client would take that client's writes
+    * for its own.
+    */
+   register(clientId: string): void {
+      if (this.reservedIds.has(clientId) || this.sessions.has(clientId) || this.opensByClient.has(clientId)) {
+         throw new DuplicateClientIdError(clientId);
+      }
+      this.sessions.set(clientId, 'live');
+   }
+
+   /** Whether `clientId` is in the session table, live or closing. */
+   isRegistered(clientId: string): boolean {
+      return this.sessions.has(clientId);
+   }
+
+   /**
+    * Mark `clientId` as closing and return every URI it has open, as a copy the
+    * caller can close while this registry changes underneath it.
+    */
+   beginClose(clientId: string): CanonicalUri[] {
+      if (this.sessions.has(clientId)) {
+         this.sessions.set(clientId, 'closing');
+      }
+      return this.opensOf(clientId);
+   }
+
+   /** Remove `clientId` from the session table and announce it. A no-op for an id that is not registered. */
+   unregister(clientId: string): void {
+      if (!this.sessions.delete(clientId)) {
+         return;
+      }
+      this.sessionClosedEmitter.fire(Object.freeze({ clientId }));
+   }
+
+   /**
+    * Record that `clientId` opened `uri`, with no options. Returns `false` when
+    * it already had it open, in which case nothing changes.
+    *
+    * Throws {@link SessionClosedError} for a session that is closing.
+    */
+   addOpen(uri: CanonicalUri, clientId: string): boolean {
+      if (this.sessions.get(clientId) === 'closing') {
+         throw new SessionClosedError(clientId);
+      }
+      let opens = this.opensByClient.get(clientId);
+      if (opens?.has(uri)) {
+         return false;
+      }
+      if (!opens) {
+         opens = new Map();
+         this.opensByClient.set(clientId, opens);
+      }
+      opens.set(uri, undefined);
+      let clients = this.clientsByUri.get(uri);
+      if (!clients) {
+         clients = new Set();
+         this.clientsByUri.set(uri, clients);
+      }
+      clients.add(clientId);
+      return true;
+   }
+
+   /** Record that `clientId` closed `uri`. Returns `false` when it did not have it open. */
+   removeOpen(uri: CanonicalUri, clientId: string): boolean {
+      const opens = this.opensByClient.get(clientId);
+      if (!opens?.delete(uri)) {
+         return false;
+      }
+      if (opens.size === 0) {
+         this.opensByClient.delete(clientId);
+      }
+      const clients = this.clientsByUri.get(uri);
+      clients?.delete(clientId);
+      if (!clients?.size) {
+         this.clientsByUri.delete(uri);
+      }
+      return true;
+   }
+
+   /** Whether `clientId` has `uri` open. */
+   isOpenIn(uri: CanonicalUri, clientId: string): boolean {
+      return !!this.clientsByUri.get(uri)?.has(clientId);
+   }
+
+   /** Whether any client has `uri` open. */
+   isOpen(uri: CanonicalUri): boolean {
+      return this.clientsByUri.has(uri);
+   }
+
+   /** The clients that have `uri` open, in the order they opened it. */
+   clientsOf(uri: CanonicalUri): string[] {
+      return [...(this.clientsByUri.get(uri) ?? [])];
+   }
+
+   /** The URIs `clientId` has open, in the order it opened them. */
+   opensOf(clientId: string): CanonicalUri[] {
+      return [...(this.opensByClient.get(clientId)?.keys() ?? [])];
+   }
+
+   /** Every document open in at least one client, with the clients that have it open. */
+   openDocuments(): Array<{ readonly uri: CanonicalUri; readonly clients: string[] }> {
+      return [...this.clientsByUri].map(([uri, clients]) => ({ uri, clients: [...clients] }));
+   }
+
+   /** The options `clientId` opened `uri` with, or `undefined` when it gave none or does not have it open. */
+   openOptions(uri: CanonicalUri, clientId: string): OpenOptions | undefined {
+      return this.opensByClient.get(clientId)?.get(uri);
+   }
+
+   /** Replace the options of an existing open. Does nothing when `clientId` does not have `uri` open. */
+   setOpenOptions(uri: CanonicalUri, clientId: string, options: OpenOptions | undefined): void {
+      const opens = this.opensByClient.get(clientId);
+      if (opens?.has(uri)) {
+         opens.set(uri, options);
+      }
+   }
+
+   /**
+    * Forget every session and open without announcing anything. Subscriptions
+    * stay, so a listener registered before the clear hears the sessions that
+    * end after it.
+    */
+   clear(): void {
+      this.sessions.clear();
+      this.clientsByUri.clear();
+      this.opensByClient.clear();
+   }
+}

package/src/documents/hydranium-text-documents.ts

@@ -20,7 +20,7 @@
 // on lsp-server, contradicting the peer architecture.
 // eslint-disable-next-line @typescript-eslint/no-restricted-imports
 import { NormalizedTextDocuments } from '@hydranium/langium/lsp';
-import { UriUtils } from '@hydranium/langium';
+import { type URI, UriUtils } from '@hydranium/langium';
 import { type ServerSharedServices } from '../langium/module.js';
 import {
    type ApplyWorkspaceEditResult,
@@ -49,6 +49,8 @@ import { type DocumentUri, TextDocument, type TextDocumentContentChangeEvent } f
 import { type CanonicalUri, type LanguageClientUri, asLanguageClientUri, DisposableCollection, type Tracer } from '@hydranium/protocol';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
 import { LANGUAGE_CLIENT_ID } from './client-ids.js';
+import { INTEGRITY_CLIENT_ID } from '../langium/integrity/integrity-rule.js';
+import { type ClientSessionClosedEvent, ClientSessionRegistry, type OpenOptions } from './client-session-registry.js';
 import { isFullReplace, LanguageClientTextShadow } from './language-client-text-shadow.js';
 
 /**
@@ -97,8 +99,6 @@ export interface HydraniumTextDocumentsOptions<T extends TextDocument = TextDocu
  * change that caused it.
  */
 export interface DocumentTrackingRecord {
-   /** Client ids currently holding this document open (multi-client membership). */
-   readonly clients: Set<string>;
    /** Author of each version, sparse-indexed by the SHARED (server-assigned) version number. */
    readonly versionAuthors: string[];
    /**
@@ -252,7 +252,8 @@ function contentHash(text: string): string {
  * Multi-client text-document tracking on top of Langium's `NormalizedTextDocuments`.
  *
  * Adds the framework features used by the integrity, model-server, and GLSP layers:
- *   - Per-document client membership (multiple clients can attach to the same URI).
+ *   - Per-document client membership (multiple clients can attach to the same
+ *     URI) and the client-session table, both kept by {@link __sessions}.
  *   - A SERVER-OWNED shared version sequence: per-URI, monotonic across
  *     close/reopen cycles, advancing exactly when the synced content changes.
  *     Client-declared version ids (Monaco's buffer numbering) feed only a
@@ -270,15 +271,20 @@ function contentHash(text: string): string {
  */
 export class HydraniumTextDocuments<T extends TextDocument = TextDocument> extends NormalizedTextDocuments<T> {
    /**
-    * Per-URI client-facing tracking ({@link DocumentTrackingRecord}): client
-    * membership, version-author history, and integrity-staged pending content,
-    * keyed by normalized URI. One record per URI so the last-client close clears
-    * every axis atomically. The language-client diff baseline stays in
-    * {@link __shadow} (its own abstraction); the parsed-document store stays in
-    * the inherited `__syncedDocuments`.
+    * Per-URI client-facing tracking ({@link DocumentTrackingRecord}), keyed by
+    * canonical URI. One record per URI, so dropping it clears every axis at
+    * once. Which client has the document open is kept apart, in
+    * {@link __sessions}.
     */
    protected __documents = new Map<CanonicalUri, DocumentTrackingRecord>();
 
+   /**
+    * Which client has which document open, and which client ids are registered
+    * sessions. Every open-state predicate on this class reads it, so an open
+    * recorded anywhere else is invisible to the last-close transition.
+    */
+   protected readonly __sessions = new ClientSessionRegistry();
+
    /**
     * Per-URI shared-version continuity across close/reopen cycles
     * ({@link VersionSequence}), written at last-client close and consulted by
@@ -496,7 +502,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             // the update) from "incoming version older than ours" (stale race).
             const reason =
                lastSeen === td.version ? `already at version ${lastSeen}` : `incoming version ${td.version} older than current ${lastSeen}`;
-            this.logUri(uri, `Ignore update by ${clientId}: ${reason}`, 'debug');
+            this.logUri(uri, `Ignore update by ${this.formatClientId(clientId)}: ${reason}`, 'debug');
             return;
          }
          record.clientVersions.set(clientId, td.version);
@@ -562,7 +568,10 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
                return;
             }
          }
-         this.log(document.uri, `Update to version ${document.version} by ${clientId}${changed ? '' : ' (content unchanged)'}`);
+         this.log(
+            document.uri,
+            `Update to version ${document.version} by ${this.formatClientId(clientId)}${changed ? '' : ' (content unchanged)'}`
+         );
          this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
       }
    }
@@ -596,22 +605,23 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          this.__syncedDocuments.set(key, document);
          this.setAuthor(key, document.version, clientId);
       }
-      this.log(document.uri, `Update to version ${document.version} by ${clientId}${changed ? '' : ' (content unchanged)'}`);
+      this.log(
+         document.uri,
+         `Update to version ${document.version} by ${this.formatClientId(clientId)}${changed ? '' : ' (content unchanged)'}`
+      );
       this.__onDidChangeContent.fire(Object.freeze({ document, clientId }));
       return document.version;
    }
 
    public notifyDidCloseTextDocument(event: DidCloseTextDocumentParams, clientId = LANGUAGE_CLIENT_ID): void {
       const uri = this.documentKey(event.textDocument.uri);
-      if (!this.isOpenInClient(uri, clientId)) {
+      if (!this.__sessions.removeOpen(uri, clientId)) {
          return;
       }
-      const closingRecord = this.__documents.get(uri);
-      closingRecord?.clients.delete(clientId);
-      closingRecord?.clientVersions.delete(clientId);
+      this.__documents.get(uri)?.clientVersions.delete(clientId);
       const syncedDocument = this.__syncedDocuments.get(uri);
       if (syncedDocument !== undefined) {
-         this.log(syncedDocument.uri, `Closed synced document: ${syncedDocument.version} by ${clientId}`);
+         this.log(syncedDocument.uri, `Closed synced document: ${syncedDocument.version} by ${this.formatClientId(clientId)}`);
          this.__onDidClose.fire(Object.freeze({ document: syncedDocument, clientId }));
 
          if (clientId === LANGUAGE_CLIENT_ID) {
@@ -623,7 +633,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             this.__shadow.invalidate(droppedUri);
             this.__pendingPushes.delete(droppedUri);
          }
-         if (!this.__documents.get(uri)?.clients.size) {
+         if (!this.__sessions.isOpen(uri)) {
             // Last client closed the document; delete sync state. The downstream
             // "rebuild from disk for file URIs / drop from index for ephemeral
             // URIs" decision lives in `HydraniumDocumentUpdateHandler.didCloseDocument`,
@@ -668,7 +678,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    public notifyDidSaveTextDocument(event: DidSaveTextDocumentParams, clientId = LANGUAGE_CLIENT_ID): void {
       const syncedDocument = this.__syncedDocuments.get(this.documentKey(event.textDocument.uri));
       if (syncedDocument !== undefined) {
-         this.log(syncedDocument.uri, `Saved synced document: ${syncedDocument.version} by ${clientId}`);
+         this.log(syncedDocument.uri, `Saved synced document: ${syncedDocument.version} by ${this.formatClientId(clientId)}`);
          this.__onDidSave.fire(Object.freeze({ document: syncedDocument, clientId }));
       }
    }
@@ -698,9 +708,9 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          return;
       }
       let document = this.__syncedDocuments.get(uri);
+      const existingClients = this.__sessions.clientsOf(uri);
+      this.__sessions.addOpen(uri, clientId);
       const record = this.trackingFor(uri);
-      const existingClients = [...record.clients];
-      record.clients.add(clientId);
       // Baseline the per-client staleness guard at the version id the client
       // declared for its own buffer (client-owned per LSP).
       record.clientVersions.set(clientId, td.version);
@@ -723,7 +733,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          const sequence = this.__versionSequences.get(uri);
          const version =
             sequence === undefined ? td.version : sequence.contentHash === contentHash(text) ? sequence.version : sequence.version + 1;
-         this.log(uri, `Open document: Version ${version} by ${clientId} [first client${source}]`);
+         this.log(uri, `Open document: Version ${version} by ${this.formatClientId(clientId)} [first client${source}]`);
          document = this.configuration.create(uri, td.languageId, version, text);
          this.__syncedDocuments.set(uri, document);
          this.setAuthor(uri, version, clientId);
@@ -786,9 +796,9 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       if (!document || this.isOpenInClient(key, clientId)) {
          return false;
       }
+      const existingClients = this.__sessions.clientsOf(key);
+      this.__sessions.addOpen(key, clientId);
       const record = this.trackingFor(key);
-      const existingClients = [...record.clients];
-      record.clients.add(clientId);
       record.clientVersions.set(clientId, document.version);
       this.logClientJoined(key, clientId, document.version, existingClients);
       return true;
@@ -797,8 +807,8 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    protected logClientJoined(uri: DocumentUri, clientId: string, version: number, existingClients: readonly string[]): void {
       this.log(
          uri,
-         `Attach client: ${clientId} joined existing document (version ${version}, ` +
-            `now open in: ${[...existingClients, clientId].join(', ')})`
+         `Attach client: ${this.formatClientId(clientId)} joined existing document (version ${version}, ` +
+            `now open in: ${[...existingClients, clientId].map(id => this.formatClientId(id)).join(', ')})`
       );
    }
 
@@ -808,7 +818,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          // Trigger a (re-)build by firing a change event.
          const timer = this.startTimerForUri(
             syncedDocument.uri,
-            `Refresh synced document: Version ${syncedDocument.version} by ${clientId}`
+            `Refresh synced document: Version ${syncedDocument.version} by ${this.formatClientId(clientId)}`
          );
          this.__onDidChangeContent.fire(Object.freeze({ document: syncedDocument, clientId }));
          timer.dispose();
@@ -846,7 +856,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    protected trackingFor(uri: CanonicalUri): DocumentTrackingRecord {
       let record = this.__documents.get(uri);
       if (!record) {
-         record = { clients: new Set(), versionAuthors: [], clientVersions: new Map() };
+         record = { versionAuthors: [], clientVersions: new Map() };
          this.__documents.set(uri, record);
       }
       return record;
@@ -946,10 +956,12 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * its own numbering, so requiring the two to agree would refuse every commit
     * on the path this exists for. Content is the thing both sides can be held to.
     *
-    * The version is KEPT rather than stepped, and no change event is fired: the
-    * repair rides the build already under way, so minting a version would
-    * invalidate the based-on token every watcher just took, and an event would
-    * re-enter the build that is mid-flight.
+    * A changed text is a new version authored by {@link INTEGRITY_CLIENT_ID}.
+    * Kept at the old version, the repair is invisible to every reader keyed on
+    * versions: a write based on the unrepaired version passes the based-on gate
+    * and replaces the repair, and an echo filter credits the repair to the
+    * client whose edit it corrected. No change event is fired: the repair
+    * rides the build already under way, and an event would re-enter it.
     */
    commitRepair(uri: DocumentUri, parsedFrom: string, repaired: string): RepairCommit<T> {
       const key = this.documentKey(uri);
@@ -961,11 +973,16 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          this.logUri(key, 'Refuse repair commit: the open document moved on from the text the AST was parsed from', 'debug');
          return { status: 'stale' };
       }
+      if (repaired === parsedFrom) {
+         return { status: 'committed', document };
+      }
       // Reassigned rather than mutated in place: the default configuration
       // updates and returns the SAME instance, but an adopter-supplied one may
       // return a new object, and the store must end up holding whichever it is.
-      const updated = this.configuration.update(document, [{ text: repaired }], document.version);
+      const updated = this.configuration.update(document, [{ text: repaired }], document.version + 1);
       this.__syncedDocuments.set(key, updated);
+      this.setAuthor(key, updated.version, INTEGRITY_CLIENT_ID);
+      this.log(updated.uri, `Update to version ${updated.version} by ${this.formatClientId(INTEGRITY_CLIENT_ID)} (repair)`);
       return { status: 'committed', document: updated };
    }
 
@@ -989,17 +1006,17 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * True iff any client still holds `uri` open. Distinct from {@link isOpen},
     * which reads `__syncedDocuments` — that map is cleared only AFTER the
     * `onDidClose` event fires for the last client, so `isOpen` returns `true`
-    * during the close event itself. `isOpenInAnyClient` reads the tracking
-    * record's `clients` set, which is updated BEFORE the fire, so an `onDidClose`
+    * during the close event itself. `isOpenInAnyClient` reads the open table
+    * ({@link __sessions}), which is updated BEFORE the fire, so an `onDidClose`
     * subscriber that finds this `false` knows the last client just closed and a
     * disk re-read / rebuild can proceed.
     */
    isOpenInAnyClient(uri: DocumentUri): boolean {
-      return (this.__documents.get(this.documentKey(uri))?.clients.size ?? 0) > 0;
+      return this.__sessions.isOpen(this.documentKey(uri));
    }
 
    isOpenInClient(uri: DocumentUri, client: string): boolean {
-      return !!this.__documents.get(this.documentKey(uri))?.clients.has(client);
+      return this.__sessions.isOpenIn(this.documentKey(uri), client);
    }
 
    isOpenInLanguageClient(uri: DocumentUri): boolean {
@@ -1010,14 +1027,14 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
    }
 
    isOnlyOpenInClient(uri: DocumentUri, client: string): boolean {
-      const key = this.documentKey(uri);
-      return this.__documents.get(key)?.clients.size === 1 && this.isOpenInClient(key, client);
+      const clients = this.__sessions.clientsOf(this.documentKey(uri));
+      return clients.length === 1 && clients[0] === client;
    }
 
    /**
     * Every document currently held open by at least one client, with the client
-    * ids holding it. Reads the same per-URI tracking records as
-    * {@link isOpenInAnyClient}, so it reflects a last-client close immediately.
+    * ids holding it. Reads the same open table as {@link isOpenInAnyClient}, so
+    * it reflects a last-client close immediately.
     *
     * Diagnostics-oriented — the server-state snapshot lists these so an operator
     * can see WHY a document is pinned: a document that lingers here after its
@@ -1025,30 +1042,116 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * under a shedding policy, explains why its CST is never shed).
     */
    openDocuments(): OpenDocument[] {
-      const result: OpenDocument[] = [];
-      for (const [uri, tracking] of this.__documents) {
-         if (tracking.clients.size > 0) {
-            result.push({ uri, clients: [...tracking.clients] });
+      return this.__sessions.openDocuments();
+   }
+
+   /** Fires once a client session has ended, after every document it had open was closed. */
+   get onDidCloseSession(): Event<ClientSessionClosedEvent> {
+      return this.__sessions.onDidCloseSession;
+   }
+
+   /**
+    * Start a client session under `clientId`. Throws `DuplicateClientIdError`
+    * where {@link ClientSessionRegistry.register} refuses the id.
+    */
+   registerSession(clientId: string): void {
+      this.__sessions.register(clientId);
+      this.tracer.info(`Session started: ${this.formatClientId(clientId)}`);
+      this.tracer.trace(`Session started: ${clientId}`);
+   }
+
+   /**
+    * End the client session `clientId`: close every document it has open, then
+    * free the id. Immediate — each close runs the ordinary close path before
+    * this returns. A no-op for an id that is not a registered session.
+    */
+   closeSession(clientId: string): void {
+      if (!this.__sessions.isRegistered(clientId)) {
+         return;
+      }
+      try {
+         for (const uri of this.__sessions.beginClose(clientId)) {
+            this.notifyDidCloseTextDocument({ textDocument: { uri } }, clientId);
+         }
+      } finally {
+         this.__sessions.unregister(clientId);
+         this.tracer.info(`Session closed: ${this.formatClientId(clientId)}`);
+         this.tracer.trace(`Session closed: ${clientId}`);
+      }
+   }
+
+   /** The options `clientId` opened `uri` with, or `undefined` when it gave none or does not have it open. */
+   openOptions(uri: DocumentUri, clientId: string): OpenOptions | undefined {
+      return this.__sessions.openOptions(this.documentKey(uri), clientId);
+   }
+
+   /** Replace the options of an existing open. Does nothing when `clientId` does not have `uri` open. */
+   setOpenOptions(uri: DocumentUri, clientId: string, options: OpenOptions | undefined): void {
+      this.__sessions.setOpenOptions(this.documentKey(uri), clientId, options);
+   }
+
+   /**
+    * The file behind `uri` was deleted: close every open of it except the
+    * language client's.
+    *
+    * The editor's open is left alone because the editor owns it: it keeps the
+    * buffer of a deleted file and goes on sending changes for it, and a store
+    * that had closed the document would drop every one of them until the editor
+    * reopened.
+    */
+   notifyDocumentDeleted(uri: DocumentUri): void {
+      const key = this.documentKey(uri);
+      for (const clientId of this.__sessions.clientsOf(key)) {
+         if (clientId !== LANGUAGE_CLIENT_ID) {
+            this.notifyDidCloseTextDocument({ textDocument: { uri: key } }, clientId);
          }
       }
-      return result;
    }
 
    /**
-    * Stages integrity-updated content for a document no editor holds.
+    * Remove the document for `uri`, closing every open of it first — the
+    * editor's included, since the document it would keep editing is gone.
+    *
+    * The base removes the synced document without consulting the open table,
+    * which leaves every open recorded against a document that no longer exists:
+    * the store then answers that the URI is open, and the next open attaches to
+    * nothing.
+    */
+   override delete(uri: string | URI | T): void {
+      const key = this.documentKey((typeof uri === 'object' && 'uri' in uri ? uri.uri : uri).toString());
+      for (const clientId of this.__sessions.clientsOf(key)) {
+         this.notifyDidCloseTextDocument({ textDocument: { uri: key } }, clientId);
+      }
+      super.delete(key);
+   }
+
+   /**
+    * A client id as log lines print it. An id containing `#` is cut eight
+    * characters after its last `#`, which leaves a minted `label#uuid` as the
+    * label and enough of the UUID to tell sessions apart; an id without `#`
+    * prints whole. The full id goes out at trace level wherever a session
+    * starts or ends.
+    */
+   protected formatClientId(clientId: string): string {
+      const separator = clientId.lastIndexOf('#');
+      return separator < 0 ? clientId : clientId.slice(0, separator + 9);
+   }
+
+   /**
+    * Stages integrity-updated content for a document no client holds.
     *
     * When `workspace/applyEdit` targets a closed file, the client opens it from
     * disk (stale) and sends `didOpen` before applying the edit. This staged
     * content is consumed by {@link notifyDidOpenTextDocument} to replace the
     * stale disk text, preventing a brief revert of the integrity update.
     *
-    * Only a FIRST open consumes it. The integrity service stages whenever the
-    * URI is not open in the language client, which includes a URI held only
-    * through another head; an editor attaching to that URI joins the existing
-    * entry and never reads the stage, and the last close discards it with the
-    * tracking record. For a closed URI an entry lingers only if
-    * `workspace/applyEdit` fails and the file is never opened — the memory cost
-    * is one serialised string per URI.
+    * Only a FIRST open consumes it, so stage only for a URI no client holds
+    * ({@link isOpenInAnyClient} is `false`). A URI held only through another
+    * head is not closed: an editor attaching to it joins the existing entry and
+    * never reads the stage, and the last close discards the stage with the
+    * tracking record. An entry lingers only if `workspace/applyEdit` fails and
+    * the file is never opened — the memory cost is one serialised string per
+    * URI.
     */
    stagePendingContent(uri: DocumentUri, text: string): void {
       this.trackingFor(this.documentKey(uri)).pendingContent = text;

package/src/documents/index.ts

@@ -8,6 +8,8 @@
  ********************************************************************************/
 
 export * from './client-ids.js';
+export * from './client-session-errors.js';
+export * from './client-session-registry.js';
 export * from './language-client-text-shadow.js';
 export * from './hydranium-text-documents.js';
 export * from './ast-document-manager.js';

package/src/langium/integrity/integrity-rule.ts

@@ -49,14 +49,22 @@ export namespace IntegrityPhase {
 }
 
 /**
- * Controls how integrity corrections are persisted for *closed* files. The
- * mode does not reach open files: their corrected text is delivered by the
- * model service's settled-state sync, whatever the mode says.
+ * Controls how integrity corrections are persisted for files no editor holds.
+ * The mode does not reach a file open in the language client: the correction
+ * is delivered to the editor, which shows it as an unsaved change.
  *
- * - `silent`: write to disk immediately; no editor involvement.
+ * - `silent`: write to disk immediately; no editor involvement. For a file
+ *    held only through the data or GLSP head, only while disk still holds the
+ *    text the correction was computed from and the text store still holds the
+ *    correction. Otherwise — the holder has unsaved edits, disk changed behind
+ *    the server, or disk cannot be read — the correction waits in the text
+ *    store for the next save.
  * - `editor`: open the file dirty via `applyEdit`. If the user closes without
  *    saving, the correction is suppressed until the file changes or the
- *    workspace reloads.
+ *    workspace reloads. A file held only through the data or GLSP head gets
+ *    neither: the correction stays in the text store, and since those heads
+ *    mark only their own edits unsaved, nothing shows that store and disk
+ *    differ until a save or the last close.
  */
 export type IntegritySyncMode = 'silent' | 'editor';