@hydranium/core 1.0.0-next.39 → 1.0.0-next.391

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,79 @@ 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;
+    /** Writes queued and not yet started. */
+    queuedWrites = 0;
+    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 to `write` or `cancelWrite` came while a write was still
+     * queued or running. 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. A different number read after the caller's write ended
+     * does not prove that write was cancelled, since a later write that
+     * cancels another queued or running write counts too. A caller that
+     * retries on it builds once more than it needs to.
+     */
+    get writeCancellations() {
+        return this.cancelledWriteCount;
+    }
     write(action) {
-        return super.write(token => runInWriteLockScope(() => action(token)));
+        const queued = super.write(token => {
+            this.queuedWrites--;
+            return runInWriteLockScope(() => this.runWrite(action, token));
+        });
+        // Counted after Langium's `write` has cancelled the write before it, so the new write does not count itself.
+        this.queuedWrites++;
+        return queued;
+    }
+    /** 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 that has ended is not counted, so the
+     * next write does not count as cancelling it. A write running when this is
+     * called has been cancelled, by this call or an earlier one, so its timer
+     * starts here.
+     */
+    cancelWrite() {
+        if (this.queuedWrites > 0 || this.runningWrite !== undefined) {
+            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;IACtC,yCAAyC;IAC/B,YAAY,GAAG,CAAC,CAAC;IAE3B,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;;;;;;;;;;OAUG;IACH,IAAI,kBAAkB;QACnB,OAAO,IAAI,CAAC,mBAAmB,CAAC;IACnC,CAAC;IAEQ,KAAK,CAAC,MAAwD;QACpE,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;YAChC,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,OAAO,mBAAmB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;QACH,6GAA6G;QAC7G,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC;IACjB,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;;;;;;OAMG;IACM,WAAW;QACjB,IAAI,IAAI,CAAC,YAAY,GAAG,CAAC,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YAC5D,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC9B,CAAC;QACD,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,9 @@ 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. A project manager that defers
+ * the relink emits them from a follow-up build of its own instead.
  *
  * Descriptor URIs that triggered the cycle are intentionally excluded
  * from the affected set by `AbstractProjectManager.onBuildUpdate` —
@@ -121,7 +133,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 +155,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 +271,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.
      */
@@ -226,13 +303,20 @@ 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. Under the project manager's
+     * `deferMemberRelink`, its follow-up build emits the members instead.
      *
      * 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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"}

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

@@ -6,12 +6,14 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { Deferred } from '@hydranium/protocol';
-import { DefaultWorkspaceManager, DocumentState, UriUtils } from '@hydranium/langium';
+import { Deferred, describeError, describeErrorWithStack } from '@hydranium/protocol';
+import { DefaultWorkspaceManager, DocumentState, interruptAndCheck, isOperationCancelled, UriUtils } from '@hydranium/langium';
+import { CancellationTokenSource } from 'vscode-languageserver';
 import { resolveLogFilePlaceholder, toLogFileWorkspaceToken } from '../diagnostics/logger.js';
 import { findRealpathDivergence } from './document-uri-policy.js';
 import { collectAdditionalDocuments } from './additional-document-contribution.js';
 import { onProcessEvent } from '../../util/environment.js';
+import { isConnectionGoneError } from '../../util/connection-liveness.js';
 /**
  * Module-level guard so repeated workspace-manager construction (e.g.
  * test environments creating multiple instances across files) doesn't
@@ -26,6 +28,12 @@ let operationCancelledSuppressionInstalled = false;
  * every later tree's genuine rejections to a logger nobody is reading.
  */
 let operationCancelledSuppressionLogger;
+/**
+ * Never cancelled: `interruptAndCheck` yields only for a token other than
+ * `CancellationToken.None`, and the load must not stop part-way, since Langium
+ * checks for cancellation once every document exists.
+ */
+const LOAD_YIELD_TOKEN = new CancellationTokenSource().token;
 /**
  * Decide what to do with a process-level unhandled promise rejection.
  *
@@ -49,7 +57,7 @@ export function handleProcessUnhandledRejection(reason, logger) {
     if (typeof reason === 'symbol' && String(reason) === 'Symbol(OperationCancelled)') {
         return;
     }
-    logger.error('Unhandled promise rejection: ' + (reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)));
+    logger.error('Unhandled promise rejection: ' + describeErrorWithStack(reason));
 }
 /**
  * Install a process-level `unhandledRejection` listener that routes every
@@ -112,8 +120,9 @@ export function installOperationCancelledSuppression(logger) {
  * 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. A project manager that defers
+ * the relink emits them from a follow-up build of its own instead.
  *
  * Descriptor URIs that triggered the cycle are intentionally excluded
  * from the affected set by `AbstractProjectManager.onBuildUpdate` —
@@ -147,6 +156,12 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
     additionalDocuments;
     /** Registry consulted by {@link warnIfUnroutable} to check a seeded document routes. */
     languageRegistry;
+    /** Whether startup runs {@link warnIfDocumentsUnserved}. */
+    warnUnservedDocuments;
+    /** URIs of the documents the running startup's file traversal loaded; see {@link loadWorkspaceDocuments}. */
+    traversedUris = new Set();
+    /** How many documents {@link loadWorkspaceDocuments} reads and parses before it may yield; below 1 counts as 1. */
+    loadChunkSize = 10;
     constructor(services, options = {}) {
         super(services);
         this.projectManager = services.workspace.ProjectManager;
@@ -156,6 +171,7 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
         this.writableFileSystemProvider = services.workspace.FileSystemProvider;
         this.additionalDocuments = services.additionalDocuments;
         this.languageRegistry = services.ServiceRegistry;
+        this.warnUnservedDocuments = options.warnUnservedDocuments ?? true;
         this.tracer = services.Tracer.for(options.logName ?? 'WorkspaceManager').trace('instantiated');
         installOperationCancelledSuppression(this.tracer);
     }
@@ -180,31 +196,32 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
         // seeded. `tags` is read at the done-emit, so the document count pushed
         // inside the callback appears in the log line.
         const tags = [`${contributions.length} contributions`];
-        let documentCount = 0;
+        const seeded = [];
         await this.tracer.time('Load additional documents', async () => {
             await collectAdditionalDocuments(this.additionalDocuments, folders, document => {
-                documentCount++;
+                seeded.push(document);
                 this.warnIfUnroutable(document);
                 collector(document);
             });
-            tags.push(`${documentCount} documents`);
+            tags.push(`${seeded.length} documents`);
         }, 'info', { logAfterMs: 0, tags });
     }
     /**
      * 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>')`.
      */
@@ -213,15 +230,14 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
             return;
         }
         const extensions = this.languageRegistry.all.flatMap(language => language.LanguageMetaData.fileExtensions);
-        this.tracer.warn(`Additional document '${document.uri.toString()}' matches no registered language, so every per-language ` +
-            'service (scope computation, naming, validation, serialization) will fail to route to it and it will ' +
-            `contribute nothing to scopes. End its URI with a registered file extension (${extensions.join(', ')}); ` +
+        this.tracer.warn(`Additional document '${document.uri.toString()}' matches no registered language, so the workspace ` +
+            `cannot load it and the startup build fails. End its URI with a registered file extension (${extensions.join(', ')}); ` +
             'for a virtual document that means passing it as the last segment, `virtualUri(contributor, "name.<ext>")`.');
     }
     async performStartup(folders) {
-        // Resolve the `{workspace}` file-tee placeholder (if configured) as early
-        // as possible — before any build logging — so per-workspace log capture
-        // names its file correctly and the buffered startup lines flush.
+        // Supply the `{workspace}` placeholder as early as possible — before any
+        // build logging — so per-workspace log capture names its file correctly
+        // and the buffered startup lines flush; the CPU profile reads it too.
         this.resolveWorkspaceLogTarget(folders);
         // Snapshot the document set around discovery so the descriptor documents
         // it creates can be identified afterwards. Plain iteration rather than
@@ -242,10 +258,131 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
                 discovered.push(document);
             }
         }
-        const documents = await super.performStartup(folders);
+        this.traversedUris.clear();
+        let documents;
+        try {
+            documents = await super.performStartup(folders);
+            if (this.warnUnservedDocuments) {
+                await this.warnIfDocumentsUnserved(documents.filter(document => !this.traversedUris.has(document.uri.toString())));
+            }
+        }
+        finally {
+            this.traversedUris.clear();
+        }
         this.probePathDivergence(folders);
         return this.withDiscoveredDescriptors(documents, discovered);
     }
+    /**
+     * 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.
+     */
+    async loadWorkspaceDocuments(uris, collector) {
+        const pending = uris.toArray();
+        const chunkSize = Math.max(1, this.loadChunkSize);
+        for (let i = 0; i < pending.length; i += chunkSize) {
+            if (i > 0) {
+                await interruptAndCheck(LOAD_YIELD_TOKEN);
+            }
+            await Promise.all(pending.slice(i, i + chunkSize).map(async (uri) => {
+                const document = await this.loadTraversedDocument(uri);
+                if (document) {
+                    this.traversedUris.add(document.uri.toString());
+                    collector(document);
+                }
+            }));
+        }
+    }
+    /**
+     * 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.
+     */
+    async loadTraversedDocument(uri) {
+        try {
+            return await this.langiumDocuments.getOrCreateDocument(uri);
+        }
+        catch (error) {
+            if (isOperationCancelled(error)) {
+                throw error;
+            }
+            const fileSystem = this.writableFileSystemProvider;
+            if (!(await (fileSystem.existsSettled?.(uri) ?? fileSystem.exists(uri)).catch(() => true))) {
+                this.tracer.debug(`Skipped ${uri.toString()}: it was removed between the workspace scan and its load`);
+                return undefined;
+            }
+            return this.langiumDocuments.getOrCreateDocument(uri);
+        }
+    }
+    /**
+     * 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`.
+     */
+    async warnIfDocumentsUnserved(documents) {
+        const unserved = [];
+        for (const document of documents) {
+            let served = false;
+            try {
+                served = await this.writableFileSystemProvider.exists(document.uri);
+            }
+            catch {
+                // Counted as unserved, below.
+            }
+            if (!served) {
+                unserved.push(document.uri);
+            }
+        }
+        if (unserved.length === 0) {
+            return;
+        }
+        const schemes = [...new Set(unserved.map(uri => uri.scheme))];
+        const named = unserved.slice(0, 3).map(uri => uri.toString());
+        this.tracer.warn(`${unserved.length} seeded document(s) under ${schemes.map(scheme => `${scheme}:`).join(', ')} cannot be served by the bound workspace.FileSystemProvider ` +
+            `(${named.join(', ')}${unserved.length > 3 ? ', …' : ''}), so each leaves the workspace at its ` +
+            `last close. Register a provider under the key ${schemes.map(scheme => `'${scheme}'`).join(', ')} in the shared ` +
+            'fileSystemProviders group, or serve the scheme from the host provider; set warnUnservedDocuments: false ' +
+            'to accept the loss.');
+    }
     /**
      * Add back the documents project discovery created that Langium's file
      * traversal then filtered out.
@@ -316,9 +453,10 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
         }
     }
     /**
-     * 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.
      */
@@ -360,6 +498,12 @@ export 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.
      */
     async initializeWorkspace(folders, cancelToken) {
         try {
@@ -367,15 +511,26 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
             this.workspaceInitializedDeferred.resolve(undefined);
         }
         catch (error) {
+            if (isOperationCancelled(error) || isConnectionGoneError(error)) {
+                this.tracer.debug(`Initial workspace build did not complete: ${describeError(error)}`);
+            }
+            else {
+                this.tracer.error(`Initial workspace build failed: ${describeErrorWithStack(error)}`);
+            }
             this.workspaceInitializedDeferred.reject(error);
+            // Langium settles `ready` only after a startup that succeeded. Marked
+            // handled, as logged above; a no-op once startup has resolved it.
+            this._ready.reject(error);
+            this._ready.promise.catch(() => undefined);
             throw error;
         }
     }
     /**
      * 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. Under the project manager's
+     * `deferMemberRelink`, its follow-up build emits the members instead.
      *
      * Subclasses can override for additional behaviour (e.g. logging,
      * telemetry, custom rebuild policies); call `super` to preserve the