@hydranium/core 1.0.0-next.115 → 1.0.0-next.117

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

@@ -0,0 +1,257 @@
+/********************************************************************************
+ * 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 MaybePromise, type TransferElement, type TransferSaveArgs, type TransferUpdateArgs } from '@hydranium/protocol';
+import { type AstNode, UriUtils } from '@hydranium/langium';
+import { type CancellationToken } from 'vscode-languageserver';
+import { type AstDocument } from '../../documents/ast-document-manager.js';
+import { SessionClosedError } from '../../documents/client-session-errors.js';
+import { type OpenOptions } from '../../documents/client-session-registry.js';
+import { type ServerSharedServices } from '../module.js';
+import { type AstDiagnostic } from '../validation/document-validator.js';
+import { type ModelService } from './model-service.js';
+
+/**
+ * One participant's handle on the documents it works on, started by
+ * `ModelService.createSession`.
+ *
+ * The session writes only what it has open: `update` and `save` fail with
+ * `DocumentNotOpenError` unless this session has the URI open when the text is
+ * applied, and the check and the apply are one synchronous step, so a write
+ * either lands while the document is open or fails. A document stays open until
+ * this session closes it, the session ends, or the file is deleted.
+ *
+ * One open per URI, without reference counting: opening a URI the session
+ * already has open changes nothing, and one `close` ends it.
+ *
+ * After `dispose`, every other member throws `SessionClosedError`
+ * synchronously, before returning a promise.
+ *
+ * Reads need no session and live on `ModelService`.
+ */
+export interface ClientSession<
+   TAst extends AstNode,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
+   TTransfer extends TransferElement = TransferElement,
+   TOpenOptions extends OpenOptions = OpenOptions
+> {
+   /** Unique in the process while the session is live: the author label on its writes and the key of its opens. */
+   readonly clientId: string;
+   readonly label: string;
+
+   /**
+    * Open `uri` for this session, reading it from disk unless some client has
+    * it open already. `options` are kept for this open until it closes; a
+    * repeat open, concurrent or not, keeps the options of the first.
+    */
+   open(uri: string, options?: TOpenOptions): Promise<void>;
+   /**
+    * Create a document with `text` and open it for this session. It reaches
+    * disk on the first `save`. Fails when the file exists or any client has the
+    * URI open, and of two creates of one URI at most one succeeds.
+    */
+   create(uri: string, text: string): Promise<void>;
+   update(args: Omit<TransferUpdateArgs<TTransfer>, 'clientId'>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   /** Write `args.model` as {@link update} does, then persist the document. */
+   save(args: Omit<TransferSaveArgs<TTransfer>, 'clientId'>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   /** Close this session's open of `uri`, at once. A no-op when it does not have `uri` open. */
+   close(uri: string): Promise<void>;
+   /**
+    * Open `uri`, run `fn`, and close `uri` when `fn` settles, whether it
+    * returned or threw. A URI the session already had open, or is still
+    * opening through another call, stays open: the close undoes only the open
+    * this call made.
+    */
+   withOpen<T>(uri: string, fn: () => MaybePromise<T>): Promise<T>;
+   /** Whether an event's `sourceClientId` names this session, i.e. the event echoes its own write. */
+   isOwnEcho(sourceClientId: string): boolean;
+   /** End the session: close everything it has open and free its id. Idempotent. */
+   dispose(): void;
+}
+
+/**
+ * The framework's {@link ClientSession}, built by
+ * `DefaultModelService.newSession`.
+ *
+ * Writes go through the owning `ModelService`, so its overrides apply to a
+ * session's writes as they do to anyone's. The open rule is enforced there, not
+ * here, because only the service reaches the point where the text is applied.
+ *
+ * An override of {@link dispose} calls `super.dispose()`: that is what closes
+ * the session's opens and frees its id.
+ */
+export class DefaultClientSession<
+   TAst extends AstNode,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
+   TTransfer extends TransferElement = TransferElement,
+   TOpenOptions extends OpenOptions = OpenOptions
+> implements ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions> {
+   protected disposed = false;
+   /**
+    * This session's opens still under way, by canonical URI. Recorded before
+    * the first await, so a second open of the same URI joins the first rather
+    * than racing it, and `withOpen` can tell an open another call is making.
+    */
+   protected readonly pendingOpens = new Map<string, Promise<void>>();
+
+   constructor(
+      protected readonly modelService: ModelService<TAst, TDiagnostic, TTransfer>,
+      protected readonly services: ServerSharedServices,
+      readonly clientId: string,
+      readonly label: string
+   ) {}
+
+   open(uri: string, options?: TOpenOptions): Promise<void> {
+      this.assertLive();
+      return this.openDocument(uri, options);
+   }
+
+   create(uri: string, text: string): Promise<void> {
+      this.assertLive();
+      return this.createDocument(uri, text);
+   }
+
+   update(args: Omit<TransferUpdateArgs<TTransfer>, 'clientId'>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
+      this.assertLive();
+      return this.modelService.update({ ...args, clientId: this.clientId }, cancelToken);
+   }
+
+   save(args: Omit<TransferSaveArgs<TTransfer>, 'clientId'>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
+      this.assertLive();
+      return this.modelService.save({ ...args, clientId: this.clientId }, cancelToken);
+   }
+
+   close(uri: string): Promise<void> {
+      this.assertLive();
+      return this.modelService.close({ uri, clientId: this.clientId });
+   }
+
+   withOpen<T>(uri: string, fn: () => MaybePromise<T>): Promise<T> {
+      this.assertLive();
+      return this.runWithOpen(uri, fn);
+   }
+
+   isOwnEcho(sourceClientId: string): boolean {
+      this.assertLive();
+      return sourceClientId === this.clientId;
+   }
+
+   dispose(): void {
+      if (this.disposed) {
+         return;
+      }
+      this.disposed = true;
+      this.services.workspace.TextDocuments.closeSession(this.clientId);
+   }
+
+   protected assertLive(): void {
+      if (this.disposed) {
+         throw new SessionClosedError(this.clientId);
+      }
+   }
+
+   /** Open `uri`, or join the open of it this session already has under way, whose options then stand. */
+   protected openDocument(uri: string, options: TOpenOptions | undefined): Promise<void> {
+      const key = this.canonicalKey(uri);
+      const pending = this.pendingOpens.get(key);
+      if (pending) {
+         return pending;
+      }
+      const opening = this.registerOpen(uri, options).finally(() => {
+         if (this.pendingOpens.get(key) === opening) {
+            this.pendingOpens.delete(key);
+         }
+      });
+      this.pendingOpens.set(key, opening);
+      return opening;
+   }
+
+   protected async registerOpen(uri: string, options: TOpenOptions | undefined): Promise<void> {
+      const textDocuments = this.services.workspace.TextDocuments;
+      const wasOpen = textDocuments.isOpenInClient(uri, this.clientId);
+      await this.modelService.open({ uri, clientId: this.clientId });
+      await this.rejectIfEnded(uri, wasOpen);
+      if (!wasOpen && options !== undefined) {
+         textDocuments.setOpenOptions(uri, this.clientId, options);
+      }
+   }
+
+   protected canonicalKey(uri: string): string {
+      return this.services.workspace.DocumentUriPolicy.canonicalUri(uri);
+   }
+
+   protected async createDocument(uri: string, text: string): Promise<void> {
+      if (await this.services.workspace.FileSystemProvider.exists(UriUtils.toUri(uri))) {
+         throw new Error(`Cannot create ${uri}: the file exists`);
+      }
+      this.assertLive();
+      if (this.modelService.isOpen(uri)) {
+         throw new Error(`Cannot create ${uri}: it is open in a client`);
+      }
+      // The check above cannot see an open that registers while this one is
+      // under way, and opening an already-open URI only attaches, dropping
+      // `text`. Only an open that creates the document fires `onDidOpen`, so
+      // hearing it for this session, during this open, is what proves the
+      // document holds `text`; the client list afterwards cannot, since a
+      // client that registered first may have closed again by then.
+      const key = this.canonicalKey(uri);
+      let created = false;
+      const listener = this.services.workspace.TextDocuments.onDidOpen(event => {
+         if (event.clientId === this.clientId && event.document.uri === key) {
+            created = true;
+         }
+      });
+      try {
+         await this.modelService.open({ uri, clientId: this.clientId, text });
+      } finally {
+         listener.dispose();
+      }
+      await this.rejectIfEnded(uri, false);
+      if (!created) {
+         await this.modelService.close({ uri, clientId: this.clientId });
+         throw new Error(`Cannot create ${uri}: it is open in a client`);
+      }
+   }
+
+   protected async runWithOpen<T>(uri: string, fn: () => MaybePromise<T>): Promise<T> {
+      // An open another call of this session is still making counts as made:
+      // closing it afterwards would take away an open that call asked for.
+      const alreadyOpen =
+         this.services.workspace.TextDocuments.isOpenInClient(uri, this.clientId) || this.pendingOpens.has(this.canonicalKey(uri));
+      await this.openDocument(uri, undefined);
+      try {
+         return await fn();
+      } finally {
+         if (!alreadyOpen && !this.disposed) {
+            await this.modelService.close({ uri, clientId: this.clientId });
+         }
+      }
+   }
+
+   /**
+    * Undo an open that completed after the session ended, then fail it.
+    *
+    * Ending the session closed only what it had open at that moment. An open
+    * still reading from disk registers afterwards, under an id that is no
+    * longer a session, and nothing would ever close it.
+    *
+    * Opens are keyed by id, so once a new session holds the same id this open
+    * is indistinguishable from one of its own, and closing it would close the
+    * new session's. It is left to that session, which releases it at its end.
+    */
+   protected async rejectIfEnded(uri: string, wasOpen: boolean): Promise<void> {
+      if (!this.disposed) {
+         return;
+      }
+      if (!wasOpen && this.modelService.getSession(this.clientId) === undefined) {
+         await this.modelService.close({ uri, clientId: this.clientId });
+      }
+      throw new SessionClosedError(this.clientId);
+   }
+}

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

@@ -8,3 +8,4 @@
  ********************************************************************************/
 
 export * from './model-service.js';
+export * from './client-session.js';

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

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import {
+   type BasedOn,
    type CanonicalUri,
    type CloseModelArgs,
    ConflictError,
@@ -34,7 +35,10 @@ import { type LogNameOptions } from '../diagnostics/logger.js';
 import { IntegrityService } from '../integrity/integrity-service.js';
 import { labelPhaseListener } from '../document-builder/labeled-phase-listener.js';
 import { LANGUAGE_CLIENT_ID } from '../../documents/client-ids.js';
+import { DocumentNotOpenError } from '../../documents/client-session-errors.js';
+import { type OpenOptions } from '../../documents/client-session-registry.js';
 import { type ServerSharedServices } from '../module.js';
+import { type ClientSession, DefaultClientSession } from './client-session.js';
 
 /**
  * The undo-stack entry for a server-authored write pushed to the editor.
@@ -274,6 +278,21 @@ export interface ModelService<
    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;
+
+   /**
+    * Start a client session. The id defaults to `label#` plus a random UUID;
+    * a fixed `clientId` is taken as given. Throws `DuplicateClientIdError` when
+    * the id is reserved by the framework, held by another live session, or has
+    * documents open under it as a client that is not a session.
+    *
+    * `TOpenOptions` types the options the session's `open` takes.
+    */
+   createSession<TOpenOptions extends OpenOptions = OpenOptions>(
+      label?: string,
+      clientId?: 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;
 }
 
 export class DefaultModelService<
@@ -318,6 +337,20 @@ export class DefaultModelService<
    protected readonly syncChains = new Map<string, Promise<void>>();
    protected readonly pendingSync = new Map<string, string>();
 
+   /**
+    * The live sessions this service started, by client id. {@link update}
+    * reads it to tell a session's write, which must find its document open,
+    * from a write under a plain client id, which opens it.
+    */
+   protected readonly sessions = new Map<string, ClientSession<TAst, TDiagnostic, TTransfer>>();
+   /**
+    * Drops an ended session from {@link sessions}. Subscribed by the first
+    * {@link createSession} rather than at construction, so a services tree with
+    * no text store, or one that knows nothing of sessions, still constructs
+    * this service.
+    */
+   protected sessionCloseListener?: Disposable;
+
    /**
     * Workspace-level readiness gate. Resolves when the framework has
     * finished its first workspace build cycle and the `ModelService`
@@ -681,8 +714,19 @@ export class DefaultModelService<
     * with vN's specific settled snapshot, intermediate-phase
     * observability, slow-warn / hard-timeout behaviour) override this
     * method.
+    *
+    * **Upsert, except for a session.** Under a plain client id the write opens
+    * the document for that client first, creating it from the payload when no
+    * file exists. Under the id of a live session from {@link createSession} it
+    * opens nothing, and fails with `DocumentNotOpenError` unless the session
+    * has the URI open at the moment the text is applied.
     */
    async update(args: TransferUpdateArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
+      // Read before the first await, while the call is still the caller's: a
+      // session that ends during the serialise would otherwise read as a plain
+      // client id here, and the write would open the document for an id no
+      // session owns any more and land there.
+      const bySession = this.sessions.has(args.clientId);
       const stopwatch = this.slowUpdateWarn !== undefined ? this.services.Clock.stopwatch() : undefined;
       // Per-stage self-time breakdown of the update/reconcile chain (serialise →
       // open → apply → rebuild), opt-in at debug — the default path skips the
@@ -731,16 +775,34 @@ export class DefaultModelService<
       // reason to close a document it never asked to open. Serialisation is
       // held back too; it is the adopter's code and need not be side-effect
       // free.
-      const currentVersion = this.services.workspace.TextDocuments.version(uri);
-      if (isSnapshotVersion(args.basedOn) && currentVersion !== args.basedOn) {
-         // Distinct from the post-build "superseded" debug line below: this is a
-         // based-on-stale rejection (the write never applies), not two writes racing.
-         this.tracer.debug(`Conflict on ${uri}: based-on v${args.basedOn} stale, server at v${currentVersion}`);
-         throw new ConflictError(uri, args.basedOn, currentVersion);
-      }
+      const textDocuments = this.services.workspace.TextDocuments;
+      this.checkBasedOn(uri, args.basedOn, textDocuments.version(uri));
+      // Whether this call's own open is the one that creates the document, read
+      // in the same step as the check above so no other open can land between.
+      const opensCold = !bySession && textDocuments.get(uri) === undefined;
       const text = await run('serialize', () => this.modelToText(uri, args.model, cancelToken));
-      await run('open', () => this.open({ uri, clientId: args.clientId, text }));
-      const appliedVersion = await run('apply', () => this.services.workspace.AstDocumentManager.update(uri, text, args.clientId));
+      if (!bySession) {
+         await run('open', () => this.open({ uri, clientId: args.clientId, text }));
+      }
+      const appliedVersion = await run('apply', () => {
+         // A session's write never opens its document. The check sits in the
+         // same synchronous step as the apply: made before the serialize await
+         // instead, it passes for a write whose session closes the document
+         // during that await, and the write then lands on a document the
+         // session no longer has open.
+         if (bySession && !textDocuments.isOpenInClient(uri, args.clientId)) {
+            throw new DocumentNotOpenError(uri, args.clientId);
+         }
+         // The gate again, in the same step as the apply: two writes based on
+         // one version both pass the check at the door while they serialise,
+         // and without this both apply. The version a cold open assigned from
+         // this write's own text is not a conflict; the store holding exactly
+         // that text is how it shows.
+         if (!(opensCold && textDocuments.get(uri)?.getText() === text)) {
+            this.checkBasedOn(uri, args.basedOn, textDocuments.version(uri));
+         }
+         return this.services.workspace.AstDocumentManager.update(uri, text, args.clientId);
+      });
       // Dispatch through the public `rebuild` (which re-canonicalizes the already-
       // canonical `uri` once, idempotently) rather than `rebuildCanonical`, so an
       // adopter `rebuild` override stays in the update path. The redundant call is
@@ -765,6 +827,23 @@ export class DefaultModelService<
       return doc;
    }
 
+   /**
+    * Throw {@link ConflictError} when `basedOn` names a version other than
+    * `currentVersion`. {@link update} calls it at the door and again in the
+    * synchronous step that applies the text, and has to call it synchronously
+    * there: a check separated from the apply by an await lets two writes based
+    * on one version both apply.
+    */
+   protected checkBasedOn(uri: string, basedOn: BasedOn, currentVersion: number): void {
+      if (isSnapshotVersion(basedOn) && currentVersion !== basedOn) {
+         // Distinct from the post-build "superseded" debug line in `update`: this
+         // is a based-on-stale rejection (the write never applies), not two
+         // writes racing.
+         this.tracer.debug(`Conflict on ${uri}: based-on v${basedOn} stale, server at v${currentVersion}`);
+         throw new ConflictError(uri, basedOn, currentVersion);
+      }
+   }
+
    /**
     * Persist `uri` to disk. Same content-change + settled-phase flow as
     * {@link update}, then writes via the
@@ -773,8 +852,16 @@ export class DefaultModelService<
     * the `onDidSave` event regardless of who originated the persist).
     *
     * Returns the post-save AST snapshot.
+    *
+    * Under the id of a live session the save also fails with
+    * `DocumentNotOpenError` when the session closes the URI while the text is
+    * being built, and writes nothing. Once the manager has taken the text, the
+    * write completes whatever the session does next.
     */
    async save(args: TransferSaveArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
+      // Read before the first await, as in `update`: a session that ends during
+      // the rebuild would otherwise read as a plain client id below.
+      const bySession = this.sessions.has(args.clientId);
       // Dispatch through `update` (not its internals) so an adopter `update`
       // override — version-matched resolution, etc. — applies to saves too.
       const doc = await this.update(args, cancelToken);
@@ -782,6 +869,12 @@ export class DefaultModelService<
       // the canonical (real) path follows any symlink to the same file, and the
       // `onDidSave` keys the one canonical registration.
       const uri = this.uriPolicy.canonicalUri(args.uri);
+      // 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.
+      if (bySession && !this.services.workspace.TextDocuments.isOpenInClient(uri, args.clientId)) {
+         throw new DocumentNotOpenError(uri, args.clientId);
+      }
       await this.services.workspace.AstDocumentManager.save(uri, args.clientId);
       return doc;
    }
@@ -906,6 +999,55 @@ export class DefaultModelService<
       return this.services.workspace.AstDocumentManager.getDocument(uri);
    }
 
+   // ============================================================
+   // Client sessions
+   // ============================================================
+
+   createSession<TOpenOptions extends OpenOptions = OpenOptions>(
+      label?: string,
+      clientId?: string
+   ): ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions> {
+      const sessionLabel = label ?? 'session';
+      const id = clientId ?? `${sessionLabel}#${globalThis.crypto.randomUUID()}`;
+      const textDocuments = this.services.workspace.TextDocuments;
+      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.sessions.delete(event.clientId);
+      });
+      let session: ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>;
+      try {
+         session = this.newSession<TOpenOptions>(id, sessionLabel);
+      } catch (err: unknown) {
+         textDocuments.closeSession(id);
+         throw err;
+      }
+      this.sessions.set(id, session);
+      return session;
+   }
+
+   getSession(clientId: string): ClientSession<TAst, TDiagnostic, TTransfer> | undefined {
+      return this.sessions.get(clientId);
+   }
+
+   /**
+    * Build the handle for a session {@link createSession} has already
+    * registered. The override point for a custom session class; narrow the
+    * return type to it.
+    *
+    * Registration and the uniqueness check have already happened when this
+    * runs, so an override cannot skip them.
+    */
+   protected newSession<TOpenOptions extends OpenOptions = OpenOptions>(
+      clientId: string,
+      label: string
+   ): ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions> {
+      return new DefaultClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>(this, this.services, clientId, label);
+   }
+
    // ============================================================
    // LSP-client sync (mirror non-LSP-client changes back to Monaco)
    // ============================================================

package/src/lsp/hydranium-document-update-handler.ts

@@ -133,7 +133,10 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
     */
    protected pendingReason?: string;
 
-   constructor(services: ServerSharedServices, options: HydraniumDocumentUpdateHandlerOptions = {}) {
+   constructor(
+      protected readonly services: ServerSharedServices,
+      options: HydraniumDocumentUpdateHandlerOptions = {}
+   ) {
       super(services);
       this.logger = services.Logger;
       this.selfSaveRegistry = services.workspace.SelfSaveRegistry;
@@ -201,6 +204,11 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
     *
     * Per-client closes (where other clients still hold the URI) are
     * suppressed via {@link HydraniumTextDocuments.isOpenInAnyClient}.
+    *
+    * The dispatch waits for the URI's disk queue to drain, because the rebuild
+    * re-reads the file: dispatched while a save is still queued, it reads the
+    * text from before that save, and the document reverts past it. A client
+    * that opens the URI meanwhile holds the text, so no revert follows.
     */
    didCloseDocument(change: TextDocumentChangeEvent<TextDocument>): void {
       if (this.textDocuments.isOpenInAnyClient(change.document.uri)) {
@@ -210,9 +218,19 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
       if (uri.scheme !== 'file') {
          return;
       }
-      this.nextReason = HYDRANIUM_BUILD_REASONS.didClose;
-      this.immediateFlush = true;
-      this.fireDocumentUpdate([uri], []);
+      this.services.workspace.AstDocumentManager.queueDiskTask(change.document.uri, async () => undefined)
+         .then(() => {
+            if (this.textDocuments.isOpenInAnyClient(change.document.uri)) {
+               return;
+            }
+            this.nextReason = HYDRANIUM_BUILD_REASONS.didClose;
+            this.immediateFlush = true;
+            this.fireDocumentUpdate([uri], []);
+         })
+         .catch((err: unknown) => {
+            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            this.logger.error(`Revert on last close dropped for ${change.document.uri}. ${detail}`);
+         });
    }
 
    override didChangeWatchedFiles(params: DidChangeWatchedFilesParams): void {

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

@@ -24,8 +24,9 @@ import type { StubLangiumDocuments } from './stub-langium-documents.js';
  * Minimal stub of {@link AstDocumentManager} for use in test
  * harnesses. Implements just the methods the framework's
  * `ModelService` calls (`open` / `close` / `update` / `save` /
- * `isOpen` / `getDocument`); `onSave` / `onClientClosed` forward to the
- * underlying stub text-document manager, `onUpdate` is driven explicitly
+ * `isOpen` / `getDocument`) and a disk queue that runs each task at once;
+ * `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
  * (`isTriggeringEdit`, `getAuthor`) throw if invoked — tests that need them
@@ -52,6 +53,7 @@ export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic extend
    | 'isOpen'
    | 'update'
    | 'save'
+   | 'queueDiskTask'
    | 'onUpdate'
    | 'onSave'
    | 'onClientClosed'
@@ -151,6 +153,9 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic ext
          await fileSystem.writeFile(UriUtils.toUri(uri), text);
          textDocuments.notifyDidSaveTextDocument({ textDocument: { uri }, text }, clientId);
       },
+      queueDiskTask<T>(_uri: string, task: () => Promise<T>): Promise<T> {
+         return task();
+      },
       // 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;