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

package/src/langium/module.ts

@@ -15,6 +15,7 @@ import { HydraniumLangiumProfiler } from './diagnostics/hydranium-langium-profil
 import { type AstNode, type Module } from '@hydranium/langium';
 import { type DefaultSharedModuleContext, type LangiumSharedServices, type PartialLangiumSharedServices } from '@hydranium/langium/lsp';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
+import { type ClientSessionFactory, DefaultClientSessionFactory } from './model-service/client-session.js';
 import { DefaultModelService, type ModelService } from './model-service/model-service.js';
 import { type ProjectManager } from './project/project-manager.js';
 import { SingleProjectManager } from './project/single-project-manager.js';
@@ -35,6 +36,7 @@ import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from './workspace/do
 import { HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
 import { DefaultAstDocumentManager, type AstDocumentManager, type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
 import { DefaultSelfSaveRegistry, type SelfSaveRegistry } from '../documents/self-save-registry.js';
+import { DefaultFileSystemTaskQueue, type FileSystemTaskQueue } from '../documents/file-system-task-queue.js';
 import { DefaultEmptyFileSystemProvider } from './workspace/file-system-provider.js';
 import { type ServerLanguageServices } from './language-module.js';
 import { ExtendedServiceRegistry } from './service-registry.js';
@@ -177,7 +179,7 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
        * Tighten Langium's read-only `FileSystemProvider` slot to
        * {@link WritableFileSystemProvider}. The framework's save path
        * ({@link AstDocumentManager.save}, integrity corrections,
-       * `ModelService.save`) requires write semantics — a read-only slot
+       * a session's `save`) requires write semantics — a read-only slot
        * type forces an `as WritableFileSystemProvider` cast at the binding
        * line and defers the failure of a read-only implementation to the
        * first save. The `.`-entry default is
@@ -217,6 +219,12 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
        * behaviour rebind this slot with a subclass.
        */
       AstDocumentManager: AstDocumentManager<AstNode>;
+      /**
+       * Orders the server's disk accesses of each file. One slot for every
+       * reader and writer: a service given a queue of its own does not order
+       * against the others.
+       */
+      FileSystemTaskQueue: FileSystemTaskQueue;
       /**
        * Wires the framework's build-time features (integrity, AST
        * enrichment) into Langium's build pipeline: owns the build-phase
@@ -273,6 +281,8 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
    model: {
       TransferEncoder: TransferEncoder;
       ModelService: ModelService<AstNode>;
+      /** Builds the handle of every session `ModelService.createSession` starts. */
+      ClientSessionFactory: ClientSessionFactory;
    };
    /**
     * Shared contribution group for batch-level build-phase passes (see
@@ -507,6 +517,7 @@ export function createServerSharedModule(
             return new DefaultEmptyFileSystemProvider(services);
          },
          AstDocumentManager: services => new DefaultAstDocumentManager(services),
+         FileSystemTaskQueue: services => new DefaultFileSystemTaskQueue(services),
          // Eagerly constructed, so its build-phase listeners attach before the
          // first build.
          BuildPipelineIntegration: services => new DefaultBuildPipelineIntegration(services),
@@ -519,7 +530,8 @@ export function createServerSharedModule(
          // Generic walker — adopters with a typed `$type → wire shape` overlay
          // rebind this slot with a subclass.
          TransferEncoder: services => new DefaultTransferEncoder(services),
-         ModelService: services => new DefaultModelService(services)
+         ModelService: services => new DefaultModelService(services),
+         ClientSessionFactory: services => new DefaultClientSessionFactory(services)
       },
       // Empty default so `services.buildPhasePasses` always resolves (Langium
       // throws on access to an unbound slot). The framework's own integrity /

package/src/langium/update-rewrite/update-rewrite.ts

@@ -13,7 +13,7 @@ import { type RegistryItem } from '../../util/registry.js';
 
 /**
  * A single transform applied to the incoming transfer model on the structured
- * (object) write path of `ModelService.update` / `ModelService.save`, before
+ * (object) write path of a client session's `update` / `save`, before
  * serialisation. The RPC-update-stage sibling of `IntegrityRule` /
  * `AstExtension` / `ValidationCheck` — same id-keyed,
  * priority-ordered registry shape, but it runs on the transfer model rather

package/src/langium/workspace/in-memory-file-system-provider.ts

@@ -43,6 +43,15 @@ export const UNSUPPORTED_WRITE = defineMessage(
    'Cannot write {uri}: the scheme names no location on disk'
 );
 
+/**
+ * A missing-file error shaped as a Node file system raises it, with code
+ * `ENOENT` and the path: callers tell a missing file from any other failure by
+ * those two fields, whichever provider is bound.
+ */
+function notFound(message: string, uri: URI): Error {
+   return Object.assign(new Error(message), { code: 'ENOENT', path: uri.fsPath });
+}
+
 /**
  * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
  *
@@ -162,7 +171,7 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       }
       const content = this.files.get(normalize(uri));
       if (content === undefined) {
-         throw new Error(NO_SUCH_FILE.format({ uri: uri.toString() }));
+         throw notFound(NO_SUCH_FILE.format({ uri: uri.toString() }), uri);
       }
       return content;
    }
@@ -192,7 +201,7 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       if (this.hasChildren(path)) {
          return { isFile: false, isDirectory: true, uri };
       }
-      throw new Error(NO_SUCH_PATH.format({ uri: uri.toString() }));
+      throw notFound(NO_SUCH_PATH.format({ uri: uri.toString() }), uri);
    }
 
    exists(uri: URI): Promise<boolean> {

package/src/langium/workspace/write-lock-scope.ts

@@ -67,7 +67,7 @@ export function isInsideWriteLock(): boolean {
 /**
  * Thrown when the model facade is reached from inside a workspace write-lock
  * holder — typically an integrity rule or build-phase pass writing through
- * `ModelService.update` / `save` / `rebuild` during a build.
+ * a session's `update` / `save` or `ModelService.rebuild` during a build.
  *
  * Named rather than a bare `Error` because the remedy is specific and worth
  * pointing at: either move the write out of the build (integrity rules that

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

@@ -7,31 +7,27 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Debouncer, type Logger, ObservableValue, type MaybeObservableValue } from '@hydranium/protocol';
+import { Debouncer, Deferred, type Logger, ObservableValue, type MaybeObservableValue } from '@hydranium/protocol';
 import { URI, UriUtils } from '@hydranium/langium';
 import { DefaultDocumentUpdateHandler } from '@hydranium/langium/lsp';
-import { type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
+import { HYDRANIUM_BUILD_REASONS, type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
 import { type ServerSharedServices } from '../langium/module.js';
 import { LANGUAGE_CLIENT_ID } from '../documents/client-ids.js';
 import { type SelfSaveRegistry } from '../documents/self-save-registry.js';
 import { type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
 import { type HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
 import { isConnectionGoneError } from '../util/connection-liveness.js';
-import { type DidChangeWatchedFilesParams, type FileEvent, FileChangeType, type TextDocumentChangeEvent } from 'vscode-languageserver';
+import {
+   type DidChangeWatchedFilesParams,
+   type FileEvent,
+   FileChangeType,
+   type TextDocumentChangeEvent,
+   type TextDocumentWillSaveEvent,
+   type TextEdit
+} from 'vscode-languageserver';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
 
-/**
- * Default LSP-event reasons stamped by {@link HydraniumDocumentUpdateHandler}
- * onto the next `documentBuilder.update` call via `markNextReason`. Exposed
- * so adopters subclassing the handler can layer additional reasons or rename
- * existing ones without losing the canonical names the framework emits.
- */
-export const HYDRANIUM_BUILD_REASONS = Object.freeze({
-   didOpen: 'didOpen',
-   didChangeContent: 'didChangeContent',
-   didChangeWatchedFiles: 'didChangeWatchedFiles',
-   didClose: 'didClose'
-} as const);
+export { HYDRANIUM_BUILD_REASONS };
 
 /**
  * Construction options for {@link HydraniumDocumentUpdateHandler}.
@@ -57,6 +53,17 @@ export interface HydraniumDocumentUpdateHandlerOptions {
     * load tests).
     */
    readonly bypassNonLanguageClientChanges?: boolean;
+   /**
+    * Longest an editor's save waits on the server, in milliseconds, at each of
+    * its two steps: the `willSaveWaitUntil` answer waits for the server's disk
+    * writes of the document already queued, and server writes queued after the
+    * answer wait for the editor's `didSave`. Either wait that runs out is
+    * logged, and the editor's write and the server's can then land in either
+    * order. Default `1000`: VS Code gives up on an answer after about 1.5 s,
+    * and switches the listener off for the session once four answers, over
+    * all documents, timed out or failed.
+    */
+   readonly willSaveGateMs?: number;
 }
 
 /**
@@ -72,19 +79,25 @@ export interface HydraniumDocumentUpdateHandlerOptions {
  *     changes and watched-file changes bypass the debounce (their
  *     producers are already coalesced).
  *  3. **Build-reason stamping** — the LSP event overrides
- *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`,
- *     `didCloseDocument`) populate {@link nextReason} with a canonical
- *     reason string. {@link fireDocumentUpdate} captures the reason;
- *     {@link dispatch} stages it on the builder via
- *     {@link HydraniumDocumentBuilder.markNextReason}, so a subclass that
- *     formats build logs can tag its line with the event that caused the
- *     build without per-adopter wiring to capture it.
- *  4. **Last-client-close rebuild trigger** ({@link didCloseDocument}) —
- *     when the final client closes a document, dispatch a build so the
- *     LangiumDocument's `textDocument` is refreshed (from disk for `file:`
- *     URIs, or removed from the index for ephemeral URIs). Langium's
- *     default handler does not implement `didCloseDocument`, so the
- *     in-memory text of the last writer would otherwise persist.
+ *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`)
+ *     populate {@link nextReason} with a canonical reason string.
+ *     {@link fireDocumentUpdate} captures the reason; {@link dispatch} stages
+ *     it on the builder via {@link HydraniumDocumentBuilder.markNextReason},
+ *     so a subclass that formats build logs can tag its line with the event
+ *     that caused the build without per-adopter wiring to capture it.
+ *  4. **Editor save gate** ({@link willSaveDocumentWaitUntil}) — the editor
+ *     writes the file itself, so the server's disk writes of that document
+ *     are ordered around it: the editor's save waits for the ones already
+ *     queued, and the ones queued during its save wait for its `didSave`.
+ *     Both waits are capped by
+ *     {@link HydraniumDocumentUpdateHandlerOptions.willSaveGateMs}.
+ *
+ * The revert to disk after a document's last close is not dispatched here:
+ * the text store runs it for every head, the LSP head included, so a
+ * `didCloseDocument` added in a subclass would build the document twice. A
+ * change still debounced for the document is dropped when the store releases
+ * it: a `file:` document's revert rebuilds it, and a document of another
+ * scheme, which does not revert, keeps its last build.
  *
  * Adopters with their own handler subclass should extend this class
  * (not Langium's `DefaultDocumentUpdateHandler`) so all of them are
@@ -133,6 +146,17 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
     */
    protected pendingReason?: string;
 
+   protected readonly willSaveGateMs: number;
+   /**
+    * Per document URI, the release of the hold an editor's save in progress
+    * keeps on the document's disk queue. A second save of the document
+    * releases the first: its hold would otherwise keep the second's answer
+    * waiting until the cap. The key is the document, not the save, so for a
+    * client that sends its next `willSaveWaitUntil` before the previous
+    * `didSave`, that late `didSave` releases the next save's hold.
+    */
+   protected readonly editorSaves = new Map<string, () => void>();
+
    constructor(
       protected readonly services: ServerSharedServices,
       options: HydraniumDocumentUpdateHandlerOptions = {}
@@ -145,6 +169,19 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
       this.debounce = ObservableValue.from(options.debounceMs ?? 0);
       this.flushDebouncer = new Debouncer(services.Clock, () => this.flushPending(), { delayMs: this.debounce });
       this.bypassNonLanguageClientChanges = options.bypassNonLanguageClientChanges ?? true;
+      this.willSaveGateMs = options.willSaveGateMs ?? 1000;
+      this.textDocuments.onDidSaveInLanguageClient(event => this.editorSaves.get(event.uri)?.());
+      // A change still debounced for a document the store has released would
+      // build it once more after the store's own revert: from disk again, or,
+      // for a file that never existed, by reading a file that is not there. A
+      // document of another scheme does not revert, so dropping its change
+      // leaves it at its last build.
+      this.textDocuments.onDidCloseLastOpen(event => {
+         this.pendingChanged.delete(URI.parse(event.uri).toString());
+         if (this.pendingChanged.size === 0 && this.pendingDeleted.size === 0) {
+            this.pendingReason = undefined;
+         }
+      });
    }
 
    didOpenDocument(_change: TextDocumentChangeEvent<TextDocument>): void {
@@ -169,70 +206,6 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
       super.didChangeContent(change);
    }
 
-   /**
-    * Last-client close is the missing rebuild trigger in Langium's
-    * `DefaultDocumentUpdateHandler`: `documents.onDidClose` fires on every
-    * per-client close, but the default handler ignores the event entirely.
-    * For multi-client servers this leaves the LangiumDocument carrying the
-    * unsaved in-memory `textDocument` of the last writer until something
-    * else triggers a rebuild — integrity rules walking `langiumDocuments.all`
-    * then see stale text long after the user discarded their edits.
-    *
-    * We funnel the last-client transition through the same dispatch path
-    * the other LSP events use, so the rebuild gets debouncing, workspace
-    * locking, build-reason stamping, and `markNextReason` for free. The
-    * scheme split governs the `DocumentBuilder.update` shape:
-    *
-    *  - **`file:` URI** → `update([uri], [])`. Routes through
-    *    `LangiumDocuments.invalidateDocument` (doc stays in the trie) and
-    *    `LangiumDocumentFactory.update`, which consults the LSP-tracked
-    *    open-documents map first. That map is cleared LATER in the same
-    *    synchronous `notifyDidCloseTextDocument` call that fires this event,
-    *    and {@link dispatch} defers the build behind `workspaceManager.ready`
-    *    — so by the time the factory looks, the URI is gone: it falls back to
-    *    `FileSystemProvider.readFile` and the doc rebuilds from disk,
-    *    Langium's canonical close-without-save semantic. A dispatch made
-    *    synchronously here would still see the open document and re-read the
-    *    in-memory text instead.
-    *  - **non-`file:` URI** (`builtin:`, `untitled:`) → no dispatch.
-    *    Adopter-loaded schemes — documents pulled in via
-    *    `loadAdditionalDocuments` — need to stay in the workspace index;
-    *    dropping them on close would break every cross-reference that
-    *    targets them. The framework cannot enumerate adopter schemes, so the
-    *    safe default is "leave alone unless it's a file." Adopters that need
-    *    ephemeral-URI cleanup handle it explicitly.
-    *
-    * 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)) {
-         return;
-      }
-      const uri = URI.parse(change.document.uri);
-      if (uri.scheme !== 'file') {
-         return;
-      }
-      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 {
       void this.filterSelfSaves(params)
          .then(filtered => {
@@ -260,6 +233,79 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
          });
    }
 
+   /**
+    * Answer an editor's `willSaveWaitUntil` with no edits once the server's
+    * disk writes of the document already queued have landed, or after
+    * {@link willSaveGateMs}, whichever is first. From the moment the queue
+    * reaches this save, disk tasks of the document queued behind it wait for
+    * the editor's `didSave`, reported through
+    * `HydraniumTextDocuments.onDidSaveInLanguageClient`, or for
+    * {@link willSaveGateMs} more.
+    *
+    * The hold is a disk task that waits only for that signal or its timer:
+    * waiting on a build, a save or anything else queued for the document would
+    * wedge its queue. Resolves in every case, since a failed request counts
+    * against the listener in VS Code; Langium drops the request's cancellation,
+    * so an abandoned request still runs to the cap. A hold that runs out is
+    * logged at debug only: an editor skips `didSave` for a save it cancels or
+    * that changed nothing.
+    */
+   willSaveDocumentWaitUntil(event: TextDocumentWillSaveEvent<TextDocument>): Promise<TextEdit[]> {
+      const uri = event.document.uri;
+      this.editorSaves.get(uri)?.();
+      const hold = new Deferred();
+      const release = (): void => {
+         if (this.editorSaves.get(uri) === release) {
+            this.editorSaves.delete(uri);
+         }
+         hold.resolve();
+      };
+      this.editorSaves.set(uri, release);
+      return new Promise<TextEdit[]>(resolve => {
+         const clock = this.services.Clock;
+         const cap = clock.setTimer(() => {
+            this.logger.warn(
+               `willSaveWaitUntil for ${uri} answered after ${this.willSaveGateMs} ms with server writes of it still queued; the editor's save may race them.`
+            );
+            resolve([]);
+         }, this.willSaveGateMs);
+         try {
+            void this.services.workspace.FileSystemTaskQueue.enqueue(uri, async () => {
+               cap.dispose();
+               resolve([]);
+               const bound = clock.setTimer(() => {
+                  this.logger.debug(
+                     `No didSave for ${uri} within ${this.willSaveGateMs} ms; server writes of it no longer wait for the editor's save.`
+                  );
+                  release();
+               }, this.willSaveGateMs);
+               await hold.promise;
+               bound.dispose();
+            });
+         } catch (err) {
+            cap.dispose();
+            this.logger.error(
+               `willSaveWaitUntil for ${uri} answered without waiting. ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`
+            );
+            release();
+            resolve([]);
+         }
+      });
+   }
+
+   /**
+    * Present so that Langium advertises `save` and editors send `didSave`;
+    * without it every hold of {@link willSaveDocumentWaitUntil} waits out its
+    * cap. The hold is released on
+    * `HydraniumTextDocuments.onDidSaveInLanguageClient` instead: it fires as
+    * soon as the editor reports the save, while `onDidSave`, and so this
+    * method, follows only once the file has been read back, and not at all
+    * when the file does not hold the store's text.
+    */
+   didSaveDocument(_event: TextDocumentChangeEvent<TextDocument>): void {
+      // Nothing to do; see the doc comment.
+   }
+
    /**
     * Drop watched-file changes whose path + mtime match a recent self-save
     * record. Deletions always pass (no mtime); stat failures pass (the

package/src/lsp/shared-module.ts

@@ -28,14 +28,10 @@ import { HydraniumDocumentUpdateHandler } from './hydranium-document-update-hand
  *   (an output channel, a structured logger) override the slot after this
  *   module.
  *
- * - {@link HydraniumDocumentUpdateHandler} wraps `didChangeWatchedFiles` to
- *   suppress echo events for the server's own writes via the shared
- *   `SelfSaveRegistry` slot, debounces `didChangeContent`, stamps build
- *   reasons through `markNextReason`, and dispatches a rebuild when the last
- *   client closes a document.
- *   Adopters with their own update-handler subclass should extend
- *   `HydraniumDocumentUpdateHandler` (not Langium's
- *   `DefaultDocumentUpdateHandler`) to preserve those behaviours.
+ * - {@link HydraniumDocumentUpdateHandler} carries the framework's handling of
+ *   the LSP document events. Adopters with their own update-handler subclass
+ *   should extend it (not Langium's `DefaultDocumentUpdateHandler`) to keep
+ *   that handling.
  *
  * **Why this is a shared slot and not a per-language one.** Langium declares
  * `DocumentUpdateHandler` in `LangiumSharedLSPServices` — there is exactly one

package/src/lsp/start-language-server.ts

@@ -22,10 +22,9 @@ import { guardDiagnosticsConnection } from './diagnostics-connection.js';
  * SHARED slot, so the head binds it in `createLspServerSharedModule` — a
  * separate module from `createLspServerLanguageModule`. An adopter who adds
  * only the language module gets a server that boots, links and serves
- * completion, and quietly runs Langium's `DefaultDocumentUpdateHandler`: echo
- * suppression for the server's own writes, the `didChangeContent` debounce,
- * `markNextReason` stamping and the last-client-close rebuild are all absent,
- * with nothing in the log to say so.
+ * completion, and quietly runs Langium's `DefaultDocumentUpdateHandler`: every
+ * behaviour `HydraniumDocumentUpdateHandler` adds, the editor save gate
+ * included, is absent, with nothing in the log to say so.
  *
  * The type system does not catch it. `createIntegrationServices` returns
  * `inject(...) as unknown as TShared`, so widening `TShared` with

package/src/testing/make-test-services.ts

@@ -23,12 +23,18 @@ import { DefaultServerLocale, type ServerLocale } from '../locale/server-locale.
 import { DefaultMessageRenderer, type MessageRenderer } from '../messages/renderer.js';
 import type { Harness } from '@hydranium/protocol/testing';
 import { type AstNode, type AstNodeDescription, type WorkspaceLock } from '@hydranium/langium';
+import {
+   type ClientSessionFactory,
+   type ClientSessionFactoryOptions,
+   DefaultClientSessionFactory
+} from '../langium/model-service/client-session.js';
 import type { ModelService, ModelServiceOptions } from '../langium/model-service/model-service.js';
 import type { ServerSharedServices } from '../langium/module.js';
 import type { AstDiagnostic } from '../langium/validation/document-validator.js';
 import { DefaultTransferEncoder, type TransferEncoder } from '../langium/transfer/transfer-encoder.js';
 import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
 import { HydraniumWorkspaceLock } from '../langium/workspace/hydranium-workspace-lock.js';
+import { DefaultFileSystemTaskQueue, type FileSystemTaskQueue } from '../documents/file-system-task-queue.js';
 import type { FakeDocumentOptions } from './fake-document.js';
 import { makeStubDocumentBuilder, type StubDocumentBuilder } from './stub-document-builder.js';
 import { makeStubIndexManager, type StubIndexManager } from './stub-index-manager.js';
@@ -85,6 +91,8 @@ export interface TestSharedServices<
       SelfSaveRegistry: StubSelfSaveRegistry;
       ProjectManager: StubProjectManager<TProject>;
       DocumentUriPolicy: DocumentUriPolicy;
+      /** The REAL queue: a stub that runs each task at once hides the save interleaving the queue exists to prevent. */
+      FileSystemTaskQueue: FileSystemTaskQueue;
       /**
        * Present only when {@link MakeTestServicesOptions.seedIndex} was passed.
        * Omitted otherwise for the same reason as `ServiceRegistry` — see that
@@ -105,6 +113,7 @@ export interface TestSharedServices<
    readonly model: {
       TransferEncoder: TransferEncoder<TTransferDiagnostic>;
       ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
+      ClientSessionFactory: ClientSessionFactory;
    };
    /**
     * The REAL services, not stubs — the framework renderer's no-catalogue
@@ -151,7 +160,7 @@ export interface MakeTestServicesOptions<
     *
     * **Default: no `ServiceRegistry` slot at all.** Binding an empty registry
     * by default would silently change behaviour for the tests that rely on the
-    * slot being absent — `ModelService.updateRewriteService` optional-chains it
+    * slot being absent — `ModelService.rewriteModel` optional-chains it
     * precisely for those bundles — so a registry appears only when a test asks
     * for one.
     */
@@ -209,11 +218,18 @@ export interface MakeTestServicesOptions<
    modelService?: (services: ServerSharedServices<TProject>) => ModelService<TAst, TDiagnostic, TTransfer>;
    /**
     * Framework {@link ModelServiceOptions} for the DEFAULT stub service, so a
-    * test can reach an option-gated path (`serializeBuilds`, the slow-warn
-    * threshold) without supplying a whole {@link modelService} factory. Ignored
-    * when `modelService` is given — that factory owns its own construction.
+    * test can reach an option-gated path (`serializeBuilds`) without supplying
+    * a whole {@link modelService} factory. Ignored when `modelService` is
+    * given — that factory owns its own construction.
     */
    modelServiceOptions?: ModelServiceOptions;
+   /**
+    * Options of the {@link DefaultClientSessionFactory} bound on
+    * `model.ClientSessionFactory`, so a test can reach the slow-update warn.
+    * Its sessions serialise and rebuild through the `model.ModelService` slot,
+    * so a test of a model service subclass passes it as {@link modelService}.
+    */
+   clientSessionFactoryOptions?: ClientSessionFactoryOptions;
    /**
     * Override the {@link TransferEncoder} factory. Default: framework
     * {@link TransferEncoder} with no overrides.
@@ -326,7 +342,7 @@ export function makeTestServices<
    // is dependency-free (as `HydraniumWorkspaceLock` is) — a no-op stub of a
    // synchronisation primitive hides the very interleaving it exists to prevent.
    //
-   // `model.TransferEncoder` / `model.ModelService` are populated below
+   // The `model` slots are populated below
    // (after the factories run); the literal uses unsafe casts to
    // partially-built objects to satisfy TestSharedServices, then patches
    // them in.
@@ -350,7 +366,8 @@ export function makeTestServices<
          // Spread for the same reason as `ServiceRegistry` above — the slot must
          // be genuinely ABSENT, not present-and-undefined, when no index was seeded.
          ...(indexManager ? { IndexManager: indexManager } : {}),
-         WorkspaceLock: new HydraniumWorkspaceLock()
+         WorkspaceLock: new HydraniumWorkspaceLock(),
+         FileSystemTaskQueue: new DefaultFileSystemTaskQueue({ workspace: { DocumentUriPolicy: documentUriPolicy } })
       },
       model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic>['model'],
       ServerLocale: {} as ServerLocale,
@@ -380,9 +397,11 @@ export function makeTestServices<
    const mutableModel = services.model as {
       TransferEncoder: TransferEncoder<TTransferDiagnostic>;
       ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
+      ClientSessionFactory: ClientSessionFactory;
    };
    mutableModel.TransferEncoder = transferEncoder;
    mutableModel.ModelService = modelService;
+   mutableModel.ClientSessionFactory = new DefaultClientSessionFactory(sharedServices, options.clientSessionFactoryOptions);
 
    return {
       services: sharedServices,

package/src/testing/node/lsp-server-connection.ts

@@ -301,7 +301,7 @@ export interface LspServerConnection extends Harness {
     *
     * **An egress push is asynchronous well past the call that triggers it** —
     * the framework coalesces per URI and drives the sync from a build-phase
-    * settle, so a `ModelService.update` resolves long before the push is sent.
+    * settle, so a session's `update` resolves long before the push is sent.
     * Record `appliedEdits.length`, drive the edit, then await this; reading the
     * capture on the line after the write proves nothing.
     */

package/src/testing/node/scratch-workspace.ts

@@ -14,7 +14,7 @@
  *
  * Any test that drives a **write path** needs one, and the reason is not
  * obvious enough to rediscover per suite. The writes themselves are usually
- * in-memory — `ModelService.update` goes to the multi-client text store, and
+ * in-memory — a session's `update` goes to the multi-client text store, and
  * only `save` reaches disk — but a rebuild also runs the integrity rules, and
  * their default `'silent'` sync mode persists repairs through
  * `WritableFileSystemProvider.writeFile`. So a write-path test pointed at a

package/src/testing/run-update-pipeline.ts

@@ -9,7 +9,7 @@
 
 /**
  * Driver for the structured-write transform chain — the rewrite registry plus
- * the serializer — run the way `ModelService.update` runs it.
+ * the serializer — run the way a session's `update` runs it.
  *
  * # Why a driver and not a documented recipe
  *
@@ -38,7 +38,7 @@
  * This runs rewrite → serialize and stops. It does NOT open the document, push
  * text into the multi-client store, drive a build or return an
  * {@link AstDocument}: those need a live workspace, and a test that wants them
- * should call `ModelService.update` itself rather than a driver standing in for
+ * should call a session's `update` itself rather than a driver standing in for
  * it. What is left is the part with no observable of its own — the text and the
  * rewritten model — which is why it needed lifting.
  *
@@ -61,7 +61,7 @@ export interface UpdatePipelineArgs<TTransfer extends TransferElement = Transfer
     * rather than merely labelling it.
     */
    readonly uri: string;
-   /** Transfer-model payload, as an adopter caller would hand it to `ModelService.update`. */
+   /** Transfer-model payload, as an adopter caller would hand it to a session's `update`. */
    readonly model: TTransfer;
    /**
     * Previous AST root threaded into every rewrite, so a diff-based rewrite can
@@ -90,7 +90,7 @@ export interface UpdatePipelineResult<TTransfer extends TransferElement = Transf
     * surface but it makes the precise assertion unavailable.
     */
    readonly rewritten: TTransfer;
-   /** The serialized text, which is what `ModelService.update` applies to the store. */
+   /** The serialized text, which is what a session's `update` applies to the store. */
    readonly text: string;
 }