@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,132 @@
+/********************************************************************************
+ * 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 AstNodeDescription, 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 { type ReferenceCandidateProvider } from '../../langium/scope/reference-candidate-provider.js';
+import { type ServerLanguageServices } from '../../langium/language-module.js';
+
+/**
+ * Completion provider that upgrades Langium's default `TextEdit` to
+ * {@link InsertReplaceEdit} so accepting a suggestion over an existing token
+ * replaces that token rather than inserting alongside it.
+ *
+ * **Why this exists.** `DefaultCompletionProvider.buildCompletionTextEdit`
+ * returns a range ending at the cursor position, so accepting a suggestion
+ * with the caret inside a token leaves the token's tail standing after the
+ * inserted text. By widening the `replace` range to the token's end while
+ * keeping the original `insert` range at the cursor, LSP clients honour the
+ * user's `editor.suggest.insertMode` preference (`insert` = Langium's narrow
+ * range, `replace` = overwrite the whole token).
+ *
+ * **Two cursor positions need widening and Langium's context only describes
+ * one of them.** Inside a token, `tokenEndOffset` points past the token and the
+ * widening reads straight off it. Sitting at a token's START — right after `= `
+ * in `writes Order.status = PAID`, say — the cursor is on whitespace as far as
+ * the completion context is concerned, so `tokenEndOffset` describes the
+ * whitespace and not the name that follows it. Without {@link getReplaceEndOffset}
+ * the item goes out with an EMPTY range and accepting it produces
+ * `SHIPPEDPAID`: the suggestion inserted in front of the word it was meant to
+ * replace. A `tsserver` in the same position returns a range covering the
+ * following word, which is the behaviour matched here.
+ *
+ * **Capability gating.** {@link InsertReplaceEdit} requires LSP 3.16+
+ * (`completionItem.insertReplaceSupport`). Older clients that ignore the
+ * wider range fall back to the narrower `insert` range, which matches
+ * Langium's original behaviour. A defensive capability check is
+ * intentionally not added so the framework default stays simple —
+ * consumers that need to support pre-3.16 clients can override and emit a
+ * plain `TextEdit`.
+ *
+ * **Candidate gathering is delegated.** Cross-reference completion reuses
+ * the {@link ReferenceCandidateProvider} pipeline (filter, canonical
+ * tier-sibling collapse, name-dedup, sort) by overriding
+ * {@link getReferenceCandidates} to return the candidate provider's scope
+ * 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.
+ */
+export class HydraniumCompletionProvider extends DefaultCompletionProvider {
+   protected readonly candidateProvider: ReferenceCandidateProvider;
+
+   constructor(services: ServerLanguageServices) {
+      super(services);
+      this.candidateProvider = services.references.CandidateProvider;
+   }
+
+   /**
+    * Delegate cross-reference candidate gathering to the candidate provider
+    * so the LSP completion dropdown applies the same filter / canonical
+    * tier-sibling collapse / name-dedup / sort as the protocol candidate
+    * picker. Langium hands us the built {@link ReferenceInfo}, which the
+    * candidate provider's `getCandidateScope` accepts directly, so the
+    * merged path walks the scope exactly once.
+    */
+   protected override getReferenceCandidates(refInfo: ReferenceInfo, _context: CompletionContext): Stream<AstNodeDescription> {
+      return this.candidateProvider.getCandidateScope(refInfo).elementScope.getAllElements();
+   }
+
+   protected override fillCompletionItem(context: CompletionContext, item: CompletionValueItem): CompletionItem | undefined {
+      const completionItem = super.fillCompletionItem(context, item);
+      if (!completionItem?.textEdit || 'insert' in completionItem.textEdit) {
+         return completionItem;
+      }
+      const replaceEndOffset = this.getReplaceEndOffset(context);
+      // Nothing to the right of the cursor that a suggestion would stand in for
+      // (completion on whitespace, on punctuation, at end of file) — the
+      // parent's narrow range is already correct.
+      if (replaceEndOffset <= context.offset) {
+         return completionItem;
+      }
+      const baseEdit = completionItem.textEdit;
+      const insertReplaceEdit: InsertReplaceEdit = {
+         newText: baseEdit.newText,
+         insert: baseEdit.range,
+         replace: { start: baseEdit.range.start, end: context.textDocument.positionAt(replaceEndOffset) }
+      };
+      completionItem.textEdit = insertReplaceEdit;
+      return completionItem;
+   }
+
+   /**
+    * Offset the `replace` range should end at: the end of the text a suggestion
+    * accepted here would stand in for, or `context.offset` when there is none.
+    *
+    * Two sources, because Langium's completion context describes the token the
+    * completion is FOR and that is not always the text under the cursor:
+    *
+    * - **Cursor inside a token** — `tokenEndOffset` already points past it.
+    * - **Cursor at a token's start** — the context describes the preceding
+    *   whitespace, so `tokenEndOffset` is at or behind the cursor and the name
+    *   to the right has to be measured from the document text.
+    *
+    * Scanning stops at the first character `GrammarConfig.nameRegexp` rejects, so
+    * a run only ever covers one name: a cursor before `Order` in `Order.status`
+    * widens to the end of `Order` and not through the dot.
+    *
+    * Adopters whose grammar has a wider notion of a replaceable token than
+    * "consecutive name characters" — a quoted or dotted identifier — override
+    * this rather than {@link fillCompletionItem}.
+    */
+   protected getReplaceEndOffset(context: CompletionContext): number {
+      if (context.tokenEndOffset > context.offset) {
+         return context.tokenEndOffset;
+      }
+      // `getText()` with no range returns the document's stored string rather
+      // than a copy, so reading it per item costs nothing.
+      const text = context.textDocument.getText();
+      const nameRegexp = this.grammarConfig.nameRegexp;
+      let end = context.offset;
+      while (end < text.length && nameRegexp.test(text.charAt(end))) {
+         end++;
+      }
+      return end;
+   }
+}

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

@@ -0,0 +1,345 @@
+/********************************************************************************
+ * 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 { Debouncer, type Logger, ObservableValue, type MaybeObservableValue } from '@hydranium/protocol';
+import { URI, UriUtils } from '@hydranium/langium';
+import { DefaultDocumentUpdateHandler } from '@hydranium/langium/lsp';
+import { type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
+import { type ServerSharedServices } from '../langium/module.js';
+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 { type DidChangeWatchedFilesParams, type FileEvent, FileChangeType, type TextDocumentChangeEvent } from 'vscode-languageserver';
+import { type TextDocument } from 'vscode-languageserver-textdocument';
+
+/**
+ * Default LSP-event reasons stamped by {@link HydraniumDocumentUpdateHandler}
+ * onto the next `documentBuilder.update` call via `markNextReason`. Exposed
+ * so adopters subclassing the handler can layer additional reasons or rename
+ * existing ones without losing the canonical names the framework emits.
+ */
+export const HYDRANIUM_BUILD_REASONS = Object.freeze({
+   didOpen: 'didOpen',
+   didChangeContent: 'didChangeContent',
+   didChangeWatchedFiles: 'didChangeWatchedFiles',
+   didClose: 'didClose'
+} as const);
+
+/**
+ * Construction options for {@link HydraniumDocumentUpdateHandler}.
+ */
+export interface HydraniumDocumentUpdateHandlerOptions {
+   /**
+    * Trailing-edge debounce window. `0` (the default) disables
+    * debouncing — `didChangeContent` flows synchronously into
+    * `fireDocumentUpdate` as in Langium's default. Accepts an
+    * {@link MaybeObservableValue} so adopters can bind to a user setting via
+    * `Settings.number`; updates to the underlying snapshot reshape
+    * the live debounce window without rebuilding the handler.
+    */
+   readonly debounceMs?: MaybeObservableValue<number>;
+   /**
+    * Bypass debouncing for changes whose author is anything other
+    * than the language client (Monaco). GLSP / form-editor /
+    * integrity-rule author changes are already coalesced upstream —
+    * debouncing them adds latency for no benefit. Default `true`.
+    *
+    * Adopters disable this when they want uniform debouncing
+    * regardless of source (rare — typically only for synthetic
+    * load tests).
+    */
+   readonly bypassNonLanguageClientChanges?: boolean;
+}
+
+/**
+ * Framework `DocumentUpdateHandler` adding these behaviours over Langium's
+ * default:
+ *
+ *  1. **Self-save filter** ({@link filterSelfSaves}) — drops
+ *     watched-file-change echoes for the server's own writes via
+ *     {@link SelfSaveRegistry}, keyed by `fsPath` + mtime.
+ *  2. **Trailing-edge debouncing** — collapses rapid
+ *     `didChangeContent` calls into one rebuild on the trailing
+ *     edge of the configured window. Non-language-client author
+ *     changes and watched-file changes bypass the debounce (their
+ *     producers are already coalesced).
+ *  3. **Build-reason stamping** — the LSP event overrides
+ *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`,
+ *     `didCloseDocument`) populate {@link nextReason} with a canonical
+ *     reason string. {@link fireDocumentUpdate} captures the reason;
+ *     {@link dispatch} stages it on the builder via
+ *     {@link HydraniumDocumentBuilder.markNextReason}, so a subclass that
+ *     formats build logs can tag its line with the event that caused the
+ *     build without per-adopter wiring to capture it.
+ *  4. **Last-client-close rebuild trigger** ({@link didCloseDocument}) —
+ *     when the final client closes a document, dispatch a build so the
+ *     LangiumDocument's `textDocument` is refreshed (from disk for `file:`
+ *     URIs, or removed from the index for ephemeral URIs). Langium's
+ *     default handler does not implement `didCloseDocument`, so the
+ *     in-memory text of the last writer would otherwise persist.
+ *
+ * Adopters with their own handler subclass should extend this class
+ * (not Langium's `DefaultDocumentUpdateHandler`) so all of them are
+ * preserved. The {@link dispatch} hook is the canonical override
+ * point for adopters that need to stamp additional per-build metadata
+ * inside the workspace-lock callback.
+ */
+export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler {
+   /**
+    * Narrow Langium's `DefaultDocumentUpdateHandler.documentBuilder` typing to
+    * the framework subclass: `markNextReason` is the only method this handler
+    * reaches for beyond the Langium interface.
+    */
+   declare protected readonly documentBuilder: HydraniumDocumentBuilder;
+
+   protected readonly logger: Logger;
+   protected readonly selfSaveRegistry: SelfSaveRegistry;
+   protected readonly fileSystemProvider: WritableFileSystemProvider;
+   protected readonly textDocuments: HydraniumTextDocuments<TextDocument>;
+
+   /** Live debounce window — a constant or a setting-bound cell; read `.value` per flush. */
+   protected readonly debounce: ObservableValue<number>;
+   protected readonly bypassNonLanguageClientChanges: boolean;
+
+   /** Accumulated changed / deleted URIs awaiting the next debounced flush. Keyed by URI string so duplicates merge. */
+   protected pendingChanged = new Map<string, URI>();
+   protected pendingDeleted = new Map<string, URI>();
+   /** Trailing-edge timing for the coalesced flush; the pending sets above are the payload it drains. */
+   protected readonly flushDebouncer: Debouncer;
+   /** Flush on the next `fireDocumentUpdate` instead of debouncing — set by the LSP event handlers when the source isn't typing. */
+   protected immediateFlush = false;
+
+   /**
+    * Build-reason for the next `fireDocumentUpdate`, stamped by the LSP
+    * event overrides. `??=` semantics in `didChangeContent` preserve a
+    * prior `'didOpen'` stamp because Langium fires `didOpen` then
+    * `didChangeContent` on document open — the open semantics are the
+    * authoritative trigger for that pair, not the content change.
+    */
+   protected nextReason?: string;
+   /**
+    * Build-reason captured at `fireDocumentUpdate` time, drained by
+    * {@link dispatch} into `markNextReason`. Survives across debounced
+    * batches (`?? pendingReason` in `fireDocumentUpdate` retains the
+    * first reason in a coalesced burst).
+    */
+   protected pendingReason?: string;
+
+   constructor(services: ServerSharedServices, options: HydraniumDocumentUpdateHandlerOptions = {}) {
+      super(services);
+      this.logger = services.Logger;
+      this.selfSaveRegistry = services.workspace.SelfSaveRegistry;
+      this.fileSystemProvider = services.workspace.FileSystemProvider;
+      this.textDocuments = services.workspace.TextDocuments;
+      this.debounce = ObservableValue.from(options.debounceMs ?? 0);
+      this.flushDebouncer = new Debouncer(services.Clock, () => this.flushPending(), { delayMs: this.debounce });
+      this.bypassNonLanguageClientChanges = options.bypassNonLanguageClientChanges ?? true;
+   }
+
+   didOpenDocument(_change: TextDocumentChangeEvent<TextDocument>): void {
+      // Langium also fires `didChangeContent` on open, which is what triggers
+      // `fireDocumentUpdate`. Stamp the reason here so the trailing
+      // `didChangeContent` preserves it via `??=`. Bypass debouncing so the
+      // LangiumDocument is in the index before consumers (model service,
+      // form-editor, GLSP) try to read it.
+      this.nextReason = HYDRANIUM_BUILD_REASONS.didOpen;
+      this.immediateFlush = true;
+   }
+
+   override didChangeContent(change: TextDocumentChangeEvent<TextDocument>): void {
+      // `??=` preserves a prior `'didOpen'` stamp (Langium fires didOpen
+      // immediately before didChangeContent on document open).
+      this.nextReason ??= HYDRANIUM_BUILD_REASONS.didChangeContent;
+      // Bypass debouncing for non-Monaco author changes (GLSP node moves, form-editor
+      // saves, integrity-rule mutations) — their producers already coalesce upstream.
+      if (this.bypassNonLanguageClientChanges && this.textDocuments.getAuthor(change.document.uri) !== LANGUAGE_CLIENT_ID) {
+         this.immediateFlush = true;
+      }
+      super.didChangeContent(change);
+   }
+
+   /**
+    * Last-client close is the missing rebuild trigger in Langium's
+    * `DefaultDocumentUpdateHandler`: `documents.onDidClose` fires on every
+    * per-client close, but the default handler ignores the event entirely.
+    * For multi-client servers this leaves the LangiumDocument carrying the
+    * unsaved in-memory `textDocument` of the last writer until something
+    * else triggers a rebuild — integrity rules walking `langiumDocuments.all`
+    * then see stale text long after the user discarded their edits.
+    *
+    * We funnel the last-client transition through the same dispatch path
+    * the other LSP events use, so the rebuild gets debouncing, workspace
+    * locking, build-reason stamping, and `markNextReason` for free. The
+    * scheme split governs the `DocumentBuilder.update` shape:
+    *
+    *  - **`file:` URI** → `update([uri], [])`. Routes through
+    *    `LangiumDocuments.invalidateDocument` (doc stays in the trie) and
+    *    `LangiumDocumentFactory.update`, which consults the LSP-tracked
+    *    open-documents map first. That map is cleared LATER in the same
+    *    synchronous `notifyDidCloseTextDocument` call that fires this event,
+    *    and {@link dispatch} defers the build behind `workspaceManager.ready`
+    *    — so by the time the factory looks, the URI is gone: it falls back to
+    *    `FileSystemProvider.readFile` and the doc rebuilds from disk,
+    *    Langium's canonical close-without-save semantic. A dispatch made
+    *    synchronously here would still see the open document and re-read the
+    *    in-memory text instead.
+    *  - **non-`file:` URI** (`builtin:`, `untitled:`) → no dispatch.
+    *    Adopter-loaded schemes — documents pulled in via
+    *    `loadAdditionalDocuments` — need to stay in the workspace index;
+    *    dropping them on close would break every cross-reference that
+    *    targets them. The framework cannot enumerate adopter schemes, so the
+    *    safe default is "leave alone unless it's a file." Adopters that need
+    *    ephemeral-URI cleanup handle it explicitly.
+    *
+    * Per-client closes (where other clients still hold the URI) are
+    * suppressed via {@link HydraniumTextDocuments.isOpenInAnyClient}.
+    */
+   didCloseDocument(change: TextDocumentChangeEvent<TextDocument>): void {
+      if (this.textDocuments.isOpenInAnyClient(change.document.uri)) {
+         return;
+      }
+      const uri = URI.parse(change.document.uri);
+      if (uri.scheme !== 'file') {
+         return;
+      }
+      this.nextReason = HYDRANIUM_BUILD_REASONS.didClose;
+      this.immediateFlush = true;
+      this.fireDocumentUpdate([uri], []);
+   }
+
+   override didChangeWatchedFiles(params: DidChangeWatchedFilesParams): void {
+      void this.filterSelfSaves(params)
+         .then(filtered => {
+            if (filtered.changes.length === 0) {
+               return;
+            }
+            // External file-system changes are authoritative — overwrite any
+            // pending reason (typically empty here; could be `didChangeContent`
+            // if a watcher event raced an in-flight Monaco edit, in which case
+            // the watcher event is the more interesting trigger to log).
+            this.nextReason = HYDRANIUM_BUILD_REASONS.didChangeWatchedFiles;
+            // External file-system changes are discrete events — flush immediately
+            // rather than coalescing with in-flight Monaco typing.
+            this.immediateFlush = true;
+            super.didChangeWatchedFiles(filtered);
+         })
+         .catch(err => {
+            // The rejection would otherwise reach the process-level
+            // `unhandledRejection` listener, which reports neither the URIs nor
+            // the fact that a watched-file rebuild was dropped — leaving the
+            // workspace diverged from disk with no diagnostic and no retry.
+            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            const uris = params.changes.map(change => change.uri).join(', ');
+            this.logger.error(`Watched-file update dropped for ${uris}. ${detail}`);
+         });
+   }
+
+   /**
+    * Drop watched-file changes whose path + mtime match a recent self-save
+    * record. Deletions always pass (no mtime); stat failures pass (the
+    * change is real enough). Keyed by `fsPath` to avoid URI-form
+    * mismatches between watcher payloads and write-time records. Stats run
+    * in parallel — order in the output is irrelevant; the consumer
+    * aggregates URIs into changed/deleted sets.
+    */
+   protected async filterSelfSaves(params: DidChangeWatchedFilesParams): Promise<DidChangeWatchedFilesParams> {
+      const kept = await Promise.all(
+         params.changes.map(async change => {
+            if (change.type === FileChangeType.Deleted) {
+               return change;
+            }
+            const uri = UriUtils.toUri(change.uri);
+            const mtimeMs = await this.fileSystemProvider.mtimeMs?.(uri);
+            if (mtimeMs !== undefined && this.selfSaveRegistry.matches(uri.fsPath, mtimeMs)) {
+               return undefined;
+            }
+            return change;
+         })
+      );
+      return { changes: kept.filter((change): change is FileEvent => change !== undefined) };
+   }
+
+   /**
+    * Coalesce `changed` / `deleted` into the pending sets, then either
+    * flush immediately (`immediateFlush` or `debounceMs <= 0`) or restart
+    * the trailing-edge timer. Subclasses that need to stamp per-build
+    * metadata can override and inspect the merged sets — but the canonical
+    * override point for the workspace-lock callback is {@link dispatch},
+    * not this method.
+    */
+   protected override fireDocumentUpdate(changed: URI[], deleted: URI[]): void {
+      // Capture the reason set by the LSP event handler immediately before
+      // we merge into the pending sets. `?? pendingReason` keeps the
+      // first reason in a coalesced burst (LSP events arriving inside an
+      // active debounce window all stamp the same `pendingReason` once,
+      // because subsequent stamps see the field already non-undefined).
+      this.pendingReason = this.nextReason ?? this.pendingReason;
+      this.nextReason = undefined;
+      for (const uri of changed) {
+         this.pendingChanged.set(uri.toString(), uri);
+      }
+      for (const uri of deleted) {
+         const key = uri.toString();
+         this.pendingDeleted.set(key, uri);
+         this.pendingChanged.delete(key);
+      }
+      if (this.immediateFlush || this.debounce.value <= 0) {
+         this.immediateFlush = false;
+         this.flushPending(); // cancels any armed flush, then drains
+         return;
+      }
+      this.flushDebouncer.schedule();
+   }
+
+   /**
+    * Drain the pending sets and dispatch a single build. Public so tests
+    * can flush deterministically and shutdown paths can drain any
+    * trailing-edge updates that would otherwise be lost when the timer
+    * never fires.
+    */
+   public flushPending(): void {
+      this.flushDebouncer.cancel();
+      const changed = Array.from(this.pendingChanged.values());
+      const deleted = Array.from(this.pendingDeleted.values());
+      this.pendingChanged.clear();
+      this.pendingDeleted.clear();
+      if (changed.length === 0 && deleted.length === 0) {
+         return;
+      }
+      this.dispatch(changed, deleted);
+   }
+
+   /**
+    * Workspace-lock + `documentBuilder.update` call for the merged sets.
+    * Mirrors Langium's `super.fireDocumentUpdate` body plus
+    * `markNextReason(pendingReason)` inside the write-lock callback, so the
+    * build the lock is about to run carries the LSP event that triggered it.
+    * Adopters override to stamp additional per-build metadata — the canonical
+    * pattern is to read the reason via `this.pendingReason`, call
+    * `super.dispatch(...)` or replicate the
+    * `workspaceManager.ready -> workspaceLock.write` block, and add
+    * adopter-specific behaviour inside the write callback.
+    */
+   protected dispatch(changed: URI[], deleted: URI[]): void {
+      const reason = this.pendingReason;
+      this.pendingReason = undefined;
+      this.workspaceManager.ready
+         .then(() =>
+            this.workspaceLock.write(token => {
+               this.documentBuilder.markNextReason(reason);
+               return this.documentBuilder.update(changed, deleted, token);
+            })
+         )
+         .catch(err => {
+            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

@@ -0,0 +1,24 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+export * from './completion/hydranium-completion-provider.js';
+export * from './instrument-connection.js';
+export * from './semantic-token-provider.js';
+export * from './language-module.js';
+export * from './shared-module.js';
+export * from './hydranium-document-update-handler.js';
+
+/**
+ * The LSP server entry point, so adopters get a unified import surface for the
+ * head: framework overrides + the start function live behind one
+ * `@hydranium/core/lsp` subpath, mirroring Langium's own `langium/lsp`
+ * convention. Signature-compatible with Langium's `startLanguageServer`, plus
+ * a guard that the head's shared module was composed.
+ */
+export * from './start-language-server.js';

package/src/lsp/instrument-connection.ts

@@ -0,0 +1,66 @@
+/********************************************************************************
+ * 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';
+
+type RequestHandler = (...args: unknown[]) => unknown;
+
+/**
+ * Wrap an LSP `Connection` so every request handler registered through
+ * `onRequest` is timed into `latency` under its method name — the LSP analog of
+ * the data-server RPC chokepoint. Langium's `startLanguageServer` registers
+ * `onCompletion`/`onHover`/… one handler at a time, so there is no single
+ * dispatch point; but every registration funnels through the ONE `onRequest`
+ * on the shared `Connection`, so decorating it catches every method with no
+ * Langium fork and no per-handler code.
+ *
+ * Opt in where the head creates the connection, before it hands it to the
+ * services factory — wrapping it afterwards is too late, because Langium has
+ * already registered its handlers against the raw connection.
+ *
+ * `onRequest` has several overloads: most register a handler for a specific
+ * method (a string, or a typed request whose `.method` names it) and one is the
+ * `StarRequestHandler` catch-all `onRequest(handler)`. The star form fires only
+ * for methods with no registered handler, so timing it would be misleading — it
+ * is passed through untouched. Every other member of the connection is
+ * forwarded unchanged.
+ *
+ * When `latency` is `undefined` the seam is off: the connection is returned
+ * unchanged (no Proxy, no per-request timing), so a head can pass the result of
+ * an env-gated factory (`latencyFromEnv()`) straight through and pay nothing
+ * when latency is not enabled.
+ */
+export function instrumentLspConnection<C extends object>(connection: C, latency: LatencyCollector | undefined): C {
+   if (!latency) {
+      return connection;
+   }
+   return new Proxy(connection, {
+      get(target, property, receiver): unknown {
+         const value: unknown = Reflect.get(target, property, receiver);
+         if (property !== 'onRequest' || typeof value !== 'function') {
+            return value;
+         }
+         const onRequest = value as (...args: unknown[]) => unknown;
+         return (...args: unknown[]): unknown => {
+            const [first, handler] = args;
+            // Star form `onRequest(handler)` — pass through; it is not a timer.
+            if (typeof first === 'function' || typeof handler !== 'function') {
+               return onRequest.apply(target, args);
+            }
+            const method = typeof first === 'string' ? first : (first as { method?: unknown }).method;
+            if (typeof method !== 'string') {
+               return onRequest.apply(target, args);
+            }
+            const original = handler as RequestHandler;
+            const timed: RequestHandler = (...handlerArgs) => latency.time(method, () => original(...handlerArgs));
+            return onRequest.apply(target, [first, timed, ...args.slice(2)]);
+         };
+      }
+   });
+}

package/src/lsp/language-module.ts

@@ -0,0 +1,64 @@
+/********************************************************************************
+ * 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 Module } from '@hydranium/langium';
+import { type ServerLanguageServices } from '../langium/language-module.js';
+import { type ServerModuleContext } from '../langium/module.js';
+import { type PartialLangiumServices } from '@hydranium/langium/lsp';
+import { HydraniumCompletionProvider } from './completion/hydranium-completion-provider.js';
+
+/**
+ * Language-level slots contributed by the LSP-textual protocol head.
+ * Bound by {@link createLspServerLanguageModule}; consumer modules
+ * layered after it can override any slot.
+ *
+ * - {@link HydraniumCompletionProvider} upgrades Langium's default
+ *   `TextEdit` to an `InsertReplaceEdit` so the user's
+ *   `editor.suggest.insertMode` preference is honoured.
+ *
+ * The head's SHARED-tier slots are bound by
+ * `createLspServerSharedModule` instead: `lsp.DocumentUpdateHandler`
+ * exists once per server rather than once per grammar, so binding it here is
+ * inert — nothing reads a per-language one.
+ */
+export interface LspServerAddedServices {
+   lsp: {
+      /* override */ CompletionProvider: HydraniumCompletionProvider;
+   };
+}
+
+/**
+ * Full language-service surface visible to consumers that compose this
+ * head: `@hydranium/core`'s bindings plus the LSP-textual additions. Use as
+ * the `T` type parameter for the consumer's own
+ * `Module<LspServerLanguageServices, ...>` if its overrides depend on
+ * any LSP-only slot.
+ */
+export type LspServerLanguageServices = ServerLanguageServices & LspServerAddedServices;
+
+/**
+ * The LSP-textual protocol head's default language module. Composes on
+ * top of `createServerLanguageModule` — as a later `inject(...)`
+ * argument, or as `languageModules.extra` when composing through
+ * `createIntegrationServices`; the adopter's own language module goes after
+ * it either way.
+ *
+ * `createServerLanguageModule` MUST be merged before this one — the
+ * lsp-server head only contributes LSP-textual-specific slots and
+ * relies on `@hydranium/core`'s references / naming bindings being present.
+ */
+export function createLspServerLanguageModule(
+   _context: ServerModuleContext
+): Module<LspServerLanguageServices, PartialLangiumServices & LspServerAddedServices> {
+   return {
+      lsp: {
+         CompletionProvider: services => new HydraniumCompletionProvider(services)
+      }
+   };
+}