@hydranium/core 1.0.0-next.8 → 1.0.0-next.85

package/lib/testing/stub-model-service.d.ts

@@ -6,12 +6,13 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import type { TransferDiagnostic, TransferElement } from '@hydranium/protocol';
+import type { TransferElement } from '@hydranium/protocol';
+import type { AstDiagnostic } from '../langium/validation/document-validator.js';
 import type { AstNode } from '@hydranium/langium';
-import { ModelService, type ModelServiceOptions } from '../langium/model-service/model-service.js';
+import { type ModelService, type ModelServiceOptions } from '../langium/model-service/model-service.js';
 import type { ServerSharedServices } from '../langium/module.js';
 /** The type of the model-service test double produced by {@link makeStubModelService}. */
-export type StubModelService<TAst extends AstNode, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement> = ModelService<TAst, TDiagnostic, TTransfer>;
+export type StubModelService<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic, TTransfer extends TransferElement = TransferElement> = ModelService<TAst, TDiagnostic, TTransfer>;
 /**
  * Build a {@link StubModelService} — a {@link ModelService} test double that
  * takes `serialize` as a constructor callback. The stub services tree has no
@@ -27,5 +28,5 @@ export type StubModelService<TAst extends AstNode, TDiagnostic extends TransferD
  * surface is {@link ModelService.rewriteModel} alongside `serialize` — should
  * subclass {@link ModelService} directly instead.
  */
-export declare function makeStubModelService<TAst extends AstNode, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement>(services: ServerSharedServices, serialize: (uri: string, root: TTransfer) => string, options?: ModelServiceOptions): StubModelService<TAst, TDiagnostic, TTransfer>;
+export declare function makeStubModelService<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic, TTransfer extends TransferElement = TransferElement>(services: ServerSharedServices, serialize: (uri: string, root: TTransfer) => string, options?: ModelServiceOptions): StubModelService<TAst, TDiagnostic, TTransfer>;
 //# sourceMappingURL=stub-model-service.d.ts.map

package/lib/testing/stub-model-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stub-model-service.d.ts","sourceRoot":"","sources":["../../src/testing/stub-model-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AACnG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AA2BjE,0FAA0F;AAC1F,MAAM,MAAM,gBAAgB,CACzB,IAAI,SAAS,OAAO,EACpB,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,SAAS,SAAS,eAAe,GAAG,eAAe,IAClD,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CACjC,IAAI,SAAS,OAAO,EACpB,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,SAAS,SAAS,eAAe,GAAG,eAAe,EAEnD,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,MAAM,EACnD,OAAO,CAAC,EAAE,mBAAmB,GAC7B,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,CAEhD"}
+{"version":3,"file":"stub-model-service.d.ts","sourceRoot":"","sources":["../../src/testing/stub-model-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAuB,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAC7H,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AA2BjE,0FAA0F;AAC1F,MAAM,MAAM,gBAAgB,CACzB,IAAI,SAAS,OAAO,EACpB,WAAW,SAAS,aAAa,GAAG,aAAa,EACjD,SAAS,SAAS,eAAe,GAAG,eAAe,IAClD,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CACjC,IAAI,SAAS,OAAO,EACpB,WAAW,SAAS,aAAa,GAAG,aAAa,EACjD,SAAS,SAAS,eAAe,GAAG,eAAe,EAEnD,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,MAAM,EACnD,OAAO,CAAC,EAAE,mBAAmB,GAC7B,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,CAEhD"}

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);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/core",
-  "version": "1.0.0-next.8",
+  "version": "1.0.0-next.85",
   "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.8",
-    "@hydranium/protocol": "1.0.0-next.8",
+    "@hydranium/langium": "1.0.0-next.85",
+    "@hydranium/protocol": "1.0.0-next.85",
     "@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.8",
-    "@hydranium/protocol": "1.0.0-next.8",
+    "@hydranium/langium": "1.0.0-next.85",
+    "@hydranium/protocol": "1.0.0-next.85",
     "@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';