@hydranium/core 1.0.0-next.10

package/lib/lsp/hydranium-document-update-handler.d.ts

@@ -0,0 +1,204 @@
+/********************************************************************************
+ * 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 } 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 { 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 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 declare const HYDRANIUM_BUILD_REASONS: Readonly<{
+    readonly didOpen: "didOpen";
+    readonly didChangeContent: "didChangeContent";
+    readonly didChangeWatchedFiles: "didChangeWatchedFiles";
+    readonly didClose: "didClose";
+}>;
+/**
+ * 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 declare 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.
+     */
+    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: Map<string, URI>;
+    protected pendingDeleted: 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: boolean;
+    /**
+     * 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);
+    didOpenDocument(_change: TextDocumentChangeEvent<TextDocument>): void;
+    didChangeContent(change: TextDocumentChangeEvent<TextDocument>): void;
+    /**
+     * 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;
+    didChangeWatchedFiles(params: DidChangeWatchedFilesParams): void;
+    /**
+     * 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 filterSelfSaves(params: DidChangeWatchedFilesParams): Promise<DidChangeWatchedFilesParams>;
+    /**
+     * 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 fireDocumentUpdate(changed: URI[], deleted: URI[]): void;
+    /**
+     * 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.
+     */
+    flushPending(): void;
+    /**
+     * 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;
+}
+//# sourceMappingURL=hydranium-document-update-handler.d.ts.map

package/lib/lsp/hydranium-document-update-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-document-update-handler.d.ts","sourceRoot":"","sources":["../../src/lsp/hydranium-document-update-handler.ts"],"names":[],"mappings":"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"}

package/lib/lsp/hydranium-document-update-handler.js

@@ -0,0 +1,288 @@
+/********************************************************************************
+ * 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, ObservableValue } from '@hydranium/protocol';
+import { URI, UriUtils } from '@hydranium/langium';
+import { DefaultDocumentUpdateHandler } from '@hydranium/langium/lsp';
+import { LANGUAGE_CLIENT_ID } from '../documents/client-ids.js';
+import { FileChangeType } from 'vscode-languageserver';
+/**
+ * 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'
+});
+/**
+ * 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 {
+    logger;
+    selfSaveRegistry;
+    fileSystemProvider;
+    textDocuments;
+    /** Live debounce window — a constant or a setting-bound cell; read `.value` per flush. */
+    debounce;
+    bypassNonLanguageClientChanges;
+    /** Accumulated changed / deleted URIs awaiting the next debounced flush. Keyed by URI string so duplicates merge. */
+    pendingChanged = new Map();
+    pendingDeleted = new Map();
+    /** Trailing-edge timing for the coalesced flush; the pending sets above are the payload it drains. */
+    flushDebouncer;
+    /** Flush on the next `fireDocumentUpdate` instead of debouncing — set by the LSP event handlers when the source isn't typing. */
+    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.
+     */
+    nextReason;
+    /**
+     * 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).
+     */
+    pendingReason;
+    constructor(services, options = {}) {
+        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) {
+        // 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;
+    }
+    didChangeContent(change) {
+        // `??=` 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) {
+        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], []);
+    }
+    didChangeWatchedFiles(params) {
+        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.
+     */
+    async filterSelfSaves(params) {
+        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 !== 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.
+     */
+    fireDocumentUpdate(changed, deleted) {
+        // 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.
+     */
+    flushPending() {
+        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.
+     */
+    dispatch(changed, deleted) {
+        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}`);
+        });
+    }
+}
+//# sourceMappingURL=hydranium-document-update-handler.js.map

package/lib/lsp/hydranium-document-update-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-document-update-handler.js","sourceRoot":"","sources":["../../src/lsp/hydranium-document-update-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,SAAS,EAAe,eAAe,EAA6B,MAAM,qBAAqB,CAAC;AACzG,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAIhE,OAAO,EAAoD,cAAc,EAAgC,MAAM,uBAAuB,CAAC;AAGvI;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,CAAC;IAClD,OAAO,EAAE,SAAS;IAClB,gBAAgB,EAAE,kBAAkB;IACpC,qBAAqB,EAAE,uBAAuB;IAC9C,QAAQ,EAAE,UAAU;CACb,CAAC,CAAC;AA4BZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,8BAA+B,SAAQ,4BAA4B;IAQ1D,MAAM,CAAS;IACf,gBAAgB,CAAmB;IACnC,kBAAkB,CAA6B;IAC/C,aAAa,CAAuC;IAEvE,0FAA0F;IACvE,QAAQ,CAA0B;IAClC,8BAA8B,CAAU;IAE3D,qHAAqH;IAC3G,cAAc,GAAG,IAAI,GAAG,EAAe,CAAC;IACxC,cAAc,GAAG,IAAI,GAAG,EAAe,CAAC;IAClD,sGAAsG;IACnF,cAAc,CAAY;IAC7C,iIAAiI;IACvH,cAAc,GAAG,KAAK,CAAC;IAEjC;;;;;;OAMG;IACO,UAAU,CAAU;IAC9B;;;;;OAKG;IACO,aAAa,CAAU;IAEjC,YAAY,QAA8B,EAAE,UAAiD,EAAE;QAC5F,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC,SAAS,CAAC,gBAAgB,CAAC;QAC5D,IAAI,CAAC,kBAAkB,GAAG,QAAQ,CAAC,SAAS,CAAC,kBAAkB,CAAC;QAChE,IAAI,CAAC,aAAa,GAAG,QAAQ,CAAC,SAAS,CAAC,aAAa,CAAC;QACtD,IAAI,CAAC,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;QAC9D,IAAI,CAAC,cAAc,GAAG,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC3G,IAAI,CAAC,8BAA8B,GAAG,OAAO,CAAC,8BAA8B,IAAI,IAAI,CAAC;IACxF,CAAC;IAED,eAAe,CAAC,OAA8C;QAC3D,wEAAwE;QACxE,8DAA8D;QAC9D,sEAAsE;QACtE,mEAAmE;QACnE,qCAAqC;QACrC,IAAI,CAAC,UAAU,GAAG,uBAAuB,CAAC,OAAO,CAAC;QAClD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;IAC9B,CAAC;IAEQ,gBAAgB,CAAC,MAA6C;QACpE,mEAAmE;QACnE,yDAAyD;QACzD,IAAI,CAAC,UAAU,KAAK,uBAAuB,CAAC,gBAAgB,CAAC;QAC7D,gFAAgF;QAChF,gFAAgF;QAChF,IAAI,IAAI,CAAC,8BAA8B,IAAI,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,kBAAkB,EAAE,CAAC;YACnH,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC9B,CAAC;QACD,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,gBAAgB,CAAC,MAA6C;QAC3D,IAAI,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7D,OAAO;QACV,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACzB,OAAO;QACV,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,uBAAuB,CAAC,QAAQ,CAAC;QACnD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IACtC,CAAC;IAEQ,qBAAqB,CAAC,MAAmC;QAC/D,KAAK,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;aAC7B,IAAI,CAAC,QAAQ,CAAC,EAAE;YACd,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACjC,OAAO;YACV,CAAC;YACD,iEAAiE;YACjE,oEAAoE;YACpE,mEAAmE;YACnE,6DAA6D;YAC7D,IAAI,CAAC,UAAU,GAAG,uBAAuB,CAAC,qBAAqB,CAAC;YAChE,uEAAuE;YACvE,uDAAuD;YACvD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;YAC3B,KAAK,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,CAAC,EAAE;YACV,wDAAwD;YACxD,oEAAoE;YACpE,iEAAiE;YACjE,gEAAgE;YAChE,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/E,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;QAC3E,CAAC,CAAC,CAAC;IACT,CAAC;IAED;;;;;;;OAOG;IACO,KAAK,CAAC,eAAe,CAAC,MAAmC;QAChE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAC3B,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAC,MAAM,EAAC,EAAE;YAC/B,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC,OAAO,EAAE,CAAC;gBAC1C,OAAO,MAAM,CAAC;YACjB,CAAC;YACD,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;YAC7D,IAAI,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;gBAC/E,OAAO,SAAS,CAAC;YACpB,CAAC;YACD,OAAO,MAAM,CAAC;QACjB,CAAC,CAAC,CACJ,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,EAAuB,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,EAAE,CAAC;IAC1F,CAAC;IAED;;;;;;;OAOG;IACgB,kBAAkB,CAAC,OAAc,EAAE,OAAc;QACjE,qEAAqE;QACrE,+DAA+D;QAC/D,mEAAmE;QACnE,kEAAkE;QAClE,kEAAkE;QAClE,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,aAAa,CAAC;QAC3D,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YACzB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,CAAC;QAChD,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;YAC5B,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,uCAAuC;YAC5D,OAAO;QACV,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACI,YAAY;QAChB,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC;QACzD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC5B,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChD,OAAO;QACV,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;;;;OAUG;IACO,QAAQ,CAAC,OAAc,EAAE,OAAc;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC;QAClC,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;QAC/B,IAAI,CAAC,gBAAgB,CAAC,KAAK;aACvB,IAAI,CAAC,GAAG,EAAE,CACR,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;YAC9B,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YAC5C,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QAC/D,CAAC,CAAC,CACJ;aACA,KAAK,CAAC,GAAG,CAAC,EAAE;YACV,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/E,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uEAAuE,MAAM,EAAE,CAAC,CAAC;QACtG,CAAC,CAAC,CAAC;IACT,CAAC;CACH"}

package/lib/lsp/index.d.ts

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+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';
+//# sourceMappingURL=index.d.ts.map

package/lib/lsp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lsp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,+CAA+C,CAAC;AAC9D,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wCAAwC,CAAC;AAEvD;;;;;;GAMG;AACH,cAAc,4BAA4B,CAAC"}

package/lib/lsp/index.js

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+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';
+//# sourceMappingURL=index.js.map

package/lib/lsp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lsp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,+CAA+C,CAAC;AAC9D,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wCAAwC,CAAC;AAEvD;;;;;;GAMG;AACH,cAAc,4BAA4B,CAAC"}

package/lib/lsp/instrument-connection.d.ts

@@ -0,0 +1,36 @@
+/********************************************************************************
+ * 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';
+/**
+ * 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 declare function instrumentLspConnection<C extends object>(connection: C, latency: LatencyCollector | undefined): C;
+//# sourceMappingURL=instrument-connection.d.ts.map

package/lib/lsp/instrument-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument-connection.d.ts","sourceRoot":"","sources":["../../src/lsp/instrument-connection.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAI5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,CAAC,CA2BjH"}