@hydranium/core 1.0.0-next.201 → 1.0.0-next.203

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

@@ -23,8 +23,8 @@ import { type AstNode, DocumentState, type LangiumDocument, OperationCancelled,
 import { type AstDiagnostic } from '../validation/document-validator.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
 import { ReentrantWriteLockError, isInsideWriteLock, isWriteLockScopeInstalled } from '../workspace/write-lock-scope.js';
-import { CancellationToken, type Disposable } from 'vscode-languageserver';
-import { AstDocument, type AstDocumentSavedEvent, type AstDocumentUpdatedEvent } from '../../documents/ast-document-manager.js';
+import { CancellationToken, Disposable } from 'vscode-languageserver';
+import { AstDocument, type AstDocumentSavedEvent } from '../../documents/ast-document-manager.js';
 import { isConnectionGoneError } from '../../util/connection-liveness.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { IntegrityService } from '../integrity/integrity-service.js';
@@ -33,6 +33,15 @@ import { LANGUAGE_CLIENT_ID } from '../../documents/client-ids.js';
 import { type OpenOptions } from '../../documents/client-session-registry.js';
 import { type ServerSharedServices } from '../module.js';
 import { type ClientSession } from './client-session.js';
+import {
+   type ModelDeletedEvent,
+   type ModelDirtyChangedEvent,
+   type ModelEventFilter,
+   type ModelPhaseFilter,
+   type ModelReleasedEvent,
+   type ModelsBuiltEvent,
+   type ModelUpdatedEvent
+} from './model-events.js';
 
 /**
  * The undo-stack entry for a server-authored write pushed to the editor.
@@ -88,6 +97,12 @@ export interface ModelServiceOptions extends LogNameOptions {
    readonly allowReentrantBuilds?: MaybeObservableValue<boolean>;
 }
 
+/** One {@link ModelService.onModelUpdated} subscription; `uri` is canonical, absent for every document. */
+export interface ModelUpdateSubscriber<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> {
+   readonly uri?: CanonicalUri;
+   readonly listener: (event: ModelUpdatedEvent<TAst, TDiagnostic>) => void;
+}
+
 /** Options for a {@link DefaultModelService} wait on one document. */
 export interface SyncedWaitOptions {
    /**
@@ -157,12 +172,9 @@ export interface SyncedWaitOptions {
  * the injected `TransferEncoder` — symmetric with the
  * `getModelDocument` envelope path.
  *
- * **Subscriptions** ({@link onModelUpdated} / {@link onModelSaved} /
- * {@link onClientClosed}) are thin pass-throughs over
- * `DocumentBuilder.onDocumentPhase` and
- * `HydraniumTextDocuments.onDidSave` / `onDidClose`. Filtering
- * by URI happens here so consumers can subscribe per-document without
- * implementing the URI gate at each callsite.
+ * **Subscriptions** (`on*`) are how a head follows documents; it subscribes
+ * here rather than to the builder or the text store. Each takes a filter, and
+ * one without a `uri` hears every document.
  *
  * **Two families.** `waitFor*` only waits: it rejects for a URI with no
  * document, and for a root behind the store's text it waits for whatever
@@ -256,9 +268,28 @@ export interface ModelService<
    modelToText(uri: string, model: TTransfer | string, cancelToken?: CancellationToken): Promise<string>;
    getDocument(uri: string): LangiumDocument | undefined;
 
-   onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
-   onModelSaved(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void): Disposable;
-   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
+   /**
+    * Fires as a document reaches the filter's phase, `Validated` by default.
+    * Listeners run inside the build, so one that throws is logged and the
+    * others still run.
+    */
+   onModelUpdated(listener: (event: ModelUpdatedEvent<TAst, TDiagnostic>) => void, filter?: ModelPhaseFilter): Disposable;
+   /**
+    * Fires once per build that reaches the phase, with every document it
+    * carried there. A listener that throws is logged, as for {@link onModelUpdated}.
+    */
+   onModelsBuilt(listener: (event: ModelsBuiltEvent) => void, filter?: Pick<ModelPhaseFilter, 'phase'>): Disposable;
+   /**
+    * Fires for every save, whichever client made it, as the store announces
+    * it. A document saved before its first build arrives as an empty envelope
+    * at `UNRECORDED_VERSION`, whose `root` is `undefined` despite its type.
+    */
+   onModelSaved(listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void, filter?: ModelEventFilter): Disposable;
+   onModelDeleted(listener: (event: ModelDeletedEvent) => void, filter?: ModelEventFilter): Disposable;
+   onDirtyChanged(listener: (event: ModelDirtyChangedEvent) => void, filter?: ModelEventFilter): Disposable;
+   onModelReleased(listener: (event: ModelReleasedEvent) => void, filter?: ModelEventFilter): Disposable;
+   /** Fires when `filter.clientId` closes `filter.uri`, its session ending included. */
+   onClientClosed(listener: () => void, filter: { readonly uri: string; readonly clientId: string }): Disposable;
 
    /**
     * Start a client session, the only way to open and write documents through
@@ -269,6 +300,12 @@ export interface ModelService<
     * held by another live session or has documents open under it as a client
     * that is not a session.
     *
+    * A `resumeToken` matching the one the live session under `clientId` was
+    * started with ends that session as lost first, so the documents it was
+    * last to hold keep their unsaved text for the new one. The token guards
+    * against taking over a session by accident, not against a peer: anyone who
+    * knows it can end the session.
+    *
     * `TOpenOptions` types the options the session's `open` takes and its
     * `openOptions` returns. The narrowing is an unchecked cast, and it holds
     * only for the caller that started the session: a holder reached through
@@ -276,7 +313,8 @@ export interface ModelService<
     */
    createSession<TOpenOptions extends OpenOptions = OpenOptions>(
       label?: string,
-      clientId?: string
+      clientId?: string,
+      options?: { readonly resumeToken?: string }
    ): ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>;
    /** The live session started under `clientId`, or `undefined` once it has ended or was never started. */
    getSession(clientId: string): ClientSession<TAst, TDiagnostic, TTransfer> | undefined;
@@ -327,6 +365,13 @@ export class DefaultModelService<
     * this service.
     */
    protected sessionCloseListener?: Disposable;
+   /** The token each live session was started with, by client id, for a takeover by {@link createSession}. */
+   protected readonly resumeTokens = new Map<string, string>();
+   /**
+    * The {@link onModelUpdated} subscribers, by phase. One builder listener per
+    * phase serves them all, kept for the life of the service.
+    */
+   protected readonly updateSubscribers = new Map<DocumentState, Set<ModelUpdateSubscriber<TAst, TDiagnostic>>>();
 
    /**
     * Workspace-level readiness gate. Resolves when the framework has
@@ -837,18 +882,25 @@ export class DefaultModelService<
 
    createSession<TOpenOptions extends OpenOptions = OpenOptions>(
       label?: string,
-      clientId?: string
+      clientId?: string,
+      options: { readonly resumeToken?: string } = {}
    ): ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions> {
       const sessionLabel = label ?? 'session';
       const id = clientId ?? `${sessionLabel}#${globalThis.crypto.randomUUID()}`;
       const textDocuments = this.services.workspace.TextDocuments;
+      if (options.resumeToken !== undefined && this.resumeTokens.get(id) === options.resumeToken) {
+         this.sessions.get(id)?.dispose('lost');
+      }
       textDocuments.registerSession(id);
       this.sessionCloseListener ??= textDocuments.onDidCloseSession(event => {
          // Also reached when the store ends a session directly; disposing the
          // handle makes its later calls fail rather than write under an id
-         // this service no longer treats as a session.
-         this.sessions.get(event.clientId)?.dispose();
+         // this service no longer treats as a session. Forgotten first: a
+         // dispose listener may start a replacement under the same id.
+         const ended = this.sessions.get(event.clientId);
          this.sessions.delete(event.clientId);
+         this.resumeTokens.delete(event.clientId);
+         ended?.dispose(event.cause);
       });
       let session: ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>;
       try {
@@ -866,6 +918,9 @@ export class DefaultModelService<
          throw err;
       }
       this.sessions.set(id, session);
+      if (options.resumeToken !== undefined) {
+         this.resumeTokens.set(id, options.resumeToken);
+      }
       return session;
    }
 
@@ -1052,41 +1107,148 @@ export class DefaultModelService<
    }
 
    // ============================================================
-   // Subscription pass-throughs
+   // Subscriptions
    // ============================================================
 
-   /**
-    * Subscribe to AST-snapshot updates for `uri`. Fires after each
-    * rebuild that reaches the target phase. Delegates to the
-    * `HydraniumTextDocuments` — single listener registration shared with
-    * any direct `HydraniumTextDocuments.onUpdate` subscriber, so the same
-    * underlying `DocumentBuilder.onDocumentPhase` listener serves both
-    * call paths. The event's reason, source and cause are
-    * {@link AstDocumentManager.attributeUpdate}'s.
-    */
-   onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable {
-      return this.services.workspace.AstDocumentManager.onUpdate(uri, listener as never);
+   onModelUpdated(listener: (event: ModelUpdatedEvent<TAst, TDiagnostic>) => void, filter: ModelPhaseFilter = {}): Disposable {
+      const phase = filter.phase ?? DocumentState.Validated;
+      let subscribers = this.updateSubscribers.get(phase);
+      if (!subscribers) {
+         const created = new Set<ModelUpdateSubscriber<TAst, TDiagnostic>>();
+         this.updateSubscribers.set(phase, created);
+         this.services.workspace.DocumentBuilder.onDocumentPhase(
+            phase,
+            labelPhaseListener(
+               (document, cancelToken) => this.deliverUpdate(phase, created, document, cancelToken),
+               'ModelService.onModelUpdated'
+            )
+         );
+         subscribers = created;
+      }
+      const subscriber = { uri: this.filterUri(filter), listener };
+      subscribers.add(subscriber);
+      return Disposable.create(() => subscribers.delete(subscriber));
    }
 
-   /**
-    * Subscribe to save events for `uri`. Fires on every persist through
-    * the multi-client text-document store — including saves originated
-    * by other heads (LSP editor `Ctrl+S`, the data-server `save`, etc.)
-    * so subscribers see one consistent stream regardless of who wrote
-    * the file. Delegates to the manager — single listener registration
-    * shared with any direct `HydraniumTextDocuments.onSave` subscriber.
-    */
-   onModelSaved(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void): Disposable {
-      return this.services.workspace.AstDocumentManager.onSave(uri, listener as never);
+   onModelsBuilt(listener: (event: ModelsBuiltEvent) => void, filter: Pick<ModelPhaseFilter, 'phase'> = {}): Disposable {
+      const phase = filter.phase ?? DocumentState.Validated;
+      return this.services.workspace.DocumentBuilder.onBuildPhase(phase, (built, cancelToken) => {
+         if (cancelToken.isCancellationRequested) {
+            return;
+         }
+         try {
+            listener(Object.freeze({ uris: built.map(document => this.uriPolicy.canonicalUri(document.uri.toString())), phase }));
+         } catch (err: unknown) {
+            this.tracer.error(`onModelsBuilt listener threw: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+         }
+      });
+   }
+
+   onModelSaved(listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void, filter: ModelEventFilter = {}): Disposable {
+      const target = this.filterUri(filter);
+      return this.services.workspace.TextDocuments.onDidSave(event => {
+         // LangiumDocuments keys by the canonical form, the saved event by the
+         // client-facing one.
+         const uri = this.uriPolicy.canonicalUri(event.document.uri);
+         if (this.matches(target, uri)) {
+            listener({ document: this.toAstDocument(UriUtils.toUri(uri)), sourceClientId: event.clientId });
+         }
+      });
+   }
+
+   onModelDeleted(listener: (event: ModelDeletedEvent) => void, filter: ModelEventFilter = {}): Disposable {
+      const target = this.filterUri(filter);
+      return this.services.workspace.DocumentBuilder.onUpdate((_changed, deleted) => {
+         for (const deletedUri of deleted) {
+            const uri = this.uriPolicy.canonicalUri(deletedUri.toString());
+            if (this.matches(target, uri)) {
+               listener(Object.freeze({ uri }));
+            }
+         }
+      });
+   }
+
+   onDirtyChanged(listener: (event: ModelDirtyChangedEvent) => void, filter: ModelEventFilter = {}): Disposable {
+      const target = this.filterUri(filter);
+      return this.services.workspace.TextDocuments.onDidChangeDirty(event => {
+         if (this.matches(target, event.uri)) {
+            listener(event);
+         }
+      });
+   }
+
+   onModelReleased(listener: (event: ModelReleasedEvent) => void, filter: ModelEventFilter = {}): Disposable {
+      const target = this.filterUri(filter);
+      return this.services.workspace.TextDocuments.onDidCloseLastOpen(event => {
+         if (this.matches(target, event.uri)) {
+            listener(event);
+         }
+      });
+   }
+
+   onClientClosed(listener: () => void, filter: { readonly uri: string; readonly clientId: string }): Disposable {
+      const target = this.uriPolicy.canonicalUri(filter.uri);
+      return this.services.workspace.TextDocuments.onDidClose(event => {
+         if (event.clientId === filter.clientId && this.uriPolicy.canonicalUri(event.document.uri) === target) {
+            listener();
+         }
+      });
+   }
+
+   protected filterUri(filter: ModelEventFilter): CanonicalUri | undefined {
+      return filter.uri === undefined ? undefined : this.uriPolicy.canonicalUri(filter.uri);
+   }
+
+   protected matches(target: CanonicalUri | undefined, uri: CanonicalUri): boolean {
+      return target === undefined || target === uri;
    }
 
    /**
-    * Subscribe to the `(uri, clientId)` close event. Delegates to the
-    * manager so the listener registry is shared with any direct
-    * `HydraniumTextDocuments.onClientClosed` subscriber.
+    * Hand every subscriber of `phase` for `document` one event, built once, so
+    * all of them see the same attribution. Built inside the build's listener
+    * and handed out without an await: after one, another build can have reset
+    * the document.
     */
-   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable {
-      return this.services.workspace.AstDocumentManager.onClientClosed(uri, clientId, listener);
+   protected deliverUpdate(
+      phase: DocumentState,
+      subscribers: ReadonlySet<ModelUpdateSubscriber<TAst, TDiagnostic>>,
+      document: LangiumDocument,
+      cancelToken: CancellationToken
+   ): void {
+      if (cancelToken.isCancellationRequested || subscribers.size === 0) {
+         return;
+      }
+      const uri = this.uriPolicy.canonicalUri(document.uri.toString());
+      const matching = [...subscribers].filter(subscriber => this.matches(subscriber.uri, uri));
+      if (matching.length === 0) {
+         return;
+      }
+      const manager = this.services.workspace.AstDocumentManager;
+      const envelope = manager.toAstDocument(document) as AstDocument<TAst, TDiagnostic>;
+      const event: ModelUpdatedEvent<TAst, TDiagnostic> = Object.freeze({
+         // Copied: a validation run without a reset, of further categories,
+         // appends to the live array.
+         document:
+            phase >= DocumentState.Validated
+               ? { ...envelope, ...(envelope.diagnostics && { diagnostics: [...envelope.diagnostics] }) }
+               : (this.withoutDiagnostics(envelope) as AstDocument<TAst, TDiagnostic>),
+         ...manager.attributeUpdate(document),
+         phase
+      });
+      for (const { listener } of matching) {
+         // A write queued by an earlier listener cancels this build. Thrown,
+         // so the builder leaves the version undelivered for those skipped.
+         if (cancelToken.isCancellationRequested) {
+            throw OperationCancelled;
+         }
+         try {
+            listener(event);
+         } catch (err: unknown) {
+            this.tracer
+               .with(uri)
+               .error(`onModelUpdated listener threw: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+         }
+      }
    }
 
    // ============================================================

package/src/langium/service-registry.ts

@@ -316,6 +316,28 @@ export class ExtendedServiceRegistry<
       return owners.length === 1 ? owners[0] : undefined;
    }
 
+   /**
+    * The language the strongest signal given names: a declared `languageId`,
+    * then `target`'s document, then the only registered language, then the sole
+    * producer of `type`. `undefined` when none answers, which leaves the
+    * fallback to the caller, since it differs per caller.
+    *
+    * A declared id comes first because every later signal is inferred, and an
+    * inference must not override a caller that said which grammar it means.
+    */
+   getLanguageFor(hint: { readonly languageId?: string; readonly target?: LanguageTarget; readonly type?: string }): TServices | undefined {
+      const declared = hint.languageId === undefined ? undefined : this.getServicesById(hint.languageId);
+      const located = declared ?? this.getServicesFor(hint.target);
+      if (located) {
+         return located;
+      }
+      const all = this.all;
+      if (all.length === 1) {
+         return all[0];
+      }
+      return hint.type === undefined ? undefined : this.soleServicesByType(hint.type);
+   }
+
    /**
     * Drop the memoised type index, so a language registered after the first
     * type lookup is accounted for. The reason this index belongs on the

package/src/langium/transfer/transfer-encoder.ts

@@ -408,9 +408,8 @@ export class DefaultTransferEncoder<
 
    /**
     * Build a wire {@link EncodedTransferDocument} envelope from a server-internal
-    * {@link AstDocument} snapshot (the AST-typed envelope emitted by
-    * `AstDocumentManager.onUpdate` / `onSave` and returned from
-    * `ModelService.request` / `update` / `save`). Distinct from
+    * {@link AstDocument} snapshot (the AST-typed envelope `ModelService`'s
+    * events carry and its reads and session writes return). Distinct from
     * {@link toTransferDocument}(`LangiumDocument`) which encodes against
     * the live build artifact — adopter facade returns hold the snapshot
     * directly, and this helper bridges that to the wire shape without a

package/src/langium/workspace/document-uri-policy.ts

@@ -51,8 +51,7 @@ export function findRealpathDivergence(uri: URI | string, fs: RealpathCapableFil
  * - {@link canonicalUri} — TOTAL: maps any URI to the single canonical *string*
  *   the framework keys a document by, regardless of whether the file exists.
  *   This is the form that MUST match the adopter's `LangiumDocuments` keying so
- *   the text store, AST-document event filters
- *   (`AstDocumentManager.onUpdate` / `onSave` / `onClientClosed`), and
+ *   the text store, `ModelService`'s event filters, and
  *   `LangiumDocuments` lookups all agree on one identity for the same file. Use
  *   for keying, comparison, and the text-store ↔ document-store bridges.
  *

package/src/testing/stub-ast-document-manager.ts

@@ -10,12 +10,7 @@
 import { type AstNode, type LangiumDocument, UriUtils } from '@hydranium/langium';
 import { Disposable } from 'vscode-languageserver';
 import { type AstDiagnostic } from '../langium/validation/document-validator.js';
-import {
-   AstDocument,
-   type AstDocumentManager,
-   type AstDocumentUpdatedEvent,
-   type UpdateAttribution
-} from '../documents/ast-document-manager.js';
+import { AstDocument, type AstDocumentManager, type UpdateAttribution } from '../documents/ast-document-manager.js';
 import { type WritableFileSystemProvider } from '../langium/workspace/file-system-provider.js';
 import { UNKNOWN_CLIENT_ID } from '../documents/client-ids.js';
 import { DefaultModelLedger, type ModelLedger } from '../documents/model-ledger.js';
@@ -24,16 +19,11 @@ import type { StubHydraniumTextDocuments } from './stub-hydranium-text-documents
 import type { StubLangiumDocuments } from './stub-langium-documents.js';
 
 /**
- * Minimal stub of {@link AstDocumentManager} for use in test
- * harnesses. Implements just the methods the model service and client
- * sessions call (`open` / `close` / `update` / `save` / `isOpen` /
- * `getDocument`);
- * `onSave` / `onClientClosed` forward to the underlying stub text store,
- * `onUpdate` is driven explicitly
- * through {@link StubAstDocumentManager.emitUpdate} because the stub tree runs
- * no build phases to emit from, and the remaining read helpers
- * (`getAuthor`) throw if invoked — tests that need them
- * should wire a richer stub or use the real {@link AstDocumentManager}.
+ * Minimal stub of {@link AstDocumentManager} for use in test harnesses,
+ * implementing what the model service and client sessions call. `getAuthor`
+ * throws if invoked, and `attributeUpdate` reports every update as its
+ * author's change; tests that need either should wire a richer stub or use
+ * the real {@link AstDocumentManager}.
  *
  * Open state is tracked per URI as the set of holding client ids, so a
  * document stays open until its last client closes. The stub forwards
@@ -51,61 +41,9 @@ import type { StubLangiumDocuments } from './stub-langium-documents.js';
  */
 export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> extends Pick<
    AstDocumentManager<TAst, TDiagnostic>,
-   | 'open'
-   | 'close'
-   | 'isOpen'
-   | 'update'
-   | 'save'
-   | 'onUpdate'
-   | 'onSave'
-   | 'onClientClosed'
-   | 'getAuthor'
-   | 'getDocument'
-   | 'toAstDocument'
-   | 'attributeUpdate'
+   'open' | 'close' | 'isOpen' | 'update' | 'save' | 'getAuthor' | 'getDocument' | 'toAstDocument' | 'attributeUpdate'
 > {
    readonly openClients: Map<string, Set<string>>;
-
-   /**
-    * Deliver an update event to every live {@link StubAstDocumentManager.onUpdate}
-    * subscriber for `uri`. Returns how many listeners received it.
-    *
-    * **This exists because `onUpdate` cannot fire on its own, and that is a
-    * trap without a driver.** The real manager emits from a
-    * `DocumentBuilder.onDocumentPhase(Validated)` hook; a `makeTestServices`
-    * tree has a stub builder that runs no phases, so a subscription made
-    * through the stub would never be called. A test written as
-    * `onUpdate(uri, …); await tick(); expect(events).toHaveLength(0)` therefore
-    * passes for the wrong reason — the listener was never wired to anything —
-    * and reads as coverage of a suppression path it never reached. Driving the
-    * event explicitly is what lets such a test first prove delivery works, so
-    * the negative assertion means something.
-    *
-    * **The return value is the point, not a convenience.** `0` says no
-    * subscriber for that URI was registered, which is the state a negative
-    * assertion cannot distinguish from correct suppression. Assert it is
-    * non-zero before believing an empty event list.
-    *
-    * Two alternatives were rejected. Making `onUpdate` THROW would fence the
-    * hazard at zero API cost, but this harness ships (`files: ["lib", "src"]`)
-    * and an adopter subclass or test that subscribes and legitimately ignores
-    * the event would start failing on a stub it never asked to fire. Wiring the
-    * stub to the text-document store's change notifications — the way `onSave`
-    * is wired — would make it fire on its own, which moves the pass reason of
-    * every existing suite on a `makeTestServices` tree and asserts a phase
-    * semantics (`Validated`, with the real manager's author lookup and
-    * `changed`/`deleted`/`rebuilt` classification) that no stub tree has.
-    */
-   emitUpdate(uri: string, event: AstDocumentUpdatedEvent<TAst, TDiagnostic>): number;
-
-   /**
-    * How many live {@link StubAstDocumentManager.onUpdate} subscribers `uri`
-    * has, or the total across every URI when called with no argument.
-    *
-    * Read from outside — it is what a test asserts to show a subscription was
-    * actually established, and what makes {@link emitUpdate}'s `0` legible.
-    */
-   updateSubscriptions(uri?: string): number;
 }
 
 export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic>(
@@ -115,10 +53,6 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic ext
    ledger: ModelLedger = new DefaultModelLedger()
 ): StubAstDocumentManager<TAst, TDiagnostic> {
    const openClients = new Map<string, Set<string>>();
-   // Keyed by the URI as given, not canonicalized: the stub has no URI policy,
-   // and `getDocument` below looks documents up by their given URI for the same
-   // reason, so both halves agree on identity.
-   const updateListeners = new Map<string, Set<(event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void>>();
    const notSupported = (method: string): never => {
       throw new Error(`StubAstDocumentManager.${method} is not implemented; wire the real AstDocumentManager if your test needs it.`);
    };
@@ -162,59 +96,6 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic ext
          textDocuments.notifyDidSaveTextDocument({ textDocument: { uri }, text }, clientId);
          return version;
       },
-      // Registers the listener but never calls it by itself — the real manager
-      // emits from a `DocumentBuilder.onDocumentPhase(Validated)` hook and the
-      // stub tree runs no phases. `emitUpdate` is the only thing that fires it;
-      // see its declaration for why that is a driver rather than a throw or an
-      // autonomous wiring.
-      onUpdate(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable {
-         const listeners = updateListeners.get(uri) ?? new Set<(event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void>();
-         listeners.add(listener);
-         updateListeners.set(uri, listeners);
-         return Disposable.create(() => {
-            listeners.delete(listener);
-            if (listeners.size === 0) {
-               updateListeners.delete(uri);
-            }
-         });
-      },
-      emitUpdate(uri: string, event: AstDocumentUpdatedEvent<TAst, TDiagnostic>): number {
-         // Snapshot before iterating: a listener that disposes itself on first
-         // delivery would otherwise mutate the set mid-iteration.
-         const listeners = [...(updateListeners.get(uri) ?? [])];
-         for (const listener of listeners) {
-            listener(event);
-         }
-         return listeners.length;
-      },
-      updateSubscriptions(uri?: string): number {
-         if (uri !== undefined) {
-            return updateListeners.get(uri)?.size ?? 0;
-         }
-         let total = 0;
-         for (const listeners of updateListeners.values()) {
-            total += listeners.size;
-         }
-         return total;
-      },
-      onSave(uri: string, listener: (event: { document: AstDocument<TAst, TDiagnostic>; sourceClientId: string }) => void): Disposable {
-         return textDocuments.onDidSave(event => {
-            if (event.document.uri !== uri) {
-               return;
-            }
-            listener({
-               document: AstDocument.create<TAst, TDiagnostic>(uri, textDocuments.version(uri), undefined as unknown as TAst),
-               sourceClientId: event.clientId
-            });
-         });
-      },
-      onClientClosed(uri: string, clientId: string, listener: () => void): Disposable {
-         return textDocuments.onDidClose(event => {
-            if (event.clientId === clientId && event.document.uri === uri) {
-               listener();
-            }
-         });
-      },
       getAuthor(): string {
          return notSupported('getAuthor');
       },

package/src/testing/stub-document-builder.ts

@@ -13,6 +13,7 @@ import {
    type DocumentPhaseListener,
    type DocumentState,
    type DocumentUpdateListener,
+   isOperationCancelled,
    type LangiumDocument,
    type URI,
    type WorkspaceLock
@@ -90,7 +91,7 @@ export interface StubDocumentBuilder
    readonly waitUntilCalls: ReadonlyArray<RecordedBuilderCall<[DocumentState, URI | undefined]>>;
    /**
     * Synchronously fire the phase listener(s) registered for `state` with
-    * `document`, then, unless `cancelToken` is cancelled, the
+    * `document`, then, unless a listener was cancelled, the
     * `onDocumentPhaseDelivered` listeners. `cancelToken` defaults to a
     * non-cancelled token; pass a cancelled token to simulate a build preempted
     * by a concurrent write lock.
@@ -217,10 +218,25 @@ export function makeStubDocumentBuilder(workspaceLock?: WorkspaceLock): StubDocu
          // may stand in for a write that moves the version on. Read only when
          // someone is told, since many fakes carry no text document.
          const version = delivered.length > 0 ? document.textDocument.version : 0;
+         // As the real builder: a listener reached on a cancelled token, or
+         // throwing OperationCancelled, counts as cancelled and withholds the
+         // delivered listeners.
+         let cancelledListeners = 0;
          for (const listener of listeners) {
-            reraise(listener(document, token));
+            if (token.isCancellationRequested) {
+               cancelledListeners++;
+               continue;
+            }
+            try {
+               reraise(listener(document, token));
+            } catch (err: unknown) {
+               if (!isOperationCancelled(err)) {
+                  throw err;
+               }
+               cancelledListeners++;
+            }
          }
-         if (!token.isCancellationRequested) {
+         if (cancelledListeners === 0) {
             for (const listener of delivered) {
                listener(document, version);
             }

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

@@ -283,7 +283,7 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
       registerSession(clientId) {
          sessions.register(clientId);
       },
-      closeSession(clientId) {
+      closeSession(clientId, cause) {
          if (!sessions.isRegistered(clientId)) {
             return;
          }
@@ -292,7 +292,7 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
                stub.fireClose(uri, clientId);
             }
          } finally {
-            sessions.unregister(clientId);
+            sessions.unregister(clientId, cause);
          }
       },
       get onDidCloseSession() {

package/src/testing/stub-service-registry.ts

@@ -29,7 +29,7 @@ export interface StubLanguageDescriptor {
     * AST `$type`s this language's grammar produces. Synthesised into a minimal
     * `Grammar` — one entry-less parser rule per type — which is exactly what
     * `collectProducibleTypes` reads, so type→language routing
-    * (`buildLanguageTypeIndex`, `DataServer.resolveReferenceLanguage`) resolves
+    * (`buildLanguageTypeIndex`, `ExtendedServiceRegistry.getLanguageFor`) resolves
     * against this stub the same way it does against generated grammars.
     *
     * Entry-less on purpose: `reachableParserRules` falls back to every parser