@hydranium/core 1.0.0-next.32 → 1.0.0-next.321

package/lib/langium/workspace/hydranium-workspace-lock.d.ts

@@ -6,8 +6,25 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
+import { type Clock, type Tracer } from '@hydranium/protocol';
 import { DefaultWorkspaceLock, type MaybePromise } from '@hydranium/langium';
-import { type CancellationToken } from 'vscode-languageserver-protocol';
+import { type CancellationToken, type Disposable } from 'vscode-languageserver-protocol';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+/** Constructor options for {@link HydraniumWorkspaceLock}. */
+export interface HydraniumWorkspaceLockOptions extends LogNameOptions {
+    /**
+     * How long a write may keep running after a later write cancelled it before
+     * the lock logs a warning. Every write and read waits behind it meanwhile, so
+     * one that never ends stops the server. Defaults to 10 s; `0` turns the
+     * check off.
+     */
+    readonly stalledWriteWarnMs?: number;
+}
+/** The write action a {@link HydraniumWorkspaceLock} is running, with the timer its cancellation started. */
+export interface RunningWrite {
+    stallTimer?: Disposable;
+}
 /**
  * Langium's {@link DefaultWorkspaceLock} with the write action marked as a
  * write-lock scope, so anything it reaches can be asked whether the lock is
@@ -26,6 +43,31 @@ import { type CancellationToken } from 'vscode-languageserver-protocol';
  * would turn ordinary read-then-write sequences into false positives.
  */
 export declare class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
+    /** Backs {@link writeCancellations}. */
+    protected cancelledWriteCount: number;
+    protected readonly clock: Clock;
+    protected readonly tracer: Tracer;
+    protected readonly stalledWriteWarnMs: number;
+    protected runningWrite?: RunningWrite;
+    constructor(services: Pick<ServerSharedServicesMinimal, 'Clock' | 'Tracer'>, options?: HydraniumWorkspaceLockOptions);
+    /**
+     * How many calls have cancelled the lock's latest write: every `write`,
+     * which cancels the write before it, and every `cancelWrite`. A caller that
+     * reads this right after queuing a write, and reads the same number later,
+     * holds a write nothing has cancelled, whether it is still queued or
+     * already running. Its token answers that only once the write runs, since
+     * a queued write has not been handed it yet.
+     */
+    get writeCancellations(): number;
     write(action: (token: CancellationToken) => MaybePromise<void>): Promise<void>;
+    /** Run `action` as {@link runningWrite}, so a cancellation while it runs can time it. */
+    protected runWrite(action: (token: CancellationToken) => MaybePromise<void>, token: CancellationToken): Promise<void>;
+    /**
+     * Counted here rather than in {@link write}, because Langium's `write` cancels
+     * through this method too. A write running when this is called has been
+     * cancelled, by this call or an earlier one, so its timer starts here.
+     */
+    cancelWrite(): void;
+    protected reportStalledWrite(): void;
 }
 //# sourceMappingURL=hydranium-workspace-lock.d.ts.map

package/lib/langium/workspace/hydranium-workspace-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydranium-workspace-lock.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-workspace-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAuB,SAAQ,oBAAoB;IACpD,KAAK,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzF"}
+{"version":3,"file":"hydranium-workspace-lock.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-workspace-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACzF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAGzE,8DAA8D;AAC9D,MAAM,WAAW,6BAA8B,SAAQ,cAAc;IAClE;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACvC;AAID,6GAA6G;AAC7G,MAAM,WAAW,YAAY;IAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAuB,SAAQ,oBAAoB;IAC7D,wCAAwC;IACxC,SAAS,CAAC,mBAAmB,SAAK;IAClC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAChC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAC9C,SAAS,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IAEtC,YAAY,QAAQ,EAAE,IAAI,CAAC,2BAA2B,EAAE,OAAO,GAAG,QAAQ,CAAC,EAAE,OAAO,GAAE,6BAAkC,EAKvH;IAED;;;;;;;OAOG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAEQ,KAAK,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;IAED,yFAAyF;IACzF,UAAgB,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW1H;IAED;;;;OAIG;IACM,WAAW,IAAI,IAAI,CAO3B;IAED,SAAS,CAAC,kBAAkB,IAAI,IAAI,CAOnC;CACH"}

package/lib/langium/workspace/hydranium-workspace-lock.js

@@ -8,6 +8,7 @@
  ********************************************************************************/
 import { DefaultWorkspaceLock } from '@hydranium/langium';
 import { runInWriteLockScope } from './write-lock-scope.js';
+const DEFAULT_STALLED_WRITE_WARN_MS = 10_000;
 /**
  * Langium's {@link DefaultWorkspaceLock} with the write action marked as a
  * write-lock scope, so anything it reaches can be asked whether the lock is
@@ -26,8 +27,64 @@ import { runInWriteLockScope } from './write-lock-scope.js';
  * would turn ordinary read-then-write sequences into false positives.
  */
 export class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
+    /** Backs {@link writeCancellations}. */
+    cancelledWriteCount = 0;
+    clock;
+    tracer;
+    stalledWriteWarnMs;
+    runningWrite;
+    constructor(services, options = {}) {
+        super();
+        this.clock = services.Clock;
+        this.tracer = services.Tracer.for(options.logName ?? 'WorkspaceLock');
+        this.stalledWriteWarnMs = options.stalledWriteWarnMs ?? DEFAULT_STALLED_WRITE_WARN_MS;
+    }
+    /**
+     * How many calls have cancelled the lock's latest write: every `write`,
+     * which cancels the write before it, and every `cancelWrite`. A caller that
+     * reads this right after queuing a write, and reads the same number later,
+     * holds a write nothing has cancelled, whether it is still queued or
+     * already running. Its token answers that only once the write runs, since
+     * a queued write has not been handed it yet.
+     */
+    get writeCancellations() {
+        return this.cancelledWriteCount;
+    }
     write(action) {
-        return super.write(token => runInWriteLockScope(() => action(token)));
+        return super.write(token => runInWriteLockScope(() => this.runWrite(action, token)));
+    }
+    /** Run `action` as {@link runningWrite}, so a cancellation while it runs can time it. */
+    async runWrite(action, token) {
+        const running = {};
+        this.runningWrite = running;
+        try {
+            await action(token);
+        }
+        finally {
+            running.stallTimer?.dispose();
+            if (this.runningWrite === running) {
+                this.runningWrite = undefined;
+            }
+        }
+    }
+    /**
+     * Counted here rather than in {@link write}, because Langium's `write` cancels
+     * through this method too. A write running when this is called has been
+     * cancelled, by this call or an earlier one, so its timer starts here.
+     */
+    cancelWrite() {
+        this.cancelledWriteCount++;
+        const running = this.runningWrite;
+        if (running && !running.stallTimer && this.stalledWriteWarnMs > 0) {
+            running.stallTimer = this.clock.setTimer(() => this.reportStalledWrite(), this.stalledWriteWarnMs);
+        }
+        super.cancelWrite();
+    }
+    reportStalledWrite() {
+        this.tracer.warn(`A write is still running ${this.stalledWriteWarnMs} ms after it was cancelled, and every write and read waits behind it. ` +
+            'Likely causes: a model-service write or rebuild from inside a build in a host with no write-lock scope tracker, ' +
+            'which waits for the build it runs in, or a write action that ignores its cancellation token. ' +
+            'See https://github.com/eclipse-emfcloud/hydranium/issues/245.');
     }
 }
 //# sourceMappingURL=hydranium-workspace-lock.js.map

package/lib/langium/workspace/hydranium-workspace-lock.js.map

@@ -1 +1 @@
-{"version":3,"file":"hydranium-workspace-lock.js","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-workspace-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,oBAAoB,EAAqB,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,sBAAuB,SAAQ,oBAAoB;IACpD,KAAK,CAAC,MAAwD;QACpE,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzE,CAAC;CACH"}
+{"version":3,"file":"hydranium-workspace-lock.js","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-workspace-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAE,oBAAoB,EAAqB,MAAM,oBAAoB,CAAC;AAI7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAa5D,MAAM,6BAA6B,GAAG,MAAM,CAAC;AAO7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,sBAAuB,SAAQ,oBAAoB;IAC7D,wCAAwC;IAC9B,mBAAmB,GAAG,CAAC,CAAC;IACf,KAAK,CAAQ;IACb,MAAM,CAAS;IACf,kBAAkB,CAAS;IACpC,YAAY,CAAgB;IAEtC,YAAY,QAA+D,EAAE,OAAO,GAAkC,EAAE;QACrH,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC;QACtE,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,IAAI,6BAA6B,CAAC;IACzF,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,kBAAkB;QACnB,OAAO,IAAI,CAAC,mBAAmB,CAAC;IACnC,CAAC;IAEQ,KAAK,CAAC,MAAwD;QACpE,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,yFAAyF;IAC/E,KAAK,CAAC,QAAQ,CAAC,MAAwD,EAAE,KAAwB;QACxG,MAAM,OAAO,GAAiB,EAAE,CAAC;QACjC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;QAC5B,IAAI,CAAC;YACF,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;gBAAS,CAAC;YACR,OAAO,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC;YAC9B,IAAI,IAAI,CAAC,YAAY,KAAK,OAAO,EAAE,CAAC;gBACjC,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;YACjC,CAAC;QACJ,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACM,WAAW;QACjB,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC;QAClC,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,kBAAkB,GAAG,CAAC,EAAE,CAAC;YACjE,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACtG,CAAC;QACD,KAAK,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;IAES,kBAAkB;QACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CACb,4BAA4B,IAAI,CAAC,kBAAkB,wEAAwE;YACxH,kHAAkH;YAClH,+FAA+F;YAC/F,+DAA+D,CACpE,CAAC;IACL,CAAC;CACH"}

package/lib/langium/workspace/hydranium-workspace-manager.d.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { Deferred, type Logger, type Tracer } from '@hydranium/protocol';
-import { DefaultWorkspaceManager, type LangiumDocument, type URI } from '@hydranium/langium';
+import { DefaultWorkspaceManager, type LangiumDocument, type Stream, type URI } from '@hydranium/langium';
 import { type CancellationToken, type InitializeParams } from 'vscode-languageserver';
 import type { WorkspaceFolder } from 'vscode-languageserver-types';
 import { type LogNameOptions } from '../diagnostics/logger.js';
@@ -15,7 +15,7 @@ import type { ServerLocale } from '../../locale/server-locale.js';
 import type { ProjectChangeEvent } from '../project/project-change-event.js';
 import type { ProjectManager } from '../project/project-manager.js';
 import type { ServerSharedServicesMinimal } from '../shared-services.js';
-import type { WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import type { WritableFileSystemProvider } from './file-system-provider.js';
 import { type DocumentUriPolicy } from './document-uri-policy.js';
 import { type AdditionalDocumentContribution } from './additional-document-contribution.js';
 /**
@@ -54,6 +54,17 @@ export declare function handleProcessUnhandledRejection(reason: unknown, logger:
  * Applies to every Langium-based server that experiences concurrent builds.
  */
 export declare function installOperationCancelledSuppression(logger: Logger): void;
+/** Options for {@link HydraniumWorkspaceManager}. */
+export interface HydraniumWorkspaceManagerOptions extends LogNameOptions {
+    /**
+     * Whether startup warns about seeded documents the bound
+     * `FileSystemProvider` cannot serve (see
+     * {@link HydraniumWorkspaceManager.warnIfDocumentsUnserved}). Defaults to
+     * `true`; turn it off for a host that drops such documents at their last
+     * close on purpose.
+     */
+    warnUnservedDocuments?: boolean;
+}
 /**
  * Framework {@link DefaultWorkspaceManager} subclass that integrates the
  * project tier with Langium's workspace startup.
@@ -86,8 +97,8 @@ export declare function installOperationCancelledSuppression(logger: Logger): vo
  * URIs (its own members plus any transitive dependents per the
  * `getAffectedProjects` hook). This manager re-runs
  * `DocumentBuilder.resetToState(doc, DocumentState.Changed)` on each
- * affected document so the next build cycle re-links them with the new
- * visibility scope.
+ * affected document so the build of the update that changed the descriptor
+ * re-links them with the new visibility scope.
  *
  * Descriptor URIs that triggered the cycle are intentionally excluded
  * from the affected set by `AbstractProjectManager.onBuildUpdate` —
@@ -121,7 +132,13 @@ export declare class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
     protected readonly additionalDocuments: Record<string, AdditionalDocumentContribution>;
     /** Registry consulted by {@link warnIfUnroutable} to check a seeded document routes. */
     protected readonly languageRegistry: ServerSharedServicesMinimal['ServiceRegistry'];
-    constructor(services: ServerSharedServicesMinimal, options?: LogNameOptions);
+    /** Whether startup runs {@link warnIfDocumentsUnserved}. */
+    protected readonly warnUnservedDocuments: boolean;
+    /** URIs of the documents the running startup's file traversal loaded; see {@link loadWorkspaceDocuments}. */
+    protected readonly traversedUris: Set<string>;
+    /** How many documents {@link loadWorkspaceDocuments} reads and parses before it may yield; below 1 counts as 1. */
+    protected readonly loadChunkSize: number;
+    constructor(services: ServerSharedServicesMinimal, options?: HydraniumWorkspaceManagerOptions);
     /**
      * Contribution form of Langium's `loadAdditionalDocuments`. Runs the base
      * behaviour first (a no-op unless a further subclass adds documents), then
@@ -137,22 +154,80 @@ export declare class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
      * Warn when a seeded additional document's URI matches no registered
      * language.
      *
-     * Such a document is added to the workspace and indexed, but every
-     * per-language service is resolved per URI — so scope computation, naming,
-     * validation and serialisation all fail to route to it, and it contributes
-     * nothing to the scopes it was written to populate. Nothing else reports
-     * this: the document exists, so no lookup errors, it is simply inert.
+     * Every per-language service is resolved per URI, so the workspace cannot
+     * load such a document: adding it throws, and the startup build fails
+     * with an error naming only the extension, not the document. This
+     * line names the document and the fix first.
      *
-     * The usual cause is a `virtualUri` with no file extension:
-     * `virtualUri(contributor)` yields `virtual:<contributor>`, and routing has
-     * nothing to match on — there is no extension, and a virtual document is
-     * never open in `TextDocuments`, so the declared-languageId rung cannot
-     * serve it either. The convention is to end the URI with a registered
+     * The usual cause is a `fromModel` or `fromStringInLanguage` document
+     * under a `virtualUri` with no file extension: `virtualUri(contributor)`
+     * yields `virtual:<contributor>`, and routing has nothing to match on —
+     * there is no extension, and a virtual document is never open in
+     * `TextDocuments`, so the declared-languageId rung cannot serve it either.
+     * A `fromString` document under such a URI never gets here: its parse
+     * throws first. The convention is to end the URI with a registered
      * extension by passing it as the last segment,
      * `virtualUri(contributor, 'name.<ext>')`.
      */
     protected warnIfUnroutable(document: LangiumDocument): void;
     protected performStartup(folders: WorkspaceFolder[]): Promise<LangiumDocument[]>;
+    /**
+     * Load the documents the file traversal found through
+     * {@link loadTraversedDocument}, {@link loadChunkSize} at a time, yielding
+     * between chunks once Langium's interruption period has passed. Langium's
+     * own load starts every read at once and parses each as it returns: over a
+     * synchronous provider nothing else runs until the last file has parsed, and
+     * over the Node provider incoming messages wait through long runs of parses.
+     * The cost: at most a chunk of reads is in flight, and each chunk waits for
+     * its slowest read, so slow storage takes a round per chunk, not one burst.
+     *
+     * Each loaded document is recorded, so startup can tell them from the
+     * documents `loadAdditionalDocuments` seeded, through the
+     * `additionalDocuments` group or an override of its own.
+     *
+     * The traversal found each of its documents through the provider, so asking
+     * it again whether they exist costs one call per workspace file and cannot
+     * come out false. Telling them apart by scheme does not work either: the
+     * registry's host answers every scheme no other provider claims, a seeded
+     * scheme nobody serves included. An override that loads documents without
+     * delegating here leaves them unrecorded, so startup asks the provider
+     * about each of them.
+     */
+    protected loadWorkspaceDocuments(uris: Stream<URI>, collector: (document: LangiumDocument) => void): Promise<void>;
+    /**
+     * Load one document the file traversal found, or answer `undefined` to
+     * leave it out of the workspace.
+     *
+     * A file whose read fails and that the provider's `existsSettled`, or
+     * `exists` for a provider without it, reports gone is left out with a debug
+     * line, since it went between the scan and the read. A file still there is
+     * read once more, since a replacing rename can hide its name for a moment;
+     * that read's failure, and cancellation, fail the startup. A check that
+     * throws counts the file as there, since it cannot say the file went. The
+     * skip is the startup's only: other callers of `getOrCreateDocument` still
+     * get the read error.
+     */
+    protected loadTraversedDocument(uri: URI): Promise<LangiumDocument | undefined>;
+    /**
+     * Warn once when the bound `FileSystemProvider` cannot serve a seeded
+     * document, naming each such document's scheme.
+     *
+     * The last close keeps a document only if the provider says it `exists`, so
+     * each such document leaves the workspace the first time an editor closes
+     * it, and whatever resolved against it breaks. The framework's registry
+     * serves `virtual:` through the `fileSystemProviders` group and every other
+     * scheme through its host, which knows nothing of a scheme an adopter
+     * invented for its seeded documents, and nothing else reports the loss. A
+     * provider that throws counts as not serving the document, since a startup
+     * that failed on a diagnostic would be worse than the loss.
+     *
+     * Runs over every document startup collected outside the file traversal,
+     * which is what `loadAdditionalDocuments` seeded, through the
+     * `additionalDocuments` group or an override of that method, once startup
+     * has added them to the workspace, unless `warnUnservedDocuments` is
+     * `false`.
+     */
+    protected warnIfDocumentsUnserved(documents: readonly LangiumDocument[]): Promise<void>;
     /**
      * Add back the documents project discovery created that Langium's file
      * traversal then filtered out.
@@ -195,9 +270,10 @@ export declare class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
      */
     protected probePathDivergence(folders: WorkspaceFolder[]): void;
     /**
-     * Resolve the `{workspace}` file-tee placeholder from the first workspace
-     * folder. No-op when no folder is known or no `{workspace}`-templated log
-     * target is configured. See {@link toLogFileWorkspaceToken} for the token
+     * Supply the `{workspace}` placeholder from the first workspace folder, which
+     * the log file-tee and the CPU profile's file name both read, whether or not
+     * a log target is configured. No-op when no folder is known. See
+     * {@link toLogFileWorkspaceToken} for the token
      * derivation — a log-capturing test harness uses the same function so the
      * server's file name and the harness's correlation key agree.
      */
@@ -207,6 +283,16 @@ export declare class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
      * params. `DefaultWorkspaceManager.initialize` reads `workspaceFolders`
      * alone, so `params.locale` would otherwise be discarded — and this is the
      * only place it arrives, which the headless init seams route through too.
+     *
+     * **The ABSENT case is reported from here rather than from `ServerLocale`,
+     * because this is the only end that can see it.** `accept` is not called
+     * when no locale was declared — nor should it be, since `''` is a claim
+     * about a language rather than the absence of one — so a log written there
+     * covers one of the two outcomes and leaves the other looking like a server
+     * that never reached init. Both lines are at `info` for the reason `accept`
+     * gives: the framework ships no catalogue, so an undeclared locale and an
+     * untranslated code produce the same English and the log is what separates
+     * them.
      */
     initialize(params: InitializeParams): void;
     /**
@@ -216,13 +302,19 @@ export declare class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
      * and either delegate to `super.initializeWorkspace(...)` (preserving the
      * default resolve) or call `this.workspaceInitializedDeferred.resolve(...)`
      * themselves after the additional work finishes.
+     *
+     * A failed setup is logged here, since every framework waiter on
+     * {@link workspaceInitialized} discards the rejection; an override that
+     * rejects the deferred itself logs its own failure. A failed startup also
+     * rejects `ready`, so its waiters fail rather than wait forever; an override
+     * that skips `super` and catches a failed startup rejects `_ready` too.
      */
     initializeWorkspace(folders: WorkspaceFolder[], cancelToken?: CancellationToken): Promise<void>;
     /**
      * Default cascade-rebuild handler. Iterates {@link ProjectChangeEvent.affectedDocuments}
-     * and resets each to {@link DocumentState.Changed} so the next build cycle
-     * re-runs the pipeline (parse → link → validate) under the new project
-     * visibility scope.
+     * and resets each to {@link DocumentState.Changed} so the build of the update
+     * that changed the descriptor re-runs the pipeline (parse → link → validate)
+     * under the new project visibility scope.
      *
      * Subclasses can override for additional behaviour (e.g. logging,
      * telemetry, custom rebuild policies); call `super` to preserve the

package/lib/langium/workspace/hydranium-workspace-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydranium-workspace-manager.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-workspace-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hydranium-workspace-manager.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-workspace-manager.ts"],"names":[],"mappings":"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"}