@hydranium/core 1.0.0-next.16 → 1.0.0-next.168

package/src/documents/ast-document-manager.ts

@@ -8,15 +8,17 @@
  ********************************************************************************/
 
 import {
+   type CanonicalUri,
    type CloseModelArgs,
    type Tracer,
    type TransferSavedEvent,
    type TransferUpdatedEvent,
-   type OpenModelArgs
+   type OpenModelArgs,
+   asSnapshotVersion,
+   type SnapshotVersion
 } from '@hydranium/protocol';
 import {
    type AstNode,
-   type DocumentBuilder,
    DocumentState,
    type FileSystemProvider,
    type LangiumDocument,
@@ -24,6 +26,7 @@ import {
    UriUtils
 } from '@hydranium/langium';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import { type AstDiagnostic } from '../langium/validation/document-validator.js';
 
 /**
  * File-system provider extension that supports writes. Langium's standard
@@ -62,8 +65,9 @@ export interface WritableFileSystemProvider extends FileSystemProvider {
     * - A non-`file:` URI (or any URI the provider cannot stat) passes through
     *   **unchanged** — it is treated as present, never reported absent.
     * - A provider with no disk to check (in-memory / browser / empty) simply
-    *   omits this method; `RealpathDocumentUriPolicy` then degrades to the
-    *   syntactic `DefaultDocumentUriPolicy` behaviour automatically.
+    *   omits this method; the framework's `FileSystemProviderRegistry` then
+    *   returns the URI unchanged, and `RealpathDocumentUriPolicy` answers as
+    *   the syntactic `DefaultDocumentUriPolicy` does.
     *
     * Synchronous (a `realpath` is a kernel-cached syscall) and optional — the
     * only consumers are the document-identity policy's `canonicalUri`/`loadUri`.
@@ -79,7 +83,7 @@ import { TextDocumentIdentifier, type TextDocumentItem } from 'vscode-languagese
 import { type TextDocument } from 'vscode-languageserver-textdocument';
 import { URI } from '@hydranium/langium';
 import { type ServerSharedServices } from '../langium/module.js';
-import { labelPhaseListener } from '../langium/document-builder/index.js';
+import { type HydraniumDocumentBuilder, labelPhaseListener } from '../langium/document-builder/index.js';
 import { UNKNOWN_CLIENT_ID } from './client-ids.js';
 import { type HydraniumTextDocuments } from './hydranium-text-documents.js';
 import { type SelfSaveRegistry } from './self-save-registry.js';
@@ -102,19 +106,18 @@ export interface UpdateInfo {
  * twins; the type-system distinction is the generic constraint, and the
  * conversion seam between them is the framework `TransferEncoder`.
  */
-export interface AstDocument<TAst extends AstNode, TDiagnostic> {
+export interface AstDocument<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> {
    root: TAst;
    diagnostics: TDiagnostic[];
    uri: string;
    /**
     * Text-document version this snapshot was taken at — read from
     * `LangiumDocument.textDocument.version`. Symmetric with
-    * `TransferDocument.version` on the wire side: in-process callers
-    * that hold an `AstDocument` and mutate it pass this value back as
-    * `TransferUpdateArgs.baseVersion` / `TransferSaveArgs.baseVersion` to opt
-    * into the conflict gate.
+    * `TransferDocument.version` on the wire side: an in-process caller that
+    * holds an `AstDocument` and mutates it sends this straight back as the
+    * `basedOn` of its session's write, and the conflict gate arms on it.
     */
-   version: number;
+   version: SnapshotVersion;
 }
 
 export namespace AstDocument {
@@ -124,13 +127,13 @@ export namespace AstDocument {
     * don't need to repeat the empty array at every call site. Mirrors
     * `TransferDocument.create` on the wire side.
     */
-   export function create<TAst extends AstNode, TDiagnostic = unknown>(
+   export function create<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic>(
       uri: string,
       version: number,
       root: TAst,
       diagnostics: TDiagnostic[] = []
    ): AstDocument<TAst, TDiagnostic> {
-      return { uri, version, root, diagnostics };
+      return { uri, version: asSnapshotVersion(version), root, diagnostics };
    }
 
    /**
@@ -146,25 +149,107 @@ export namespace AstDocument {
     * carry that identity, not the subscriber's (possibly non-canonical) URI:
     * a subscriber already knows the URI it subscribed with, so the useful
     * thing to surface is the canonical one every other layer keys by.
+    *
+    * Narrowing `TDiagnostic` below the constraint asserts that the validators
+    * in play produce that shape, and nothing here checks it: the build fills the
+    * array, so a document carrying a diagnostic from elsewhere — a lexer error,
+    * another validator — satisfies the declared type and not the narrowed one.
     */
-   export function from<TAst extends AstNode, TDiagnostic = unknown>(document: LangiumDocument): AstDocument<TAst, TDiagnostic> {
+   export function from<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic>(
+      document: LangiumDocument
+   ): AstDocument<TAst, TDiagnostic> {
       return create<TAst, TDiagnostic>(
          document.textDocument.uri,
          document.textDocument.version,
          document.parseResult.value as TAst,
-         (document.diagnostics ?? []) as unknown as TDiagnostic[]
+         (document.diagnostics ?? []) as TDiagnostic[]
       );
    }
 }
 
 /** Update event delivered by {@link AstDocumentManager.onUpdate} — typed alias over the generic event wrapper. */
-export type AstDocumentUpdatedEvent<TAst extends AstNode, TDiagnostic> = TransferUpdatedEvent<AstDocument<TAst, TDiagnostic>>;
+export type AstDocumentUpdatedEvent<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> = TransferUpdatedEvent<
+   AstDocument<TAst, TDiagnostic>
+>;
 
 /** Save event delivered by {@link AstDocumentManager.onSave} — typed alias over the generic event wrapper. */
-export type AstDocumentSavedEvent<TAst extends AstNode, TDiagnostic> = TransferSavedEvent<AstDocument<TAst, TDiagnostic>>;
+export type AstDocumentSavedEvent<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> = TransferSavedEvent<
+   AstDocument<TAst, TDiagnostic>
+>;
+
+/**
+ * Why an update event fired and whose write it echoes, as
+ * {@link AstDocumentManager.attributeUpdate} answers for a document. The
+ * fields mean what they mean on `TransferUpdatedEvent`.
+ */
+export interface UpdateAttribution {
+   reason: 'changed' | 'rebuilt';
+   sourceClientId: string;
+   causedBy: string;
+}
 
 /** Construction options for {@link AstDocumentManager}. */
-export type AstDocumentManagerOptions = LogNameOptions;
+export interface AstDocumentManagerOptions extends LogNameOptions {
+   /**
+    * Skip a queued save of a URI when a newer save of it is queued behind. The
+    * newer save took its text later, so disk ends the same with fewer writes.
+    * A skipped save announces nothing and takes the newer save's outcome: it
+    * resolves when that one lands and rejects with its error when it fails,
+    * since disk then holds neither text. Defaults to `false`: every save
+    * writes. The framework binds the manager without options, so turning this
+    * on means rebinding `AstDocumentManager` with them.
+    */
+   readonly coalesceSaves?: boolean;
+}
+
+/**
+ * The document slot the model server and the integrity service talk to:
+ * open/close/update/save plus the AST-typed event streams, with the LSP
+ * plumbing hidden.
+ *
+ * Generic over `<TAst extends AstNode, TDiagnostic>` so each consumer projects
+ * its own AST root type and diagnostic shape into the emitted
+ * {@link AstDocument} envelopes.
+ *
+ * **URI contract.** Every URI-accepting member takes a URI in *any* spelling
+ * (canonical, symlinked, `..`/case-divergent) and canonicalizes internally
+ * through the {@link DocumentUriPolicy}, so a caller never has to canonicalize
+ * first and an implementation may not require it.
+ */
+export interface AstDocumentManager<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> {
+   open(args: OpenModelArgs): Promise<Disposable>;
+   close(args: CloseModelArgs): Promise<void>;
+   isOpen(uri: string): boolean;
+
+   /** Apply `text` as `clientId`'s edit. Resolves to the resulting text-document version. */
+   update(uri: string, text: string, clientId: string): Promise<number>;
+   /**
+    * Write the document's current text to disk through `FileSystemTaskQueue`.
+    * The text is taken when this is called, so saves of one file land in the
+    * order they were called.
+    */
+   save(uri: string, clientId: string): Promise<void>;
+
+   onUpdate(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onSave(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void | Promise<void>): Disposable;
+   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
+
+   getDocument(uri: string): LangiumDocument | undefined;
+
+   /** Client id that authored the document's current version, or `undefined` for a framework-internal build. */
+   getAuthor(document: LangiumDocument): string | undefined;
+
+   /**
+    * The reason, source and cause of an update event for `document` emitted
+    * now, from a phase listener of the build that carries it. Every head takes
+    * its update events' attribution from here, so they name the same client
+    * for one build. For a document a client opened, while rebuilds validate,
+    * the answer changes once its `Validated` listeners have all run: a later
+    * event at that version is `'rebuilt'`. `TransferDocumentUpdateReason`
+    * names the cases that fall back to the last update.
+    */
+   attributeUpdate(document: LangiumDocument): UpdateAttribution;
+}
 
 /**
  * Higher-level facade over {@link HydraniumTextDocuments} that speaks the
@@ -186,13 +271,53 @@ export type AstDocumentManagerOptions = LogNameOptions;
  * resolution (the egress `applyEditToLanguageClient`) stay on
  * {@link HydraniumTextDocuments}, their owner.
  */
-export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = unknown> {
+export class DefaultAstDocumentManager<
+   TAst extends AstNode,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic
+> implements AstDocumentManager<TAst, TDiagnostic> {
+   /** The last `DocumentBuilder.update`'s URIs; the reason for a document the store does not track. */
    protected lastUpdate?: UpdateInfo;
+   /**
+    * Canonical URIs a client has opened since the file was last deleted,
+    * whose versions the store keeps. One no client has opened keeps Langium's
+    * version `0` through every change of its content, so its version says
+    * nothing. Kept past the last close, since the store continues the version
+    * sequence on the next open; a delivery can land after that close.
+    */
+   protected readonly trackedUris = new Set<CanonicalUri>();
+   /**
+    * Per tracked URI, the version whose `Validated` listeners last all ran,
+    * which is the version an update event was delivered for. Dropped on
+    * deletion, so a file created again with the same text is changed again.
+    */
+   protected readonly deliveredVersions = new Map<CanonicalUri, number>();
+   /**
+    * Whose writes the build under way carries, set when it starts: the author
+    * of every open document's undelivered version, and the unknown-client id
+    * for a change no write explains, such as a deletion, a document no client
+    * has open, or a write that changed nothing. An undelivered version is one
+    * whose build has not validated it yet, so a write whose build was
+    * cancelled stays a cause of the build that takes over.
+    *
+    * Errs toward more than one cause, and so toward the unknown client, which
+    * a reader treats as foreign: an answer it repeats, never one it misses.
+    * A change no write explains counts for its own build only, so a build
+    * that takes over from a cancelled one loses it. One field for every build:
+    * a build started outside the workspace lock, such as a re-queue of an
+    * orphaned document, reads the causes of whichever build started last.
+    * An open document no build delivers, one a `shouldValidate` override
+    * skips, stays undelivered, so it is a cause of every build while open.
+    */
+   protected readonly buildCauses = new Set<string>();
+
+   /** Per canonical URI, the newest save queued for it, which {@link coalesceSaves} lets older queued saves defer to. */
+   protected readonly newestSaves = new Map<CanonicalUri, Promise<void>>();
+   protected readonly coalesceSaves: boolean;
 
    protected readonly textDocuments: HydraniumTextDocuments<TextDocument>;
    protected readonly fileSystemProvider: WritableFileSystemProvider;
    protected readonly langiumDocs: LangiumDocuments;
-   protected readonly documentBuilder: DocumentBuilder;
+   protected readonly documentBuilder: HydraniumDocumentBuilder;
    protected readonly uriPolicy: DocumentUriPolicy;
    protected readonly tracer: Tracer;
 
@@ -206,13 +331,41 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
       this.documentBuilder = services.workspace.DocumentBuilder;
       this.uriPolicy = services.workspace.DocumentUriPolicy;
       this.tracer = services.Tracer.for(options.logName ?? 'AstDocumentManager').trace('instantiated');
-      this.textDocuments.onDidOpen(event =>
-         this.open({ clientId: event.clientId, uri: event.document.uri, languageId: event.document.languageId })
-      );
+      this.coalesceSaves = options.coalesceSaves ?? false;
+      this.textDocuments.onDidOpen(event => {
+         this.trackedUris.add(this.uriPolicy.canonicalUri(event.document.uri));
+         return this.open({ clientId: event.clientId, uri: event.document.uri, languageId: event.document.languageId });
+      });
       this.textDocuments.onDidClose(event => this.close({ clientId: event.clientId, uri: event.document.uri }));
       this.documentBuilder.onUpdate((changed, deleted) => {
          this.lastUpdate = { changed, deleted };
+         this.buildCauses.clear();
+         for (const textDocument of this.textDocuments.all()) {
+            if (!this.isDelivered(textDocument.uri, textDocument.version)) {
+               this.buildCauses.add(this.textDocuments.getAuthor(textDocument.uri, textDocument.version) ?? UNKNOWN_CLIENT_ID);
+            }
+         }
+         const unexplained = changed.some(uri => {
+            const textDocument = this.textDocuments.get(uri.toString());
+            return textDocument === undefined || this.isDelivered(textDocument.uri, textDocument.version);
+         });
+         if (unexplained || deleted.length > 0) {
+            this.buildCauses.add(UNKNOWN_CLIENT_ID);
+         }
+         // The only place a deletion is observable: `DocumentBuilder.update`
+         // removes a deleted document before it builds anything, so no phase
+         // listener ever sees it.
+         for (const uri of deleted) {
+            const key = this.uriPolicy.canonicalUri(uri.toString());
+            this.trackedUris.delete(key);
+            this.deliveredVersions.delete(key);
+            this.textDocuments.notifyDocumentDeleted(uri.toString());
+         }
       });
+      // Once every listener ran, not in a listener of its own: listeners after
+      // it could still be skipped by a cancel, and the next build would then
+      // report as rebuilt a version they never delivered.
+      this.documentBuilder.onDocumentPhaseDelivered(DocumentState.Validated, (document, version) => this.markDelivered(document, version));
       // Content transitions for CLOSED documents bypass the text store: the
       // last-close revert and watched-file changes rebuild from disk into a
       // factory-fresh text document carrying the factory's own version. At the
@@ -304,20 +457,16 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
          if (this.uriPolicy.canonicalUri(document.uri) !== target) {
             return;
          }
-         // Presentation boundary: the event field is a concrete `string`, so an
-         // unauthored (framework-rebuilt) document surfaces the readable default
-         // rather than `undefined` to subscribers and logs.
-         const sourceClientId = this.getAuthor(document) ?? UNKNOWN_CLIENT_ID;
+         // No `'deleted'` reason: `DocumentBuilder.update` drops a deleted
+         // document from `LangiumDocuments` before deriving the rebuild set
+         // from it, so a deleted URI is never built and never reaches this
+         // phase listener. A subscriber needing deletions has to be told on
+         // a channel that does not require a built document.
          const event: TransferUpdatedEvent<AstDocument<TAst, TDiagnostic>> = {
             document: this.toAstDocument(document),
-            sourceClientId,
-            reason: this.lastUpdate?.changed.find(changed => UriUtils.equals(changed, document.uri))
-               ? 'changed'
-               : this.lastUpdate?.deleted.find(deleted => UriUtils.equals(deleted, document.uri))
-                 ? 'deleted'
-                 : 'rebuilt'
+            ...this.attributeUpdate(document)
          };
-         this.tracer.with(uri).trace(`emitUpdate start: source=${sourceClientId}, reason=${event.reason}`);
+         this.tracer.with(uri).trace(`emitUpdate start: source=${event.sourceClientId}, reason=${event.reason}, cause=${event.causedBy}`);
          listener(event);
          this.tracer.with(uri).trace('emitUpdate listener returned');
       };
@@ -326,23 +475,86 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
 
    /**
     * The client that authored `document`'s current version, or `undefined` when
-    * no client wrote it — a framework-internal rebuild (workspace startup, a
-    * cascade relink, a `didClose`-reload) or a genuine author gap. Honest about
-    * absence so routing consumers (`ModelService.isNonLanguageClientEdit`)
-    * test `undefined` directly rather than against a sentinel; the presentation
-    * default ({@link UNKNOWN_CLIENT_ID}) is applied at the boundary that needs a
-    * concrete value (the `onUpdate` event's `sourceClientId`, the data-server's
-    * `resolveSourceClientId`).
+    * no client wrote it: a document no client has open. A rebuild that keeps
+    * the version keeps its author, so this does not say who caused a build;
+    * {@link attributeUpdate} does.
+    * Honest about absence so a routing consumer tests `undefined` directly
+    * rather than against a sentinel; the presentation default
+    * ({@link UNKNOWN_CLIENT_ID}) is applied where an event needs a value.
     */
-   getAuthor(document: LangiumDocument<AstNode>): string | undefined {
+   getAuthor(document: LangiumDocument): string | undefined {
       return this.textDocuments.getAuthor(document.textDocument.uri, document.textDocument.version);
    }
 
+   /**
+    * `'changed'` for the first delivery of the document's version, crediting
+    * its author; `'rebuilt'` for a later one, crediting nobody, since it echoes
+    * no write, and naming the build's single cause if it has one.
+    *
+    * A document the rule does not apply to (see {@link isTracked}) falls back
+    * to the last update: it is `'changed'` when its URI was passed to
+    * `DocumentBuilder.update`. An open document that a validating build skips,
+    * through a `shouldValidate` override, is never delivered, so each of its
+    * events is its author's change.
+    */
+   attributeUpdate(document: LangiumDocument): UpdateAttribution {
+      const key = this.uriPolicy.canonicalUri(document.uri.toString());
+      const changed = this.isTracked(key)
+         ? this.deliveredVersions.get(key) !== document.textDocument.version
+         : this.lastUpdate?.changed.some(uri => UriUtils.equals(uri, document.uri)) === true;
+      if (changed) {
+         // Presentation boundary: the event field is a concrete `string`, so an
+         // unauthored document surfaces the readable default rather than
+         // `undefined` to subscribers and logs.
+         const author = this.getAuthor(document) ?? UNKNOWN_CLIENT_ID;
+         return { reason: 'changed', sourceClientId: author, causedBy: author };
+      }
+      const [cause] = this.buildCauses;
+      return { reason: 'rebuilt', sourceClientId: UNKNOWN_CLIENT_ID, causedBy: this.buildCauses.size === 1 ? cause : UNKNOWN_CLIENT_ID };
+   }
+
+   /**
+    * Whether the version rule applies to `uri`: the store keeps its version,
+    * and rebuilds validate. With `updateBuildOptions.validation` off no version
+    * is ever delivered, and the rule would report every event of an open
+    * document as its author's change.
+    */
+   protected isTracked(uri: CanonicalUri): boolean {
+      return this.keepsVersion(uri) && Boolean(this.documentBuilder.updateBuildOptions.validation);
+   }
+
+   /**
+    * Whether the store keeps `uri`'s version: a client opened it since its
+    * file was last deleted, or has it open still, as an editor keeps a
+    * deleted file's buffer.
+    */
+   protected keepsVersion(uri: CanonicalUri): boolean {
+      return this.trackedUris.has(uri) || this.textDocuments.isOpen(uri);
+   }
+
+   /**
+    * Record that `version` of `document` was delivered, when the store tracks
+    * it. The version the listeners saw, not the document's current one: a
+    * write during them has moved that on, and marking it would report the
+    * write's own build as rebuilt.
+    */
+   protected markDelivered(document: LangiumDocument, version: number): void {
+      const key = this.uriPolicy.canonicalUri(document.uri.toString());
+      if (this.keepsVersion(key)) {
+         this.deliveredVersions.set(key, version);
+      }
+   }
+
+   /** Whether `version` of `uri` was delivered. */
+   protected isDelivered(uri: string, version: number): boolean {
+      return this.deliveredVersions.get(this.uriPolicy.canonicalUri(uri)) === version;
+   }
+
    async open(args: OpenModelArgs): Promise<Disposable> {
       // `open()` is the RPC-level "ensure this document is loaded" call. It is issued
-      // by a view attaching, but also internally by `update()` / `save()` and by every
-      // additional client attaching to the same URI, including the several sub-editors
-      // a composite view opens. When the document is already loaded there is nothing to
+      // by a session opening the document, including by every additional client
+      // attaching to the same URI and the several sub-editors a composite view
+      // opens. When the document is already loaded there is nothing to
       // do here but hand back the close-disposable — callers that want the current
       // state read it from this method's surrounding RPC response, not from a re-build.
       //
@@ -355,10 +567,28 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
       // transiently breaks cross-document linking mid-rebuild (a dependent briefly
       // seeing an `extends`/`type` reference unresolved). And because the constructor
       // wires `onDidOpen -> this.open`, it would fire a second, identical rebuild on
-      // every first open. So an already-open `open()` is a no-op.
+      // every first open.
+      //
+      // So an already-open `open()` records the attaching client's open and nothing
+      // else. The open is per `(uri, clientId)` and the last-close revert counts down
+      // to it, so skipping it lets the first client's close tear down a document
+      // another client is still reading. A document waiting out the revert grace
+      // is still loaded: a client lost from it within its own grace attaches and
+      // keeps its text, and for any other client the attach releases it, so the
+      // open reads the file.
+      if (this.isOpen(args.uri)) {
+         this.textDocuments.attachClient(args.uri, args.clientId);
+      }
       if (!this.isOpen(args.uri)) {
          const textDocument = await this.createDocumentFromTextOrFileSystem(args.uri, args.languageId, args.version, args.text);
+         const creates = !this.isOpen(args.uri);
          this.textDocuments.notifyDidOpenTextDocument({ textDocument }, args.clientId);
+         if (creates && args.text !== undefined) {
+            // Text the caller supplies was not read from the file, so no file
+            // is assumed: the document is dirty until its first save, whatever
+            // the file holds.
+            this.textDocuments.updateDiskBaseline(args.uri, undefined);
+         }
       }
       return Disposable.create(() => this.close(args));
    }
@@ -393,31 +623,80 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
     * callers don't need to pass it — the manager owns content and version
     * sequencing.
     *
+    * The text is taken synchronously, before the save waits in the file's task
+    * queue; the compare and the write run in the queue. Taken later, a save
+    * that waits behind another writes whatever the store holds when its turn
+    * comes, edits made after the call included, and announces that text under
+    * its own client id.
+    *
+    * **The write is skipped when the file already holds that text; the
+    * notification is not.** A save announces that the content is on disk, which
+    * is true either way — so a subscriber clearing a dirty marker or reacting to
+    * a persist behaves the same, while an mtime is not moved for byte-identical
+    * content that a downstream mtime-keyed build would then read as new work.
+    *
     * Throws if no document is open for `uri`.
     */
    async save(uri: string, clientId: string): Promise<void> {
-      const document = this.textDocuments.get(uri);
+      // Canonical throughout: the write and the read that gates it must address
+      // the same file the store was keyed by, or a divergent spelling compares
+      // one file and writes another.
+      const canonical = this.uriPolicy.canonicalUri(uri);
+      const document = this.textDocuments.get(canonical);
       if (!document) {
          throw new Error(`Document ${uri} hasn't been opened for saving yet`);
       }
       const text = document.getText();
-      await this.tracer.with(uri).time(
-         `Write file (${text.length} bytes, from ${clientId})`,
-         // Async write so a slow disk does not block the event loop for the duration of the fs call.
-         () => this.fileSystemProvider.writeFile(UriUtils.toUri(uri), text),
-         'debug'
-      );
+      let supersededBy: Promise<void> | undefined;
+      const saved: Promise<void> = this.services.workspace.FileSystemTaskQueue.enqueue(canonical, async () => {
+         const newest = this.newestSaves.get(canonical);
+         if (this.coalesceSaves && newest !== saved) {
+            supersededBy = newest;
+            return;
+         }
+         await this.writeSave(canonical, text, clientId);
+      })
+         .then(() => supersededBy)
+         .finally(() => {
+            if (this.newestSaves.get(canonical) === saved) {
+               this.newestSaves.delete(canonical);
+            }
+         });
+      this.newestSaves.set(canonical, saved);
+      return saved;
+   }
+
+   /** Write `text` to `uri` unless the file already holds it, then announce the save. Runs inside the file's task queue. */
+   protected async writeSave(uri: CanonicalUri, text: string, clientId: string): Promise<void> {
+      if (!(await this.matchesDisk(uri, text))) {
+         await this.tracer.with(uri).time(
+            `Write file (${text.length} bytes, from ${clientId})`,
+            // Async write so a slow disk does not block the event loop for the duration of the fs call.
+            () => this.fileSystemProvider.writeFile(UriUtils.toUri(uri), text),
+            'debug'
+         );
+      }
       this.textDocuments.notifyDidSaveTextDocument({ textDocument: TextDocumentIdentifier.create(uri), text }, clientId);
    }
 
-   isOpen(uri: string): boolean {
-      return !!this.textDocuments.get(uri);
+   /**
+    * Whether the file at `uri` already holds `text`.
+    *
+    * Compared by CONTENT rather than against a remembered version, so a write
+    * from outside this server is still corrected: a version this manager already
+    * saved says nothing about what is on disk now. `false` when the file cannot
+    * be read at all, which is the answer that writes — a document whose file does
+    * not exist yet is exactly the one a first save has to create.
+    */
+   protected async matchesDisk(uri: string, text: string): Promise<boolean> {
+      return this.fileSystemProvider
+         .readFile(UriUtils.toUri(uri))
+         .then(onDisk => onDisk === text)
+         .catch(() => false);
    }
 
-   /** True if the URI was in the directly-changed set of the most recent build (not just affected). */
-   isDirectChange(uri: string): boolean {
-      const canonical = this.uriPolicy.canonicalUri(uri);
-      return this.lastUpdate?.changed.some(changed => this.uriPolicy.canonicalUri(changed) === canonical) ?? false;
+   isOpen(uri: string): boolean {
+      return !!this.textDocuments.get(uri);
    }
 
    /**
@@ -437,11 +716,16 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
       version = 0,
       text?: string
    ): Promise<TextDocumentItem> {
-      return { uri, languageId, version, text: text ?? (await this.readFile(uri)) };
-   }
-
-   async readFile(uri: string): Promise<string> {
-      return this.fileSystemProvider.readFile(UriUtils.toUri(uri));
+      // Read in the file's task queue: a read beside a queued save of the file
+      // returns the text from before it, and the document then opens on that.
+      return {
+         uri,
+         languageId,
+         version,
+         text:
+            text ??
+            (await this.services.workspace.FileSystemTaskQueue.enqueue(uri, () => this.fileSystemProvider.readFile(UriUtils.toUri(uri))))
+      };
    }
 
    /**

package/src/documents/client-ids.ts

@@ -8,26 +8,9 @@
  ********************************************************************************/
 
 /**
- * Well-known client-kind identifiers used across the multi-client framework.
- *
- * The framework tracks each document as belonging to one or more "clients"
- * — typically an LSP-text-client (Monaco, VS Code, etc.), a GLSP diagram
- * client, and/or a structured-form client. Each kind carries a stable id so
- * the server can route outbound corrections, edits, and notifications to the
- * right transport.
- */
-
-/** Identifier for an LSP-text client (Monaco, VS Code, …). */
-export const LANGUAGE_CLIENT_ID = 'language-client';
-
-/** Fallback identifier when a document's author is unknown (e.g. cold workspace-init load). */
-export const UNKNOWN_CLIENT_ID = 'unknown';
-
-/**
- * Synthetic author id on the `onDocumentUpdated` broadcast a data-server
- * emits after the LAST client closed a document and the framework rebuilt it
- * from its disk content (discarding unsaved in-session edits). Not a real
- * client: it lets consumers distinguish the revert broadcast from
- * client-authored updates.
+ * Re-export, because these are WIRE values and the side that has to recognise
+ * them is the client. They are defined in `@hydranium/protocol` so a frontend
+ * can name them without depending on the server tier; this path stays so
+ * server-side code keeps importing them from where it already does.
  */
-export const REVERT_ON_CLOSE_CLIENT_ID = 'revert-on-close';
+export { FRAMEWORK_CLIENT_IDS, LANGUAGE_CLIENT_ID, REVERT_ON_CLOSE_CLIENT_ID, UNKNOWN_CLIENT_ID } from '@hydranium/protocol';

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

@@ -0,0 +1,24 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Re-export, because these errors cross the wire and the side that has to
+ * recognise them is the client. They are defined in `@hydranium/protocol` so a
+ * frontend can name them without depending on the server tier.
+ */
+export {
+   DocumentNotOpenError,
+   DuplicateClientIdError,
+   ReservedClientIdError,
+   SessionClosedError,
+   isDocumentNotOpenError,
+   isDuplicateClientIdError,
+   isReservedClientIdError,
+   isSessionClosedError
+} from '@hydranium/protocol';