@hydranium/protocol 1.0.0-next.29 → 1.0.0-next.298

package/src/client/worker-handshake.ts

@@ -0,0 +1,83 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * The handshake between a page and the worker hosting its heads, shared by
+ * both ends so neither can drift from the other.
+ *
+ * **Every head gets its own `MessagePort`; none is bound to the worker
+ * global.** The heads share one worker so they share one Langium store, and
+ * that makes the global contended: a head bound to it receives every other
+ * head's traffic, since a JSON-RPC reader filters nothing. The global is
+ * unusable even for a single head: GLSP's worker launcher posts its startup
+ * handshake through the global `postMessage` regardless of the connection it
+ * was configured with, a plain string no JSON-RPC reader can parse.
+ *
+ * The global therefore carries the host protocol: the bootstrap in, failure
+ * reports out, and whatever else the host adds for itself. A message that
+ * belongs to a head belongs on that head's port.
+ *
+ * The ports are {@link TransferredMessagePort}s, because this package compiles
+ * without the DOM lib and the structural type is also what rejects a `Worker`
+ * or the worker global at an adopter's call site.
+ */
+
+import type { TransferredMessagePort } from './post-message-transport';
+
+/** Discriminator of the bootstrap message a page posts on the worker global. */
+export const WORKER_BOOTSTRAP_MESSAGE_TYPE = 'hydranium/bootstrap';
+
+/** One transferred port per head. */
+export interface HeadPorts {
+   readonly lsp: TransferredMessagePort;
+   readonly data: TransferredMessagePort;
+   readonly glsp: TransferredMessagePort;
+}
+
+/** The one message the worker answers, by starting its heads on the ports. */
+export interface WorkerBootstrapMessage {
+   readonly type: typeof WORKER_BOOTSTRAP_MESSAGE_TYPE;
+   readonly ports: HeadPorts;
+}
+
+export function isWorkerBootstrapMessage(value: unknown): value is WorkerBootstrapMessage {
+   if (typeof value !== 'object' || value === null) {
+      return false;
+   }
+   const candidate = value as Partial<WorkerBootstrapMessage>;
+   return candidate.type === WORKER_BOOTSTRAP_MESSAGE_TYPE && typeof candidate.ports === 'object' && candidate.ports !== null;
+}
+
+/**
+ * Discriminator of a failure report the worker posts on the global.
+ *
+ * A worker has no console anyone is looking at, and the failures that matter
+ * most reach nobody by default: an LSP notification handler that rejects has
+ * no reply to reject, so a workspace walk that throws looks exactly like a
+ * workspace with no documents in it.
+ */
+export const WORKER_ERROR_MESSAGE_TYPE = 'hydranium/worker-error';
+
+/** The phase a failed bootstrap reports under; no head answers after it. */
+export const WORKER_BOOTSTRAP_PHASE = 'bootstrap';
+
+export interface WorkerErrorMessage {
+   readonly type: typeof WORKER_ERROR_MESSAGE_TYPE;
+   /** What the worker was doing, {@link WORKER_BOOTSTRAP_PHASE} for a failed bootstrap. */
+   readonly phase: string;
+   readonly message: string;
+}
+
+export function isWorkerErrorMessage(value: unknown): value is WorkerErrorMessage {
+   if (typeof value !== 'object' || value === null) {
+      return false;
+   }
+   const candidate = value as Partial<WorkerErrorMessage>;
+   return candidate.type === WORKER_ERROR_MESSAGE_TYPE && typeof candidate.phase === 'string' && typeof candidate.message === 'string';
+}

package/src/client-ids.ts

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Well-known values of the wire's `clientId` / `sourceClientId` field.
+ *
+ * The framework tracks each document as belonging to one or more "clients" —
+ * typically an LSP-text client (Monaco, VS Code, …), a GLSP diagram client,
+ * and/or a structured-form client — and keys its holds and watches per
+ * `(uri, clientId)`. These three values are not real participants, so a client
+ * minting its own id must avoid them.
+ *
+ * **Here rather than in the server package, because the side that has to
+ * RECOGNISE them is the client.** An inbound `onDocumentUpdated` carries
+ * `sourceClientId`, and a consumer deciding what to do with it is asking which
+ * of these it is — so a frontend would otherwise have to depend on the server
+ * tier to name three strings, and in practice retypes the literal instead.
+ */
+
+/** Identifier for an LSP-text client (Monaco, VS Code, …). */
+export const LANGUAGE_CLIENT_ID = 'language-client';
+
+/**
+ * The id an event names when no single client is behind it: the source of a
+ * `'rebuilt'` event, a document no client authored, or a build with more than
+ * one cause.
+ */
+export const UNKNOWN_CLIENT_ID = 'unknown';
+
+/**
+ * Synthetic author id on the `onDocumentUpdated` broadcast a data-server
+ * emits for the build that follows a document's release, once no client holds
+ * it; by default that build reverts the document to its disk content,
+ * discarding unsaved edits. Not a real client: it lets consumers tell the
+ * release broadcast from client-authored updates.
+ */
+export const DOCUMENT_RELEASE_CLIENT_ID = 'document-release';
+
+/**
+ * Every id the framework reserves, for a client checking that the identity it
+ * is about to mint collides with none of them.
+ */
+export const FRAMEWORK_CLIENT_IDS: readonly string[] = [LANGUAGE_CLIENT_ID, UNKNOWN_CLIENT_ID, DOCUMENT_RELEASE_CLIENT_ID];

package/src/clock.ts

@@ -14,9 +14,11 @@ import { Disposable } from './util';
  * 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).
+ * precise and immune to wall-clock steps (a time sync or a manual change can
+ * make a `Date.now` delta go backwards; a stopwatch cannot). In Node on Linux
+ * it also leaves out time the system spends suspended, so a duration spanning
+ * a suspend reads as the awake time only. Use this for every duration, a TTL
+ * included, and {@link Clock.now} for "what time is it".
  *
  * 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
@@ -45,16 +47,16 @@ export interface Stopwatch {
  * 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.
+ * Two distinct readings on purpose: {@link now} is wall-clock, for a
+ * timestamp, while {@link stopwatch} measures durations off a monotonic
+ * source. They are different clocks; do not subtract two {@link now} readings
+ * to measure a duration. Framework code reads time only through a `Clock`, so
+ * a platform workaround lives in one place.
  *
  * 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.
+ * Note: code that measures real CPU, heap or event-loop time never takes the
+ * bound `Clock`: faking the time it measures would invert its meaning.
  */
 export interface Clock {
    /** Current wall-clock time in milliseconds (the `Date.now` reading). */
@@ -76,8 +78,30 @@ export interface Clock {
     */
    measure<T>(callback: () => Promise<T>): Promise<Timed<T>>;
    measure<T>(callback: () => T): Timed<T>;
+   /**
+    * Settle with `promise`, or with {@link TIMED_OUT} once `ms` have elapsed
+    * first. A promise that rejects first rejects this one; one that rejects
+    * after the timer is ignored. The timer is disposed the moment `promise`
+    * settles, so a won race leaves nothing scheduled, but `promise` itself
+    * runs on: nothing here can cancel it.
+    *
+    * Unlike VS Code's `raceTimeout`, this settles with a sentinel rather than
+    * `undefined`, so a promise resolving to `undefined` is not taken for a
+    * timeout; the caller branches on the result instead of passing an
+    * `onTimeout`.
+    *
+    * A custom implementation extends {@link SystemClock}, whose race runs over
+    * the subclass's {@link setTimer}.
+    */
+   raceTimer<T>(promise: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT>;
 }
 
+/**
+ * What {@link Clock.raceTimer} settles with when its timer fires first.
+ * Registered under a global key, so two copies of this package agree on it.
+ */
+export const TIMED_OUT = Symbol.for('hydranium/protocol/timed-out');
+
 /**
  * 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
@@ -144,6 +168,10 @@ function unrefTimer(handle: { unref?: () => void }): void {
  * Default {@link Clock}: delegates to the platform's `Date.now`,
  * `performance.now`, and `setTimeout`/`clearTimeout`. Bound everywhere in
  * production; swapped for `makeFakeClock` in tests.
+ *
+ * {@link measure} and {@link raceTimer} run over {@link stopwatch} and
+ * {@link setTimer}, so a clock that extends this one and replaces those
+ * measures and races on its own time, as the test clock does.
  */
 export class SystemClock implements Clock {
    now(): number {
@@ -170,4 +198,34 @@ export class SystemClock implements Clock {
       }
       return { result: result as T, elapsedMs: stopwatch.elapsedMs };
    }
+
+   /**
+    * The timer settles the race one microtask after it fires. A real timer
+    * runs only once pending resolutions are delivered, while a fake one fires
+    * inside its `advance`, so settling at once would let a promise already
+    * resolved when `advance` runs lose to a timer it beats in production. The
+    * deferral covers only that promise: one that settles through further
+    * chained reactions, such as a `.then` chain, an async function or
+    * `Promise.allSettled`, can still lose to an `advance` in the same turn,
+    * while it wins on the platform's timer. The handlers go on `promise`
+    * before {@link setTimer} runs, so a `setTimer` that throws still leaves
+    * `promise` observed.
+    */
+   raceTimer<T>(promise: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT> {
+      return new Promise<T | typeof TIMED_OUT>((resolve, reject) => {
+         // eslint-disable-next-line prefer-const -- with a `const`, a `setTimer` that throws leaves it uninitialised, and the handlers' later read of it is an unhandled ReferenceError
+         let timer: Disposable | undefined;
+         promise.then(
+            value => {
+               timer?.dispose();
+               resolve(value);
+            },
+            (err: unknown) => {
+               timer?.dispose();
+               reject(err);
+            }
+         );
+         timer = this.setTimer(() => void Promise.resolve().then(() => resolve(TIMED_OUT)), ms);
+      });
+   }
 }

package/src/console-logger.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * 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 { AbstractLogger } from './abstract-logger';
+import { type LogLevel, type Logger } from './logger';
+
+/** `console.trace` prints a stack with every line, so `trace` goes out at `debug`. */
+const CONSOLE_METHODS: Record<LogLevel, 'error' | 'warn' | 'info' | 'debug'> = {
+   error: 'error',
+   warn: 'warn',
+   info: 'info',
+   debug: 'debug',
+   trace: 'debug'
+};
+
+/**
+ * {@link Logger} that writes each line to `console`, at the method matching its
+ * level: the framework's `[Label - time] [component]` prefix and the message,
+ * then any trailing arguments as they are, so a browser console can expand
+ * them. For a browser page, webview or extension host, which has no other sink
+ * to hand. On Node, `info` and `debug` reach stdout, so a process whose stdout
+ * carries a protocol stream must not use it.
+ */
+export class ConsoleLogger extends AbstractLogger implements Logger {
+   protected emit(level: LogLevel, label: string, message: string, args: readonly unknown[]): void {
+      console[CONSOLE_METHODS[level]](`${this.formatLinePrefix(label)} ${message}`, ...args);
+   }
+
+   protected derive(component: string): this {
+      const Subclass = this.constructor as new (component?: string) => this;
+      return new Subclass(component);
+   }
+}

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

@@ -20,11 +20,17 @@ import type {
 
 /** Request-method names on {@link DocumentServerProtocol}. */
 export const DOCUMENT_SERVER_PROTOCOL_METHODS = [
+   'createSession',
+   'closeSession',
+   'createModelDocument',
+   'updateModelDocuments',
    'openModelDocument',
    'closeModelDocument',
    'getModelDocument',
    'updateModelDocument',
    'saveModelDocument',
+   'persistModelDocument',
+   'deleteModelDocument',
    'watchModelDocument',
    'unwatchModelDocument',
    'waitForReady'
@@ -56,12 +62,16 @@ export const REFERENCE_SERVER_PROTOCOL_METHODS = [
    'findReferenceCandidates',
    'resolveReference',
    'findNextName'
-] as const satisfies ReadonlyArray<keyof ReferenceServerProtocol<TransferElement> & string>;
+] as const satisfies ReadonlyArray<keyof ReferenceServerProtocol & string>;
 
 /** Notification-method names on {@link DocumentClientProtocol}. */
-export const DOCUMENT_CLIENT_PROTOCOL_METHODS = ['onDocumentUpdated', 'onDocumentSaved'] as const satisfies ReadonlyArray<
-   keyof DocumentClientProtocol<TransferElement> & string
->;
+export const DOCUMENT_CLIENT_PROTOCOL_METHODS = [
+   'onDocumentUpdated',
+   'onDocumentSaved',
+   'onDocumentDirtyChanged',
+   'onDocumentDeleted',
+   'onDocumentsBuilt'
+] 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>;

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

@@ -10,16 +10,29 @@
 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 { TransferCreatedDocument, TransferDocument, TransferSavedDocument, TransferWatchedDocument } 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 {
+   ProjectsChangedEvent,
+   TransferDocumentDeletedEvent,
+   TransferDocumentDirtyChangedEvent,
+   TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
+   TransferDocumentUpdatedEvent
+} from './events';
+import type {
+   CloseSessionArgs,
+   CreateModelDocumentArgs,
+   CreateSessionArgs,
    GetModelDocumentArgs,
    GetProjectForUriArgs,
+   TransferDeleteDocumentArgs,
+   TransferPersistDocumentArgs,
    TransferSaveDocumentArgs,
    WatchModelDocumentArgs,
-   TransferUpdateDocumentArgs
+   TransferUpdateDocumentArgs,
+   TransferUpdateDocumentsArgs
 } from './requests';
 
 /**
@@ -40,35 +53,77 @@ import type {
  */
 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.
+    * Register `args.clientId` as a client session owned by this connection.
+    * Rejects with a `DuplicateClientIdError` code when the id is live anywhere
+    * in the server process, and with a `ReservedClientIdError` code when the
+    * framework reserves it.
+    *
+    * A request carrying a registered id acts as that session: it writes only
+    * what the session has open, failing with a `DocumentNotOpenError` code
+    * otherwise, and opens nothing implicitly; its open reads the file and takes
+    * no `languageId`, `version` or `text` seed. The session ends with
+    * {@link closeSession} or when the connection closes, and either closes
+    * every document it has open.
     *
-    * 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).
+    * A registration carrying the `resumeToken` an earlier registration of the
+    * same id carried ends that session first, from any connection, so a client
+    * whose connection dropped can register again before the server notices.
+    */
+   createSession(args: CreateSessionArgs): Promise<void>;
+
+   /**
+    * End a session this connection registered: close every document it has
+    * open, drop its watches, and free its id. A no-op for an id this
+    * connection did not register.
     */
-   openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+   closeSession(args: CloseSessionArgs): Promise<void>;
 
    /**
-    * 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.
+    * Create a document with `args.text`, open for the session, and return it
+    * as {@link openModelDocument} does, with the version the create made in
+    * `created`. The answer is read after the create, so it can already hold
+    * another client's write or an integrity repair; a write based on
+    * `created.version` then conflicts. It reaches disk with the first save.
+    * Fails when the file exists or any client has the URI open, and with a
+    * `SessionClosedError` code when `args.clientId` is not a session
+    * registered on this connection.
+    */
+   createModelDocument(args: CreateModelDocumentArgs): Promise<TransferCreatedDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Write several documents the session has open, all or none: a conflict or
+    * a document not open fails the whole set before any text applies.
+    * Resolves to the documents in the order given. Only for a session
+    * registered on this connection.
+    */
+   updateModelDocuments(args: TransferUpdateDocumentsArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>[]>;
+
+   /**
+    * Open a document for the client session `clientId` and return its current
+    * state. `clientId` must be a session this connection registered with
+    * {@link createSession}; any other id fails with the closed-session code,
+    * as every document request here does. The document is read from disk
+    * unless a client has it open already, so the request carries no
+    * `languageId`, `version` or `text` seed. Returns the document at
+    * the server's configured target phase, as {@link getModelDocument} does.
+    * A repeat open changes nothing.
+    *
+    * 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: Pick<OpenModelArgs, 'uri' | 'clientId' | 'options'>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Close the session's open of `uri`. Counterpart to
+    * {@link openModelDocument}; the document stays open until every client
+    * has closed it, and then the server releases it, by default reverting it
+    * to disk. The default
+    * `DataServer` impl ALSO releases any watch for the same
+    * `(uri, clientId)` (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>;
 
@@ -81,34 +136,69 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
    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.
+    * Update a document's content as the session `clientId`, which must have
+    * it open. 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
+    * Write a document as the session `clientId`, which must have it open, and
+    * persist it to disk. The response is the build of the text written, with
+    * its version in `persisted`, sent once the language client has answered
+    * the push of that text, applied or refused, or a server-side bound on
+    * that wait passes; it does not wait again for a push that wait already
+    * gave up on and the client has not answered since. Save semantics depend
+    * on the filesystem-provider wiring; rejection paths surface as awaited
     * promise rejections.
     */
-   saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+   saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Persist the text the server holds for a document the session `clientId`
+    * has open, as it is: no update and no serialisation, so another client's
+    * unsaved text keeps its formatting. `baseVersion` is checked in the step
+    * that takes the text, so text that moved on fails with a `ConflictError`
+    * code. The saved event names this session, whoever wrote the text.
+    * Answers after the same language-client wait as {@link saveModelDocument},
+    * with the document's latest build, read after that wait, so another
+    * session's write during it shows; `persisted` carries the version written.
+    */
+   persistModelDocument(args: TransferPersistDocumentArgs): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Delete a document the session `clientId` has open, at once: its file,
+    * then the document, as a deletion a file watcher reports removes it. Every
+    * session's open of it closes and every client hears
+    * {@link DocumentClientProtocol.onDocumentDeleted} naming this session; the
+    * session's own watch is released, as {@link closeModelDocument} releases
+    * it. `baseVersion` is checked in the step that marks the document for
+    * deletion, so text that moved on fails with a `ConflictError` code. A file
+    * already gone deletes only the document; a file that cannot be removed
+    * fails the call and changes nothing. Resolves once the build that removes
+    * the document has run; a read then answers the URI without a model, unless
+    * an editor still has it open, whose buffer the document is built from.
+    */
+   deleteModelDocument(args: TransferDeleteDocumentArgs): Promise<void>;
 
    /**
     * 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.
+    * Answers with the key the watch's events name the document by, whether
+    * a document exists, taken once the watch is in place and the document
+    * is loaded as a read loads it, the text held at that moment, and the
+    * position of the last update or deletion event sent as of it, so an event
+    * the client heard while the watch was in flight tells by its own position
+    * whether it is newer than the answer. No handle: the event channel is the
+    * client interface. 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>;
+   watchModelDocument(args: WatchModelDocumentArgs): Promise<TransferWatchedDocument>;
 
    /**
     * Stop watching `(uri, clientId)` previously started by
@@ -194,6 +284,22 @@ export interface DataServerProtocol<
 >
    extends DocumentServerProtocol<TTransfer, TDiagnostic>, ProjectServerProtocol<TProject> {}
 
+/**
+ * The diagnostic shape a server answers with, read back off its own
+ * declaration.
+ *
+ * This is what lets a client tier stay generic over the server alone and still
+ * describe what it hands back. Both parameters must be inferred: naming
+ * {@link TransferElement} for the transfer instead fails to match while that
+ * parameter is still generic, and a default declared against the constraint
+ * then stops satisfying it.
+ */
+export type DiagnosticOf<TServer> =
+   TServer extends DocumentServerProtocol<infer _TTransfer, infer TDiagnostic> ? TDiagnostic : TransferDiagnostic;
+
+/** The project shape a server answers with, read back off its own declaration. */
+export type ProjectOf<TServer> = TServer extends ProjectServerProtocol<infer TProject> ? TProject : Project;
+
 /**
  * Cross-reference / naming slice of the server surface — scope-aware
  * queries that resolve against the language's reference services. NOT part
@@ -204,11 +310,11 @@ export interface DataServerProtocol<
  * 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.
+ * Not generic over a server's root type: {@link resolveReference} answers with
+ * a node a reference names, which is no document root, and candidates and
+ * names are diagnostic-free.
  */
-export interface ReferenceServerProtocol<TTransfer extends TransferElement> {
+export interface ReferenceServerProtocol {
    /**
     * List the reference candidates reachable for the property named in `ctx`
     * from its (possibly synthetic) source. Backed by the language's
@@ -221,8 +327,13 @@ export interface ReferenceServerProtocol<TTransfer extends TransferElement> {
     * 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.
+    *
+    * `TElement` is the caller's claim about the target node's type; nothing
+    * checks it, so leave it at the default unless the reference names one type.
     */
-   resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined>;
+   resolveReference<TElement extends TransferElement = TransferElement>(
+      ref: ReferenceRequest
+   ): Promise<ReferenceTarget<TElement> | undefined>;
 
    /**
     * Compute the next free name for a new element of `args.type` based on
@@ -262,6 +373,39 @@ export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiag
     * codepath, not a subscription codepath).
     */
    onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+
+   /**
+    * Delivered when a subscribed document's text starts or stops differing
+    * from its file, as the server last knew it. Gated like
+    * {@link onDocumentSaved}; the answer at any one moment is the `dirty` of
+    * the documents the server sends. After a reconnect, a `DataSession`
+    * delivers here the answer of each document it restored, when that differs
+    * from the last this client was told: the flips while the connection was
+    * down reached no one.
+    */
+   onDocumentDirtyChanged(event: TransferDocumentDirtyChangedEvent): void;
+
+   /**
+    * Delivered when a document's backing file was removed. Separate from
+    * {@link onDocumentUpdated} for the same reason as {@link onDocumentSaved},
+    * and more strongly: there is no built state to deliver, and the build-phase
+    * path cannot report a deletion at all.
+    *
+    * Ungated, because on a browser host — where the workspace lives behind the
+    * head — no other source can observe a file disappearing. Recipients that
+    * only care about their own documents filter by URI.
+    */
+   onDocumentDeleted(event: TransferDocumentDeletedEvent): void;
+
+   /**
+    * Delivered once per build, naming the documents that reached the
+    * subscription phase and that
+    * nobody on this connection watches — chiefly the ones rebuilt as a cascade
+    * from a dependency's change, which no filesystem watcher can see because
+    * their own files did not change. The complement of
+    * {@link onDocumentUpdated}; carries URIs and no documents.
+    */
+   onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void;
 }
 
 /**