@hydranium/core 1.0.0-next.10

package/src/testing/stub-project-manager.ts

@@ -0,0 +1,161 @@
+/********************************************************************************
+ * 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 { type Project, UNQUALIFIED_PROJECT_REFERENCE } from '@hydranium/protocol';
+import { type AstNode, AstUtils, type URI, UriUtils } from '@hydranium/langium';
+import { Disposable } from 'vscode-languageserver';
+import type { WorkspaceFolder } from 'vscode-languageserver-types';
+import type { ProjectChangeEvent, ProjectChangeListener } from '../langium/project/project-change-event.js';
+import type { ProjectManager } from '../langium/project/project-manager.js';
+
+/**
+ * Stub for {@link ProjectManager}. Backed by a mutable `projects` array so
+ * tests can rearrange the registry between assertions, with test-only
+ * helpers:
+ *
+ * - {@link ownUri} — declare which project owns a given URI. Drives
+ *   {@link getProject} lookups so tests can model multi-project workspaces
+ *   without spinning up an `AbstractProjectManager`.
+ * - {@link fireProjectsChanged} — synchronously deliver a synthetic
+ *   {@link ProjectChangeEvent} to subscribers.
+ *
+ * `getProjectUris` / `getVisibleProjects` / `isVisible` answer from the
+ * declared ownership and the projects' `dependencies`, matching what
+ * `AbstractProjectManager` computes. `discoverProjects` and
+ * `isProjectDescriptor` are inert defaults (no-op / always `false`);
+ * override the returned object's methods for tests that need discovery
+ * behaviour.
+ */
+export interface StubProjectManager<TProject extends Project = Project> extends ProjectManager<TProject> {
+   /** Mutable project list; push / splice to model a changing registry. */
+   readonly projects: TProject[];
+   /** Declare which project owns the given URI for {@link getProject} lookups. */
+   ownUri(uri: string | URI, projectId: string): void;
+   /** Synchronously deliver a {@link ProjectChangeEvent} to every registered listener. */
+   fireProjectsChanged(event: ProjectChangeEvent<TProject>): void;
+   /** Drop ownership state, projects, and listeners. */
+   reset(): void;
+}
+
+/** Build a {@link StubProjectManager}. Initial `projects` are pushed onto the mutable backing array. */
+export function makeStubProjectManager<TProject extends Project = Project>(
+   initialProjects: readonly TProject[] = []
+): StubProjectManager<TProject> {
+   const projects: TProject[] = [...initialProjects];
+   const listeners: ProjectChangeListener<TProject>[] = [];
+   const ownership = new Map<string, string>();
+
+   return {
+      get projects() {
+         return projects;
+      },
+      ready: Promise.resolve(),
+      async discoverProjects(_folders: readonly WorkspaceFolder[]): Promise<void> {
+         // No-op default: the stub's registry is seeded directly. Tests that
+         // exercise discovery semantics override this method or use a real
+         // `AbstractProjectManager` subclass.
+      },
+      isProjectDescriptor(): boolean {
+         return false;
+      },
+      isSingleProject(): boolean {
+         return projects.length <= 1;
+      },
+      isUnqualifiedProjectReference(uri: URI | string) {
+         const project = this.getProject(uri);
+         return project === undefined || project.referenceName === UNQUALIFIED_PROJECT_REFERENCE;
+      },
+      getProjects() {
+         return projects;
+      },
+      getProjectById(id: string) {
+         return projects.find(project => project.id === id);
+      },
+      getProject(uri: URI | string) {
+         const key = typeof uri === 'string' ? uri : uri.toString();
+         const projectId = ownership.get(key);
+         return projectId ? projects.find(project => project.id === projectId) : undefined;
+      },
+      getProjectForNode(node: AstNode) {
+         const uri = AstUtils.findRootNode(node).$document?.uri;
+         return uri ? this.getProject(uri) : undefined;
+      },
+      getProjectUris(projectId: string): readonly URI[] {
+         // Registration gates the ownership scan, as in `AbstractProjectManager`:
+         // an id no project carries owns nothing, whatever the ownership map
+         // says. Without the gate a test could assert membership for a project
+         // that was never registered.
+         if (!projects.some(project => project.id === projectId)) {
+            return [];
+         }
+         return [...ownership.entries()].filter(([, id]) => id === projectId).map(([uri]) => UriUtils.toUri(uri));
+      },
+      getVisibleProjects(projectId: string): readonly string[] {
+         // Transitive closure of `Project.dependencies` including the source
+         // — mirrors `AbstractProjectManager.getVisibleProjects` so tests
+         // observe the same visibility model the production manager does.
+         if (!projects.some(project => project.id === projectId)) {
+            return [];
+         }
+         const visited = new Set<string>();
+         const ordered: string[] = [];
+         const walk = (id: string): void => {
+            if (visited.has(id)) {
+               return;
+            }
+            visited.add(id);
+            const project = projects.find(p => p.id === id);
+            if (!project) {
+               return;
+            }
+            ordered.push(id);
+            for (const dep of project.dependencies ?? []) {
+               walk(dep);
+            }
+         };
+         walk(projectId);
+         return ordered;
+      },
+      isVisible(sourceProjectId: string, targetProjectId: string, selfVisible = false): boolean {
+         // Same logic as AbstractProjectManager.isVisible — kept inline so the
+         // stub stays self-contained.
+         const visible = this.getVisibleProjects(sourceProjectId);
+         if (visible.length === 0) {
+            return false;
+         }
+         if (sourceProjectId === targetProjectId) {
+            return selfVisible;
+         }
+         return visible.includes(targetProjectId);
+      },
+      onProjectsChanged(listener: ProjectChangeListener<TProject>) {
+         listeners.push(listener);
+         return Disposable.create(() => {
+            const idx = listeners.indexOf(listener);
+            if (idx >= 0) {
+               listeners.splice(idx, 1);
+            }
+         });
+      },
+      ownUri(uri, projectId) {
+         const key = typeof uri === 'string' ? uri : uri.toString();
+         ownership.set(key, projectId);
+      },
+      fireProjectsChanged(event) {
+         for (const listener of listeners.slice()) {
+            listener(event);
+         }
+      },
+      reset() {
+         projects.length = 0;
+         listeners.length = 0;
+         ownership.clear();
+      }
+   };
+}

package/src/testing/stub-self-save-registry.ts

@@ -0,0 +1,43 @@
+/********************************************************************************
+ * 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 type { SelfSaveRegistry } from '../documents/self-save-registry.js';
+
+/**
+ * Stub for the framework's {@link SelfSaveRegistry}. Records `register` calls
+ * so tests can assert that a save path correctly notified the registry.
+ *
+ * # Stub-vs-real surface
+ *
+ * The stub declares only the methods exercised by tests via
+ * `Pick<SelfSaveRegistry, ...>` — TypeScript enforces that each picked
+ * method's signature stays in lockstep with the real class. `matches`, the
+ * only other member, is not claimed and so cannot be called through this
+ * interface; a test that needs the TTL / mtime matching either picks it here
+ * or uses the real class.
+ */
+export interface StubSelfSaveRegistry extends Pick<SelfSaveRegistry, 'register'> {
+   readonly registerCalls: ReadonlyArray<{ fsPath: string; mtimeMs: number }>;
+   reset(): void;
+}
+
+export function makeStubSelfSaveRegistry(): StubSelfSaveRegistry {
+   const registerCalls: { fsPath: string; mtimeMs: number }[] = [];
+   return {
+      get registerCalls() {
+         return registerCalls;
+      },
+      register(fsPath, mtimeMs) {
+         registerCalls.push({ fsPath, mtimeMs });
+      },
+      reset() {
+         registerCalls.length = 0;
+      }
+   };
+}

package/src/testing/stub-service-registry.ts

@@ -0,0 +1,192 @@
+/********************************************************************************
+ * 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 type { Grammar, LangiumSharedCoreServices, URI } from '@hydranium/langium';
+import type { TextDocument } from 'vscode-languageserver-textdocument';
+import type { ServerLanguageServices } from '../langium/language-module.js';
+import { ExtendedServiceRegistry } from '../langium/service-registry.js';
+import { makeNoopLanguageServices, type NoopLanguageServicesOverrides } from './make-noop-language-services.js';
+
+/**
+ * One language to register on a {@link StubServiceRegistry}. Only
+ * {@link languageId} and {@link fileExtensions} are required — they are what
+ * Langium's routing ladder actually reads.
+ */
+export interface StubLanguageDescriptor {
+   /** The language's id, as `LanguageMetaData.languageId`. */
+   readonly languageId: string;
+   /** Extensions routed to this language, leading dot included (`'.fake'`). */
+   readonly fileExtensions: readonly string[];
+   /** Whole file names routed to this language (Langium's `fileNameMap` rung). */
+   readonly fileNames?: readonly string[];
+   /**
+    * AST `$type`s this language's grammar produces. Synthesised into a minimal
+    * `Grammar` — one entry-less parser rule per type — which is exactly what
+    * `collectProducibleTypes` reads, so type→language routing
+    * (`buildLanguageTypeIndex`, `DataServer.resolveReferenceLanguage`) resolves
+    * against this stub the same way it does against generated grammars.
+    *
+    * Entry-less on purpose: `reachableParserRules` falls back to every parser
+    * rule when a grammar declares no entry rule, so each listed type is
+    * produced. A test that needs the reachability semantics itself (a rule
+    * present but unreachable) should build a real grammar rather than list it
+    * here.
+    */
+   readonly producedTypes?: readonly string[];
+   /**
+    * Per-language service slots the code under test reads (`references`,
+    * `serializer`, `ast`, …). Forwarded to {@link makeNoopLanguageServices},
+    * which supplies no-op defaults for the `shared` sub-tree only — an unlisted
+    * per-language slot stays absent and reads `undefined`.
+    */
+   readonly services?: NoopLanguageServicesOverrides;
+}
+
+/** Optional configuration for {@link makeStubServiceRegistry}. */
+export interface MakeStubServiceRegistryOptions {
+   /**
+    * Documents to declare open with a client-supplied `languageId`, as
+    * `{ [uri]: languageId }`. Drives the FIRST rung of Langium's lookup ladder
+    * (languageId, then file name, then extension) by standing in for the
+    * `workspace.TextDocuments` provider the registry consults.
+    */
+   readonly openLanguageIds?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Test-facing view of a stub registry: the real
+ * {@link ExtendedServiceRegistry} surface plus seeding/introspection helpers.
+ */
+export interface StubServiceRegistry extends ExtendedServiceRegistry<ServerLanguageServices> {
+   /**
+    * Narrows Langium's `readonly LangiumCoreServices[]` to the framework's
+    * per-language type, so call sites reading a framework slot off a
+    * registered language (`references`, `serializer`, …) stay cast-free.
+    */
+   readonly all: readonly ServerLanguageServices[];
+   /** Registered stub language services by id, in registration order. */
+   readonly languagesById: ReadonlyMap<string, ServerLanguageServices>;
+   /**
+    * Declare `uri` open under `languageId`, so `getServices(uri)` resolves by
+    * the declared id rather than the extension. Pass an unregistered id to
+    * exercise the fall-through to file name / extension.
+    */
+   seedOpen(uri: string, languageId: string): void;
+   /** Undo a {@link seedOpen} — the document is no longer open. */
+   seedClosed(uri: string): void;
+}
+
+/**
+ * Minimal `Grammar` carrying one parser rule per produced `$type`. Shaped for
+ * `collectProducibleTypes`, which reads `rules[].name` / `fragment` /
+ * `dataType` / `returnType` / `inferredType` and walks each rule's contents —
+ * an empty `Group` is a well-formed, action-free rule definition.
+ */
+function makeStubGrammar(producedTypes: readonly string[]): Grammar {
+   return {
+      $type: 'Grammar',
+      rules: producedTypes.map(name => ({ $type: 'ParserRule', name, definition: { $type: 'Group', elements: [] } }))
+   } as unknown as Grammar;
+}
+
+/**
+ * A `TextDocumentProvider` over a plain uri→languageId map. Only `languageId`
+ * is populated: it is the sole field `DefaultServiceRegistry.getServices` reads
+ * off the returned document, so a fuller `TextDocument` shell would state a
+ * fidelity the stub does not have.
+ */
+function makeLanguageIdProvider(openLanguageIds: Map<string, string>): { get(uri: string | URI): TextDocument | undefined } {
+   return {
+      get(uri) {
+         const languageId = openLanguageIds.get(uri.toString());
+         return languageId === undefined ? undefined : ({ languageId } as TextDocument);
+      }
+   };
+}
+
+/**
+ * The framework's own {@link ExtendedServiceRegistry}, carrying stub languages
+ * and the seeding hooks {@link StubServiceRegistry} adds.
+ *
+ * Private per the test-support convention for doubles that must subclass a real
+ * production class (see `makeStubModelService`): the class is an implementation
+ * detail, {@link makeStubServiceRegistry} is the entry point.
+ */
+class StubServiceRegistryImpl extends ExtendedServiceRegistry<ServerLanguageServices> implements StubServiceRegistry {
+   readonly languagesById = new Map<string, ServerLanguageServices>();
+
+   override get all(): readonly ServerLanguageServices[] {
+      return super.all as readonly ServerLanguageServices[];
+   }
+
+   constructor(protected readonly openLanguageIds: Map<string, string>) {
+      // Langium reads exactly one thing off this argument — `workspace.TextDocuments`
+      // — and only to resolve an open document's declared languageId. Passing a
+      // provider-only shell keeps the stub free of a full shared-services tree.
+      super({ workspace: { TextDocuments: makeLanguageIdProvider(openLanguageIds) } } as unknown as LangiumSharedCoreServices);
+   }
+
+   override register(language: ServerLanguageServices): void {
+      super.register(language);
+      this.languagesById.set(language.LanguageMetaData.languageId, language);
+   }
+
+   seedOpen(uri: string, languageId: string): void {
+      this.openLanguageIds.set(uri, languageId);
+   }
+
+   seedClosed(uri: string): void {
+      this.openLanguageIds.delete(uri);
+   }
+}
+
+/**
+ * Build a {@link StubServiceRegistry} over the given stub languages.
+ *
+ * **The registry is REAL.** This double stubs the *languages*, not the
+ * registry: the returned object is the framework's own
+ * {@link ExtendedServiceRegistry}, so `getServices` walks Langium's actual
+ * lookup ladder (declared languageId → file name → extension), throws
+ * Langium's actual messages on a miss, and picks up `hasServices`,
+ * `getServicesById` and `getServicesByExtension` for free. Hand-rolled
+ * registry objects re-implement that ladder, and a re-implementation is
+ * exactly the fixture-vs-reality gap that lets a multi-grammar defect pass
+ * a green test.
+ *
+ * Pass the same descriptors to `makeTestServices`' `languages` option to
+ * get the registry bound on a full shared-services tree.
+ */
+export function makeStubServiceRegistry(
+   languages: readonly StubLanguageDescriptor[],
+   options: MakeStubServiceRegistryOptions = {}
+): StubServiceRegistry {
+   const registry = new StubServiceRegistryImpl(new Map(Object.entries(options.openLanguageIds ?? {})));
+   for (const descriptor of languages) {
+      registry.register(
+         makeNoopLanguageServices({
+            // A real language always HAS the `references` group, so code
+            // reading `language.references.X` off a routed language is right to
+            // do so without a second optional chain. Seeding it empty keeps
+            // that true for a descriptor that names no reference service; the
+            // individual slots stay absent, so an unstubbed one still reads
+            // `undefined` rather than silently answering. A descriptor
+            // supplying `references` replaces this wholesale.
+            references: {},
+            ...descriptor.services,
+            Grammar: makeStubGrammar(descriptor.producedTypes ?? []),
+            LanguageMetaData: {
+               languageId: descriptor.languageId,
+               fileExtensions: [...descriptor.fileExtensions],
+               ...(descriptor.fileNames ? { fileNames: [...descriptor.fileNames] } : {})
+            }
+         })
+      );
+   }
+   return registry;
+}

package/src/testing/stub-writable-file-system.ts

@@ -0,0 +1,58 @@
+/********************************************************************************
+ * 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 type { URI } from '@hydranium/langium';
+import type { WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import type { StubSelfSaveRegistry } from './stub-self-save-registry.js';
+
+/**
+ * Stub for {@link WritableFileSystemProvider}. Records `writeFile` calls so
+ * tests can assert on the save path; reads return empty strings / empty
+ * directory listings (the framework's read paths don't run against this
+ * stub in the tests exercised today).
+ *
+ * When constructed with a {@link StubSelfSaveRegistry}, `writeFile` notifies
+ * the registry with the current wall-clock as the mtime — standing in for
+ * `DefaultFileSystemProvider.writeFile`, which registers the written file's
+ * real mtime so the watcher echo for the server's own write is suppressed.
+ *
+ * # Stub-vs-real surface
+ *
+ * Picks only the framework-relevant methods from {@link WritableFileSystemProvider}
+ * (`readFile`, `readDirectory`, `writeFile`); the compiler enforces those
+ * signatures stay aligned with the real interface. Langium's wider
+ * `FileSystemProvider` surface (`stat`, `statSync`, `exists`, `existsSync`,
+ * etc.) is deliberately not picked — tests that need it should construct
+ * the real `DefaultFileSystemProvider` instead. Binding the stub at
+ * `services.workspace.FileSystemProvider` therefore needs a narrowing cast at
+ * the binding site; casting the object literal itself would hide drift on the
+ * picked methods too.
+ */
+export interface StubWritableFileSystem extends Pick<WritableFileSystemProvider, 'readFile' | 'readDirectory' | 'writeFile'> {
+   readonly writes: ReadonlyArray<{ uri: string; content: string }>;
+   reset(): void;
+}
+
+export function makeStubWritableFileSystem(selfSaveRegistry?: StubSelfSaveRegistry): StubWritableFileSystem {
+   const writes: { uri: string; content: string }[] = [];
+   return {
+      get writes() {
+         return writes;
+      },
+      readFile: async () => '',
+      readDirectory: async () => [],
+      async writeFile(uri: URI, content: string) {
+         writes.push({ uri: uri.toString(), content });
+         selfSaveRegistry?.register(uri.fsPath, Date.now());
+      },
+      reset() {
+         writes.length = 0;
+      }
+   };
+}

package/src/util/connection-liveness.ts

@@ -0,0 +1,47 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Phrases `vscode-jsonrpc` uses when a call loses its connection. Matched on the
+ * message because the condition surfaces in two different shapes:
+ *
+ * - a **throw** from `throwIfClosedOrDisposed` (`Connection is disposed.` /
+ *   `Connection is closed.`), a `ConnectionError` raised synchronously by
+ *   `sendRequest` / `sendNotification` and by `RemoteConsole.send`;
+ * - a **rejection** of an already-issued request (`Pending response rejected
+ *   since connection got disposed`), a `ResponseError` produced when the
+ *   pending-response map is drained on teardown.
+ *
+ * Both are typed, but they are different error classes carrying codes from
+ * different enums, so no single code check covers both. Kept
+ * lowercase-normalised and anchored on `connection` so an unrelated "disposed"
+ * message cannot match.
+ */
+const CONNECTION_GONE_PATTERNS = [/connection is disposed/, /connection is closed/, /connection got disposed/, /connection got closed/];
+
+/**
+ * Whether `err` means "the peer is gone", as opposed to a genuine failure of
+ * the operation.
+ *
+ * The distinction is a **log-severity** one, and it matters because the two are
+ * indistinguishable at the call site otherwise. Pushing an edit to a language
+ * client that has already disconnected is a no-op, not a fault — it happens on
+ * every ordinary shutdown, and reporting it at `error` turns routine teardown
+ * into something that looks like it needs investigation. A real `applyEdit`
+ * failure (the client refused, the request malformed) still deserves `error`.
+ *
+ * Callers that only need to *survive* a dead connection rather than classify it
+ * should just catch — see `LspLogger.emit`, whose fallback path does exactly
+ * that, since a logger has nowhere to report a logging failure anyway.
+ */
+export function isConnectionGoneError(err: unknown): boolean {
+   const message = err instanceof Error ? err.message : String(err);
+   const normalized = message.toLowerCase();
+   return CONNECTION_GONE_PATTERNS.some(pattern => pattern.test(normalized));
+}

package/src/util/environment.ts

@@ -0,0 +1,88 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// The single home for Node-global access in neutral (`.`-entry) code. Neutral
+// code never touches `process` / `Buffer` directly (enforced by the eslint
+// `no-restricted-globals` ban, whose only neutral exemption is this module); it
+// goes through these guarded accessors so it degrades cleanly in a browser.
+//
+// Capability-detected, NOT environment-detected: bundlers inject a partial
+// `process` shim into browser builds (Theia's browser-app has `process.env` but
+// no `process.memoryUsage` / `fs`), so `typeof process` alone is not a reliable
+// "am I in Node" check. Each accessor only claims the specific API it tests.
+
+/** `process.env` when a Node `process` exposes it, else `undefined`. */
+export function processEnv(): NodeJS.ProcessEnv | undefined {
+   return typeof process !== 'undefined' && process.env ? process.env : undefined;
+}
+
+/** `process.pid` when available, else `undefined` (browser). */
+export function processPid(): number | undefined {
+   return typeof process !== 'undefined' ? process.pid : undefined;
+}
+
+/**
+ * Whether the host filesystem treats paths case-insensitively — `true` on
+ * Windows and macOS, `false` on Linux and in a browser.
+ *
+ * Capability cannot be detected without touching the filesystem, so this reads
+ * `process.platform` and answers `false` when there is none. That default is
+ * the safe one: folding case where the filesystem does NOT would make two
+ * genuinely distinct files collide, which is a correctness bug, whereas failing
+ * to fold merely misses an optimisation.
+ */
+export function isCaseInsensitiveFileSystem(): boolean {
+   const platform = typeof process !== 'undefined' ? process.platform : undefined;
+   return platform === 'win32' || platform === 'darwin';
+}
+
+/** Node `process` lifecycle / error / signal events accepted by {@link onProcessEvent}. */
+export type ProcessEvent =
+   'exit' | 'beforeExit' | 'uncaughtException' | 'unhandledRejection' | 'rejectionHandled' | 'warning' | 'SIGINT' | 'SIGTERM' | 'SIGHUP';
+
+/**
+ * Register a process lifecycle handler (`'exit'`, `'unhandledRejection'`, …) if
+ * a Node `process` with `on` is present; a no-op in a browser worker (no
+ * `process`, no such events).
+ */
+export function onProcessEvent(event: ProcessEvent, handler: (...args: unknown[]) => void): void {
+   if (typeof process !== 'undefined' && typeof process.on === 'function') {
+      process.on(event, handler);
+   }
+}
+
+/**
+ * Write already-formatted text to the process's standard error, when a
+ * Node-like `process` exposes one. Returns `true` when the text was written and
+ * `false` in a browser, so a caller can fall back to `console.*`.
+ *
+ * Exists because **a server's stdout is a data channel, not a log channel**: an
+ * LSP or data-server head launched over stdio carries JSON-RPC frames on
+ * stdout, so a log line written there corrupts the protocol stream. `stderr` is
+ * the diagnostics channel by the same convention, and is the stream a parent
+ * process inherits when it spawns a head as a child.
+ */
+export function writeStderr(text: string): boolean {
+   if (typeof process === 'undefined' || !process.stderr || typeof process.stderr.write !== 'function') {
+      return false;
+   }
+   process.stderr.write(text);
+   return true;
+}
+
+/**
+ * `process.memoryUsage()` guarded for non-Node hosts — `undefined` in a browser
+ * (where a partial `process` shim has no `memoryUsage`).
+ */
+export function currentMemoryUsage(): { heapUsed: number; heapTotal: number; rss: number } | undefined {
+   if (typeof process === 'undefined' || typeof process.memoryUsage !== 'function') {
+      return undefined;
+   }
+   return process.memoryUsage();
+}

package/src/util/index.ts

@@ -0,0 +1,18 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './connection-liveness.js';
+export * from './environment.js';
+export * from './registry.js';
+// Side-effect import: the `UriUtils` namespace augmentation
+// (`UriUtils.toUri` / `.isAncestorOrEqual`) lives in the langium chokepoint.
+// Pulling it in here keeps it loaded for any consumer importing from
+// `@hydranium/core/util`, and the chokepoint also loads it whenever any
+// `@hydranium/langium` symbol is imported.
+import '@hydranium/langium';