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

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,10 +433,28 @@ export class AstDocumentManager<TAst extends AstNode = AstNode, TDiagnostic = un
       // transiently breaks cross-document linking mid-rebuild (a dependent briefly
       // seeing an `extends`/`type` reference unresolved). And because the constructor
       // wires `onDidOpen -> this.open`, it would fire a second, identical rebuild on
-      // every first open. So an already-open `open()` is a no-op.
+      // every first open.
+      //
+      // So an already-open `open()` records the attaching client's open and nothing
+      // else. The open is per `(uri, clientId)` and the last-close revert counts down
+      // to it, so skipping it lets the first client's close tear down a document
+      // another client is still reading. A document waiting out the revert grace
+      // is still loaded: a client lost from it within its own grace attaches and
+      // keeps its text, and for any other client the attach releases it, so the
+      // open reads the file.
+      if (this.isOpen(args.uri)) {
+         this.textDocuments.attachClient(args.uri, args.clientId);
+      }
       if (!this.isOpen(args.uri)) {
          const textDocument = await this.createDocumentFromTextOrFileSystem(args.uri, args.languageId, args.version, args.text);
+         const creates = !this.isOpen(args.uri);
          this.textDocuments.notifyDidOpenTextDocument({ textDocument }, args.clientId);
+         if (creates && args.text !== undefined) {
+            // Text the caller supplies was not read from the file, so no file
+            // is assumed: the document is dirty until its first save, whatever
+            // the file holds.
+            this.textDocuments.updateDiskBaseline(args.uri, undefined);
+         }
       }
       return Disposable.create(() => this.close(args));
    }
@@ -393,31 +489,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 +582,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';