@hydranium/core 1.0.0-next.200 → 1.0.0-next.202

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

@@ -27,7 +27,7 @@ import { Disposable } from 'vscode-languageserver';
 import { TextDocumentIdentifier, type TextDocumentItem } from 'vscode-languageserver-protocol';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
 import { type ServerSharedServices } from '../langium/module.js';
-import { type HydraniumDocumentBuilder, labelPhaseListener } from '../langium/document-builder/index.js';
+import { type HydraniumDocumentBuilder } from '../langium/document-builder/index.js';
 import { UNKNOWN_CLIENT_ID } from './client-ids.js';
 import { type HydraniumTextDocuments } from './hydranium-text-documents.js';
 import { type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
@@ -38,9 +38,8 @@ export interface UpdateInfo {
 }
 
 /**
- * Server-internal document envelope at the AST layer. Emitted by
- * {@link AstDocumentManager.onUpdate} / {@link AstDocumentManager.onSave}
- * for in-process subscribers (`ModelService`, integrity service, etc.).
+ * Server-internal document envelope at the AST layer, which `ModelService`
+ * reads and events hand to in-process callers.
  *
  * `root` is the live AST the build holds, not an encoded copy like
  * `TransferDocument.model`, so mutating it changes the model every reader sees.
@@ -83,12 +82,12 @@ export namespace AstDocument {
    }
 }
 
-/** Update event delivered by {@link AstDocumentManager.onUpdate} — typed alias over the generic event wrapper. */
+/** The update event a document's build delivers, typed over the generic event wrapper. */
 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. */
+/** The event a save delivers, typed over the generic event wrapper. */
 export type AstDocumentSavedEvent<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> = TransferSavedEvent<
    AstDocument<TAst, TDiagnostic>
 >;
@@ -120,8 +119,8 @@ export interface AstDocumentManagerOptions extends 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.
+ * open/close/update/save and the attribution of update events, with the LSP
+ * plumbing hidden. Events are `ModelService`'s, which builds them from here.
  *
  * Generic over `<TAst extends AstNode, TDiagnostic>` so each consumer projects
  * its own AST root type and diagnostic shape into the emitted
@@ -152,10 +151,6 @@ export interface AstDocumentManager<TAst extends AstNode, TDiagnostic extends As
     */
    save(uri: string, clientId: string): Promise<TextVersion>;
 
-   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;
 
    /**
@@ -174,12 +169,13 @@ export interface AstDocumentManager<TAst extends AstNode, TDiagnostic extends As
 
    /**
     * The reason, source and cause of an update event for `document` emitted
-    * now, from a phase listener of the build that carries it. Every head takes
-    * its update events' attribution from here, so they name the same client
-    * for one build. For a document a client opened, while rebuilds validate,
-    * the answer changes once its `Validated` listeners have all run: a later
-    * event at that version is `'rebuilt'`. `TransferDocumentUpdateReason`
-    * names the cases that fall back to the last update.
+    * now, from a phase listener of the build that carries it. `ModelService`
+    * takes its update events' attribution from here, once per document and
+    * phase, so every subscriber names the same client for one build. For a
+    * document a client opened, while rebuilds validate, the answer changes
+    * once its `Validated` listeners have all run: a later event at that
+    * version is `'rebuilt'`. `TransferDocumentUpdateReason` names the cases
+    * that fall back to the last update.
     */
    attributeUpdate(document: LangiumDocument): UpdateAttribution;
 }
@@ -329,64 +325,6 @@ export class DefaultAstDocumentManager<
       return languages.length === 1 ? languages[0].LanguageMetaData.languageId : 'plaintext';
    }
 
-   /**
-    * Subscribe to the save event of the document at `uri`. The callback fires only when the
-    * URI of the saved document matches `uri` (compared by canonical form).
-    */
-   onSave(uri: string, listener: (event: TransferSavedEvent<AstDocument<TAst, TDiagnostic>>) => void | Promise<void>): Disposable {
-      const target = this.uriPolicy.canonicalUri(uri);
-      return this.textDocuments.onDidSave(async event => {
-         if (this.uriPolicy.canonicalUri(event.document.uri) !== target) {
-            return undefined;
-         }
-         // Look the document up by its canonical URI: the adopter's
-         // `LangiumDocuments` keys by the canonical form, while the saved
-         // event carries the (possibly symlinked) client-facing URI.
-         const documentURI = UriUtils.toUri(target);
-         if (documentURI !== undefined && this.langiumDocs.hasDocument(documentURI)) {
-            const document = await this.langiumDocs.getOrCreateDocument(documentURI);
-            return listener({
-               document: this.toAstDocument(document),
-               sourceClientId: event.clientId
-            });
-         }
-         return undefined;
-      });
-   }
-
-   /** Fires when `clientId` detaches from the document at `uri` (matched by canonical form). */
-   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable {
-      const target = this.uriPolicy.canonicalUri(uri);
-      return this.textDocuments.onDidClose(event => {
-         if (event.clientId === clientId && this.uriPolicy.canonicalUri(event.document.uri) === target) {
-            listener();
-         }
-      });
-   }
-
-   /** Fires when the document at `uri` reaches `Validated` after each rebuild. */
-   onUpdate(uri: string, listener: (event: TransferUpdatedEvent<AstDocument<TAst, TDiagnostic>>) => void): Disposable {
-      const target = this.uriPolicy.canonicalUri(uri);
-      const emitUpdate = (document: LangiumDocument): void => {
-         if (this.uriPolicy.canonicalUri(document.uri) !== target) {
-            return;
-         }
-         // No `'deleted'` reason: `DocumentBuilder.update` drops a deleted
-         // document from `LangiumDocuments` before deriving the rebuild set
-         // from it, so a deleted URI is never built and never reaches this
-         // phase listener. A subscriber needing deletions has to be told on
-         // a channel that does not require a built document.
-         const event: TransferUpdatedEvent<AstDocument<TAst, TDiagnostic>> = {
-            document: this.toAstDocument(document),
-            ...this.attributeUpdate(document)
-         };
-         this.tracer.with(uri).trace(`emitUpdate start: source=${event.sourceClientId}, reason=${event.reason}, cause=${event.causedBy}`);
-         listener(event);
-         this.tracer.with(uri).trace('emitUpdate listener returned');
-      };
-      return this.documentBuilder.onDocumentPhase(DocumentState.Validated, labelPhaseListener(emitUpdate, 'AstDocumentManager.onUpdate'));
-   }
-
    /**
     * The client that authored `document`'s current version, or `undefined` when
     * no client wrote it: a document no client has open. A rebuild that keeps

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

@@ -36,6 +36,7 @@ export type ClientSessionState = 'live' | 'closing';
 /** Delivered by {@link ClientSessionRegistry.onDidCloseSession}. */
 export interface ClientSessionClosedEvent {
    readonly clientId: string;
+   readonly cause: SessionEndCause;
 }
 
 /**
@@ -128,12 +129,12 @@ export class ClientSessionRegistry {
       return this.opensOf(clientId);
    }
 
-   /** Remove `clientId` from the session table and announce it. A no-op for an id that is not registered. */
-   unregister(clientId: string): void {
+   /** Remove `clientId` from the session table and announce it with `cause`. A no-op for an id that is not registered. */
+   unregister(clientId: string, cause: SessionEndCause = 'closed'): void {
       if (!this.sessions.delete(clientId)) {
          return;
       }
-      this.sessionClosedEmitter.fire(Object.freeze({ clientId }));
+      this.sessionClosedEmitter.fire(Object.freeze({ clientId, cause }));
    }
 
    /**

package/src/documents/hydranium-text-documents.ts

@@ -1685,7 +1685,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
             this.notifyDidCloseTextDocument({ textDocument: { uri } }, clientId, cause);
          }
       } finally {
-         this.__sessions.unregister(clientId);
+         this.__sessions.unregister(clientId, cause);
          this.tracer.info(`Session closed: ${this.formatClientId(clientId)}`);
          this.tracer.trace(`Session closed: ${clientId}`);
       }

package/src/langium/document-builder/document-builder.ts

@@ -30,6 +30,7 @@ import { CancellationToken, Diagnostic, Disposable } from 'vscode-languageserver
 import type { HydraniumTextDocuments } from '../../documents/hydranium-text-documents.js';
 import { type VersionSyncService } from '../../documents/version-sync-service.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
+import { IntegrityService } from '../integrity/integrity-service.js';
 import type { MessageRenderer } from '../../messages/renderer.js';
 import { CST_REHYDRATION_RESET_STATE, isCstShed } from '../residency/cst-residency-service.js';
 import { type ExtendedServiceRegistry } from '../service-registry.js';
@@ -357,6 +358,19 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       return `current state: '${docState}', last phase: ${lastPhase}, active build: ${this.formatSession(this.activeSession)}`;
    }
 
+   /**
+    * The last phase a rebuild reaches under {@link updateBuildOptions}:
+    * `Validated`, or {@link IntegrityService.SettledState} when rebuilds do
+    * not validate, since no build then reaches `Validated` and a wait for it
+    * would never end. A document a `shouldValidate` override skips stops
+    * short of it; waiting on it is this builder's to resolve. An override that
+    * returns a phase rebuilds never reach makes every wait for it hang, the
+    * session writes that answer at it included.
+    */
+   finalBuildState(): DocumentState {
+      return this.updateBuildOptions.validation ? DocumentState.Validated : IntegrityService.SettledState;
+   }
+
    /** Render a session for a status line. `undefined` — no build in progress — reads as `none`. */
    protected formatSession(session: BuildSession | undefined): string {
       if (!session) {

package/src/langium/model-service/client-session.ts

@@ -19,13 +19,12 @@ import {
    type Tracer,
    type TransferElement
 } from '@hydranium/protocol';
-import { type AstNode, type DocumentBuilder, DocumentState, UriUtils } from '@hydranium/langium';
-import { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import { type AstNode, UriUtils } from '@hydranium/langium';
+import { type CancellationToken, type Disposable, Emitter, type Event } from 'vscode-languageserver';
 import { type AstDocument, type SavedAstDocument } from '../../documents/ast-document-manager.js';
 import { DocumentNotOpenError, SessionClosedError } from '../../documents/client-session-errors.js';
 import { type OpenOptions, type SessionEndCause } from '../../documents/client-session-registry.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
-import { IntegrityService } from '../integrity/integrity-service.js';
 import { type ServerSharedServices } from '../module.js';
 import { type AstDiagnostic } from '../validation/document-validator.js';
 import { type ModelService } from './model-service.js';
@@ -118,11 +117,11 @@ export interface ClientSession<
    save(args: ClientSessionWriteArgs<TTransfer>, cancelToken?: CancellationToken): Promise<SavedAstDocument<TAst, TDiagnostic>>;
    /**
     * Persist the text the store holds for `args.uri` as it is, with no update
-    * and no serialisation, and resolve to the document as {@link save} does.
-    * The saved event names this session, also when another client wrote the
-    * text.
+    * and no serialisation. Resolves with the version of the text written, once
+    * it is on disk, without waiting for a build. The saved event names this
+    * session, also when another client wrote the text.
     */
-   persist(args: ClientSessionPersistArgs, cancelToken?: CancellationToken): Promise<SavedAstDocument<TAst, TDiagnostic>>;
+   persist(args: ClientSessionPersistArgs): Promise<TextVersion>;
    /** Close this session's open of `uri`, at once. A no-op when it does not have `uri` open. */
    close(uri: string): Promise<void>;
    /**
@@ -142,21 +141,12 @@ export interface ClientSession<
     * reason reverts such a document at once.
     */
    dispose(cause?: SessionEndCause): void;
-}
-
-/**
- * The phase a session write waits for before it answers: `Validated`, or
- * {@link IntegrityService.SettledState} when rebuilds do not validate, since
- * no build then reaches `Validated` and the wait would never end. Read from
- * `updateBuildOptions`, which every rebuild takes; a document a
- * `shouldValidate` override skips is the builder's to resolve.
- *
- * Waiting for the write's own build is not enough: a later write cancels it,
- * and the build that takes over validates the document after the answer was
- * taken.
- */
-function answerState(builder: DocumentBuilder): DocumentState {
-   return builder.updateBuildOptions.validation ? DocumentState.Validated : IntegrityService.SettledState;
+   /**
+    * Fires once the session has ended, its documents closed, with the cause it
+    * ended with. A takeover through `createSession` ends it as `'lost'` from
+    * another caller, so a holder that keeps per-session state releases it here.
+    */
+   readonly onDidDispose: Event<SessionEndCause>;
 }
 
 /**
@@ -197,6 +187,7 @@ export class DefaultClientSession<
    protected readonly openOptionsByUri = new Map<string, TOpenOptions | undefined>();
    /** Drops an open's options from {@link openOptionsByUri} when the store closes the open. */
    protected readonly closeListener: Disposable;
+   protected readonly disposeEmitter = new Emitter<SessionEndCause>();
    /** Logs under `logName`, `ClientSession` when none is given, with this session's id in a bracket of its own, so a line names the session that wrote. */
    protected readonly tracer: Tracer;
    /** The service bound on `model.ModelService`, which serialises and rebuilds for this session. */
@@ -256,9 +247,9 @@ export class DefaultClientSession<
       return this.saveDocument(args, cancelToken);
    }
 
-   persist(args: ClientSessionPersistArgs, cancelToken?: CancellationToken): Promise<SavedAstDocument<TAst, TDiagnostic>> {
+   persist(args: ClientSessionPersistArgs): Promise<TextVersion> {
       this.assertLive();
-      return this.persistDocument(args, cancelToken);
+      return this.persistDocument(args);
    }
 
    close(uri: string): Promise<void> {
@@ -283,6 +274,12 @@ export class DefaultClientSession<
       this.disposed = true;
       this.services.workspace.TextDocuments.closeSession(this.clientId, cause);
       this.closeListener.dispose();
+      this.disposeEmitter.fire(cause ?? 'closed');
+      this.disposeEmitter.dispose();
+   }
+
+   get onDidDispose(): Event<SessionEndCause> {
+      return this.disposeEmitter.event;
    }
 
    protected assertLive(): void {
@@ -328,7 +325,10 @@ export class DefaultClientSession<
     *
     * Resolves with the latest build of the document, which may already carry
     * a newer write; that is logged at debug, and a slow update at warn when
-    * `ClientSessionFactoryOptions.slowUpdateWarnMs` is set.
+    * `ClientSessionFactoryOptions.slowUpdateWarnMs` is set. It waits for the
+    * builder's final phase rather than the write's own build: a later write
+    * cancels that build, and the one that takes over validates the document
+    * after the answer was taken.
     */
    protected async updateDocument(
       args: ClientSessionWriteArgs<TTransfer>,
@@ -353,7 +353,7 @@ export class DefaultClientSession<
       // An override that awaits before calling the base can outlast the build
       // this write already has, and then builds it twice; see
       // `ModelService.rebuild`.
-      const doc = await run('rebuild', () => service.rebuild(uri, answerState(this.services.workspace.DocumentBuilder), cancelToken));
+      const doc = await run('rebuild', () => service.rebuild(uri, this.services.workspace.DocumentBuilder.finalBuildState(), cancelToken));
       const finalVersion = textDocuments.version(uri);
       if (finalVersion > appliedVersion) {
          this.tracer.debug(`Update to v${appliedVersion} ready at v${finalVersion} (changed again before it settled)`);
@@ -409,50 +409,45 @@ export class DefaultClientSession<
       check();
       const applied = uris.map((uri, i) => this.services.workspace.AstDocumentManager.update(uri, texts[i], this.clientId));
       await Promise.all(applied);
-      const state = answerState(this.services.workspace.DocumentBuilder);
+      const state = this.services.workspace.DocumentBuilder.finalBuildState();
       return Promise.all(uris.map(uri => service.rebuild(uri, state, cancelToken)));
    }
 
    /**
-    * Write `args.model` through {@link updateDocument}, so an override of it
-    * applies to saves too, then persist the document.
+    * Write `args.model` through {@link updateDocument}, then persist it through
+    * {@link persistDocument}, so an override of either applies to saves too.
     *
     * Fails with `DocumentNotOpenError` and writes nothing when this session
-    * closes the URI while the text is being built: the check sits in the same
-    * synchronous step as the manager taking the text. Checked any earlier, a
-    * session that closes the URI during the rebuild still has the shared
-    * text, other clients' edits included, written in its name. Once taken,
-    * the write completes whatever the session does next.
+    * closes the URI while the text is being built. Persisted at `'any'`: the
+    * update already gated on `args.baseVersion` and moved the text past it.
     */
    protected async saveDocument(
       args: ClientSessionWriteArgs<TTransfer>,
       cancelToken?: CancellationToken
    ): Promise<SavedAstDocument<TAst, TDiagnostic>> {
       const doc = await this.updateDocument(args, cancelToken);
-      const uri = this.canonicalKey(args.uri);
-      this.assertOpen(uri);
-      const version = await this.services.workspace.AstDocumentManager.save(uri, this.clientId);
+      const version = await this.persistDocument({ uri: args.uri, baseVersion: 'any' });
       return { ...doc, persisted: { version } };
    }
 
    /**
-    * Persist the store's text for `args.uri` under this session's id.
+    * Persist the store's text for `args.uri` under this session's id. Every
+    * write to disk a session makes goes through here, so an override sees each
+    * of them.
     *
     * The open check and the `baseVersion` gate sit in the same synchronous step
     * as the manager taking the text: an await between them lets another
     * client's write land after the gate, and its text is then persisted under
-    * this session's id without this session ever having seen it.
+    * this session's id without this session ever having seen it. An override
+    * that awaits before calling the base lets a diagram save take its
+    * documents' texts at different moments, and a diagram that ends during the
+    * await fails the documents not yet taken with `DocumentNotOpenError`.
     */
-   protected async persistDocument(
-      args: ClientSessionPersistArgs,
-      cancelToken?: CancellationToken
-   ): Promise<SavedAstDocument<TAst, TDiagnostic>> {
+   protected async persistDocument(args: ClientSessionPersistArgs): Promise<TextVersion> {
       const uri = this.canonicalKey(args.uri);
       this.assertOpen(uri);
       this.assertBaseVersion(uri, args.baseVersion, this.services.workspace.TextDocuments.version(uri));
-      const version = await this.services.workspace.AstDocumentManager.save(uri, this.clientId);
-      const doc = await this.modelService.ensureDocumentState(uri, answerState(this.services.workspace.DocumentBuilder), cancelToken);
-      return { ...doc, persisted: { version } };
+      return this.services.workspace.AstDocumentManager.save(uri, this.clientId);
    }
 
    protected async closeDocument(uri: string): Promise<void> {

package/src/langium/model-service/index.ts

@@ -7,5 +7,6 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './model-events.js';
 export * from './model-service.js';
 export * from './client-session.js';

package/src/langium/model-service/model-events.ts

@@ -0,0 +1,74 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+import { type CanonicalUri } from '@hydranium/protocol';
+import { type AstNode, type DocumentState } from '@hydranium/langium';
+import { type AstDocumentUpdatedEvent } from '../../documents/ast-document-manager.js';
+import { type DocumentDirtyChangedEvent } from '../../documents/hydranium-text-documents.js';
+import { type AstDiagnostic } from '../validation/document-validator.js';
+
+/** Which documents a `ModelService` subscription hears about. */
+export interface ModelEventFilter {
+   /** One document, in any spelling; matched by canonical form. Absent for every document. */
+   readonly uri?: string;
+}
+
+/** A {@link ModelEventFilter} for an event a build phase fires. */
+export interface ModelPhaseFilter extends ModelEventFilter {
+   /** Defaults to `Validated`. */
+   readonly phase?: DocumentState;
+}
+
+/**
+ * A document reaching {@link phase} in a build.
+ *
+ * `document` holds for the listener's synchronous run: its root is the one the
+ * build carried to the phase, and at `Validated` its diagnostics are that
+ * build's, copied. A later build can unlink that root in place or replace it,
+ * so a listener that awaits first reads the document again through the phase
+ * reads or `snapshot`.
+ *
+ * Below `Validated` the document carries no diagnostics: any it held would be
+ * an earlier build's.
+ */
+export interface ModelUpdatedEvent<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> extends AstDocumentUpdatedEvent<
+   TAst,
+   TDiagnostic
+> {
+   readonly phase: DocumentState;
+}
+
+/**
+ * The documents one build carried to {@link phase}. Not fired for a cancelled
+ * build, so a document it built shows up in the build that takes over.
+ */
+export interface ModelsBuiltEvent {
+   readonly uris: readonly CanonicalUri[];
+   readonly phase: DocumentState;
+}
+
+/**
+ * A document's file was removed. No build reaches a deleted document, so no
+ * {@link ModelUpdatedEvent} reports it.
+ */
+export interface ModelDeletedEvent {
+   readonly uri: CanonicalUri;
+}
+
+/** A document's text started or stopped differing from its file. */
+export type ModelDirtyChangedEvent = DocumentDirtyChangedEvent;
+
+/**
+ * A document no client has open any more was released and reverts to disk.
+ * The rebuild that reverts it follows as a {@link ModelUpdatedEvent}, unless a
+ * client opens the document first or its file is deleted.
+ */
+export interface ModelReleasedEvent {
+   readonly uri: CanonicalUri;
+}