@hydranium/core 1.0.0-next.11 → 1.0.0-next.111

package/src/locale/server-locale.ts

@@ -0,0 +1,86 @@
+/********************************************************************************
+ * 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 { Locale, Tracer } from '@hydranium/protocol';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+
+/** Construction options for {@link ServerLocale}. */
+export type ServerLocaleOptions = LogNameOptions;
+
+/**
+ * The locale contract the `ServerLocale` slot holds, implemented by
+ * {@link DefaultServerLocale}.
+ *
+ * An interface rather than the class, so the slot is compared STRUCTURALLY —
+ * a class-typed slot carries its `protected` members into every assignability
+ * check, compared nominally, which makes it unsatisfiable across two physical
+ * copies of this package and unreplaceable by an adopter's own declaration.
+ */
+export interface ServerLocale {
+   /** The locale, or `undefined` when no init supplied one — the framework's English. */
+   readonly value: Locale | undefined;
+   accept(locale: Locale): void;
+}
+
+/**
+ * The locale the server was handed at init, for whoever needs to render in the
+ * reading user's language. Held apart from the message renderer that reads it,
+ * so replacing the renderer cannot drop locale handling.
+ *
+ * A plain string in and out. A consumer that must react to a change rather than
+ * read the current value wraps this itself — nothing does today, and both real
+ * hosts respawn the server on a display-language switch.
+ */
+export class DefaultServerLocale implements ServerLocale {
+   protected readonly tracer: Tracer;
+   protected current: Locale | undefined;
+
+   constructor(services: ServerSharedServicesMinimal, options: ServerLocaleOptions = {}) {
+      this.tracer = services.Tracer.for(options.logName ?? 'ServerLocale').trace('instantiated');
+   }
+
+   /** The locale, or `undefined` when no init supplied one — which means the framework's English. */
+   get value(): Locale | undefined {
+      return this.current;
+   }
+
+   /**
+    * Take the locale an init declared.
+    *
+    * **One locale per process, and the reason the OTHER heads need none of
+    * their own.** The data and GLSP heads publish a port over the LSP
+    * connection and are reached by forwarding a socket to it, so they are the
+    * same process as the LSP head that was handed this locale — there is no
+    * topology in which one of them serves a second frontend. The Theia backend
+    * is the case that would break it, and it holds no locale precisely because
+    * it serves every frontend at once; nothing there writes here.
+    *
+    * The framework accepts a locale and never sources one, and neither
+    * validates nor normalises the tag: rejecting an unfamiliar one would be
+    * selecting a locale.
+    *
+    * Override to ignore the argument, which is how a host pins a locale it
+    * already knows but has no LSP client to declare.
+    *
+    * **The line is at `info`, which is a deliberate exception to the
+    * per-service default.** A locale is written once per process and it is the
+    * one setting that silently changes every user-facing sentence the server
+    * produces, so a reader trying to explain an unexpected language has nothing
+    * else to look at: the framework ships no catalogue, so "no entry for this
+    * code" and "no locale declared" both render the English and are
+    * indistinguishable in the output. At `debug` the line is below the default
+    * threshold and therefore absent from exactly the log someone would be
+    * reading.
+    */
+   accept(locale: Locale): void {
+      this.current = locale;
+      this.tracer.info(`rendering messages in locale '${locale}'`);
+   }
+}

package/src/lsp/completion/hydranium-completion-provider.ts

@@ -7,9 +7,16 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type AstNodeDescription, type ReferenceInfo, type Stream } from '@hydranium/langium';
+import { type AstNodeDescription, type LangiumDocument, type ReferenceInfo, type Stream } from '@hydranium/langium';
 import { DefaultCompletionProvider, type CompletionContext, type CompletionValueItem } from '@hydranium/langium/lsp';
-import type { CompletionItem, InsertReplaceEdit } from 'vscode-languageserver';
+import {
+   CompletionList,
+   type CancellationToken,
+   type CompletionItem,
+   type CompletionParams,
+   type InsertReplaceEdit,
+   type Position
+} from 'vscode-languageserver';
 import { type ReferenceCandidateProvider } from '../../langium/scope/reference-candidate-provider.js';
 import { type ServerLanguageServices } from '../../langium/language-module.js';
 
@@ -52,6 +59,14 @@ import { type ServerLanguageServices } from '../../langium/language-module.js';
  * elements. The provider owns that pipeline in one place, so the
  * text-editor dropdown and the protocol candidate picker stay in sync; this
  * class keeps only the LSP-specific {@link fillCompletionItem} upgrade.
+ *
+ * **A comment is not a completion site.** Langium's context builder reads the
+ * non-hidden token stream alone, so a cursor in a comment is indistinguishable
+ * from one in the whitespace between the tokens surrounding it: the grammar's
+ * follow-set goes out as keyword proposals, and none of them is filtered,
+ * because the characters the user typed belong to the hidden token and the
+ * prefix matched against is therefore empty. {@link isInsideComment} suppresses
+ * the request instead.
  */
 export class HydraniumCompletionProvider extends DefaultCompletionProvider {
    protected readonly candidateProvider: ReferenceCandidateProvider;
@@ -61,6 +76,71 @@ export class HydraniumCompletionProvider extends DefaultCompletionProvider {
       this.candidateProvider = services.references.CandidateProvider;
    }
 
+   /**
+    * Answer no proposals at all when the cursor is inside a comment.
+    *
+    * Suppressing the whole request is what makes the rule hold for every
+    * proposal kind at once. Filtering the built contexts instead has to catch
+    * each context kind the base builds separately, and a kind added upstream
+    * arrives unguarded.
+    *
+    * The list is marked incomplete so the client re-asks on the next keystroke
+    * and proposals resume the moment the cursor leaves the comment.
+    */
+   override async getCompletion(
+      document: LangiumDocument,
+      params: CompletionParams,
+      cancelToken?: CancellationToken
+   ): Promise<CompletionList | undefined> {
+      if (this.isInsideComment(document, params.position)) {
+         return CompletionList.create([], true);
+      }
+      return super.getCompletion(document, params, cancelToken);
+   }
+
+   /**
+    * Whether `position` falls in text a comment terminal claims.
+    *
+    * The two comment kinds part company at their far edge. A single-line
+    * comment runs to the line break, so a cursor at its end offset is still in
+    * prose and that offset counts as inside. A multi-line comment is
+    * terminated, so a cursor at its end offset has passed the terminator and is
+    * back in code. A cursor ON the opening delimiter is outside either way,
+    * that offset being a legal position for whatever token the comment
+    * displaced.
+    *
+    * The hidden token stream decides rather than the CST. A leaf lookup by
+    * offset misses the position a cursor reaches by typing prose into a
+    * trailing comment, because that comment ends AT the line break and
+    * whitespace is discarded before a CST node is built over it — so the
+    * lookup answers nothing exactly where proposals are least wanted.
+    *
+    * An adopter whose comment syntax carries completable content — a
+    * documentation tag naming a type — narrows this to return `false` over that
+    * region rather than replacing {@link getCompletion}.
+    */
+   protected isInsideComment(document: LangiumDocument, position: Position): boolean {
+      const text = document.textDocument.getText();
+      const offset = document.textDocument.offsetAt(position);
+      const multilineCommentRules = this.grammarConfig.multilineCommentRules;
+      for (const token of this.lexer.tokenize(text).hidden) {
+         if (token.startOffset >= offset) {
+            // Hidden tokens arrive in document order, so no later one reaches back over the cursor.
+            return false;
+         }
+         // `endOffset` is optional on the token type and the image is not, so
+         // the width comes from the image and needs no absent-value branch.
+         const endOffset = token.startOffset + token.image.length;
+         if (offset < endOffset) {
+            return true;
+         }
+         if (offset === endOffset && !multilineCommentRules.includes(token.tokenType.name)) {
+            return true;
+         }
+      }
+      return false;
+   }
+
    /**
     * Delegate cross-reference candidate gathering to the candidate provider
     * so the LSP completion dropdown applies the same filter / canonical

package/src/lsp/connection-features.ts

@@ -0,0 +1,67 @@
+/********************************************************************************
+ * 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 { LogMessageNotification, MessageType, type Features, type RemoteConsole } from 'vscode-languageserver';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
+
+/**
+ * Add Hydranium's connection-liveness handling to a language-server
+ * connection's console. The upstream `RemoteConsole` catches every failed log
+ * notification and prints `Sending log message failed`, so every ordinary
+ * teardown reports a failure; this console drops only a failure that
+ * {@link isConnectionGoneError} recognises and re-raises any other as an
+ * unhandled rejection.
+ *
+ * Supply it where the connection is created. `createConnection` builds the
+ * console from these features, so a connection that already exists keeps the
+ * upstream console for its whole lifetime.
+ */
+export function withHydraniumLspFeatures<T extends Features>(features: T): T {
+   return {
+      ...features,
+      console: (Base: new () => RemoteConsole) =>
+         class extends Base {
+            override error(message: string): void {
+               this.sendLogMessage(MessageType.Error, message);
+            }
+
+            override warn(message: string): void {
+               this.sendLogMessage(MessageType.Warning, message);
+            }
+
+            override info(message: string): void {
+               this.sendLogMessage(MessageType.Info, message);
+            }
+
+            override log(message: string): void {
+               this.sendLogMessage(MessageType.Log, message);
+            }
+
+            override debug(message: string): void {
+               this.sendLogMessage(MessageType.Debug, message);
+            }
+
+            private sendLogMessage(type: MessageType, message: string): void {
+               try {
+                  void this.connection.sendNotification(LogMessageNotification.type, { type, message }).catch(error => {
+                     this.handleLogSendFailure(error);
+                  });
+               } catch (error) {
+                  this.handleLogSendFailure(error);
+               }
+            }
+
+            private handleLogSendFailure(error: unknown): void {
+               if (!isConnectionGoneError(error)) {
+                  void Promise.reject(error);
+               }
+            }
+         }
+   } as T;
+}

package/src/lsp/diagnostics-connection.ts

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * 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 { Connection } from 'vscode-languageserver';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
+
+const wrappedConnections = new WeakSet<object>();
+
+/**
+ * Protect Langium's fire-and-forget diagnostics publish from the expected
+ * failure caused by a peer disconnecting during teardown.
+ *
+ * A publish issued after the connection is disposed throws synchronously
+ * instead of rejecting, and Langium's publisher is a document-phase listener,
+ * so an unguarded throw fails the build that validated the document. The
+ * `try` answers that case with a resolved promise; a guard on the promise
+ * alone never sees it.
+ *
+ * Otherwise the original promise is returned unchanged. The detached catch is
+ * deliberate: it marks the original promise as observed, suppresses only the
+ * expected connection-liveness error, and rethrows unexpected failures so they
+ * stay visible as unhandled rejections, as an unguarded fire-and-forget send
+ * would leave them.
+ */
+export function guardDiagnosticsConnection(connection: Connection): void {
+   if (wrappedConnections.has(connection)) {
+      return;
+   }
+   wrappedConnections.add(connection);
+
+   const sendDiagnostics = connection.sendDiagnostics.bind(connection);
+   connection.sendDiagnostics = params => {
+      let result: Promise<void>;
+      try {
+         result = sendDiagnostics(params);
+      } catch (error: unknown) {
+         if (isConnectionGoneError(error)) {
+            return Promise.resolve();
+         }
+         throw error;
+      }
+      void result.catch(error => {
+         if (isConnectionGoneError(error)) {
+            return;
+         }
+         throw error;
+      });
+      return result;
+   };
+}

package/src/lsp/hydranium-document-update-handler.ts

@@ -16,6 +16,7 @@ import { LANGUAGE_CLIENT_ID } from '../documents/client-ids.js';
 import { type SelfSaveRegistry } from '../documents/self-save-registry.js';
 import { type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
 import { type HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
 import { type DidChangeWatchedFilesParams, type FileEvent, FileChangeType, type TextDocumentChangeEvent } from 'vscode-languageserver';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
 
@@ -257,7 +258,7 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             }
             const uri = UriUtils.toUri(change.uri);
             const mtimeMs = await this.fileSystemProvider.mtimeMs?.(uri);
-            if (mtimeMs !== undefined && this.selfSaveRegistry.matches(uri.fsPath, mtimeMs)) {
+            if (mtimeMs !== undefined && this.selfSaveRegistry.isRegistered(uri.fsPath, mtimeMs)) {
                return undefined;
             }
             return change;
@@ -338,6 +339,14 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             })
          )
          .catch(err => {
+            // A deferred rebuild can finish after the LSP peer has gone away.
+            // Unless the head was started through `startLanguageServer`, whose
+            // guard absorbs it, the diagnostics publish then fails this build:
+            // a routine teardown race, not a failed workspace update. Keep
+            // genuine update failures visible.
+            if (isConnectionGoneError(err)) {
+               return;
+            }
             const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
             this.logger.error(`Workspace initialization failed. Could not perform document update. ${detail}`);
          });

package/src/lsp/index.ts

@@ -8,7 +8,9 @@
  ********************************************************************************/
 
 export * from './completion/hydranium-completion-provider.js';
-export * from './instrument-connection.js';
+export * from './lsp-latency.js';
+export * from './connection-features.js';
+export * from './diagnostics-connection.js';
 export * from './semantic-token-provider.js';
 export * from './language-module.js';
 export * from './shared-module.js';

package/src/lsp/lsp-latency.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * 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 { LatencyCollector } from '@hydranium/protocol';
+import type { ConnectionOptions, Message } from 'vscode-jsonrpc';
+
+/**
+ * Connection options that time every inbound LSP message into `latency` under
+ * its method name — the LSP analog of the data-server RPC chokepoint.
+ *
+ * Pass the result to `createConnection` where the head builds its connection:
+ * `createConnection(ProposedFeatures.all, lspLatencyOptions(latency))`. The
+ * transport is untouched, so a head keeps whatever `--stdio` / `--socket`
+ * selection its arguments make.
+ *
+ * **`messageStrategy` is the seam because it is the only one the handlers
+ * actually pass through.** `vscode-languageserver` builds its `Connection` as an
+ * object whose `onHover`, `onCompletion` and every other named helper register
+ * against the inner protocol connection captured in their closure — not against
+ * the returned object's own `onRequest`. Langium registers exclusively through
+ * those helpers, so decorating the `Connection` reaches none of them and reports
+ * an empty LSP half no matter how much traffic ran. `handleMessage` sits on the
+ * dispatch path itself, which every request and notification crosses, so it also
+ * catches `initialize` — special-cased into `onInitialize` and invisible to any
+ * `onRequest` decoration.
+ *
+ * What it measures is **dispatch plus handler**, not handler alone: the wait a
+ * client actually experiences, including time queued behind other work.
+ *
+ * When `latency` is `undefined` the seam is off and this returns `undefined`, so
+ * a head can pass the result of an env-gated factory (`latencyFromEnv()`)
+ * straight through and pay nothing when timing is not enabled.
+ */
+export function lspLatencyOptions(latency: LatencyCollector | undefined): ConnectionOptions | undefined {
+   if (!latency) {
+      return undefined;
+   }
+   return {
+      messageStrategy: {
+         handleMessage: (message: Message, next: (message: Message) => void | Promise<void>) => {
+            // Responses to requests the SERVER sent carry no method and are not
+            // work this head performed; timing them would report the client's
+            // latency under a name this collector cannot supply.
+            if (!hasMethod(message)) {
+               return next(message);
+            }
+            return latency.time(message.method, () => next(message));
+         }
+      }
+   };
+}
+
+/** Narrow to the messages that name an operation — requests and notifications. */
+function hasMethod(message: Message): message is Message & { method: string } {
+   return typeof (message as { method?: unknown }).method === 'string';
+}

package/src/lsp/semantic-token-provider.ts

@@ -14,7 +14,9 @@ import {
    CstUtils,
    GrammarAST,
    interruptAndCheck,
+   isLeafCstNode,
    type LangiumDocument,
+   type LeafCstNode,
    type ReferenceInfo
 } from '@hydranium/langium';
 import { AbstractSemanticTokenProvider, type SemanticTokenAcceptor } from '@hydranium/langium/lsp';
@@ -54,6 +56,23 @@ export interface HydraniumSemanticTokenProviderOptions {
     * render in the editor's default foreground.
     */
    readonly highlightKeywords?: boolean;
+
+   /**
+    * Also emit a `comment` token for every comment leaf of the CST.
+    *
+    * OFF by default for the same reason as {@link highlightKeywords}, and the
+    * loss is larger: a TextMate grammar distinguishes `comment.line` from
+    * `comment.block` and scopes the delimiters separately, where a semantic
+    * token carries one flat `comment` that overrides all of them. It exists
+    * for the host that ships no client-side grammar, where a comment otherwise
+    * renders in the editor's default foreground.
+    *
+    * What counts as a comment is every hidden terminal the lexer retains,
+    * which is every hidden terminal whose pattern is not whitespace. A grammar
+    * whose hidden non-whitespace terminal means something other than a comment
+    * is miscoloured, and this option is the place to say no.
+    */
+   readonly highlightComments?: boolean;
 }
 
 /**
@@ -133,7 +152,9 @@ export abstract class AbstractHydraniumSemanticTokenProvider extends AbstractSem
       cancelToken: CancellationToken
    ): Promise<void> {
       await super.computeHighlighting(document, acceptor, cancelToken);
-      if (this.options.highlightKeywords !== true) {
+      const keywords = this.options.highlightKeywords === true;
+      const comments = this.options.highlightComments === true;
+      if (!keywords && !comments) {
          return;
       }
       const root = document.parseResult.value.$cstNode;
@@ -142,14 +163,60 @@ export abstract class AbstractHydraniumSemanticTokenProvider extends AbstractSem
       }
       for (const cst of CstUtils.streamCst(root)) {
          await interruptAndCheck(cancelToken);
-         // The grammar source is the whole filter. A keyword is always a leaf,
-         // and the hidden leaves a comment or a run of whitespace contributes
-         // are sourced from a terminal rule rather than a `Keyword` — so
-         // neither a composite-node check nor a hidden-token check adds
-         // anything here.
-         if (GrammarAST.isKeyword(cst.grammarSource)) {
+         // A keyword is always a leaf with a `Keyword` grammar source, so that
+         // check alone separates it from everything else in the walk.
+         if (keywords && GrammarAST.isKeyword(cst.grammarSource)) {
             acceptor({ cst, type: SemanticTokenTypes.keyword });
          }
+         // A comment leaf cannot be recognised the same way — the CST builder
+         // adds hidden nodes from the token alone, so `grammarSource` is
+         // undefined, which is also why the keyword filter never matches one.
+         //
+         // `hidden` alone IS the comment test, and nothing narrower is needed:
+         // the token builder groups a hidden terminal as `Lexer.SKIPPED` when
+         // its pattern matches whitespace and as `hidden` otherwise, so the
+         // lexer discards whitespace before a CST node is ever built and every
+         // hidden leaf that survives is a comment. Classifying the terminal
+         // again here would be a second guard for the same property, which no
+         // test could then distinguish. An adopter whose token builder RETAINS
+         // whitespace breaks that equivalence and would colour its gaps.
+         if (comments && isLeafCstNode(cst) && cst.hidden) {
+            this.acceptComment(cst, acceptor);
+         }
+      }
+   }
+
+   /**
+    * Emit a comment as ONE TOKEN PER LINE, never as one multi-line range.
+    *
+    * A block comment is the first token this provider emits that can span
+    * lines, and the upstream encoder mishandles that for a client which does
+    * not advertise `multilineTokenSupport` — the split path computes the first
+    * line's length as `nextLineOffset - range.start.character - 1`, subtracting
+    * a COLUMN from a document OFFSET, so the length is right only for a token
+    * starting on line 0 and overruns its line everywhere else. No client in
+    * this repository advertises that capability, so the broken path is the one
+    * taken. Splitting here means every range handed over starts and ends on one
+    * line and the arithmetic is never reached.
+    *
+    * Lines come from the leaf's own text rather than from the document, so
+    * nothing has to re-derive where the comment ends.
+    */
+   protected acceptComment(cst: LeafCstNode, acceptor: SemanticTokenAcceptor): void {
+      const lines = cst.text.split('\n');
+      for (let index = 0; index < lines.length; index++) {
+         // A `\r\n` document leaves the carriage return on the line's end;
+         // colouring it would extend the token past the visible text.
+         const length = lines[index].replace(/\r$/, '').length;
+         const character = index === 0 ? cst.range.start.character : 0;
+         if (length === 0) {
+            continue;
+         }
+         const line = cst.range.start.line + index;
+         acceptor({
+            range: { start: { line, character }, end: { line, character: character + length } },
+            type: SemanticTokenTypes.comment
+         });
       }
    }
 

package/src/lsp/start-language-server.ts

@@ -13,6 +13,7 @@ import {
    type ServiceRequirements
 } from '@hydranium/langium/lsp';
 import { HydraniumDocumentUpdateHandler } from './hydranium-document-update-handler.js';
+import { guardDiagnosticsConnection } from './diagnostics-connection.js';
 
 /**
  * Fail the LSP head's start when its shared module was never composed.
@@ -58,11 +59,17 @@ export function assertLspHeadComposed(services: LangiumSharedServices): void {
 
 /**
  * The framework's LSP server entry point: {@link assertLspHeadComposed}, then
- * Langium's `startLanguageServer` unchanged. Signature-compatible with
- * Langium's, so it is a drop-in for adopters importing from
- * `@hydranium/core/lsp`.
+ * {@link guardDiagnosticsConnection} on the tree's connection, then Langium's
+ * `startLanguageServer`. Signature-compatible with Langium's, so it is a
+ * drop-in for adopters importing from `@hydranium/core/lsp`. Calling Langium's
+ * directly skips both: the composition check, and the guard without which a
+ * publish racing teardown fails the build that validated the document.
  */
 export function startLanguageServer(services: LangiumSharedServices, serviceRequirements: Partial<ServiceRequirements> = {}): void {
    assertLspHeadComposed(services);
+   const connection = services.lsp.Connection;
+   if (connection) {
+      guardDiagnosticsConnection(connection);
+   }
    startLangiumLanguageServer(services, serviceRequirements);
 }

package/src/messages/carriers.ts

@@ -0,0 +1,78 @@
+/********************************************************************************
+ * 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 {
+   hasMessageIdentity,
+   messageData,
+   type HydraniumMessageData,
+   type MessageDefinition,
+   type ParamsArg,
+   type ResolvedMessage
+} from '@hydranium/protocol';
+import type { AstNode, DiagnosticData, DiagnosticInfo, Properties, ValidationAcceptor } from '@hydranium/langium';
+import { Diagnostic } from 'vscode-languageserver-protocol';
+
+/**
+ * Raise a validation diagnostic from a declaration, so the call site never
+ * restates the code or the sentence.
+ *
+ * `code` is omitted from `info` because this owns it — the framework claims LSP
+ * `Diagnostic.code` for framework codes, which collides with no adopter today
+ * and is a stated rule rather than an accident. `data` is deliberately NOT
+ * omitted: Langium owns `data.code` for code-action dispatch, so a caller has to
+ * be able to request a quick fix. The identity is merged OVER whatever they
+ * pass, which makes the two conventions co-exist rather than compete.
+ *
+ * `data` admits adopter-owned keys beside Langium's, which is why the index
+ * signature is there rather than a bare `Partial<DiagnosticData>`. Langium's
+ * shape is closed, and a diagnostic that carries a COMPANION payload for its own
+ * surface to read — the field a form must highlight, say — has nowhere else to
+ * put it: an encoder projecting that payload reads `diagnostic.data`, so the
+ * narrower type made the identity and the companion mutually exclusive.
+ *
+ * The identity lands in both `code` and `data.hydranium` on purpose. `code` is
+ * what survives to the editor surface; Theia's converter drops `data` before the
+ * squiggle, so a parameterised diagnostic falls back to the server's English
+ * there while any adopter-owned surface can still render the parameterised form
+ * from the marker store.
+ *
+ * `DiagnosticInfo` must be Langium's own type: a `Parameters<ValidationAcceptor>[2]`
+ * shortcut compiles but loses the `property?: Properties<N>` relation. The `data`
+ * re-type has to be an intersection rather than an `Omit` alone, because Langium
+ * declares `data?: unknown` and an `unknown` cannot be spread.
+ */
+export function acceptMessage<S extends string, N extends AstNode, P extends Properties<N> = Properties<N>>(
+   accept: ValidationAcceptor,
+   severity: 'error' | 'warning' | 'info' | 'hint',
+   message: MessageDefinition<S>,
+   info: Omit<DiagnosticInfo<N, P>, 'code' | 'data'> & { data?: Partial<DiagnosticData> & Record<string, unknown> },
+   ...params: ParamsArg<S>
+): void {
+   const data: HydraniumMessageData & Partial<DiagnosticData> & Record<string, unknown> = {
+      ...info.data,
+      ...messageData(message, ...params)
+   };
+   accept(severity, message.format(...params), { ...info, code: message.code, data });
+}
+
+/**
+ * Recover the identity from a published diagnostic, for a surface that
+ * identifies or renders diagnostics itself.
+ *
+ * `Diagnostic.message` is `string | MarkupContent` in LSP 3.17+, so the text
+ * comes from upstream's own `Diagnostic.getMessageString` rather than a
+ * hand-rolled narrowing — consuming the library in its style, and one fewer
+ * place restating the union.
+ */
+export function resolvedFromDiagnostic(diagnostic: Diagnostic): ResolvedMessage | undefined {
+   if (!hasMessageIdentity(diagnostic.data)) {
+      return undefined;
+   }
+   return { ...diagnostic.data.hydranium, text: Diagnostic.getMessageString(diagnostic) };
+}