@hydranium/core 1.0.0-next.18 → 1.0.0-next.181

package/src/testing/playwright/flaky-network-proxy.ts

@@ -0,0 +1,240 @@
+/********************************************************************************
+ * 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 { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
+import { connect, createServer as createTcpServer, type Server as TcpServer, type Socket } from 'node:net';
+
+/**
+ * A TCP proxy that can half-close a connection, so an e2e suite can reproduce a
+ * flaky network against a real browser session.
+ *
+ * Toggling the browser offline is not enough. On localhost the server sees the
+ * close immediately and reaps the socket before the browser reconnects, so the
+ * window where both sides disagree about the session — the one where reconnect
+ * defects live — never opens. Reaching it needs the browser's socket to die
+ * while the server still believes it is alive, and nothing inside the app or in
+ * Playwright's offline emulation can produce that asymmetry: both close cleanly
+ * at both ends.
+ *
+ * The proxy holds both halves of every connection and lets a test kill them
+ * independently:
+ *
+ *   `break`    destroy the BROWSER-side sockets, keep the server-side ones open.
+ *              The browser reconnects through a fresh pair while the server
+ *              still holds the old one.
+ *   `release`  destroy the orphaned server-side sockets `break` left. The
+ *              server's disconnect handler fires at once, rather than whenever
+ *              its next heartbeat write would have failed.
+ */
+
+/** Where the proxy listens, and the application it fronts. */
+export interface FlakyNetworkProxyOptions {
+   /** Port the browser connects to. */
+   readonly listenPort: number;
+   /** Port of the application being proxied. */
+   readonly targetPort: number;
+   /** Host of the application being proxied. Defaults to loopback. */
+   readonly targetHost?: string;
+   /** Port the HTTP control channel listens on. Defaults to `listenPort + 1000`. */
+   readonly controlPort?: number;
+}
+
+/** The commands the control channel accepts, and the proxy's own vocabulary. */
+export type FlakyNetworkCommand = 'break' | 'release' | 'status';
+
+/** Drives a running proxy. Implemented both in-process and over HTTP. */
+export interface FlakyNetworkControl {
+   /** Kill the browser side of every live connection; leave the server side up. */
+   break(): Promise<string>;
+   /** Kill the server side of every connection `break` orphaned. */
+   release(): Promise<string>;
+   /** How many connections are live and how many are orphaned. */
+   status(): Promise<string>;
+}
+
+export interface FlakyNetworkProxy extends FlakyNetworkControl {
+   /** Base URL a browser should be pointed at, i.e. Playwright's `baseURL`. */
+   readonly url: string;
+   /** Control channel, for workers that cannot reach this object directly. */
+   readonly controlUrl: string;
+   close(): Promise<void>;
+}
+
+interface ConnectionPair {
+   readonly id: number;
+   readonly browserSocket: Socket;
+   readonly targetSocket: Socket;
+   orphaned: boolean;
+}
+
+/**
+ * Starts the proxy in the calling process.
+ *
+ * Call it from a Playwright config, which runs in the main process before any
+ * worker forks. Workers are separate processes and cannot reach the returned
+ * object, which is what {@link controlUrl} and {@link flakyNetworkControlClient}
+ * are for.
+ */
+export async function startFlakyNetworkProxy(options: FlakyNetworkProxyOptions): Promise<FlakyNetworkProxy> {
+   const targetHost = options.targetHost ?? '127.0.0.1';
+   const controlPort = options.controlPort ?? options.listenPort + 1000;
+   const pairs = new Set<ConnectionPair>();
+   let sequence = 0;
+   let transcript: string[] = [];
+
+   const log = (message: string): void => {
+      transcript.push(message);
+      console.log(`[flaky-network] ${message}`);
+   };
+
+   const proxyServer: TcpServer = createTcpServer(browserSocket => {
+      const id = ++sequence;
+      const targetSocket = connect(options.targetPort, targetHost);
+      const pair: ConnectionPair = { id, browserSocket, targetSocket, orphaned: false };
+      pairs.add(pair);
+
+      // Forwarded by hand rather than with `pipe()`, so killing one side does not
+      // tear the other down — which is the entire point of the proxy.
+      browserSocket.on('data', chunk => {
+         if (!targetSocket.destroyed) {
+            targetSocket.write(chunk);
+         }
+      });
+      targetSocket.on('data', chunk => {
+         if (!pair.orphaned && !browserSocket.destroyed) {
+            browserSocket.write(chunk);
+         }
+      });
+
+      const teardown = (origin: 'browser' | 'target'): void => {
+         if (pair.orphaned && origin === 'browser') {
+            // Expected: `break` killed this side deliberately. The server side
+            // stays up until `release`.
+            return;
+         }
+         pairs.delete(pair);
+         browserSocket.destroy();
+         targetSocket.destroy();
+      };
+
+      browserSocket.on('close', () => teardown('browser'));
+      targetSocket.on('close', () => teardown('target'));
+      // A half-killed pair reliably raises ECONNRESET on the surviving side; an
+      // unhandled 'error' would take the whole runner down with it.
+      browserSocket.on('error', () => undefined);
+      targetSocket.on('error', () => undefined);
+   });
+
+   const commands: Record<FlakyNetworkCommand, () => void> = {
+      break: () => {
+         const live = [...pairs].filter(pair => !pair.orphaned);
+         if (live.length === 0) {
+            log('nothing to break');
+            return;
+         }
+         for (const pair of live) {
+            pair.orphaned = true;
+            pair.browserSocket.destroy();
+         }
+         log(`${live.length} connection(s) broken; the browser should reconnect shortly`);
+      },
+      release: () => {
+         const orphans = [...pairs].filter(pair => pair.orphaned);
+         if (orphans.length === 0) {
+            log('no orphaned connections; run `break` first');
+            return;
+         }
+         for (const pair of orphans) {
+            pairs.delete(pair);
+            pair.targetSocket.destroy();
+         }
+         log(`${orphans.length} orphaned connection(s) destroyed; their late disconnect fires now`);
+      },
+      status: () => {
+         const live = [...pairs].filter(pair => !pair.orphaned).length;
+         const orphaned = pairs.size - live;
+         log(`${live} live, ${orphaned} orphaned`);
+      }
+   };
+
+   const run = (name: string): string => {
+      transcript = [];
+      const command = commands[name as FlakyNetworkCommand];
+      if (command) {
+         command();
+      } else {
+         log(`unknown command '${name}'; use: ${Object.keys(commands).join(' | ')}`);
+      }
+      return transcript.join('\n');
+   };
+
+   const controlServer: HttpServer = createHttpServer((request, response) => {
+      const output = run((request.url ?? '').replace(/^\//, '').split('?')[0]);
+      response.writeHead(200, { 'content-type': 'text/plain' });
+      response.end(`${output}\n`);
+   });
+
+   await Promise.all([listen(proxyServer, options.listenPort), listen(controlServer, controlPort)]);
+   // Neither server keeps the process alive, so a runner that starts one from a
+   // config does not need a teardown hook to exit — and a caller that wants a
+   // deterministic shutdown still has `close()`.
+   proxyServer.unref();
+   controlServer.unref();
+
+   return {
+      url: `http://localhost:${options.listenPort}`,
+      controlUrl: `http://localhost:${controlPort}`,
+      break: async () => run('break'),
+      release: async () => run('release'),
+      status: async () => run('status'),
+      close: async () => {
+         for (const pair of pairs) {
+            pair.browserSocket.destroy();
+            pair.targetSocket.destroy();
+         }
+         pairs.clear();
+         await Promise.all([close(proxyServer), close(controlServer)]);
+      }
+   };
+}
+
+/**
+ * Drives a proxy running in another process, over its control channel.
+ *
+ * This is what a spec uses: Playwright workers are separate processes from the
+ * config that started the proxy.
+ */
+export function flakyNetworkControlClient(controlUrl: string): FlakyNetworkControl {
+   const send = async (command: FlakyNetworkCommand): Promise<string> => {
+      const response = await fetch(`${controlUrl}/${command}`);
+      if (!response.ok) {
+         throw new Error(`flaky-network proxy rejected '${command}': ${response.status}`);
+      }
+      return (await response.text()).trim();
+   };
+   return {
+      break: () => send('break'),
+      release: () => send('release'),
+      status: () => send('status')
+   };
+}
+
+function listen(server: TcpServer | HttpServer, port: number): Promise<void> {
+   return new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, () => {
+         server.off('error', reject);
+         resolve();
+      });
+   });
+}
+
+function close(server: TcpServer | HttpServer): Promise<void> {
+   return new Promise(resolve => server.close(() => resolve()));
+}

package/src/testing/playwright/index.ts

@@ -11,6 +11,7 @@
 // `@hydranium/core/testing` barrel) so importing the framework's unit-test
 // helpers never pulls in `@playwright/test` — which is an OPTIONAL peer here.
 export * from './e2e-profiling.js';
+export * from './flaky-network-proxy.js';
 export * from './browser-capture-bridge.js';
 export * from './server-log-capture.js';
 export * from './server-log-fixture.js';

package/src/testing/playwright/server-log-capture.ts

@@ -160,16 +160,28 @@ export function serverLogSpecName(file: string): string {
  * Rename each `<token>.log` (backend) and `<token>.browser.log` (forwarded
  * browser console) to the spec name recorded in its `<token>.spec` sidecar
  * (written by {@link markServerLog}), then delete the sidecar. Colliding names —
- * a spec that opened more than one workspace — get a `-2`, `-3`, … suffix. Token
- * logs without a sidecar are left untouched. Run once, after all server processes
- * have exited (e.g. a reporter's `onEnd`). Best-effort.
+ * a spec that opened more than one workspace — get a `-2`, `-3`, … suffix. Run
+ * once, after all server processes have exited (e.g. a reporter's `onEnd`).
+ * Best-effort.
+ *
+ * Returns the workspace tokens left UNATTRIBUTED — a log the capture wrote that
+ * no test claimed, because that spec never reached
+ * {@link markServerLog} (no `serverLog` fixture, no `beforeEach` call).
+ *
+ * **Returned rather than ignored, because the unattributed state is the
+ * misleading one.** Such a log still exists, still has content, and is named by
+ * an opaque token with no test boundaries in it — so a capture run that covered
+ * nothing looks exactly like one that covered everything, and the logs are
+ * there to be read. A caller that can warn should warn.
  */
-export function renameServerLogs(dir: string): void {
+export function renameServerLogs(dir: string): string[] {
    let entries: string[];
    try {
       entries = readdirSync(dir);
    } catch {
-      return;
+      // An unreadable capture dir has nothing to report — including nothing
+      // unattributed, since no log was observed at all.
+      return [];
    }
    // Per suffix (`.log`, `.browser.log`) a `taken` set guards collisions, so the
    // backend and browser logs for one spec share the same friendly base name.
@@ -190,6 +202,11 @@ export function renameServerLogs(dir: string): void {
          // ignore
       }
    };
+   // Every token the capture produced a backend log for, so the ones no sidecar
+   // claims can be reported rather than silently left behind.
+   const unattributed = new Set(
+      entries.filter(entry => entry.endsWith('.log') && !entry.endsWith('.browser.log')).map(entry => entry.slice(0, -'.log'.length))
+   );
    for (const entry of entries) {
       if (!entry.endsWith('.spec')) {
          continue;
@@ -210,9 +227,11 @@ export function renameServerLogs(dir: string): void {
       if (!name) {
          continue;
       }
+      unattributed.delete(token);
       rename(token, name, '.log');
       rename(token, name, '.browser.log');
    }
+   return [...unattributed];
 }
 
 /**

package/src/testing/playwright/server-log-rename-reporter.ts

@@ -24,6 +24,17 @@ export default class ServerLogRenameReporter {
    }
 
    onEnd(): void {
-      renameServerLogs(this.dir);
+      const unattributed = renameServerLogs(this.dir);
+      if (unattributed.length > 0) {
+         // Loud, because the alternative is a capture run that reads as
+         // complete: these logs exist and have content, but are named by an
+         // opaque workspace token and carry no test boundaries, so nothing
+         // about them says which spec they belong to.
+         console.warn(
+            `[server-log] ${unattributed.length} captured log(s) belong to no test: ${unattributed.join(', ')}.\n` +
+               '[server-log] Those specs never marked a boundary — apply the `serverLog` fixture, ' +
+               'or call `markServerLog`/`attachServerLog` from the suite, or their logs cannot be read per test.'
+         );
+      }
    }
 }

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;
 }
 

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

@@ -9,27 +9,30 @@
 
 import { type AstNode, type LangiumDocument, UriUtils } from '@hydranium/langium';
 import { Disposable } from 'vscode-languageserver';
+import { type AstDiagnostic } from '../langium/validation/document-validator.js';
 import {
-   type AstDocument,
+   AstDocument,
    type AstDocumentManager,
    type AstDocumentUpdatedEvent,
+   type UpdateAttribution,
    type WritableFileSystemProvider
 } from '../documents/ast-document-manager.js';
+import { UNKNOWN_CLIENT_ID } from '../documents/client-ids.js';
 import type { CloseModelArgs, OpenModelArgs } from '@hydranium/protocol';
 import type { StubHydraniumTextDocuments } from './stub-hydranium-text-documents.js';
 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
+ * 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
- * (`isDirectChange`, `getAuthor`, `readFile`) throw if invoked — tests that
- * need them should wire a richer stub or use the real
- * {@link AstDocumentManager}.
+ * (`getAuthor`) throw if invoked — tests that need them
+ * 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
@@ -45,7 +48,7 @@ import type { StubLangiumDocuments } from './stub-langium-documents.js';
  * are still picked so signature drift on them produces a compile
  * error rather than silent divergence.
  */
-export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic = unknown> extends Pick<
+export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> extends Pick<
    AstDocumentManager<TAst, TDiagnostic>,
    | 'open'
    | 'close'
@@ -57,8 +60,7 @@ export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic = unkn
    | 'onClientClosed'
    | 'getAuthor'
    | 'getDocument'
-   | 'isDirectChange'
-   | 'readFile'
+   | 'attributeUpdate'
 > {
    readonly openClients: Map<string, Set<string>>;
 
@@ -104,7 +106,7 @@ export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic = unkn
    updateSubscriptions(uri?: string): number;
 }
 
-export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic = unknown>(
+export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic>(
    textDocuments: StubHydraniumTextDocuments,
    fileSystem: Pick<WritableFileSystemProvider, 'writeFile'>,
    documents?: StubLangiumDocuments<TAst, TDiagnostic>
@@ -131,10 +133,13 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic = u
          clients.add(args.clientId);
          openClients.set(args.uri, clients);
          // The real `open` materialises the synced document (from the payload
-         // text or the filesystem); mirror that so a subsequent `update` finds
-         // an open document to apply its content change to.
+         // text or the filesystem), or attaches the client to the one that is
+         // there; mirror both so a subsequent `update` finds the document open
+         // for this client.
          if (!textDocuments.get(args.uri)) {
             textDocuments.seedOpen(args.uri, args.text ?? '', args.clientId);
+         } else {
+            textDocuments.attachClient(args.uri, args.clientId);
          }
          return Disposable.create(() => close({ uri: args.uri, clientId: args.clientId }));
       },
@@ -193,7 +198,7 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic = u
                return;
             }
             listener({
-               document: { uri, version: textDocuments.version(uri), root: undefined as unknown as TAst, diagnostics: [] as TDiagnostic[] },
+               document: AstDocument.create<TAst, TDiagnostic>(uri, textDocuments.version(uri), undefined as unknown as TAst),
                sourceClientId: event.clientId
             });
          });
@@ -208,17 +213,19 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic = u
       getAuthor(): string {
          return notSupported('getAuthor');
       },
+      // Reports every event as a change by the version's author: the stub
+      // tree runs no builds, so there is no delivery to tell a rebuild by. A
+      // test of the rebuilt branch replaces this method or uses the real
+      // manager.
+      attributeUpdate(document: LangiumDocument): UpdateAttribution {
+         const author = textDocuments.getAuthor(document.textDocument.uri, document.textDocument.version) ?? UNKNOWN_CLIENT_ID;
+         return { reason: 'changed', sourceClientId: author, causedBy: author };
+      },
       // Canonicalizing document gateway. The stub has no canonicalizer, so it looks
       // the document up in the seeded `StubLangiumDocuments` by its given URI (tests
       // that need real symlink canonicalization wire the real AstDocumentManager).
       getDocument(uri: string): LangiumDocument | undefined {
          return documents?.getDocument(UriUtils.toUri(uri));
-      },
-      isDirectChange(): boolean {
-         return notSupported('isDirectChange');
-      },
-      async readFile(uri: string): Promise<string> {
-         return notSupported(`readFile(${uri})`);
       }
    };
 }

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

@@ -9,13 +9,16 @@
 
 import {
    type DocumentBuilder,
+   type DocumentBuildListener,
    type DocumentPhaseListener,
    type DocumentState,
    type DocumentUpdateListener,
    type LangiumDocument,
-   type URI
+   type URI,
+   type WorkspaceLock
 } from '@hydranium/langium';
 import { type CancellationToken, Disposable } from 'vscode-languageserver';
+import { type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
 
 /** Recorded call to a stubbed {@link DocumentBuilder} method. */
 export interface RecordedBuilderCall<TArgs extends unknown[]> {
@@ -45,8 +48,7 @@ export interface StubWaitUntilGate {
 
 /**
  * Stub for Langium's {@link DocumentBuilder}. Implements the slice production
- * code reads from on the framework's test paths (`update` / `waitUntil` /
- * `onDocumentPhase` / `onUpdate`) plus test-only helpers:
+ * code reads on the framework's test paths, plus test-only helpers:
  *
  * - {@link firePhase} — synchronously dispatch the registered phase
  *   listener(s) for a document, simulating a build completing.
@@ -64,16 +66,17 @@ export interface StubWaitUntilGate {
  * Picks the methods the framework reads from {@link DocumentBuilder} on
  * the slot path — the compiler enforces those signatures stay aligned.
  * `update`, `onDocumentPhase`, `onUpdate`, and `waitUntil` carry stubbed
- * implementations; `build`, `onBuildPhase`, and `resetToState` are
- * implemented as loud-failing `notSupported` throwers so production code
- * that goes through the cast at the bind site (i.e. accesses methods the
+ * implementations, and `scheduleUpdate` calls `update` in one lock write per
+ * call (see {@link makeStubDocumentBuilder}); `build`, `onBuildPhase`, and
+ * `resetToState` are implemented as loud-failing `notSupported` throwers
+ * so production code that goes through the cast at the bind site (i.e. accesses methods the
  * stub claims but doesn't meaningfully implement) fails with a clear
  * message instead of "undefined is not a function".
  */
-export interface StubDocumentBuilder extends Pick<
-   DocumentBuilder,
-   'update' | 'onDocumentPhase' | 'onUpdate' | 'build' | 'onBuildPhase' | 'resetToState'
-> {
+export interface StubDocumentBuilder
+   extends
+      Pick<DocumentBuilder, 'update' | 'onDocumentPhase' | 'onUpdate' | 'build' | 'onBuildPhase' | 'resetToState' | 'updateBuildOptions'>,
+      Pick<HydraniumDocumentBuilder, 'onDocumentPhaseDelivered' | 'scheduleUpdate'> {
    /**
     * Single-overload stub of {@link DocumentBuilder.waitUntil}. Real has
     * two overloads (`(state, cancelToken?): Promise<void>` and
@@ -87,13 +90,22 @@ export interface StubDocumentBuilder extends Pick<
    readonly waitUntilCalls: ReadonlyArray<RecordedBuilderCall<[DocumentState, URI | undefined]>>;
    /**
     * Synchronously fire the phase listener(s) registered for `state` with
-    * `document`. `cancelToken` defaults to a non-cancelled token; pass a
-    * cancelled token to simulate a build preempted by a concurrent write
-    * lock.
+    * `document`, then, unless `cancelToken` is 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.
     */
    firePhase(state: DocumentState, document: LangiumDocument, cancelToken?: CancellationToken): void;
    /** Synchronously fire every registered `onUpdate` listener. */
    fireOnUpdate(changed: URI[], deleted: URI[]): void;
+   /**
+    * Synchronously fire the BUILD-phase listener(s) for `state` with the whole
+    * batch. The per-build counterpart of {@link firePhase}: a subject that
+    * reports once per build rather than once per document subscribes here, and
+    * a stub that only fired {@link firePhase} would leave it silent while
+    * looking wired.
+    */
+   fireBuildPhase(state: DocumentState, built: LangiumDocument[], cancelToken?: CancellationToken): void;
    /**
     * Hold the next {@link waitUntil} call. The returned handle releases it;
     * the call's return value resolves on the next tick after `resolve` runs.
@@ -128,9 +140,16 @@ function reraise(result: unknown): void {
  * want to observe rebuilt state should `set` the new root on the document
  * registry and then call `firePhase` to trigger the framework's post-build
  * read path.
+ *
+ * `workspaceLock` is the lock `scheduleUpdate` writes under, without the real
+ * builder's sharing: pass the services tree's own, so a caller's lock ordering
+ * and reentrancy behave as against the real builder. Without one,
+ * `scheduleUpdate` records the update unlocked.
  */
-export function makeStubDocumentBuilder(): StubDocumentBuilder {
+export function makeStubDocumentBuilder(workspaceLock?: WorkspaceLock): StubDocumentBuilder {
    const phaseListeners = new Map<DocumentState, DocumentPhaseListener[]>();
+   const deliveredListeners = new Map<DocumentState, Array<(document: LangiumDocument, version: number) => void>>();
+   const buildPhaseListeners = new Map<DocumentState, DocumentBuildListener[]>();
    const onUpdateListeners: DocumentUpdateListener[] = [];
    const gates: Array<{ take(release: () => void): void }> = [];
    const updateCalls: RecordedBuilderCall<[URI[], URI[]]>[] = [];
@@ -140,6 +159,9 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
       throw new Error(`StubDocumentBuilder.${method} is not implemented; wire a real DocumentBuilder if your test needs it.`);
    };
    const stub: StubDocumentBuilder = {
+      // Langium's own default, so a session write waits for `Validated` here
+      // as it does against the real builder.
+      updateBuildOptions: { validation: { categories: ['built-in', 'fast'] } },
       get updateCalls() {
          return updateCalls;
       },
@@ -149,6 +171,9 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
       async update(changed: URI[], deleted: URI[]) {
          updateCalls.push({ args: [changed, deleted] });
       },
+      scheduleUpdate(changed: URI[], deleted: URI[]) {
+         return workspaceLock ? workspaceLock.write(() => stub.update(changed, deleted)) : stub.update(changed, deleted);
+      },
       async waitUntil(state: DocumentState, uri?: URI) {
          waitUntilCalls.push({ args: [state, uri] });
          const gate = gates.shift();
@@ -185,15 +210,58 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
                onCancellationRequested: () => Disposable.create(() => undefined)
             } as CancellationToken);
          const listeners = phaseListeners.get(state) ?? [];
+         const delivered = deliveredListeners.get(state) ?? [];
+         // Taken before the listeners, as the real builder does: one of them
+         // 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;
          for (const listener of listeners) {
             reraise(listener(document, token));
          }
+         if (!token.isCancellationRequested) {
+            for (const listener of delivered) {
+               listener(document, version);
+            }
+         }
+      },
+      onDocumentPhaseDelivered(state: DocumentState, listener: (document: LangiumDocument, version: number) => void) {
+         const list = deliveredListeners.get(state) ?? [];
+         list.push(listener);
+         deliveredListeners.set(state, list);
+         return Disposable.create(() => {
+            const idx = list.indexOf(listener);
+            if (idx >= 0) {
+               list.splice(idx, 1);
+            }
+         });
       },
       fireOnUpdate(changed: URI[], deleted: URI[]) {
          for (const listener of onUpdateListeners.slice()) {
             reraise(listener(changed, deleted));
          }
       },
+      onBuildPhase(state: DocumentState, listener: DocumentBuildListener) {
+         const list = buildPhaseListeners.get(state) ?? [];
+         list.push(listener);
+         buildPhaseListeners.set(state, list);
+         return Disposable.create(() => {
+            const idx = list.indexOf(listener);
+            if (idx >= 0) {
+               list.splice(idx, 1);
+            }
+         });
+      },
+      fireBuildPhase(state: DocumentState, built: LangiumDocument[], cancelToken?: CancellationToken) {
+         const token =
+            cancelToken ??
+            ({
+               isCancellationRequested: false,
+               onCancellationRequested: () => Disposable.create(() => undefined)
+            } as CancellationToken);
+         for (const listener of buildPhaseListeners.get(state) ?? []) {
+            reraise(listener(built, token));
+         }
+      },
       gateNextWaitUntil(): StubWaitUntilGate {
          let release: (() => void) | undefined;
          const entry = {
@@ -224,14 +292,12 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
       build() {
          return notSupported('build');
       },
-      onBuildPhase() {
-         return notSupported('onBuildPhase');
-      },
       resetToState() {
          return notSupported('resetToState');
       },
       reset() {
          phaseListeners.clear();
+         deliveredListeners.clear();
          onUpdateListeners.length = 0;
          gates.length = 0;
          updateCalls.length = 0;