@hydranium/protocol 1.0.0-next.39 → 1.0.0-next.390

package/src/testing/fake-clock.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Clock, type Stopwatch, type Timed } from '../clock';
+import { type Clock, type Stopwatch, SystemClock } from '../clock';
 import { Disposable } from '../util';
 
 /** A {@link Clock} whose time only moves when the test calls {@link FakeClock.advance}. */
@@ -17,9 +17,19 @@ export interface FakeClock extends Clock {
     * whose deadline falls within the window — in chronological order, each at
     * its own deadline (so `now()` inside a callback reads the fire instant, not
     * the advance target). Timers scheduled by a callback fire too if they fall
-    * within the same window.
+    * within the same window. A {@link Clock.raceTimer} over a promise that
+    * settles through a chain still pending loses to the timer, so let that
+    * chain settle before advancing.
     */
    advance(ms: number): void;
+   /**
+    * Move `now()` by `ms`, backwards when negative, leaving stopwatches and
+    * timers where they are: the wall-clock step a time sync or a manual change makes,
+    * which a duration taken from two `now()` readings gets wrong.
+    */
+   jumpWallClock(ms: number): void;
+   /** How many {@link Clock.setTimer} timers have neither fired nor been disposed. */
+   pendingTimers(): number;
 }
 
 interface FakeTimer {
@@ -35,72 +45,90 @@ interface FakeTimer {
  * (`Date.now` for `now()`, `performance.now()` for the stopwatch); the fake
  * collapses them onto ONE virtual time axis, so a single
  * {@link FakeClock.advance} drives `now()`, every live stopwatch's elapsed, and
- * any due timer together.
+ * any due timer together; only {@link FakeClock.jumpWallClock} pulls `now()`
+ * off that axis.
  *
  * Server-free and DI-free — lives in `@hydranium/protocol/testing` so every
  * head can bind it without pulling in a server package.
+ *
+ * The clock is a `SystemClock` with its time replaced, so its methods live on
+ * its prototype and a spread of it carries none of them. Replace one by
+ * assigning it onto the clock, or layer over the clock with `Object.create`.
  */
 export function makeFakeClock(options: { now?: number } = {}): FakeClock {
-   let current = options.now ?? 0;
-   const timers: FakeTimer[] = [];
+   return new VirtualClock(options.now ?? 0);
+}
+
+/**
+ * A `SystemClock` whose time, stopwatches and timers read one virtual axis, so
+ * the `measure` and `raceTimer` it inherits run on that axis too.
+ */
+class VirtualClock extends SystemClock implements FakeClock {
+   protected readonly timers: FakeTimer[] = [];
+   /** What {@link jumpWallClock} has added to `now()`. */
+   protected wallClockOffset = 0;
 
-   const makeStopwatch = (): Stopwatch => {
-      const start = current;
-      let lastLap = current;
+   constructor(protected current: number) {
+      super();
+   }
+
+   override now(): number {
+      return this.current + this.wallClockOffset;
+   }
+
+   jumpWallClock(ms: number): void {
+      this.wallClockOffset += ms;
+   }
+
+   override setTimer(callback: () => void, ms: number): Disposable {
+      const timer: FakeTimer = { at: this.current + ms, callback, disposed: false, fired: false };
+      this.timers.push(timer);
+      return Disposable.create(() => {
+         timer.disposed = true;
+      });
+   }
+
+   override stopwatch(): Stopwatch {
+      const read = (): number => this.current;
+      const start = read();
+      let lastLap = start;
       let stopped: number | undefined;
       return {
          get elapsedMs(): number {
-            return (stopped ?? current) - start;
+            return (stopped ?? read()) - start;
          },
          lap(): number {
-            const at = stopped ?? current;
+            const at = stopped ?? read();
             const split = at - lastLap;
             lastLap = at;
             return split;
          },
          stop(): number {
-            if (stopped === undefined) {
-               stopped = current;
-            }
+            stopped ??= read();
             return stopped - start;
          }
       };
-   };
+   }
 
-   return {
-      now: () => current,
-      setTimer(callback: () => void, ms: number): Disposable {
-         const timer: FakeTimer = { at: current + ms, callback, disposed: false, fired: false };
-         timers.push(timer);
-         return Disposable.create(() => {
-            timer.disposed = true;
-         });
-      },
-      stopwatch: makeStopwatch,
-      measure: (<T>(callback: () => T | Promise<T>): Timed<T> | Promise<Timed<T>> => {
-         const stopwatch = makeStopwatch();
-         const result = callback();
-         if (result instanceof Promise) {
-            return (result as Promise<T>).then(value => ({ result: value, elapsedMs: stopwatch.elapsedMs }));
-         }
-         return { result: result as T, elapsedMs: stopwatch.elapsedMs };
-      }) as Clock['measure'],
-      advance(ms: number): void {
-         const target = current + ms;
-         // Fire due timers one at a time, re-scanning after each so a callback
-         // that schedules a nearer timer still fires within this window.
-         for (;;) {
-            const next = timers
-               .filter(timer => !timer.disposed && !timer.fired && timer.at <= target)
-               .sort((left, right) => left.at - right.at)[0];
-            if (!next) {
-               break;
-            }
-            current = next.at;
-            next.fired = true;
-            next.callback();
+   pendingTimers(): number {
+      return this.timers.filter(timer => !timer.disposed && !timer.fired).length;
+   }
+
+   advance(ms: number): void {
+      const target = this.current + ms;
+      // Fire due timers one at a time, re-scanning after each so a callback
+      // that schedules a nearer timer still fires within this window.
+      for (;;) {
+         const next = this.timers
+            .filter(timer => !timer.disposed && !timer.fired && timer.at <= target)
+            .sort((left, right) => left.at - right.at)[0];
+         if (!next) {
+            break;
          }
-         current = target;
+         this.current = next.at;
+         next.fired = true;
+         next.callback();
       }
-   };
+      this.current = target;
+   }
 }

package/src/testing/harness.ts

@@ -22,3 +22,13 @@ export interface Harness {
    /** Release every resource the harness holds. Idempotent; the uniform teardown hook. */
    dispose(): void;
 }
+
+/**
+ * {@link Harness} for a harness whose teardown has to wait, such as one that
+ * deletes a directory only once its server reads none of it. Separate rather
+ * than a widened `Harness`, whose callers rely on a synchronous `dispose()`.
+ */
+export interface AsyncHarness {
+   /** Release every resource the harness holds, resolving once it has. Idempotent. */
+   dispose(): Promise<void>;
+}

package/src/testing/index.ts

@@ -11,13 +11,13 @@
 // primitives: `makeFakeClock` (deterministic `Clock` double on one virtual time
 // axis), `waitFor` / `tick`, the client-side data-head doubles
 // (`makeFakeDataPort` / `makeCapturingDataClient`), the translation-catalogue
-// audit (`flattenCatalogue` / `findUndeclaredCodes` / `findSharedCodes`), and
-// the `Harness` marker
+// audit (`flattenCatalogue` / `findUndeclaredCodes` / `findSharedCodes`), the
+// transfer-node builder (`makeTransferNodeBuilder`), and the `Harness` marker
 // interface every framework harness extends. Kept out of the main barrel so production bundles don't pull
 // the test scaffolding in by default; adopters opt in by importing from
 // `@hydranium/protocol/testing`.
 //
-// Neutrality is gated (`scripts/check-neutral-bundles.mjs`), which is why the
+// Neutrality is gated (`scripts/check-neutral-bundles.mts`), which is why the
 // duplex transports are NOT here: a `PassThrough` pair is in their exported
 // type, so they cannot be made portable and live at `./testing/node` instead.
 // The same rule the package surface uses — the portable name is the short one.
@@ -26,4 +26,5 @@ export * from './catalogue-audit';
 export * from './data-doubles';
 export * from './fake-clock';
 export * from './harness';
+export * from './transfer-node-builder';
 export * from './wait-for';

package/src/testing/node/duplex-connection.ts

@@ -32,8 +32,9 @@ export function makeDuplexConnectionPair(): DuplexConnectionPair {
    const pair = makeDuplexStreamPair();
    const { clientToServer, serverToClient } = pair;
 
-   const left = createMessageConnection(new StreamMessageReader(serverToClient), new StreamMessageWriter(clientToServer));
-   const right = createMessageConnection(new StreamMessageReader(clientToServer), new StreamMessageWriter(serverToClient));
+   // `console`, so a protocol fault on either end shows in the test's output.
+   const left = createMessageConnection(new StreamMessageReader(serverToClient), new StreamMessageWriter(clientToServer), console);
+   const right = createMessageConnection(new StreamMessageReader(clientToServer), new StreamMessageWriter(serverToClient), console);
 
    left.listen();
    right.listen();

package/src/testing/node/index.ts

@@ -8,8 +8,7 @@
  ********************************************************************************/
 
 // Subpath barrel for `@hydranium/protocol/testing/node` — the test transports
-// that need a Node runtime: a crossed `PassThrough` pair and the in-process
-// `MessageConnection` bridge over it.
+// that need a Node runtime, and the capture of `process`'s unhandled rejections.
 //
 // Separate from `./testing` because a `PassThrough` is in `DuplexStreamPair`'s
 // exported type and `StreamMessageReader` comes from `vscode-jsonrpc/node`, so
@@ -20,3 +19,5 @@
 
 export * from './duplex-connection';
 export * from './duplex-stream';
+export * from './message-port-pair';
+export * from './unhandled-rejections';

package/src/testing/node/message-port-pair.ts

@@ -0,0 +1,40 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { MessageChannel } from 'node:worker_threads';
+import type { TransferredMessagePort } from '../../client/post-message-transport';
+
+/**
+ * The two ends of a `worker_threads` `MessageChannel`, typed as the transferred
+ * browser ports `createMessagePortTransport` takes. Node's port clones and keeps
+ * order as a browser's does, which is what lets a headless test stand in for a
+ * worker.
+ *
+ * `dispose` closes both ports. Node reports that as a close and a browser port
+ * reports nothing, so a test that asserts on a close does so before teardown.
+ */
+export interface MessagePortPair {
+   readonly port1: TransferredMessagePort;
+   readonly port2: TransferredMessagePort;
+   dispose(): void;
+}
+
+export function makeMessagePortPair(): MessagePortPair {
+   const channel = new MessageChannel();
+   return {
+      // Node's port satisfies the structural type at runtime; the cast records
+      // one platform's port standing in for the other's.
+      port1: channel.port1 as unknown as TransferredMessagePort,
+      port2: channel.port2 as unknown as TransferredMessagePort,
+      dispose(): void {
+         channel.port1.close();
+         channel.port2.close();
+      }
+   };
+}

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

package/src/testing/transfer-node-builder.ts

@@ -0,0 +1,107 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import type { TransferElement } from '../transfer-element';
+import type { ConcreteTypeName, SingleTypeName } from '../types';
+
+/**
+ * The per-type constant the generated transfer model emits under each type's
+ * name, as Langium does for the AST. Its `$type` literal picks the interface
+ * out of the builder's type map.
+ */
+export interface TransferTypeConstant<TType extends string = string> {
+   readonly $type: TType;
+}
+
+/**
+ * What {@link makeTransferNodeBuilder} reads from a reflection: each type's
+ * grammar properties and their defaults. The generated
+ * `<LanguageId>TransferReflection` satisfies it without importing it, and
+ * keeps the literal type of its `types` so the builder can tell which fields
+ * the grammar defaults.
+ */
+export interface TransferReflection {
+   getTypeMetaData(type: string): { readonly properties: Readonly<Record<string, { readonly defaultValue?: unknown }>> };
+}
+
+/** The properties of `TType` that `TReflection`'s literal `types` gives a `defaultValue`; none for a reflection typed only as the interface. */
+type DefaultedKeys<TReflection, TType> = TReflection extends { readonly types: infer Types }
+   ? TType extends keyof Types
+      ? Types[TType] extends { readonly properties: infer Properties }
+         ? { [K in keyof Properties]: Properties[K] extends { readonly defaultValue: unknown } ? K : never }[keyof Properties]
+         : never
+      : never
+   : never;
+
+/**
+ * Init payload of a {@link TransferNodeBuilder}: every field of `T` as its
+ * interface declares it, except that the fields named by `TDefaulted`, which
+ * the grammar defaults, are optional. `$type` comes from the constant.
+ */
+export type TransferNodeInit<T extends TransferElement, TDefaulted extends PropertyKey = never> = Omit<T, '$type' | TDefaulted> &
+   Partial<Pick<T, Extract<TDefaulted, keyof T>>>;
+
+/**
+ * Transfer-node factory bound to a grammar's type map, the transfer twin of
+ * core's `AstNodeBuilder`. `TMap` is the generated `<LanguageId>TransferTypes`,
+ * `TReflection` the type of the generated reflection.
+ */
+export interface TransferNodeBuilder<TMap, TReflection extends TransferReflection = TransferReflection> {
+   /** A complete node: the grammar's defaults, then `init`. */
+   <TType extends ConcreteTypeName<TMap>>(
+      typeConstant: TransferTypeConstant<TType> & SingleTypeName<TType>,
+      init: TransferNodeInit<Extract<TMap[TType], TransferElement>, DefaultedKeys<TReflection, TType>>
+   ): Extract<TMap[TType], TransferElement>;
+   /**
+    * A node holding only `init`, with no defaults filled, typed as the
+    * incomplete node it is.
+    */
+   partial<TType extends ConcreteTypeName<TMap>>(
+      typeConstant: TransferTypeConstant<TType> & SingleTypeName<TType>,
+      init?: Partial<Omit<Extract<TMap[TType], TransferElement>, '$type'>>
+   ): Partial<Extract<TMap[TType], TransferElement>> & TransferTypeConstant<TType>;
+}
+
+/**
+ * Bind a {@link TransferNodeBuilder} to a grammar's reflection, so a test names
+ * only the fields it cares about and a containment field the grammar gains
+ * later needs no change at the call site.
+ *
+ * Defaults come from the reflection's grammar metadata alone, so a derived
+ * field the overlay adds is never defaulted, and stays required. An array
+ * default is a fresh `[]` per node. An init field named as `undefined` keeps
+ * its default, since the init type cannot refuse `undefined` for an optional
+ * field and a plain assign would leave the node typed complete without it.
+ *
+ * The constant's `$type` is written after `init`, because the init type keeps
+ * out only a `$type` written in the call: a spread of another node passes the
+ * check and would otherwise hand back a node typed as one type and tagged as
+ * another.
+ */
+export function makeTransferNodeBuilder<TMap, TReflection extends TransferReflection = TransferReflection>(
+   reflection: TReflection
+): TransferNodeBuilder<TMap, TReflection> {
+   const build = (typeConstant: TransferTypeConstant, init: object): object => {
+      const node: Record<string, unknown> = { $type: typeConstant.$type };
+      for (const [name, property] of Object.entries(reflection.getTypeMetaData(typeConstant.$type).properties)) {
+         if (property.defaultValue !== undefined) {
+            node[name] = Array.isArray(property.defaultValue) ? [...property.defaultValue] : property.defaultValue;
+         }
+      }
+      for (const [name, value] of Object.entries(init)) {
+         if (value !== undefined || !Object.hasOwn(node, name)) {
+            node[name] = value;
+         }
+      }
+      node.$type = typeConstant.$type;
+      return node;
+   };
+   const partial = (typeConstant: TransferTypeConstant, init: object = {}): object => ({ ...init, $type: typeConstant.$type });
+   return Object.assign(build, { partial }) as TransferNodeBuilder<TMap, TReflection>;
+}

package/src/testing/wait-for.ts

@@ -33,13 +33,19 @@ export interface WaitForOptions {
    readonly timeoutMs?: number;
    /** Poll the predicate every this-many milliseconds. Default 5. */
    readonly intervalMs?: number;
-   /** Error message on timeout. Default a generic phrasing. */
-   readonly message?: string;
+   /**
+    * Error message on timeout, and when the predicate throws. A function is
+    * called only then, so it can report the state the wait ended on; when it
+    * throws, the default text is used, with its throw as the error's `cause`
+    * unless the predicate threw. Default a generic phrasing.
+    */
+   readonly message?: string | (() => string);
 }
 
 /**
  * Resolve once `predicate()` returns true, polling at `intervalMs`; reject with
- * `message` once `timeoutMs` elapses. The **non-racy** alternative to a fixed
+ * `message` once `timeoutMs` elapses, or at once when the predicate throws, with
+ * the throw as the error's `cause`. The **non-racy** alternative to a fixed
  * sleep for awaiting an asynchronous side effect that lands on an observable
  * value.
  *
@@ -56,20 +62,62 @@ export interface WaitForOptions {
 export function waitFor(predicate: () => boolean, options: WaitForOptions = {}): Promise<void> {
    const timeoutMs = options.timeoutMs ?? 2000;
    const intervalMs = options.intervalMs ?? 5;
-   const message = options.message ?? `Timed out after ${timeoutMs}ms waiting for a condition`;
-   if (predicate()) {
-      return Promise.resolve();
-   }
+   const defaultMessage = `Timed out after ${timeoutMs}ms waiting for a condition`;
    return new Promise<void>((resolve, reject) => {
-      const deadline = setTimeout(() => {
+      // A throw from the predicate or the message function would leave the
+      // promise unsettled from the poll's or the deadline's timer, or escape
+      // `waitFor` itself on the first check; it rejects instead, with the
+      // predicate's throw, else the message function's, as cause. True once
+      // the promise is settled.
+      const settle = (timedOut: boolean): boolean => {
+         let met = false;
+         let threw = false;
+         let cause: unknown;
+         try {
+            met = predicate();
+         } catch (error: unknown) {
+            threw = true;
+            cause = error;
+         }
+         if (met) {
+            resolve();
+            return true;
+         }
+         if (!timedOut && !threw) {
+            return false;
+         }
+         let message = defaultMessage;
+         try {
+            if (typeof options.message === 'function') {
+               message = options.message();
+            } else if (options.message !== undefined) {
+               message = options.message;
+            }
+         } catch (error: unknown) {
+            if (!threw) {
+               threw = true;
+               cause = error;
+            }
+         }
+         reject(new Error(message, threw ? { cause } : undefined));
+         return true;
+      };
+      if (settle(false)) {
+         return;
+      }
+      const stop = (): void => {
          clearInterval(poll);
-         reject(new Error(message));
+         clearTimeout(deadline);
+      };
+      // A stalled loop can run the deadline after the condition came true but
+      // before the next poll saw it, so the deadline checks once more.
+      const deadline = setTimeout(() => {
+         settle(true);
+         stop();
       }, timeoutMs);
       const poll = setInterval(() => {
-         if (predicate()) {
-            clearInterval(poll);
-            clearTimeout(deadline);
-            resolve();
+         if (settle(false)) {
+            stop();
          }
       }, intervalMs);
    });

package/src/tracer.ts

@@ -12,6 +12,7 @@ import { Format, Logger, type LogThreshold } from './logger';
 import { NoopLogger } from './noop-logger';
 import { DefaultProfileSession, type ProfileSession } from './profile-session';
 import { Disposable } from './util';
+import { describeErrorWithStack } from './messages/primitives';
 
 /** Module-global so nested timers don't reuse ids. */
 let nextTimerId = 0;
@@ -181,15 +182,10 @@ export class DefaultTracer implements Tracer {
          const suffix = this.timingSuffix(status, elapsed, options);
          this.logger[logLevel](`${label} [#${id} ${status}, ${Format.elapsed(elapsed)}${currentExtras()}${suffix}]`);
          if (status === 'failed') {
-            // The timing line above sits at `logLevel`, which may be below the
-            // active threshold — and on its own it never carries *why* the op
-            // failed. Surface the error at warn so the failure is never silent,
-            // with the stack at debug. Cancellations are normal control flow.
-            const detail = error instanceof Error ? error.message : String(error);
-            this.logger.warn(`${label} [#${id}] failed: ${detail}`);
-            if (error instanceof Error && error.stack) {
-               this.logger.debug(error.stack);
-            }
+            // Reporting the failure is the caller's, who receives it: a line at
+            // warn here would exist only while `logLevel` is enabled.
+            const detail = describeErrorWithStack(error);
+            this.logger.debug(`${label} [#${id}] failed: ${detail}`);
          }
       };
       let result: T;

package/src/transfer-diagnostic.ts

@@ -91,6 +91,18 @@ export namespace TransferDiagnostic {
       return diagnostic.type === 'parsing-error';
    }
 
+   /**
+    * Whether `diagnostic` is a lexer or parser error, the condition a session
+    * refuses a model write over with `DocumentSyntaxError`. A hint only: the
+    * server decides on the parse itself, and the diagnostics can lag it or miss
+    * an error, as when Langium has no position for a parser error or the
+    * validation skipped its built-in checks. A blank document takes the write,
+    * since it has no text to lose.
+    */
+   export function isSyntaxError(diagnostic: TransferDiagnostic): boolean {
+      return diagnostic.type === 'lexing-error' || diagnostic.type === 'parsing-error';
+   }
+
    /**
     * The diagnostic as a renderable message, for a surface that translates.
     * `undefined` when it carries no framework identity — a syntactic error, an
@@ -129,4 +141,9 @@ export namespace TransferDiagnostic {
    export function hasParseErrors(diagnostics: TransferDiagnostic[]): boolean {
       return diagnostics.some(isParseError);
    }
+
+   /** Whether any of `diagnostics` is a syntax error, with the limits {@link isSyntaxError} names. */
+   export function hasSyntaxErrors(diagnostics: TransferDiagnostic[]): boolean {
+      return diagnostics.some(isSyntaxError);
+   }
 }