@hydranium/core 1.0.0-next.12 → 1.0.0-next.123

package/lib/testing/stub-model-service.js

@@ -6,7 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { ModelService } from '../langium/model-service/model-service.js';
+import { DefaultModelService } from '../langium/model-service/model-service.js';
 /**
  * Implementation detail of {@link makeStubModelService}. A {@link ModelService}
  * subclass that takes `serialize` as a constructor callback — the test stub
@@ -14,7 +14,7 @@ import { ModelService } from '../langium/model-service/model-service.js';
  * path would fail. Construct it through the factory; the {@link StubModelService}
  * type alias is the public type name.
  */
-class StubModelServiceImpl extends ModelService {
+class StubModelServiceImpl extends DefaultModelService {
     serializeFn;
     constructor(services, serializeFn, options) {
         super(services, options);
@@ -32,8 +32,8 @@ class StubModelServiceImpl extends ModelService {
  * `makeTestServices` wires this stub automatically.
  *
  * `options` are the framework {@link ModelServiceOptions}, forwarded verbatim, so
- * a test can exercise an option-gated code path (`serializeBuilds`, the slow-warn
- * threshold) without hand-rolling a subclass just to reach the constructor.
+ * a test can exercise an option-gated code path (`serializeBuilds`) without
+ * hand-rolling a subclass just to reach the constructor.
  *
  * Adopters that need richer override behaviour — the framework's own extension
  * surface is {@link ModelService.rewriteModel} alongside `serialize` — should

package/lib/testing/stub-model-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"stub-model-service.js","sourceRoot":"","sources":["../../src/testing/stub-model-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,YAAY,EAA4B,MAAM,2CAA2C,CAAC;AAGnG;;;;;;GAMG;AACH,MAAM,oBAIJ,SAAQ,YAA0C;IAG3B;IAFtB,YACG,QAA8B,EACX,WAAqD,EACxE,OAA6B;QAE7B,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAHN,gBAAW,GAAX,WAAW,CAA0C;IAI3E,CAAC;IAEkB,SAAS,CAAC,GAAW,EAAE,IAAe;QACtD,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;CACH;AASD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAKjC,QAA8B,EAC9B,SAAmD,EACnD,OAA6B;IAE7B,OAAO,IAAI,oBAAoB,CAA+B,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAC/F,CAAC"}
+{"version":3,"file":"stub-model-service.js","sourceRoot":"","sources":["../../src/testing/stub-model-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAKlF,OAAO,EAAE,mBAAmB,EAA+C,MAAM,2CAA2C,CAAC;AAG7H;;;;;;GAMG;AACH,MAAM,oBAIJ,SAAQ,mBAAiD;IAGlC;IAFtB,YACG,QAA8B,EACX,WAAqD,EACxE,OAA6B;QAE7B,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAHN,gBAAW,GAAX,WAAW,CAA0C;IAI3E,CAAC;IAEkB,SAAS,CAAC,GAAW,EAAE,IAAe;QACtD,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;CACH;AASD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAKjC,QAA8B,EAC9B,SAAmD,EACnD,OAA6B;IAE7B,OAAO,IAAI,oBAAoB,CAA+B,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAC/F,CAAC"}

package/lib/util/connection-liveness.d.ts

@@ -10,12 +10,13 @@
  * Whether `err` means "the peer is gone", as opposed to a genuine failure of
  * the operation.
  *
- * The distinction is a **log-severity** one, and it matters because the two are
- * indistinguishable at the call site otherwise. Pushing an edit to a language
- * client that has already disconnected is a no-op, not a fault — it happens on
- * every ordinary shutdown, and reporting it at `error` turns routine teardown
- * into something that looks like it needs investigation. A real `applyEdit`
- * failure (the client refused, the request malformed) still deserves `error`.
+ * The two are indistinguishable at the call site otherwise, and callers act on
+ * the answer: a gone peer is logged at `debug` or dropped, a genuine failure is
+ * logged at `error` or re-raised as an unhandled rejection. Pushing an edit to
+ * a language client that has already disconnected is a no-op, not a fault — it
+ * happens on every ordinary shutdown — so a `false` here turns routine teardown
+ * into errors that look like they need investigation. A `true` for a real
+ * `applyEdit` failure (the client refused, the request malformed) hides it.
  *
  * Callers that only need to *survive* a dead connection rather than classify it
  * should just catch — see `LspLogger.emit`, whose fallback path does exactly

package/lib/util/connection-liveness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection-liveness.d.ts","sourceRoot":"","sources":["../../src/util/connection-liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAoBlF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAI3D"}
+{"version":3,"file":"connection-liveness.d.ts","sourceRoot":"","sources":["../../src/util/connection-liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAuClF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAO3D"}

package/lib/util/connection-liveness.js

@@ -7,38 +7,59 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 /**
- * Phrases `vscode-jsonrpc` uses when a call loses its connection. Matched on the
- * message because the condition surfaces in two different shapes:
+ * Phrases that mean a call lost its connection. Matched on the message because
+ * the condition surfaces in shapes that share no discriminator:
  *
  * - a **throw** from `throwIfClosedOrDisposed` (`Connection is disposed.` /
  *   `Connection is closed.`), a `ConnectionError` raised synchronously by
  *   `sendRequest` / `sendNotification` and by `RemoteConsole.send`;
  * - a **rejection** of an already-issued request (`Pending response rejected
  *   since connection got disposed`), a `ResponseError` produced when the
- *   pending-response map is drained on teardown.
+ *   pending-response map is drained on teardown;
+ * - a **write into a destroyed transport** (`Cannot call write after a stream
+ *   was destroyed`), Node's own error for a message the writer queued before
+ *   the connection was disposed and flushed after its stream was destroyed.
+ *   A notification rejects with Node's error itself, which
+ *   {@link isDestroyedStreamError} catches by its code; a request rejects with
+ *   a `ResponseError` that copies only the message, so the phrase is needed
+ *   too.
  *
- * Both are typed, but they are different error classes carrying codes from
- * different enums, so no single code check covers both. Kept
- * lowercase-normalised and anchored on `connection` so an unrelated "disposed"
- * message cannot match.
+ * The typed errors come from different classes carrying codes from different
+ * enums, so no single code check covers them. Kept lowercase-normalised and
+ * anchored on `connection` or `stream` so an unrelated "disposed" message
+ * cannot match.
  */
-const CONNECTION_GONE_PATTERNS = [/connection is disposed/, /connection is closed/, /connection got disposed/, /connection got closed/];
+const CONNECTION_GONE_PATTERNS = [
+    /connection is disposed/,
+    /connection is closed/,
+    /connection got disposed/,
+    /connection got closed/,
+    /after a stream was destroyed/
+];
+const DESTROYED_STREAM_CODE = 'ERR_STREAM_DESTROYED';
+function isDestroyedStreamError(err) {
+    return err instanceof Error && 'code' in err && err.code === DESTROYED_STREAM_CODE;
+}
 /**
  * Whether `err` means "the peer is gone", as opposed to a genuine failure of
  * the operation.
  *
- * The distinction is a **log-severity** one, and it matters because the two are
- * indistinguishable at the call site otherwise. Pushing an edit to a language
- * client that has already disconnected is a no-op, not a fault — it happens on
- * every ordinary shutdown, and reporting it at `error` turns routine teardown
- * into something that looks like it needs investigation. A real `applyEdit`
- * failure (the client refused, the request malformed) still deserves `error`.
+ * The two are indistinguishable at the call site otherwise, and callers act on
+ * the answer: a gone peer is logged at `debug` or dropped, a genuine failure is
+ * logged at `error` or re-raised as an unhandled rejection. Pushing an edit to
+ * a language client that has already disconnected is a no-op, not a fault — it
+ * happens on every ordinary shutdown — so a `false` here turns routine teardown
+ * into errors that look like they need investigation. A `true` for a real
+ * `applyEdit` failure (the client refused, the request malformed) hides it.
  *
  * Callers that only need to *survive* a dead connection rather than classify it
  * should just catch — see `LspLogger.emit`, whose fallback path does exactly
  * that, since a logger has nowhere to report a logging failure anyway.
  */
 export function isConnectionGoneError(err) {
+    if (isDestroyedStreamError(err)) {
+        return true;
+    }
     const message = err instanceof Error ? err.message : String(err);
     const normalized = message.toLowerCase();
     return CONNECTION_GONE_PATTERNS.some(pattern => pattern.test(normalized));

package/lib/util/connection-liveness.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection-liveness.js","sourceRoot":"","sources":["../../src/util/connection-liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,wBAAwB,GAAG,CAAC,wBAAwB,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,uBAAuB,CAAC,CAAC;AAExI;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAC/C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACzC,OAAO,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;AAC7E,CAAC"}
+{"version":3,"file":"connection-liveness.js","sourceRoot":"","sources":["../../src/util/connection-liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,wBAAwB,GAAG;IAC9B,wBAAwB;IACxB,sBAAsB;IACtB,yBAAyB;IACzB,uBAAuB;IACvB,8BAA8B;CAChC,CAAC;AAEF,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AAErD,SAAS,sBAAsB,CAAC,GAAY;IACzC,OAAO,GAAG,YAAY,KAAK,IAAI,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,qBAAqB,CAAC;AACtF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAC/C,IAAI,sBAAsB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IACf,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACzC,OAAO,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;AAC7E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/core",
-  "version": "1.0.0-next.12",
+  "version": "1.0.0-next.123",
   "description": "Foundational runtime of the hydranium framework: AST coordination layer (services, integrity, AST extension, serialization, multi-client documents) plus the LSP textual head at the /lsp subpath. Consumed by protocol-head packages (@hydranium/data-server, @hydranium/glsp-server).",
   "keywords": [
     "hydranium",
@@ -72,6 +72,14 @@
     "./lib/testing/playwright": {
       "types": "./lib/testing/playwright/index.d.ts",
       "default": "./lib/testing/playwright/index.js"
+    },
+    "./messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
+    "./lib/messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
     }
   },
   "main": "lib/index.js",
@@ -96,8 +104,8 @@
     "diff": "^5.2.0"
   },
   "devDependencies": {
-    "@hydranium/langium": "1.0.0-next.12",
-    "@hydranium/protocol": "1.0.0-next.12",
+    "@hydranium/langium": "1.0.0-next.123",
+    "@hydranium/protocol": "1.0.0-next.123",
     "@playwright/test": "^1.40.0",
     "@types/diff": "^5.2.0",
     "rimraf": "^5.0.0",
@@ -109,12 +117,12 @@
     "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "@hydranium/langium": "1.0.0-next.12",
-    "@hydranium/protocol": "1.0.0-next.12",
+    "@hydranium/langium": "1.0.0-next.123",
+    "@hydranium/protocol": "1.0.0-next.123",
     "@playwright/test": "^1.40.0",
-    "vscode-jsonrpc": "^8.0.0 || ^9.0.0",
-    "vscode-languageserver": "^9.0.0 || ^10.0.0",
-    "vscode-languageserver-protocol": "^3.17.5",
+    "vscode-jsonrpc": "9.0.1",
+    "vscode-languageserver": "~10.0.1",
+    "vscode-languageserver-protocol": "~3.18.1",
     "vscode-languageserver-textdocument": "^1.0.12",
     "vscode-languageserver-types": "^3.17.5"
   },
@@ -129,6 +137,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. It does NOT prevent a NESTED copy — `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship — so a consumer of the GLSP head must pin the chain in its own manifest, and docs/adopting/requirements.md carries the block to paste. This manifest declares the two links ABOVE the transport as well, and they carry `~` for the same reason: each admits exactly what `langium@4.3.1` itself admits, and a wider range reaches a `vscode-languageserver@9` / `vscode-languageserver-protocol@3.17.x` that depends on the 8.x transport, which is the same split one level up. `vscode-languageserver-types` and `vscode-languageserver-textdocument` are deliberately NOT narrowed: both declare zero dependencies and expose structural APIs, so a duplicate of either drags no transport in and no identity check reads it.",
   "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
   "//sideEffects": "NOT `false`: two barrels do work at module load that their re-exports do not account for, and a bundler skips an unflagged re-export barrel outright. `node/index.js` calls `installNodeLogFileSink()` and `installNodeWriteLockScope()`, which is how a Node host gets the log file-tee and write-lock reentrancy detection merely by importing `@hydranium/core/node`. `util/index.js` carries a bare `import '@hydranium/langium'` so the `UriUtils` namespace augmentation stays loaded for anything importing from here. Both failures are runtime-only and silent — a missing log file, a `UriUtils.toUri` that is `undefined`."
 }

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

@@ -8,11 +8,14 @@
  ********************************************************************************/
 
 import {
+   type CanonicalUri,
    type CloseModelArgs,
    type Tracer,
    type TransferSavedEvent,
    type TransferUpdatedEvent,
-   type OpenModelArgs
+   type OpenModelArgs,
+   asSnapshotVersion,
+   type SnapshotVersion
 } from '@hydranium/protocol';
 import {
    type AstNode,
@@ -24,6 +27,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
@@ -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,85 @@ 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>
+>;
 
 /** 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;
+}
 
 /**
  * Higher-level facade over {@link HydraniumTextDocuments} that speaks the
@@ -186,9 +249,16 @@ 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> {
    protected lastUpdate?: UpdateInfo;
 
+   /** 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;
@@ -206,12 +276,19 @@ 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.coalesceSaves = options.coalesceSaves ?? false;
       this.textDocuments.onDidOpen(event =>
          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 };
+         // 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) {
+            this.textDocuments.notifyDocumentDeleted(uri.toString());
+         }
       });
       // Content transitions for CLOSED documents bypass the text store: the
       // last-close revert and watched-file changes rebuild from disk into a
@@ -311,11 +388,12 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
          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'
+            // No `'deleted'` arm: `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.
+            reason: this.lastUpdate?.changed.some(changed => UriUtils.equals(changed, document.uri)) ? 'changed' : 'rebuilt'
          };
          this.tracer.with(uri).trace(`emitUpdate start: source=${sourceClientId}, reason=${event.reason}`);
          listener(event);
@@ -328,21 +406,21 @@ 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
+    * absence so a routing consumer tests `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`).
     */
-   getAuthor(document: LangiumDocument<AstNode>): string | undefined {
+   getAuthor(document: LangiumDocument): string | undefined {
       return this.textDocuments.getAuthor(document.textDocument.uri, document.textDocument.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,7 +433,18 @@ 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);
          this.textDocuments.notifyDidOpenTextDocument({ textDocument }, args.clientId);
@@ -393,31 +482,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 +575,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,22 @@
+/********************************************************************************
+ * 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,
+   SessionClosedError,
+   isDocumentNotOpenError,
+   isDuplicateClientIdError,
+   isSessionClosedError
+} from '@hydranium/protocol';