@hydranium/core 1.0.0-next.11 → 1.0.0-next.112

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.11",
+  "version": "1.0.0-next.112",
   "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.11",
-    "@hydranium/protocol": "1.0.0-next.11",
+    "@hydranium/langium": "1.0.0-next.112",
+    "@hydranium/protocol": "1.0.0-next.112",
     "@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.11",
-    "@hydranium/protocol": "1.0.0-next.11",
+    "@hydranium/langium": "1.0.0-next.112",
+    "@hydranium/protocol": "1.0.0-next.112",
     "@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

@@ -12,7 +12,9 @@ import {
    type Tracer,
    type TransferSavedEvent,
    type TransferUpdatedEvent,
-   type OpenModelArgs
+   type OpenModelArgs,
+   asSnapshotVersion,
+   type SnapshotVersion
 } from '@hydranium/protocol';
 import {
    type AstNode,
@@ -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
@@ -102,19 +105,19 @@ 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
+    * `TransferUpdateArgs.basedOn` / `TransferSaveArgs.basedOn`, 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,26 +149,82 @@ 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;
 
+/**
+ * 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>;
+   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;
+
+   /**
+    * Whether `uri` is one of the URIs the most recent build request named, as
+    * opposed to a document that build swept in as a dependent. Deletions are
+    * excluded: they never reach this layer, since a deleted document is
+    * removed before the build set is computed.
+    *
+    * The answer refers to the latest request, which may still be building, and
+    * it is retained between builds — so outside a build it describes whichever
+    * one ran last.
+    */
+   isTriggeringEdit(uri: string): boolean;
+}
+
 /**
  * Higher-level facade over {@link HydraniumTextDocuments} that speaks the
  * model-server protocol (open/close/update/save with the transfer-model event
@@ -186,7 +245,10 @@ 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;
 
    protected readonly textDocuments: HydraniumTextDocuments<TextDocument>;
@@ -311,11 +373,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);
@@ -334,7 +397,7 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
     * 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);
    }
 
@@ -355,10 +418,17 @@ 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 hold and nothing
+      // else. The hold is per `(uri, clientId)` and the last-close revert counts down
+      // to it, so skipping it lets the first holder's close tear down a document
+      // another client is still reading.
       if (!this.isOpen(args.uri)) {
          const textDocument = await this.createDocumentFromTextOrFileSystem(args.uri, args.languageId, args.version, args.text);
          this.textDocuments.notifyDidOpenTextDocument({ textDocument }, args.clientId);
+      } else {
+         this.textDocuments.attachClient(args.uri, args.clientId);
       }
       return Disposable.create(() => this.close(args));
    }
@@ -393,29 +463,56 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
     * callers don't need to pass it — the manager owns content and version
     * sequencing.
     *
+    * **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'
-      );
-      this.textDocuments.notifyDidSaveTextDocument({ textDocument: TextDocumentIdentifier.create(uri), text }, clientId);
+      if (!(await this.matchesDisk(canonical, text))) {
+         await this.tracer.with(canonical).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(canonical), text),
+            'debug'
+         );
+      }
+      this.textDocuments.notifyDidSaveTextDocument({ textDocument: TextDocumentIdentifier.create(canonical), text }, clientId);
+   }
+
+   /**
+    * 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);
    }
 
    isOpen(uri: string): boolean {
       return !!this.textDocuments.get(uri);
    }
 
-   /** True if the URI was in the directly-changed set of the most recent build (not just affected). */
-   isDirectChange(uri: string): boolean {
+   isTriggeringEdit(uri: string): boolean {
       const canonical = this.uriPolicy.canonicalUri(uri);
       return this.lastUpdate?.changed.some(changed => this.uriPolicy.canonicalUri(changed) === canonical) ?? false;
    }
@@ -437,11 +534,7 @@ 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));
+      return { uri, languageId, version, text: text ?? (await 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';