@hydranium/core 1.0.0-next.11 → 1.0.0-next.112

package/src/node/profiling-run.ts

@@ -55,8 +55,8 @@ export interface ProfilingRunOptions {
    /**
     * Optional latency collector. When present, {@link ProfilingRun.finish} writes
     * its report to `server-latency.json` and records a `server-latency` manifest artefact. A
-    * head feeds it via the RPC binding / `instrumentLspConnection`; a pure
-    * headless build with no request traffic leaves it empty.
+    * head feeds it via the RPC binding / `lspLatencyOptions`; a pure headless
+    * build with no request traffic leaves it empty.
     */
    latency?: LatencyCollector;
 }
@@ -97,7 +97,7 @@ export class ProfilingRun {
       // `HYDRANIUM_LOG_FILE` env, which every `@hydranium/core` copy reads when
       // its logger is CONSTRUCTED — so `ProfilingRun.start` must run before the
       // head's services are created (as `measureModelMemory` does). This is the
-      // only mechanism that crosses a yalc'd adopter's separate core copy; a
+      // only mechanism that crosses an adopter's separate core copy; a
       // process-local `setLogFilePath` would only reach this module's own copy.
       this.previousLogFileEnv = process.env[DEFAULT_LOG_FILE_ENV];
       process.env[DEFAULT_LOG_FILE_ENV] = this.serverLogPath;

package/src/node/rename-over-open-readers.ts

@@ -0,0 +1,78 @@
+/********************************************************************************
+ * 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 * as fsp from 'node:fs/promises';
+
+/**
+ * Errnos Windows raises when a replacing `rename` meets a handle already on the
+ * destination open. POSIX renames are unaffected by open handles, so these
+ * cannot fire there and the retry below costs nothing.
+ */
+export const RENAME_CONTENTION_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+/**
+ * How long a replacing rename may keep retrying before it gives up.
+ *
+ * BOUNDED, not open-ended: a genuine permission fault raises the same errno as
+ * contention and is distinguishable from it only by never clearing, so an
+ * unbounded wait would convert a hard error into a hang.
+ *
+ * The figure is a judgement, not a measurement, and the honest bound on it is
+ * that the previous 2s was observed EXHAUSTED on a loaded Windows CI runner
+ * while no upper bound has been established. What would settle it is recording
+ * how long a real contended rename takes to clear. graceful-fs tolerates 60s
+ * for Windows rename contention, but that is weaker support than it looks: it
+ * retries only where the destination has GONE, which is the opposite of
+ * replacing one a reader holds open.
+ */
+export const RENAME_BUDGET_MS = 10_000;
+
+/** Seams for the test, which cannot make a real rename fail on demand. */
+export interface RenameOverOpenReadersOptions {
+   readonly rename?: (from: string, to: string) => Promise<void>;
+   readonly budgetMs?: number;
+}
+
+/**
+ * `rename` the staged content over `destination`, retrying while Windows
+ * reports the destination as held open.
+ *
+ * The staging file exists so a reader never sees a half-written file, and on
+ * Windows the very presence of that reader is what makes the replacing rename
+ * fail — so the indivisible write breaks under exactly the contention it was
+ * built for, and it breaks intermittently, which is worse than never working.
+ * A reader's handle is released in milliseconds, so waiting turns a spurious
+ * failure into a slightly later success.
+ *
+ * Exhausting the budget rethrows the last failure, leaving the caller's cleanup
+ * and error contract unchanged. An errno OUTSIDE the contention set is rethrown
+ * without waiting at all: retrying a fault that will not clear only delays it.
+ */
+export async function renameOverOpenReaders(
+   staging: string,
+   destination: string,
+   options: RenameOverOpenReadersOptions = {}
+): Promise<void> {
+   const rename = options.rename ?? fsp.rename;
+   const deadline = Date.now() + (options.budgetMs ?? RENAME_BUDGET_MS);
+   for (let attempt = 0; ; attempt++) {
+      try {
+         await rename(staging, destination);
+         return;
+      } catch (err: unknown) {
+         const code = err instanceof Error && 'code' in err ? String((err as NodeJS.ErrnoException).code) : undefined;
+         if (code === undefined || !RENAME_CONTENTION_CODES.has(code) || Date.now() >= deadline) {
+            throw err;
+         }
+         // Backs off to keep a long contention window from spinning, capped so
+         // a late attempt still lands promptly once the handle is released.
+         await new Promise(resolve => setTimeout(resolve, Math.min(2 ** attempt, 50)));
+      }
+   }
+}

package/src/node/socket-launcher.ts

@@ -24,6 +24,21 @@ export interface SocketServerOptions {
     * resolves (only then is the address info available).
     */
    readonly port?: number;
+   /**
+    * Interface to bind. Default `'127.0.0.1'` (LOCAL ONLY) — a head whose
+    * port is OS-assigned and announced over the LSP connection is
+    * reachable only by a client on the same machine anyway, so a wider
+    * binding exposes a port nothing off-box can address. Matches
+    * `startGlspServer`'s default, so the two socket heads agree.
+    *
+    * Pass `'::'` for every interface: that is the dual-stack any-address,
+    * so both IPv4 and IPv6 clients connect. `'0.0.0.0'` is NOT the same —
+    * it takes IPv4 only and refuses `::1`.
+    *
+    * An address no local interface holds fails the bind, so `started`
+    * rejects with `EADDRNOTAVAIL` rather than falling back to a wider one.
+    */
+   readonly host?: string;
    /**
     * Optional logger. If omitted, the launcher runs silently — the
     * adopter is expected to surface lifecycle events through their own
@@ -88,6 +103,7 @@ export interface StartedSocketServer extends IntegratedServer {
  */
 export function startSocketServer(options: SocketServerOptions, onClientConnection: OnClientConnection): StartedSocketServer {
    const port = options.port ?? 0;
+   const host = options.host ?? '127.0.0.1';
    const logger = options.logger;
    const tag = options.logTag ?? 'SocketServer';
    const started = new Deferred<void>();
@@ -128,7 +144,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
       connection.listen();
    });
 
-   netServer.listen(port);
+   netServer.listen(port, host);
    netServer.on('listening', () => {
       const addressInfo = netServer.address();
       if (!addressInfo) {
@@ -144,7 +160,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
          return;
       }
       handle.port = addressInfo.port;
-      logger?.info(`[${tag}] Ready to accept new client requests on port: ${addressInfo.port}`);
+      logger?.info(`[${tag}] Ready to accept new client requests on ${addressInfo.address} port: ${addressInfo.port}`);
       started.resolve();
    });
    netServer.on('error', err => {

package/src/testing/fake-document.ts

@@ -7,7 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { DocumentState, type AstNode, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+import { DocumentState, type AstNode, type AstReflection, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+import { buildAstNode } from '../langium/ast-extension/ast-node-builder.js';
+import { type AstDiagnostic } from '../langium/validation/document-validator.js';
 
 /**
  * Build a typed AST-node fixture for unit tests.
@@ -23,12 +25,29 @@ import { DocumentState, type AstNode, type LangiumDocument, UriUtils, type URI }
  * framework synthetic node, and marking it would change scope/index behaviour.
  * A test that wants a genuine synthetic node calls `markSynthetic` explicitly.
  *
+ * **Without a `reflection`, the fixture carries only what the test spells out**,
+ * which is a shape production never produces: a parsed or built node always has
+ * its grammar-declared containment arrays, so a fixture that omits one lets a
+ * test pass against an impossible node, and lets code that walks a list crash
+ * only under test. Pass the grammar's reflection whenever the type is a real
+ * one and the code under test reads a collection off it. Fixtures typed against
+ * ad-hoc names have no reflection to pass and keep the plain form.
+ *
  * @param node the node shape — `$type` is required; every other property is a
  *   value the test cares about (`$container`, cross-reference values, internal
- *   `_id` fields, …). The object is returned by reference, not copied.
+ *   `_id` fields, …).
+ * @param reflection when given, pre-fills the grammar's declared defaults the
+ *   same way {@link buildAstNode} does, and the result is a fresh object rather
+ *   than `node` itself. Omitted, `node` is returned by reference.
  */
-export function makeFakeAstNode<TAst extends AstNode = AstNode>(node: { $type: string } & Record<string, unknown>): TAst {
-   return node as unknown as TAst;
+export function makeFakeAstNode<TAst extends AstNode = AstNode>(
+   node: { $type: string } & Record<string, unknown>,
+   reflection?: AstReflection
+): TAst {
+   if (!reflection) {
+      return node as unknown as TAst;
+   }
+   return buildAstNode<TAst>(reflection, node.$type, node);
 }
 
 /**
@@ -86,7 +105,7 @@ function stringifyFakeRoot(root: unknown): string {
  * staging. Override via `options.state` for tests that gate on earlier
  * phases.
  */
-export function makeFakeDocument<TAst extends AstNode = AstNode, TDiagnostic = unknown>(
+export function makeFakeDocument<TAst extends AstNode = AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic>(
    uri: string | URI,
    root: TAst,
    options: FakeDocumentOptions<TAst, TDiagnostic> = {}

package/src/testing/make-noop-shared-services.ts

@@ -9,6 +9,8 @@
 
 import { type Clock, DefaultTracer, type Logger, NoopLogger, SystemClock, type Tracer } from '@hydranium/protocol';
 import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { DefaultServerLocale, type ServerLocale } from '../locale/server-locale.js';
+import { DefaultMessageRenderer, type MessageRenderer } from '../messages/renderer.js';
 
 /**
  * Overrides for {@link makeNoopSharedServices}. The three observability slots
@@ -29,6 +31,18 @@ export interface NoopSharedServicesOverrides {
    Logger?: Logger;
    /** Bound on the top-level `Tracer` slot. Default: a `DefaultTracer` over `Logger` + `Clock`. */
    Tracer?: Tracer;
+   /** Factory for the `ServerLocale` slot. Default: a real one, reporting no locale. */
+   ServerLocale?: (services: ServerSharedServicesMinimal) => ServerLocale;
+   /**
+    * Factory for the `MessageRenderer` slot. Default: the real
+    * {@link DefaultMessageRenderer}, whose no-catalogue behaviour is a
+    * pass-through — so the default is the framework's own behaviour, not a stub.
+    *
+    * A factory rather than an instance, because a renderer reads the tree it is
+    * bound into. Both slots are resolved lazily, so an override is honoured
+    * however late the caller reads them.
+    */
+   MessageRenderer?: (services: ServerSharedServicesMinimal) => MessageRenderer;
    /** Per-slot `workspace` overrides. Slots left out resolve to `undefined`. */
    workspace?: Record<string, unknown>;
    /** Any other minimal slot (`ServiceRegistry`, `AstReflection`, `additionalDocuments`, …). */
@@ -63,11 +77,21 @@ export interface NoopSharedServicesOverrides {
 export function makeNoopSharedServices<T extends ServerSharedServicesMinimal = ServerSharedServicesMinimal>(
    overrides: NoopSharedServicesOverrides = {}
 ): T {
-   const { Clock: clock, Logger: logger, Tracer: tracer, workspace, additionalDocuments, ...restTop } = overrides;
+   const {
+      Clock: clock,
+      Logger: logger,
+      Tracer: tracer,
+      ServerLocale: serverLocale,
+      MessageRenderer: messageRenderer,
+      workspace,
+      additionalDocuments,
+      ...restTop
+   } = overrides;
    const resolvedClock = clock ?? new SystemClock();
    const resolvedLogger = logger ?? new NoopLogger();
    const resolvedTracer = tracer ?? new DefaultTracer(resolvedLogger, resolvedClock);
-   return {
+   // Assembled in two steps, because both defaults read the tree they belong to.
+   const services = {
       Clock: resolvedClock,
       Logger: resolvedLogger,
       Tracer: resolvedTracer,
@@ -75,4 +99,28 @@ export function makeNoopSharedServices<T extends ServerSharedServicesMinimal = S
       ...restTop,
       workspace: { ...(workspace ?? {}) }
    } as unknown as T;
+   // Lazy, like Langium's own per-slot construction — and load-bearing here:
+   // both services emit an `instantiated` trace, so building them eagerly puts
+   // two lines into the capture of every test that passes a capturing logger
+   // and asserts on emptiness.
+   defineLazySlot(services, 'ServerLocale', () => serverLocale?.(services) ?? new DefaultServerLocale(services));
+   defineLazySlot(services, 'MessageRenderer', () => messageRenderer?.(services) ?? new DefaultMessageRenderer(services));
+   return services;
+}
+
+/** Install `name` as a memoized getter, so nothing is constructed until it is read. */
+function defineLazySlot(target: object, name: string, create: () => unknown): void {
+   let resolved: unknown;
+   let built = false;
+   Object.defineProperty(target, name, {
+      configurable: true,
+      enumerable: true,
+      get: () => {
+         if (!built) {
+            resolved = create();
+            built = true;
+         }
+         return resolved;
+      }
+   });
 }

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

@@ -10,6 +10,7 @@
 import {
    type Clock,
    DefaultTracer,
+   type Locale,
    type Logger,
    NoopLogger,
    type Project,
@@ -18,11 +19,14 @@ 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 { 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 type { FakeDocumentOptions } from './fake-document.js';
@@ -46,12 +50,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;
@@ -90,17 +103,27 @@ export interface TestSharedServices<
       WorkspaceLock: WorkspaceLock;
    };
    readonly model: {
-      TransferEncoder: TransferEncoder<unknown, TDiagnostic>;
+      TransferEncoder: TransferEncoder<TTransferDiagnostic>;
       ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
    };
+   /**
+    * 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 +135,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:
@@ -187,7 +218,7 @@ export interface MakeTestServicesOptions<
     * Override the {@link TransferEncoder} factory. Default: framework
     * {@link TransferEncoder} with no overrides.
     */
-   transferEncoder?: (services: ServerSharedServices<TProject>) => TransferEncoder<unknown, TDiagnostic>;
+   transferEncoder?: (services: ServerSharedServices<TProject>) => TransferEncoder<TTransferDiagnostic>;
 }
 
 /**
@@ -205,9 +236,10 @@ 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 documents: StubLangiumDocuments<TAst, TDiagnostic>;
@@ -229,10 +261,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,12 +287,13 @@ 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();
@@ -289,7 +330,7 @@ export function makeTestServices<
    // (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,
@@ -311,20 +352,33 @@ export function makeTestServices<
          ...(indexManager ? { IndexManager: indexManager } : {}),
          WorkspaceLock: new HydraniumWorkspaceLock()
       },
-      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>;
 
+   // 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>;
    };
    mutableModel.TransferEncoder = transferEncoder;
@@ -346,6 +400,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;
 
@@ -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 },