@hydranium/protocol 1.0.0-next.10

package/src/data/events.ts

@@ -0,0 +1,127 @@
+/********************************************************************************
+ * 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 { TransferDiagnostic } from '../transfer-diagnostic';
+import type { TransferElement } from '../transfer-element';
+import type { Project } from '../project';
+import type { TransferDocument } from '../transfer-document';
+
+/**
+ * Why an update event fired. Subscribers filter on reason for behaviour
+ * decisions (e.g. dirty-flag handling, undo-history grouping, telemetry):
+ *
+ * - `'changed'` — the URI appeared in `DocumentBuilder.onUpdate`'s
+ *   `changed` list. The framework's underlying primitive is "this URI was
+ *   passed to `documentBuilder.update(changed, deleted)`", which spans
+ *   `didChange` text-document events, `notifyDidChangeTextDocument` calls,
+ *   and any programmatic `documentBuilder.update([uri], [])` invocation.
+ *   The name matches Langium's own `changed` parameter — it's vague-on-
+ *   purpose because the underlying primitive is.
+ * - `'rebuilt'` — the URI was rebuilt as a cascade from another URI's
+ *   build (dependency graph re-derivation), without itself being passed to
+ *   `documentBuilder.update`. The complement of `'changed'`.
+ * - `'saved'` — emitted by adopters that synthesise a unified update stream
+ *   from both `onDocumentUpdated` and `onDocumentSaved`. The framework's own
+ *   `dispatchPhaseEvent` does NOT emit `'saved'` — saves take the dedicated
+ *   `DataClientProtocol.onDocumentSaved` channel.
+ * - `'deleted'` — the URI appeared in `DocumentBuilder.onUpdate`'s
+ *   `deleted` list. The backing file was removed.
+ */
+export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved' | 'deleted';
+
+/**
+ * Delivered on the data-server when a document's content (or existence)
+ * changed. Subscribers receive this via `DocumentServerProtocol.watchModelDocument`.
+ *
+ * The `document` field carries the latest built state — diagnostics + root
+ * are coherent with each other at the time the event fired.
+ */
+export interface TransferDocumentUpdatedEvent<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic
+> {
+   document: TransferDocument<TTransfer, TDiagnostic>;
+   /** Stable identifier of the client that triggered the update. */
+   sourceClientId: string;
+   reason: TransferDocumentUpdateReason;
+}
+
+/** Callback shape for `DataClientProtocol.onDocumentUpdated`. */
+export type TransferDocumentUpdatedListener<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic
+> = (event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>) => void;
+
+/**
+ * Delivered on the data-server when a document was persisted to disk via
+ * `DataServerProtocol.saveModelDocument`. Distinct from
+ * {@link TransferDocumentUpdatedEvent}: subscribers that only care about
+ * persistence (external sync, editor "saved" indicators, dirty-flag
+ * clear) listen for this event family instead of filtering an update
+ * stream for `reason: 'saved'`.
+ *
+ * The `document` field carries the post-save built state — same shape
+ * the synchronous `saveModelDocument` RPC response returns, delivered
+ * to subscribers (`DataClientProtocol.onDocumentSaved`) so non-caller
+ * clients see the persistence event too.
+ */
+export interface TransferDocumentSavedEvent<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic
+> {
+   document: TransferDocument<TTransfer, TDiagnostic>;
+   /**
+    * The client whose `saveModelDocument` call produced this. Every subscriber
+    * receives the event including the originator, which already had the same
+    * state as the RPC response — compare against your own id to drop the echo
+    * rather than re-rendering from it.
+    */
+   sourceClientId: string;
+}
+
+/** Callback shape for `DataClientProtocol.onDocumentSaved`. */
+export type TransferDocumentSavedListener<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic
+> = (event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>) => void;
+
+/**
+ * Why a project-change event fired. `added` — the project was newly
+ * registered (descriptor discovered); `updated` — the project's
+ * descriptor content changed and its registry entry was refreshed
+ * (same id, possibly different version / dependencies / adopter-specific
+ * fields); `removed` — the project's descriptor disappeared and the
+ * registry entry was dropped.
+ */
+export type ProjectChangeReason = 'added' | 'updated' | 'removed';
+
+/**
+ * Delivered on the data-server when a project's lifecycle state changed
+ * (added / updated / removed in the registry). Subscribers receive this
+ * via `DataClientProtocol.onProjectsChanged`.
+ *
+ * Granularity is one event per affected project: an internal registry
+ * diff with three additions and one removal fans out to four wire
+ * notifications. This matches the typical client-side pattern of "react
+ * to one project at a time" (refresh a tree entry, update a tab badge,
+ * etc.) without forcing clients to walk arrays.
+ *
+ * For `reason: 'removed'`, the carried {@link project} is the pre-removal
+ * snapshot — by the time the event fires, the registry has already
+ * cleared the entry, so clients that need the removed project's metadata
+ * (id, version, dependencies, adopter-specific fields) read it here
+ * instead of maintaining their own snapshot.
+ */
+export interface ProjectsChangedEvent<TProject extends Project = Project> {
+   readonly project: TProject;
+   readonly reason: ProjectChangeReason;
+}
+
+/** Callback shape for `DataClientProtocol.onProjectsChanged`. */
+export type ProjectsChangedListener<TProject extends Project = Project> = (event: ProjectsChangedEvent<TProject>) => void;

package/src/data/index.ts

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Subpath barrel for `@hydranium/protocol/data` — typed bidirectional
+// contract for the data-server protocol head, split into composable
+// `*ServerProtocol` / `*ClientProtocol` fragments. Implementations live in
+// `@hydranium/data-server`; typed proxies are produced by the
+// direction-neutral `createRpcProxy` (in `../rpc`) with the data-server
+// method-name lists + wire prefix exported here from
+// `./data-protocol-methods.ts`.
+
+export * from './data-protocol-methods';
+export * from './data-server-protocol';
+export * from './diagnostics';
+export * from './events';
+export * from './methods';
+export * from './requests';

package/src/data/methods.ts

@@ -0,0 +1,59 @@
+/********************************************************************************
+ * 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 shared path identifier under which the data-server exposes its typed
+ * RPC methods. Production adopters using vscode-jsonrpc transports use this
+ * as the connection-builder path; the data-server side uses it when
+ * registering handlers.
+ *
+ * Distinct from the LSP (`languageId`-routed) and GLSP (`diagram-type`-routed)
+ * heads — each protocol head owns its own path namespace.
+ */
+export const DATA_SERVER_PATH = '/hydranium/data-server';
+
+/**
+ * Wire-name prefix used by `createRpcProxy` and `DataServer`'s
+ * handler binding. Every property name on the typed `DataServerProtocol`
+ * (or `DataClientProtocol`) interface lowers to `<prefix><methodName>` on
+ * the wire — so renaming a TS method renames the wire method,
+ * intentionally.
+ *
+ * Adopters writing custom transports or inspecting the wire derive each
+ * wire name as `DATA_SERVER_WIRE_PREFIX + methodName`, where the method
+ * names live in `DATA_SERVER_PROTOCOL_METHODS` (request methods) and
+ * `DATA_CLIENT_PROTOCOL_METHODS` (notification methods), both exported
+ * from `./data-protocol-methods`. The interface (`DataServerProtocol`,
+ * `DataClientProtocol`) is the source of truth; the method-name arrays
+ * are typed against the interface (`as const satisfies …`) so they
+ * cannot drift.
+ */
+export const DATA_SERVER_WIRE_PREFIX = 'data-server/';
+
+/**
+ * Default LSP command id under which a data-server publishes its listening
+ * TCP port for client discovery. Parallel to {@link DATA_SERVER_PATH} (the
+ * service-path routing constant) — both name the data-server head's transport
+ * surface so a simple adopter needs no constants of its own.
+ *
+ * Two ends reference this id:
+ * - PUBLISH (server): the launcher registers the port under this command on
+ *   the LSP connection —
+ *   `publishPortOnLspConnection(conn, DATA_SERVER_PORT_COMMAND, port)`.
+ *   `@hydranium/core`'s `publishPortOnLspConnection` stays command-agnostic
+ *   (it publishes any port under any command); the adopter passes this
+ *   constant.
+ * - EXTRACT (Theia host): `@hydranium/data-client-theia`'s
+ *   `DataServerConnectionHandler` polls this command to discover the port —
+ *   its `portCommand` option defaults to this value.
+ *
+ * Adopters with an established command id (e.g. `'modelserver:port'`)
+ * override both ends.
+ */
+export const DATA_SERVER_PORT_COMMAND = 'hydranium/data-server/port';

package/src/data/requests.ts

@@ -0,0 +1,70 @@
+/********************************************************************************
+ * 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 { TransferSaveArgs, TransferUpdateArgs } from '../model-service/args';
+
+/** Get the current state of a single document. The server returns the latest built version. */
+export interface GetModelDocumentArgs {
+   /** Document URI. */
+   uri: string;
+   /**
+    * When `true`, the response is settled at the validation phase so its
+    * `diagnostics` are populated. When `false`/absent, the response returns at
+    * the (faster) integrity-settled phase and `diagnostics` may be absent —
+    * they are computed asynchronously and delivered via the subscription
+    * channel (and, for an LSP head, `publishDiagnostics`).
+    *
+    * Set this for one-shot / unsubscribed callers (CLI queries, batch checks)
+    * that need diagnostics in the response itself. Mirrors Langium's
+    * `BuildOptions.validation: boolean`. Note it does not *strip* diagnostics:
+    * a document already validated still carries them; the flag only controls
+    * whether the read forces/awaits validation.
+    */
+   includeDiagnostics?: boolean;
+}
+
+/**
+ * Look up the project owning the given document URI. Membership semantics
+ * are decided by the server's `ProjectManager` (default in
+ * `AbstractProjectManager`: closest-ancestor descriptor folder); the data-
+ * server forwards the URI without interpretation.
+ */
+export interface GetProjectForUriArgs {
+   /** Document URI to look up. */
+   uri: string;
+}
+
+/**
+ * Update a document's content. Wire-side projection of the facade's
+ * {@link TransferUpdateArgs}; structurally identical so the data-server RPC
+ * handler can forward straight to the in-process `ModelService.update`
+ * without an args mapping.
+ */
+export type TransferUpdateDocumentArgs<TTransfer> = TransferUpdateArgs<TTransfer>;
+
+/** Persist a document to disk. Wire-side projection of {@link TransferSaveArgs}. */
+export type TransferSaveDocumentArgs<TTransfer> = TransferSaveArgs<TTransfer>;
+
+/**
+ * Identifies a per-document watch on the data server. Shared by both
+ * `watchModelDocument` and `unwatchModelDocument` — the `(uri, clientId)`
+ * pair is the watch key, so unwatching names the same watch that was
+ * started. The `clientId` identifies the originator the same way it does
+ * on facade-side mutations (`TransferUpdateArgs.clientId`,
+ * `TransferSaveArgs.clientId`): it keys the per-`(uri, clientId)` watch
+ * bucket so multiple watchers on the same wire stay distinct, AND it lets
+ * each watcher recognise its own echo on inbound `onDocumentUpdated` events
+ * (the wire shape's `sourceClientId` carries the originating mutation's
+ * `clientId`).
+ */
+export interface WatchModelDocumentArgs {
+   uri: string;
+   /** Stable identifier for the watching client. */
+   clientId: string;
+}

package/src/debouncer.ts

@@ -0,0 +1,118 @@
+/********************************************************************************
+ * 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 Clock } from './clock';
+import { ObservableValue, type MaybeObservableValue } from './observable-value';
+import { type Disposable } from './util';
+
+/** Construction options for {@link Debouncer}. */
+export interface DebouncerOptions {
+   /**
+    * Trailing-edge delay in milliseconds, read per {@link Debouncer.schedule}
+    * so a setting-bound cell reshapes the live window without rebuilding the
+    * debouncer. A value `<= 0` still defers to the next tick via
+    * {@link Clock.setTimer}; callers wanting a synchronous path handle that
+    * themselves before scheduling.
+    */
+   readonly delayMs: MaybeObservableValue<number>;
+   /**
+    * Optional starvation ceiling. When calls keep arriving faster than
+    * {@link delayMs}, the trailing edge never settles and `fn` would never
+    * run; with `maxWaitMs` set, a fire is forced once that many milliseconds
+    * have elapsed since the first pending {@link Debouncer.schedule}, so a
+    * continuous stream still makes progress. Omitted (the default) = pure
+    * trailing edge, which may defer indefinitely under a non-stop stream.
+    */
+   readonly maxWaitMs?: number;
+}
+
+/**
+ * Trailing-edge debounce built on the injectable {@link Clock}, so the window
+ * is deterministically testable with `makeFakeClock` — the framework's timer
+ * seam rather than raw `setTimeout` (which `p-debounce` / `lodash.debounce`
+ * hold internally and cannot be driven by a fake clock).
+ *
+ * Owns ONLY timing. {@link fn} is zero-argument and returns nothing: the caller
+ * keeps whatever payload it is coalescing — an accumulator set, a "latest
+ * value" field — and reads it inside `fn` when the debouncer fires. That
+ * timing/payload split is what lets one primitive serve both an accumulating
+ * caller (merge changed/deleted sets) and a replacing one (last value wins).
+ *
+ * Leading-edge invocation and a result-returning ("await the debounced run")
+ * variant are deliberately omitted to keep this a pure timing primitive; both
+ * are additive later (a `leading` option; a separate promise helper) rather
+ * than a breaking change.
+ */
+export class Debouncer implements Disposable {
+   protected readonly delay: ObservableValue<number>;
+   protected readonly maxWaitMs?: number;
+   protected timer?: Disposable;
+   /** Virtual time of the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
+   protected firstScheduledAt?: number;
+
+   constructor(
+      protected readonly clock: Clock,
+      protected readonly fn: () => void,
+      options: DebouncerOptions
+   ) {
+      this.delay = ObservableValue.from(options.delayMs);
+      this.maxWaitMs = options.maxWaitMs;
+   }
+
+   /** True while a fire is armed (scheduled, not yet fired or cancelled). */
+   get pending(): boolean {
+      return this.timer !== undefined;
+   }
+
+   /**
+    * Arm — or re-arm — the trailing-edge timer. Repeated calls within the
+    * window collapse into a single {@link fn} run at the trailing edge; with
+    * {@link DebouncerOptions.maxWaitMs} set, the run is forced once that ceiling
+    * elapses since the first pending call.
+    */
+   schedule(): void {
+      const now = this.clock.now();
+      if (this.firstScheduledAt === undefined) {
+         this.firstScheduledAt = now;
+      }
+      let wait = Math.max(0, this.delay.value);
+      if (this.maxWaitMs !== undefined) {
+         const untilCeiling = this.firstScheduledAt + this.maxWaitMs - now;
+         wait = Math.min(wait, Math.max(0, untilCeiling));
+      }
+      this.timer?.dispose();
+      this.timer = this.clock.setTimer(() => this.fire(), wait);
+   }
+
+   /** If a fire is pending, run {@link fn} now and clear the window; otherwise a no-op. */
+   flush(): void {
+      if (this.timer !== undefined) {
+         this.fire();
+      }
+   }
+
+   /** Drop a pending fire without running {@link fn}. */
+   cancel(): void {
+      this.timer?.dispose();
+      this.timer = undefined;
+      this.firstScheduledAt = undefined;
+   }
+
+   /** Cancel any pending fire and release. */
+   dispose(): void {
+      this.cancel();
+   }
+
+   protected fire(): void {
+      this.timer?.dispose();
+      this.timer = undefined;
+      this.firstScheduledAt = undefined;
+      this.fn();
+   }
+}

package/src/errors.ts

@@ -0,0 +1,127 @@
+/********************************************************************************
+ * 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 { ResponseError } from 'vscode-jsonrpc';
+
+/**
+ * Application-specific JSON-RPC error code for {@link ConflictError}.
+ * Outside the reserved range (-32768 .. -32000) per JSON-RPC 2.0.
+ *
+ * The code is the load-bearing identifier across realm boundaries —
+ * `code` is a first-class field on the JSON-RPC error envelope and
+ * survives wire reconstruction; the custom `Error` subclass name does
+ * not.
+ */
+export const CONFLICT_ERROR_CODE = 1001;
+
+/**
+ * Structured payload carried in {@link ConflictError.data}, and the only place
+ * a post-RPC caller can read the version mismatch from.
+ */
+export interface ConflictErrorData {
+   readonly uri: string;
+   /** The based-on version the caller authored against. */
+   readonly expected: number;
+   /** The server's current text-document version at the time of the throw. */
+   readonly actual: number;
+}
+
+/**
+ * Thrown by `ModelService.update` / `ModelService.save` when the caller-
+ * supplied based-on version no longer matches the server's current text-
+ * document version for the same URI — i.e. the snapshot the caller
+ * authored against has been superseded by an intervening edit.
+ *
+ * Extends vscode-jsonrpc's {@link ResponseError} so the typed
+ * {@link ConflictErrorData} payload rides on the standard JSON-RPC
+ * error envelope (`code`, `message`, `data`) — all three fields are
+ * preserved by RPC reconstruction. Adopters that catch the error on
+ * the receiving side of an RPC call read the version mismatch from
+ * `err.data` (the instance is reconstructed as a generic
+ * `ResponseError`, so subclass getters / fields do not survive).
+ *
+ * Detection is opt-in via the optional `baseVersion` field on
+ * `TransferUpdateArgs` / `TransferSaveArgs`; callers that omit the field get
+ * no gating. This mirrors LSP's `OptionalVersionedTextDocumentIdentifier`
+ * posture, so headless / CLI / batch tooling with no meaningful based-on
+ * version can opt out explicitly.
+ *
+ * Three reasonable adopter recovery strategies:
+ *
+ * | Strategy | Use case |
+ * |---|---|
+ * | Drop + refetch | Form-widget save; user can re-trigger if they still want the edit. |
+ * | Refetch + replay user edit | Specific structural edits (`setField`, drag-position). Adopter responsibility. |
+ * | Surface to user | Large edits, multi-step transactions. Adopter UI. |
+ *
+ * The framework provides the **detection**; adopters provide the **policy**.
+ * No auto-retry or auto-merge ships by default.
+ */
+export class ConflictError extends ResponseError<ConflictErrorData> {
+   constructor(uri: string, expected: number, actual: number) {
+      super(CONFLICT_ERROR_CODE, `Stale-based update for ${uri}: expected v${expected}, server is at v${actual}`, {
+         uri,
+         expected,
+         actual
+      });
+      this.name = 'ConflictError';
+      // ResponseError's constructor calls `Object.setPrototypeOf(this,
+      // ResponseError.prototype)` to keep its own prototype chain intact across
+      // transpilation targets; that resets us to ResponseError, hiding the
+      // ConflictError-specific getters. Restore the prototype here so
+      // `err.uri` / `.expected` / `.actual` resolve through this class.
+      Object.setPrototypeOf(this, ConflictError.prototype);
+   }
+
+   get uri(): string {
+      return this.data!.uri;
+   }
+
+   get expected(): number {
+      return this.data!.expected;
+   }
+
+   get actual(): number {
+      return this.data!.actual;
+   }
+}
+
+/** Marker substring present in every {@link ConflictError} message, used by
+ *  {@link isConflictError} as a fallback when a transport re-wraps the error
+ *  and drops the JSON-RPC code. */
+const CONFLICT_ERROR_MESSAGE_MARKER = 'Stale-based update for ';
+
+/**
+ * Type guard for {@link ConflictError}. Detection ladder:
+ *
+ *  1. `error.name === 'ConflictError'` — direct in-process throw, no
+ *     RPC round-trip.
+ *  2. `(error as ResponseError).code === CONFLICT_ERROR_CODE` — the
+ *     canonical wire-side check; the JSON-RPC `code` field is preserved
+ *     across reconstruction, so any adopter catching after an RPC call
+ *     hits this branch.
+ *  3. `error.message.includes('Stale-based update for ')` — fallback
+ *     for transports that re-wrap the message and drop the code (rare).
+ *
+ * `instanceof ConflictError` alone would silently return `false` on the
+ * reconstructed shape, so callers do not use it.
+ */
+export function isConflictError(error: unknown): error is ConflictError {
+   if (!(error instanceof Error)) {
+      return false;
+   }
+   if (error.name === 'ConflictError') {
+      return true;
+   }
+   const code = (error as Partial<ResponseError<unknown>>).code;
+   if (code === CONFLICT_ERROR_CODE) {
+      return true;
+   }
+   return typeof error.message === 'string' && error.message.includes(CONFLICT_ERROR_MESSAGE_MARKER);
+}

package/src/host-diagnostics.ts

@@ -0,0 +1,63 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Diagnostics contract for the HOST (parent) process — the Theia backend
+ * itself, the process that runs the data-client connection handlers and any
+ * in-process services. Distinct from `DataServerDiagnosticsProtocol`,
+ * which targets the separate data-server child (the heavy model store): the
+ * host process is reached by an ordinary in-process Theia RPC service, NOT over
+ * the data-server socket. Universal (`process.memoryUsage()` always works) and
+ * cheap, so the framework wires it by default for every host that opts the
+ * data-client backend module in.
+ *
+ * Returns are plain formatted strings — the caller (a command, a log sink, the
+ * pod's stdout) decides how to surface them.
+ */
+
+/** Arguments for {@link HostDiagnosticsProtocol.dumpHostState}. */
+export interface DumpHostStateArgs {
+   /** Optional label folded into the snapshot heading (e.g. an ISO timestamp). */
+   label?: string;
+}
+
+/** Arguments for {@link HostDiagnosticsProtocol.writeHostHeapSnapshot}. */
+export interface WriteHostHeapSnapshotArgs {
+   /** Optional label folded into the snapshot filename. */
+   label?: string;
+   /** Directory to write into; defaults to the OS temp dir when absent or not present on disk. */
+   directory?: string;
+}
+
+/**
+ * Memory diagnostics the running HOST (Theia backend) process exposes. Computed
+ * in-process: the snapshots reflect the parent process, the counterpart to the
+ * data-server child's `DataServerDiagnosticsProtocol`.
+ */
+export interface HostDiagnosticsProtocol {
+   /**
+    * Capture a host-process memory snapshot — heap, rss, external, V8 limit —
+    * and return it formatted. The host hosts no Langium documents, so this is
+    * the lighter `formatProcessMemory` view, not `formatServerState`.
+    */
+   dumpHostState(args: DumpHostStateArgs): Promise<string>;
+
+   /**
+    * Write a V8 heap snapshot of the host process to disk (full GC first;
+    * briefly pauses the process) and return the absolute file path.
+    */
+   writeHostHeapSnapshot(args: WriteHostHeapSnapshotArgs): Promise<string>;
+}
+
+/**
+ * Theia service path the host-diagnostics RPC service is registered under. An
+ * ordinary in-process backend service (`RpcConnectionHandler`), unlike the
+ * socket-forwarded `DATA_SERVER_PATH`.
+ */
+export const HOST_DIAGNOSTICS_PATH = '/hydranium/host-diagnostics';

package/src/index.ts

@@ -0,0 +1,41 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Public API barrel — re-exports every PRODUCTION entry of `@hydranium/protocol`.
+// `./client` and `./data` are re-exported as well as declared standalone, so a
+// consumer wanting the whole production surface needs one specifier while one
+// wanting a narrower graph can still name the subpath. `./testing` is excluded
+// on the opposite constraint: re-exporting it would put the test doubles in
+// every production bundle that imports the root.
+
+export * from './abstract-logger';
+export * from './client';
+export * from './clock';
+export * from './data';
+export * from './browser-runtime';
+export * from './debouncer';
+export * from './errors';
+export * from './host-diagnostics';
+export * from './logger';
+export * from './latency-collector';
+export * from './patch-merge';
+export * from './noop-logger';
+export * from './observable-value';
+export * from './profile-session';
+export * from './profiling';
+export * from './tracer';
+export * from './transfer-diagnostic';
+export * from './transfer-element';
+export * from './model-service';
+export * from './transfer-document';
+export * from './model-server';
+export * from './project';
+export * from './rpc';
+export * from './uri';
+export * from './util';