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

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

@@ -10,6 +10,7 @@
 import {
    type Clock,
    DefaultTracer,
+   type Locale,
    type Logger,
    NoopLogger,
    type Project,
@@ -18,13 +19,22 @@ import {
    type TransferDiagnostic,
    type TransferElement
 } from '@hydranium/protocol';
+import { DefaultServerLocale, type ServerLocale } from '../locale/server-locale.js';
+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 { TransferEncoder } from '../langium/transfer/transfer-encoder.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';
@@ -46,12 +56,21 @@ import { makeStubWritableFileSystem, type StubWritableFileSystem } from './stub-
  * to `ServerSharedServices` in {@link makeTestServices} is therefore the
  * single named place where the "stub stands in for the full service tree"
  * assertion happens.
+ *
+ * **`TDiagnostic` and `TTransferDiagnostic` are the two ends of a conversion
+ * and must stay separate.** The first is what the build left on
+ * `LangiumDocument.diagnostics` and what `ModelService` hands back on an
+ * `AstDocument`; the second is what `TransferEncoder.toTransferDiagnostic`
+ * produces for the wire. One parameter serving both makes the tree
+ * unbindable for an adopter who extends either shape, since extending one
+ * says nothing about the other.
  */
 export interface TestSharedServices<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
    readonly Clock: Clock;
    readonly Logger: Logger;
@@ -72,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
@@ -90,17 +111,28 @@ export interface TestSharedServices<
       WorkspaceLock: WorkspaceLock;
    };
    readonly model: {
-      TransferEncoder: TransferEncoder<unknown, TDiagnostic>;
+      TransferEncoder: TransferEncoder<TTransferDiagnostic>;
       ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
+      ClientSessionFactory: ClientSessionFactory;
    };
+   /**
+    * The REAL services, not stubs — the framework renderer's no-catalogue
+    * behaviour is a pass-through, so the stub tree agrees with a production one
+    * unless a test installs a catalogue. Bound rather than omitted because
+    * `HydraniumDocumentBuilder` renders through the renderer on every
+    * `Validated` phase, where an omitted slot is a `TypeError`.
+    */
+   readonly ServerLocale: ServerLocale;
+   readonly MessageRenderer: MessageRenderer;
 }
 
 /** Optional configuration for {@link makeTestServices}. */
 export interface MakeTestServicesOptions<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
    /**
     * Serialiser used by the bundled `StubModelService`. The stub tree
@@ -112,6 +144,14 @@ export interface MakeTestServicesOptions<
     * for tests that don't assert on the produced text.
     */
    serialize?: (uri: string, root: TTransfer) => string;
+   /**
+    * Renderer bound on `MessageRenderer`. Default: the framework's own, which
+    * passes every sentence through unchanged. Supply one to install a catalogue
+    * or to drive the throwing path.
+    */
+   messageRenderer?: (services: ServerSharedServices<TProject>) => MessageRenderer;
+   /** Locale handed to the bundle's {@link ServerLocale}. Default: none, i.e. the framework's English. */
+   locale?: Locale;
    /**
     * Languages to register on a {@link StubServiceRegistry} bound on the
     * `ServiceRegistry` slot. This is how a test gets multi-language routing:
@@ -120,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.
     */
@@ -178,16 +218,23 @@ 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 (`allowReentrantBuilds`) 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.
     */
-   transferEncoder?: (services: ServerSharedServices<TProject>) => TransferEncoder<unknown, TDiagnostic>;
+   transferEncoder?: (services: ServerSharedServices<TProject, TTransferDiagnostic>) => TransferEncoder<TTransferDiagnostic>;
 }
 
 /**
@@ -205,11 +252,12 @@ export interface MakeTestServicesOptions<
  */
 export interface TestServicesBundle<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > extends Harness {
-   readonly services: ServerSharedServices<TProject>;
+   readonly services: ServerSharedServices<TProject, TTransferDiagnostic>;
    readonly documents: StubLangiumDocuments<TAst, TDiagnostic>;
    readonly textDocuments: StubHydraniumTextDocuments;
    readonly astDocumentManager: StubAstDocumentManager<TAst, TDiagnostic>;
@@ -229,10 +277,18 @@ export interface TestServicesBundle<
     */
    readonly indexManager: StubIndexManager | undefined;
    readonly modelService: ModelService<TAst, TDiagnostic, TTransfer>;
-   readonly transferEncoder: TransferEncoder<unknown, TDiagnostic>;
+   readonly transferEncoder: TransferEncoder<TTransferDiagnostic>;
    readonly logger: Logger;
    /** The clock bound on the `Clock` slot — a `makeFakeClock()` if one was passed. */
    readonly clock: Clock;
+   /**
+    * The service bound on `ServerLocale`, so a test can hand over a locale
+    * mid-run — which is also how it verifies the renderer reads the locale per
+    * render rather than caching it at construction.
+    */
+   readonly serverLocale: ServerLocale;
+   /** The renderer bound on `MessageRenderer` — the framework's own unless one was supplied. */
+   readonly messageRenderer: MessageRenderer;
 }
 
 /**
@@ -247,22 +303,24 @@ export interface TestServicesBundle<
  */
 export function makeTestServices<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 >(
-   options: MakeTestServicesOptions<TAst, TDiagnostic, TTransfer, TProject> = {}
-): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject> {
+   options: MakeTestServicesOptions<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> = {}
+): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> {
    const documents = makeStubLangiumDocuments<TAst, TDiagnostic>(options.seedDocuments);
    const textDocuments = makeStubHydraniumTextDocuments();
-   const documentBuilder = makeStubDocumentBuilder();
+   const logger = options.logger ?? new NoopLogger();
+   const clock = options.clock ?? new SystemClock();
+   const tracer = new DefaultTracer(logger, clock);
+   const workspaceLock = new HydraniumWorkspaceLock({ Clock: clock, Tracer: tracer });
+   const documentBuilder = makeStubDocumentBuilder(workspaceLock);
    const selfSaveRegistry = makeStubSelfSaveRegistry();
    const fileSystem = makeStubWritableFileSystem(selfSaveRegistry);
    const projectManager = makeStubProjectManager<TProject>(options.seedProjects);
    const astDocumentManager = makeStubAstDocumentManager<TAst, TDiagnostic>(textDocuments, fileSystem, documents);
-   const logger = options.logger ?? new NoopLogger();
-   const clock = options.clock ?? new SystemClock();
-   const tracer = new DefaultTracer(logger, clock);
    const documentUriPolicy = options.documentUriPolicy ?? new DefaultDocumentUriPolicy();
    const serviceRegistry = options.languages
       ? makeStubServiceRegistry(options.languages, { openLanguageIds: options.openLanguageIds })
@@ -285,11 +343,11 @@ 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.
-   const services: TestSharedServices<TAst, TDiagnostic, TTransfer, TProject> = {
+   const services: TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> = {
       Clock: clock,
       Logger: logger,
       Tracer: tracer,
@@ -309,26 +367,42 @@ 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: workspaceLock,
+         FileSystemTaskQueue: new DefaultFileSystemTaskQueue({ workspace: { DocumentUriPolicy: documentUriPolicy } })
       },
-      model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject>['model']
+      model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic>['model'],
+      ServerLocale: {} as ServerLocale,
+      MessageRenderer: {} as DefaultMessageRenderer
    };
-   const sharedServices = services as unknown as ServerSharedServices<TProject>;
+   const sharedServices = services as unknown as ServerSharedServices<TProject, TTransferDiagnostic>;
+
+   // Patched in after the literal, like `model` below: both read the tree they
+   // belong to, and the renderer reads the locale service.
+   const mutableMessages = services as { ServerLocale: ServerLocale; MessageRenderer: MessageRenderer };
+   const serverLocale = new DefaultServerLocale(sharedServices);
+   if (options.locale) {
+      serverLocale.accept(options.locale);
+   }
+   mutableMessages.ServerLocale = serverLocale;
+   const messageRenderer = options.messageRenderer?.(sharedServices) ?? new DefaultMessageRenderer(sharedServices);
+   mutableMessages.MessageRenderer = messageRenderer;
 
    const serialize = options.serialize ?? ((_uri: string, root: TTransfer) => JSON.stringify(root));
    const transferEncoder = options.transferEncoder
       ? options.transferEncoder(sharedServices)
-      : new TransferEncoder<unknown, TDiagnostic>(sharedServices);
+      : new DefaultTransferEncoder<unknown, TTransferDiagnostic>(sharedServices);
    const modelService = options.modelService
       ? options.modelService(sharedServices)
       : makeStubModelService<TAst, TDiagnostic, TTransfer>(sharedServices, serialize, options.modelServiceOptions);
 
    const mutableModel = services.model as {
-      TransferEncoder: TransferEncoder<unknown, TDiagnostic>;
+      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,
@@ -346,6 +420,8 @@ export function makeTestServices<
       transferEncoder,
       logger,
       clock,
+      serverLocale,
+      messageRenderer,
       dispose: () => {
          // No-op: the bundled stubs hold only in-memory state (maps, arrays),
          // released with the bundle when it goes out of scope. The hook exists

package/src/testing/node/index.ts

@@ -27,3 +27,4 @@ export * from './lsp-harness.js';
 export * from './lsp-server-connection.js';
 export * from './scratch-workspace.js';
 export * from './spawned-server.js';
+export * from './unhandled-rejections.js';

package/src/testing/node/lsp-harness.ts

@@ -216,12 +216,14 @@ export function makeLspHarness(options: MakeLspHarnessOptions): LspHarness {
       },
       shutdown: transport.shutdown,
       openDocument: transport.openDocument,
+      closeDocument: transport.closeDocument,
       changeDocument: transport.changeDocument,
       completion: transport.completion,
       hover: transport.hover,
       semanticTokens: transport.semanticTokens,
       nextDiagnostics: transport.nextDiagnostics,
       appliedEdits: transport.appliedEdits,
+      wireBytes: transport.wireBytes,
       nextAppliedEdit: transport.nextAppliedEdit,
       setApplyEditHandler: transport.setApplyEditHandler,
       buildWorkspace: folders => buildWorkspaceProgrammatically(services, folders),

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

@@ -8,17 +8,16 @@
  ********************************************************************************/
 
 import { type Harness } from '@hydranium/protocol/testing';
-import { makeDuplexStreamPair } from '@hydranium/protocol/testing/node';
+import { PassThrough, type TransformCallback } from 'node:stream';
 import { StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node';
 import { type Connection, ProposedFeatures } from 'vscode-languageserver/node';
+import { withHydraniumLspFeatures } from '../../lsp/connection-features.js';
 // The node `createConnection` from `vscode-languageserver/node` is built for a
 // standalone server PROCESS: it wires `process.exit()` onto the input stream's
 // `end`/`close` events, onto the `exit` notification (via its watchDog), and onto
-// a parent-pid liveness timer, and it calls `endProtocolConnection()` (a write)
-// on stream close. In-process every one of those is fatal — destroying the
-// streams at teardown trips the `close` handler, which writes into the destroyed
-// stream (an uncatchable synchronous `ERR_STREAM_DESTROYED`) and/or exits the host
-// test runner. The lower-level common `createConnection(connectionFactory,
+// a parent-pid liveness timer. In-process every one of those is fatal —
+// destroying the streams at teardown trips the `close` handler, which exits the
+// host test runner. The lower-level common `createConnection(connectionFactory,
 // watchDog, features)` form does none of that: it lets us inject a no-op-`exit`
 // WatchDog and build the connection over the in-memory streams, so teardown is the
 // primitive's responsibility alone.
@@ -30,6 +29,7 @@ import {
    ApplyWorkspaceEditRequest,
    CompletionRequest,
    DidChangeTextDocumentNotification,
+   DidCloseTextDocumentNotification,
    DidOpenTextDocumentNotification,
    HoverRequest,
    InitializeRequest,
@@ -170,8 +170,8 @@ function insertedText(edit: WorkspaceEdit): string {
 }
 
 /**
- * The in-process LSP transport seam — a real `Connection` over the in-memory
- * {@link makeDuplexStreamPair}, plus the client side, the diagnostics capture,
+ * The in-process LSP transport seam — a real `Connection` over a crossed pair
+ * of in-memory streams, plus the client side, the diagnostics capture,
  * and the typed request facades — with NO services attached. It is the lower
  * half of `makeLspHarness`, factored out so a caller can OWN the services
  * tree: build the tree around {@link serverConnection} (`createXxxServices({
@@ -226,6 +226,12 @@ export interface LspServerConnection extends Harness {
     * unhandled method.
     */
    readonly appliedEdits: ReadonlyArray<AppliedEdit>;
+   /** Bytes written in each direction of the in-process JSON-RPC wire. */
+   readonly wireBytes: () => {
+      readonly clientToServer: number;
+      readonly serverToClient: number;
+      readonly total: number;
+   };
 
    /**
     * Drive the real LSP `initialize` → `initialized` handshake and return the
@@ -247,6 +253,8 @@ export interface LspServerConnection extends Harness {
     * associates with a language (silent no-diagnostics). `version` defaults to 1.
     */
    openDocument(uri: string, text: string, languageId: string, version?: number): void;
+   /** Send `textDocument/didClose` for a document opened through this harness. */
+   closeDocument(uri: string): Promise<void>;
    /** Send `textDocument/didChange` for `uri` as a single full-text replacement at `version`. */
    changeDocument(uri: string, text: string, version: number): void;
 
@@ -293,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.
     */
@@ -319,6 +327,39 @@ export interface LspServerConnection extends Harness {
    dispose(): void;
 }
 
+/**
+ * A `PassThrough` that counts the bytes written through it. Counting here
+ * rather than in a `'data'` listener is what keeps the wire buffering: a
+ * listener switches the stream to flowing mode, and a message written before
+ * the server calls `listen()` is then delivered to the counter alone and lost.
+ */
+class CountingPassThrough extends PassThrough {
+   bytes = 0;
+
+   override _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void {
+      this.bytes += chunk.length;
+      callback(null, chunk);
+   }
+}
+
+/** A crossed pair of {@link CountingPassThrough}s, disposed as one. */
+function makeCountingStreamPair(): {
+   readonly clientToServer: CountingPassThrough;
+   readonly serverToClient: CountingPassThrough;
+   dispose(): void;
+} {
+   const clientToServer = new CountingPassThrough();
+   const serverToClient = new CountingPassThrough();
+   return {
+      clientToServer,
+      serverToClient,
+      dispose(): void {
+         clientToServer.destroy();
+         serverToClient.destroy();
+      }
+   };
+}
+
 /**
  * Build the in-process LSP transport seam (server `Connection` + client + wire +
  * diagnostics capture + typed facades) WITHOUT attaching a server. The caller
@@ -331,7 +372,7 @@ export interface LspServerConnection extends Harness {
  * additional protocol heads (data-server, GLSP) onto the same `shared` services.
  */
 export function makeLspServerConnection(): LspServerConnection {
-   const pair = makeDuplexStreamPair();
+   const pair = makeCountingStreamPair();
 
    // No-op watchDog: in-process, no LSP lifecycle event (parent-pid liveness, the
    // `exit` notification, …) may exit the host test runner — `dispose()` owns
@@ -347,7 +388,7 @@ export function makeLspServerConnection(): LspServerConnection {
       logger =>
          createProtocolConnection(new StreamMessageReader(pair.clientToServer), new StreamMessageWriter(pair.serverToClient), logger),
       watchDog,
-      ProposedFeatures.all
+      withHydraniumLspFeatures(ProposedFeatures.all)
    );
 
    // Client side mirrors the directions: reads serverToClient, writes clientToServer.
@@ -415,6 +456,11 @@ export function makeLspServerConnection(): LspServerConnection {
       client,
       diagnostics,
       appliedEdits,
+      wireBytes: () => ({
+         clientToServer: pair.clientToServer.bytes,
+         serverToClient: pair.serverToClient.bytes,
+         total: pair.clientToServer.bytes + pair.serverToClient.bytes
+      }),
 
       async initialize(params?: Partial<InitializeParams>): Promise<InitializeResult> {
          const initializeParams: InitializeParams = {
@@ -455,6 +501,10 @@ export function makeLspServerConnection(): LspServerConnection {
          });
       },
 
+      async closeDocument(uri: string): Promise<void> {
+         await client.sendNotification(DidCloseTextDocumentNotification.type, { textDocument: { uri } });
+      },
+
       changeDocument(uri: string, text: string, version: number): void {
          client.sendNotification(DidChangeTextDocumentNotification.type, {
             textDocument: { uri, version },

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

@@ -14,15 +14,15 @@
  *
  * 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
  * committed sample workspace can **rewrite the sample files**, after which
  * every later run asserts against already-repaired input: a suite that passes
  * while testing nothing. The same applies to a fixture built in place, which
- * additionally loses its explanatory comments, because the write-back goes
- * through the serializer.
+ * additionally comes back in the serializer's layout, because the write-back
+ * goes through it.
  *
  * The second reason is cleanup. Hand-rolled `mkdtempSync` without a matching
  * `rmSync` leaks a directory per test run into the OS temp dir, which nobody
@@ -49,7 +49,7 @@
  */
 
 import { URI } from '@hydranium/langium';
-import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 
@@ -106,7 +106,12 @@ export interface ScratchWorkspace {
  * returned {@link ScratchWorkspace.dispose} with an `afterEach`.
  */
 export function makeScratchWorkspace(options: ScratchWorkspaceOptions = {}): ScratchWorkspace {
-   const root = mkdtempSync(path.join(tmpdir(), options.prefix ?? 'hydranium-scratch-'));
+   // RESOLVED, because `tmpdir()` can itself be a symlink — on macOS it answers
+   // `/tmp`, which links to `/private/tmp`. A root the server canonicalises to a
+   // different path than the one it was handed registers documents under one
+   // spelling and reads them under the other, failing initialization with an
+   // ENOENT that names neither the link nor this call.
+   const root = realpathSync(mkdtempSync(path.join(tmpdir(), options.prefix ?? 'hydranium-scratch-')));
    if (options.seed) {
       cpSync(options.seed, root, { recursive: true });
    }

package/src/testing/node/spawned-server.ts

@@ -203,6 +203,37 @@ export interface SpawnedServer extends Harness {
    dispose(): Promise<number | null>;
 }
 
+/**
+ * Every server started and not yet disposed, so {@link disposeSpawnedServers}
+ * can reach one a test forgot.
+ *
+ * Holds the server — and through it the `ChildProcess` — rather than a pid. A
+ * pid identifies a process only while that process is alive: once it exits the
+ * OS may reissue the number, and Windows does so within seconds. A teardown
+ * that signalled a recorded pid would therefore reach whatever holds it now,
+ * which on a concurrent build is another task's compiler or test runner.
+ */
+const liveServers = new Set<SpawnedServer>();
+
+/**
+ * Terminate every server this module started that has not been disposed, and
+ * forget them.
+ *
+ * Safe to call when none are outstanding, and safe to call twice. Nothing here
+ * can reach a process this module did not spawn, because every kill goes
+ * through the `ChildProcess` handle libuv holds and libuv will not signal a
+ * child it has already reaped.
+ *
+ * A suite that disposes each server as it finishes needs this only as a net; a
+ * suite that does not needs it, because an orphan holding a port or a pipe
+ * makes the NEXT run's verdict meaningless.
+ */
+export async function disposeSpawnedServers(): Promise<void> {
+   const outstanding = [...liveServers];
+   liveServers.clear();
+   await Promise.all(outstanding.map(server => server.dispose()));
+}
+
 /** The captured streams, quoted into a boot-failure message. */
 function bootDiagnosis(stdoutPrefix: string, stderr: string): string {
    return (
@@ -390,7 +421,7 @@ export async function startSpawnedServer(options: SpawnedServerOptions): Promise
       return exitCode;
    }
 
-   return {
+   const server: SpawnedServer = {
       connection,
       pid: child.pid,
       initializeResult,
@@ -440,8 +471,11 @@ export async function startSpawnedServer(options: SpawnedServerOptions): Promise
          });
       },
       dispose(): Promise<number | null> {
+         liveServers.delete(server);
          disposal ??= terminate();
          return disposal;
       }
    };
+   liveServers.add(server);
+   return server;
 }

package/src/testing/node/unhandled-rejections.ts

@@ -0,0 +1,31 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Run a Node-only assertion while collecting process-level unhandled rejection
+ * events. The callback owns the event-loop drain and can therefore choose the
+ * right observation window for the operation under test.
+ *
+ * Inside the window a rejection reaches only the array: while any listener is
+ * registered, Node hands none to its default handler and Vitest reports none as
+ * an error. A callback that never asserts on the array therefore hides every
+ * rejection it provokes.
+ */
+export async function captureUnhandledRejections<T>(callback: (rejections: unknown[]) => Promise<T>): Promise<T> {
+   const rejections: unknown[] = [];
+   const listener = (reason: unknown): void => {
+      rejections.push(reason);
+   };
+   process.on('unhandledRejection', listener);
+   try {
+      return await callback(rejections);
+   } finally {
+      process.off('unhandledRejection', listener);
+   }
+}