@hydranium/protocol 1.0.0-next.10

package/src/clock.ts

@@ -0,0 +1,173 @@
+/********************************************************************************
+ * 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 { Disposable } from './util';
+
+/**
+ * Measures how long something takes. Born running at {@link Clock.stopwatch};
+ * there is no `start` — you create it at the moment timing begins.
+ *
+ * Backed by a monotonic source (`performance.now`), so it is sub-millisecond
+ * precise and immune to wall-clock jumps (NTP/DST adjustments can make a
+ * `Date.now` delta go backwards; a stopwatch cannot). Use this for durations
+ * and {@link Clock.now} for "what time is it" (timestamps, TTLs).
+ *
+ * It holds no scheduled resource and is therefore NOT a {@link Disposable} —
+ * the disposable thing is a {@link Clock.setTimer}. Reads are lazy, so a fake
+ * clock just answers the current virtual time.
+ */
+export interface Stopwatch {
+   /** Total elapsed since creation; live while running, frozen after {@link stop}. */
+   readonly elapsedMs: number;
+   /**
+    * Split: the elapsed since the previous `lap` (or since creation for the
+    * first call), starting a new split. Non-destructive — the running total
+    * ({@link elapsedMs}) is unaffected, so `lap` is not a restart.
+    */
+   lap(): number;
+   /**
+    * Freeze and return the grand total (the sum of every lap plus the tail
+    * since the last lap). Idempotent: further calls return the same value and
+    * {@link elapsedMs} stops advancing.
+    */
+   stop(): number;
+}
+
+/**
+ * Injectable time, so logic gated on time (debounce windows, slow-update
+ * warnings, request timeouts, the self-save TTL) is deterministically
+ * testable instead of waiting on real wall-clock. The {@link SystemClock}
+ * default delegates to the platform; tests bind `makeFakeClock`.
+ *
+ * Two distinct readings on purpose: {@link now} is wall-clock (for timestamps
+ * and TTLs that compare against a file's mtime), while {@link stopwatch}
+ * measures durations off a monotonic source. They are different clocks; do not
+ * subtract two {@link now} readings to measure a duration.
+ *
+ * A cross-head contract, so it carries no platform or DI-framework coupling.
+ *
+ * Note: the runtime health monitors (event-loop, memory) intentionally keep
+ * the real wall-clock rather than taking a `Clock` — faking the time they
+ * measure would invert their meaning.
+ */
+export interface Clock {
+   /** Current wall-clock time in milliseconds (the `Date.now` reading). */
+   now(): number;
+   /**
+    * Run `callback` after `ms` have elapsed; the returned {@link Disposable}
+    * cancels it if disposed before it fires. This is the testable
+    * `setTimeout` — debounce, deferred slow-warn, request timeouts.
+    */
+   setTimer(callback: () => void, ms: number): Disposable;
+   /** Start measuring a duration. See {@link Stopwatch}. */
+   stopwatch(): Stopwatch;
+   /**
+    * Run `callback` and return its result together with how long it took.
+    * Sugar over {@link stopwatch} — pure measurement, no logging and no
+    * threshold gating (unlike `Tracer.time`). Use in
+    * measurement pipelines that consume `elapsedMs` directly. Async callbacks
+    * return a Promise of the same shape, timed across the full settle.
+    */
+   measure<T>(callback: () => Promise<T>): Promise<Timed<T>>;
+   measure<T>(callback: () => T): Timed<T>;
+}
+
+/**
+ * The result of {@link Clock.measure}: a callback's return value paired with
+ * its elapsed wall-time in milliseconds. A plain value object — no methods, no
+ * logging — deliberately distinct from `@theia/core`'s `Measurement` (a
+ * stateful self-logging handle), which would collide in a Theia process.
+ */
+export interface Timed<T> {
+   /**
+    * The callback's return value, unchanged. For an async callback this is the
+    * settled value rather than the promise — and a callback that REJECTS
+    * produces no `Timed` at all, because the rejection propagates, so a failed
+    * run cannot be timed through this shape.
+    */
+   result: T;
+   /**
+    * Milliseconds off the monotonic source, so it is comparable with
+    * {@link Stopwatch.elapsedMs} and NOT with a difference of two
+    * {@link Clock.now} readings. For an async callback it spans the full settle,
+    * not just the synchronous prefix.
+    */
+   elapsedMs: number;
+}
+
+class SystemStopwatch implements Stopwatch {
+   protected readonly start = performance.now();
+   protected lastLap = this.start;
+   protected stopped: number | undefined;
+
+   get elapsedMs(): number {
+      return (this.stopped ?? performance.now()) - this.start;
+   }
+
+   lap(): number {
+      const at = this.stopped ?? performance.now();
+      const split = at - this.lastLap;
+      this.lastLap = at;
+      return split;
+   }
+
+   stop(): number {
+      if (this.stopped === undefined) {
+         this.stopped = performance.now();
+      }
+      return this.stopped - this.start;
+   }
+}
+
+/**
+ * Detach a timer from the event loop so a single pending timer never keeps a
+ * Node process alive — a CLI run or test worker can exit cleanly while deferred
+ * work (debounce, slow-warn, idle CST eviction) is still scheduled; the
+ * persistent server connection keeps the loop alive in production regardless.
+ *
+ * `unref` is Node-only. {@link SystemClock} also runs in the browser, where
+ * `setTimeout` returns a bare numeric handle with no `unref` — the optional
+ * call is a no-op there, and declaring the parameter's `unref` optional accepts
+ * a Node `NodeJS.Timeout` structurally without a cast.
+ */
+function unrefTimer(handle: { unref?: () => void }): void {
+   handle.unref?.();
+}
+
+/**
+ * Default {@link Clock}: delegates to the platform's `Date.now`,
+ * `performance.now`, and `setTimeout`/`clearTimeout`. Bound everywhere in
+ * production; swapped for `makeFakeClock` in tests.
+ */
+export class SystemClock implements Clock {
+   now(): number {
+      return Date.now();
+   }
+
+   setTimer(callback: () => void, ms: number): Disposable {
+      const handle = setTimeout(callback, ms);
+      unrefTimer(handle);
+      return Disposable.create(() => clearTimeout(handle));
+   }
+
+   stopwatch(): Stopwatch {
+      return new SystemStopwatch();
+   }
+
+   measure<T>(callback: () => Promise<T>): Promise<Timed<T>>;
+   measure<T>(callback: () => T): Timed<T>;
+   measure<T>(callback: () => T | Promise<T>): Timed<T> | Promise<Timed<T>> {
+      const stopwatch = this.stopwatch();
+      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 };
+   }
+}

package/src/data/data-protocol-methods.ts

@@ -0,0 +1,79 @@
+/********************************************************************************
+ * 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 { TransferElement } from '../transfer-element';
+import type {
+   DataClientProtocol,
+   DataServerProtocol,
+   DocumentClientProtocol,
+   DocumentServerProtocol,
+   ProjectClientProtocol,
+   ProjectServerProtocol,
+   ReferenceServerProtocol
+} from './data-server-protocol';
+
+/** Request-method names on {@link DocumentServerProtocol}. */
+export const DOCUMENT_SERVER_PROTOCOL_METHODS = [
+   'openModelDocument',
+   'closeModelDocument',
+   'getModelDocument',
+   'updateModelDocument',
+   'saveModelDocument',
+   'watchModelDocument',
+   'unwatchModelDocument',
+   'waitForReady'
+] as const satisfies ReadonlyArray<keyof DocumentServerProtocol<TransferElement> & string>;
+
+/** Request-method names on {@link ProjectServerProtocol}. */
+export const PROJECT_SERVER_PROTOCOL_METHODS = ['getProjects', 'getProjectForUri'] as const satisfies ReadonlyArray<
+   keyof ProjectServerProtocol & string
+>;
+
+/**
+ * Request-method names on the composed {@link DataServerProtocol} — the
+ * document fragment followed by the project fragment. The `as const satisfies`
+ * constraint makes the array typed against the interface — stale names (typos,
+ * renamed methods) fail to typecheck.
+ */
+export const DATA_SERVER_PROTOCOL_METHODS = [
+   ...DOCUMENT_SERVER_PROTOCOL_METHODS,
+   ...PROJECT_SERVER_PROTOCOL_METHODS
+] as const satisfies ReadonlyArray<keyof DataServerProtocol<TransferElement> & string>;
+
+/**
+ * Request-method names on {@link ReferenceServerProtocol}. NOT part of
+ * {@link DATA_SERVER_PROTOCOL_METHODS} — adopters that compose the reference
+ * fragment register these alongside (e.g. via a `DataServer` subclass's
+ * `additionalMethods`).
+ */
+export const REFERENCE_SERVER_PROTOCOL_METHODS = [
+   'findReferenceCandidates',
+   'resolveReference',
+   'findNextName'
+] as const satisfies ReadonlyArray<keyof ReferenceServerProtocol<TransferElement> & string>;
+
+/** Notification-method names on {@link DocumentClientProtocol}. */
+export const DOCUMENT_CLIENT_PROTOCOL_METHODS = ['onDocumentUpdated', 'onDocumentSaved'] as const satisfies ReadonlyArray<
+   keyof DocumentClientProtocol<TransferElement> & string
+>;
+
+/** Notification-method names on {@link ProjectClientProtocol}. */
+export const PROJECT_CLIENT_PROTOCOL_METHODS = ['onProjectsChanged'] as const satisfies ReadonlyArray<keyof ProjectClientProtocol & string>;
+
+/**
+ * Notification-method names on the composed {@link DataClientProtocol}.
+ * Passed as the `localMethods` allowlist to `createRpcProxy` (frontend) /
+ * `bindRpcMethods` (backend) when binding inbound `on*` notifications — the
+ * data head's connection routes `<methodNamespace>onDocumentUpdated` etc. to
+ * the bound client target.
+ */
+export const DATA_CLIENT_PROTOCOL_METHODS = [
+   ...DOCUMENT_CLIENT_PROTOCOL_METHODS,
+   ...PROJECT_CLIENT_PROTOCOL_METHODS
+] as const satisfies ReadonlyArray<keyof DataClientProtocol<TransferElement> & string>;

package/src/data/data-server-protocol.ts

@@ -0,0 +1,296 @@
+/********************************************************************************
+ * 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';
+import type { CloseModelArgs, FindNextNameArgs, OpenModelArgs, ReferenceContext, ReferenceRequest } from '../model-server';
+import type { ReferenceCandidate, ReferenceTarget } from '../model-service/reference-candidate';
+import type { ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from './events';
+import type {
+   GetModelDocumentArgs,
+   GetProjectForUriArgs,
+   TransferSaveDocumentArgs,
+   WatchModelDocumentArgs,
+   TransferUpdateDocumentArgs
+} from './requests';
+
+/**
+ * Document-scoped slice of the data-server wire contract: the per-document
+ * lifecycle (get / update / save), the per-`(uri, clientId)` watch
+ * pair, and the global `waitForReady` startup gate that callers await before
+ * the first document request.
+ *
+ * Generic over the transfer root type (`TTransfer`) and the diagnostic
+ * shape (`TDiagnostic`). `TTransfer extends TransferElement` constrains the
+ * root to the wire data shape (no `$container` cycles, references as
+ * strings — see `transfer-element.ts`) — the type-system bridge between the
+ * data-server's protocol surface and the transfer-model overlay each adopter
+ * declares.
+ *
+ * Composed into {@link DataServerProtocol} alongside {@link ProjectServerProtocol};
+ * a pure single-document consumer can compose only this fragment.
+ */
+export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+   /**
+    * Open a document for an editor session and return its current state.
+    * Registers `(uri, clientId)` with the multi-client document manager
+    * (so concurrent editors share one built document) and returns the
+    * document at the server's configured target phase — the same shape
+    * {@link getModelDocument} returns, except that `version` is taken from
+    * the text-document store so the caller's first `baseVersion` write
+    * cannot self-conflict. Idempotent in registration terms: opening an
+    * already-open document refreshes the client registration. Note it does
+    * NOT avoid a rebuild — a second client attaching triggers
+    * `refreshContent`, which fires a change event, so mounting a form on a
+    * document already open in a text editor rebuilds it.
+    *
+    * The default `DataServer` impl delegates to `ModelService.open` then
+    * reads the built state. Pair with {@link watchModelDocument} to receive
+    * subsequent build-phase events (open returns a one-shot snapshot;
+    * later validation diagnostics arrive on the watch channel).
+    */
+   openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Close an editor session for `(uri, clientId)`. Counterpart to
+    * {@link openModelDocument}; the underlying document stays built until
+    * every registered client has closed. The default `DataServer` impl
+    * delegates to `ModelService.close` and ALSO releases any watch for the
+    * same `(uri, clientId)` (closing a session frees its own watch — a
+    * forgotten {@link unwatchModelDocument} would otherwise leak dispatch;
+    * the implicit unwatch is idempotent). `watchModelDocument` is NOT
+    * coupled the other way: opening does not force a watch, so a snapshot
+    * reader can open without streaming.
+    */
+   closeModelDocument(args: CloseModelArgs): Promise<void>;
+
+   /**
+    * Get the current state of a document. The server-side build is brought
+    * up to date before the response returns — callers don't need to await
+    * a separate "ready" gate per request, only the global
+    * {@link waitForReady} gate at startup.
+    */
+   getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Update a document's content. The response carries the latest built
+    * state including diagnostics; callers observe convergence via that
+    * response.
+    */
+   updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Persist a document to disk. The response is the post-save document
+    * state (matches the file on disk). Save semantics depend on the
+    * filesystem-provider wiring; rejection paths surface as awaited
+    * promise rejections.
+    */
+   saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Start watching `(uri, clientId)`. The server starts dispatching
+    * {@link DocumentClientProtocol.onDocumentUpdated} on the paired wire
+    * for every build-phase event on `uri`.
+    *
+    * Returns `Promise<void>` — the bidirectional pattern means the event
+    * channel is the client interface, not a returned handle. Callers fan
+    * out a single inbound `onDocumentUpdated` to multiple local listeners
+    * with their own `Emitter<T>` (matching Theia's pattern). Pair every
+    * `watchModelDocument` with {@link unwatchModelDocument} when no longer
+    * needed; the server holds the watch record until the matching unwatch
+    * lands.
+    */
+   watchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
+
+   /**
+    * Stop watching `(uri, clientId)` previously started by
+    * {@link watchModelDocument}. Idempotent — unwatching twice is a no-op.
+    */
+   unwatchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
+
+   /**
+    * Resolve once the data-server is ready to serve requests. The default
+    * implementation in `DataServer` returns `Promise.resolve()`; adopters
+    * that need to warm-load services (workspace indexing, custom service
+    * initialisation) override this hook on their subclass.
+    *
+    * Callers SHOULD await `waitForReady` once at startup before the first
+    * `getModelDocument` / subscription call — Langium's document builder
+    * may otherwise miss documents added during the initial workspace
+    * walk.
+    */
+   waitForReady(): Promise<void>;
+}
+
+/**
+ * Project-scoped slice of the data-server wire contract: enumerate the
+ * workspace's projects and resolve the project owning a URI.
+ *
+ * Generic over the project shape (`TProject`); most adopters use the
+ * default {@link Project}. Composed into {@link DataServerProtocol}
+ * alongside {@link DocumentServerProtocol}.
+ */
+export interface ProjectServerProtocol<TProject extends Project = Project> {
+   /**
+    * List projects exposed by the workspace. Returns an empty array when
+    * no project tier is wired (e.g. `SingleProjectManager` default with no
+    * descriptor discovery configured).
+    */
+   getProjects(): Promise<readonly TProject[]>;
+
+   /**
+    * Look up the project owning the given URI. Returns `undefined` when
+    * the URI does not belong to any registered project, or when no
+    * project tier is wired (the `SingleProjectManager` default returns
+    * its synthetic workspace project for every URI, so that case never
+    * resolves to `undefined`).
+    *
+    * Membership semantics are decided by the server's `ProjectManager`
+    * implementation — the default in `AbstractProjectManager` is closest-
+    * ancestor descriptor folder; adopters override for explicit URI
+    * listings, glob patterns, manifest-declared file lists, etc.
+    */
+   getProjectForUri(args: GetProjectForUriArgs): Promise<TProject | undefined>;
+}
+
+/**
+ * Typed RPC contract for the data-server protocol head — the server-exposed
+ * surface clients call. Composed from the role-explicit fragments
+ * {@link DocumentServerProtocol} (per-document lifecycle + subscriptions +
+ * the readiness gate) and {@link ProjectServerProtocol} (project tier).
+ * Implementations live in `@hydranium/data-server`; typed client proxies are
+ * produced by `createRpcProxy` (in this package's `./rpc` subpath). The
+ * wire-level method names are `DATA_SERVER_WIRE_PREFIX + methodName` for
+ * every method in `DATA_SERVER_PROTOCOL_METHODS` (request methods)
+ * and `DATA_CLIENT_PROTOCOL_METHODS` (notification methods).
+ *
+ * Most adopters parameterise only `TTransfer`; `TDiagnostic` defaults to
+ * {@link TransferDiagnostic} and `TProject` to {@link Project}.
+ *
+ * **Bidirectional pattern.** `DataServerProtocol` is the SERVER-EXPOSED
+ * surface — methods the client calls. The dual surface
+ * {@link DataClientProtocol} contains methods the server calls (delivered
+ * as JSON-RPC notifications). The pair composes via `createRpcProxy`
+ * (`localTarget`/`localMethods`) so server and client are typed end-to-end
+ * with no method-list drift.
+ *
+ * **Architectural placement.** The SOLE typed surface for the data-server
+ * peer. `lsp-server` and `glsp-server` define their own peer-equivalent
+ * surfaces and DO NOT extend this one; all three heads sit at the same tier,
+ * coordinating through shared services in `@hydranium/core`.
+ */
+export interface DataServerProtocol<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TProject extends Project = Project
+>
+   extends DocumentServerProtocol<TTransfer, TDiagnostic>, ProjectServerProtocol<TProject> {}
+
+/**
+ * Cross-reference / naming slice of the server surface — scope-aware
+ * queries that resolve against the language's reference services. NOT part
+ * of the {@link DataServerProtocol} composition: a pure data consumer
+ * doesn't need it, so adopters compose it onto their connection explicitly.
+ * The default `DataServer` impls delegate to
+ * the per-language `references` services, resolved from each request's
+ * source/URI (an `ElementSource` with no URI resolves to the sole
+ * registered language; a multi-language workspace overrides).
+ *
+ * Generic over the transfer root type only — the resolution result
+ * ({@link ReferenceTarget}) carries the resolved node's encoded subtree;
+ * candidates and names are diagnostic-free.
+ */
+export interface ReferenceServerProtocol<TTransfer extends TransferElement> {
+   /**
+    * List the reference candidates reachable for the property named in `ctx`
+    * from its (possibly synthetic) source. Backed by the language's
+    * `ReferenceCandidateProvider`.
+    */
+   findReferenceCandidates(ctx: ReferenceContext): Promise<ReferenceCandidate[]>;
+
+   /**
+    * Resolve a concrete reference request to its target, returning the
+    * target's document URI, display fields, and the resolved node's encoded
+    * transfer subtree. Resolves via the language's reference services;
+    * `undefined` when the reference does not resolve.
+    */
+   resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined>;
+
+   /**
+    * Compute the next free name for a new element of `args.type` based on
+    * `args.proposal`, unique within the `args.tier` scope (default
+    * `'project'`). Backed by the language's `NameProvider`.
+    */
+   findNextName(args: FindNextNameArgs): Promise<string>;
+}
+
+/**
+ * Document-scoped slice of the client surface — notifications the server
+ * delivers about subscribed documents. The dual of
+ * {@link DocumentServerProtocol}.
+ *
+ * Notification methods are conventionally `on*`-prefixed so the generic
+ * `createRpcProxy` helper routes them as `sendNotification` calls.
+ * Multi-listener fan-out is the consumer's responsibility — wrap a local
+ * implementation with an `Emitter<T>` to fan a single inbound
+ * `onDocumentUpdated` call out to multiple local subscribers.
+ */
+export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+   /**
+    * Delivered when a subscribed document reached one of the data-server's
+    * configured build phases. Subscribers filter incoming events by URI
+    * if they hold multiple subscriptions on the same wire.
+    */
+   onDocumentUpdated(event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>): void;
+
+   /**
+    * Delivered when a subscribed document was persisted to disk via
+    * {@link DocumentServerProtocol.saveModelDocument}. The persistence event
+    * is delivered on a separate channel from the build-phase update
+    * stream — subscribers tracking "saved" status (editor dirty-flag
+    * indicators, external sync drivers) listen here instead of filtering
+    * `onDocumentUpdated` for `reason: 'saved'` (the build-phase path
+    * never emits `'saved'` because saves take a synchronous RPC-response
+    * codepath, not a subscription codepath).
+    */
+   onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+}
+
+/**
+ * Project-scoped slice of the client surface — the project-registry change
+ * notification. The dual of {@link ProjectServerProtocol}.
+ */
+export interface ProjectClientProtocol<TProject extends Project = Project> {
+   /**
+    * Delivered when a project was added, updated, or removed from the
+    * registry. The data-server subscribes to its `ProjectManager`'s
+    * change channel and fans the internal `ProjectChangeEvent` (which
+    * carries arrays of added/updated/removed ids per registry diff) out
+    * to one wire notification per affected project — `'removed'` events
+    * carry the pre-removal snapshot so clients with no local cache can
+    * still read the project's metadata.
+    */
+   onProjectsChanged(event: ProjectsChangedEvent<TProject>): void;
+}
+
+/**
+ * Client-side surface — methods the data-server invokes on the client as
+ * JSON-RPC notifications. The bidirectional dual of {@link DataServerProtocol},
+ * composed from {@link DocumentClientProtocol} and {@link ProjectClientProtocol}.
+ * A `createRpcProxy` over the connection exposes the server surface outbound and
+ * binds an implementation of this interface inbound (`localTarget`).
+ */
+export interface DataClientProtocol<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TProject extends Project = Project
+>
+   extends DocumentClientProtocol<TTransfer, TDiagnostic>, ProjectClientProtocol<TProject> {}

package/src/data/diagnostics.ts

@@ -0,0 +1,116 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Optional diagnostics slice of the data-server wire contract: capture memory /
+ * state snapshots of the running server process for OOM debugging (notably in a
+ * cloud pod). Kept OUT of `DataServerProtocol` so the core document /
+ * project contract stays lean, but the framework `DataServer` registers these
+ * BY DEFAULT (so every head gets them with no wiring); a head that does not want
+ * them drops the names via `DataServerOptions.excludedMethods`.
+ *
+ * Returns are plain formatted strings — the caller (a command, a log sink, the
+ * pod's stdout) decides how to surface them. The wire names are
+ * `DATA_SERVER_WIRE_PREFIX + methodName`, same as the core methods.
+ */
+
+import type { LatencyReport } from '../latency-collector.js';
+import type { ProfileCaptureOptions } from '../profiling.js';
+
+/** Arguments for {@link DataServerDiagnosticsProtocol.dumpServerState}. */
+export interface DumpServerStateArgs {
+   /** Optional label folded into the snapshot heading (e.g. an ISO timestamp). */
+   label?: string;
+}
+
+/**
+ * Arguments for {@link DataServerDiagnosticsProtocol.startProfiling} — the capture
+ * dimensions to sample over the window (all off unless named). The wire args are
+ * exactly the neutral {@link ProfileCaptureOptions}.
+ */
+export type StartProfilingArgs = ProfileCaptureOptions;
+
+/** Arguments for {@link DataServerDiagnosticsProtocol.stopProfiling}. */
+export interface StopProfilingArgs {
+   /** Optional label folded into the profile filenames + report heading. */
+   label?: string;
+   /** Directory to write profile artefacts into; defaults to the OS temp dir when absent or not present on disk. */
+   directory?: string;
+}
+
+/** Arguments for {@link DataServerDiagnosticsProtocol.writeHeapSnapshot}. */
+export interface WriteServerHeapSnapshotArgs {
+   /** 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 / state diagnostics the running server process exposes. Implemented by
+ * the framework `DataServer`; computed in the data-server process (the heavy
+ * model store), so the snapshots reflect the process that actually holds the
+ * workspace AST/CST — the one that OOMs.
+ */
+export interface DataServerDiagnosticsProtocol {
+   /**
+    * Capture a server-process state snapshot — heap, rss, V8 stats, event-loop
+    * utilisation, CPU usage, and document counts — and return it formatted.
+    */
+   dumpServerState(args: DumpServerStateArgs): Promise<string>;
+
+   /**
+    * Write a V8 heap snapshot of the server process to disk (full GC first;
+    * briefly pauses the process) and return the absolute file path. Open it in
+    * Chrome DevTools > Memory > Load for retained-size analysis.
+    */
+   writeHeapSnapshot(args: WriteServerHeapSnapshotArgs): Promise<string>;
+
+   /**
+    * Capture a pod/container memory snapshot — cgroup v2/v1 current/peak/limit
+    * plus a per-process RSS tree, the figure the Kubernetes OOM-killer watches.
+    * Degrades to a "no cgroup controller" note outside a container.
+    */
+   dumpPodMemory(): Promise<string>;
+
+   /**
+    * Begin a windowed sampled-profile capture (CPU / allocation / GC / event-loop
+    * delay, per the named dimensions) of the server process. Sampling does NOT
+    * pause the process. Rejects if a capture is already active — one inspector
+    * session at a time. Pair with {@link stopProfiling}.
+    */
+   startProfiling(args: StartProfilingArgs): Promise<void>;
+
+   /**
+    * Stop the active capture, write the requested profile artefacts, and return
+    * the formatted profile report. Rejects if no capture is active.
+    */
+   stopProfiling(args: StopProfilingArgs): Promise<string>;
+
+   /**
+    * Return the per-method RPC/LSP latency + throughput collected so far (count,
+    * p50/p99/max, total per method). Empty when the head was not started with a
+    * latency collector. Read-only — does not reset the window.
+    */
+   getLatency(): Promise<LatencyReport>;
+}
+
+/**
+ * Request-method names on {@link DataServerDiagnosticsProtocol}. The framework
+ * `DataServer` appends these to its registered method set by default; the
+ * `as const satisfies` constraint keeps the array in lockstep with the interface.
+ */
+export const DATA_SERVER_DIAGNOSTICS_METHODS = [
+   'dumpServerState',
+   'writeHeapSnapshot',
+   'dumpPodMemory',
+   'startProfiling',
+   'stopProfiling',
+   'getLatency'
+] as const satisfies ReadonlyArray<keyof DataServerDiagnosticsProtocol & string>;