@hydranium/core 1.0.0-next.34 → 1.0.0-next.340

package/src/langium/workspace/hydranium-workspace-manager.ts

@@ -7,19 +7,29 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Deferred, type Logger, type Tracer } from '@hydranium/protocol';
-import { DefaultWorkspaceManager, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
-import { type CancellationToken, type InitializeParams } from 'vscode-languageserver';
+import { Deferred, type Logger, type Tracer, describeError, describeErrorWithStack } from '@hydranium/protocol';
+import {
+   DefaultWorkspaceManager,
+   DocumentState,
+   interruptAndCheck,
+   isOperationCancelled,
+   type LangiumDocument,
+   type Stream,
+   UriUtils,
+   type URI
+} from '@hydranium/langium';
+import { type CancellationToken, CancellationTokenSource, type InitializeParams } from 'vscode-languageserver';
 import type { WorkspaceFolder } from 'vscode-languageserver-types';
 import { type LogNameOptions, resolveLogFilePlaceholder, toLogFileWorkspaceToken } from '../diagnostics/logger.js';
 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, findRealpathDivergence } from './document-uri-policy.js';
 import { type AdditionalDocumentContribution, 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.
@@ -37,6 +47,13 @@ let operationCancelledSuppressionInstalled = false;
  */
 let operationCancelledSuppressionLogger: Logger | undefined;
 
+/**
+ * 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.
  *
@@ -60,7 +77,7 @@ export function handleProcessUnhandledRejection(reason: unknown, logger: 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));
 }
 
 /**
@@ -93,6 +110,18 @@ export 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.
@@ -125,8 +154,8 @@ export function installOperationCancelledSuppression(logger: Logger): void {
  * 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` —
@@ -163,8 +192,14 @@ export 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'];
+   /** 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 = new Set<string>();
+   /** How many documents {@link loadWorkspaceDocuments} reads and parses before it may yield; below 1 counts as 1. */
+   protected readonly loadChunkSize: number = 10;
 
-   constructor(services: ServerSharedServicesMinimal, options: LogNameOptions = {}) {
+   constructor(services: ServerSharedServicesMinimal, options: HydraniumWorkspaceManagerOptions = {}) {
       super(services);
       this.projectManager = services.workspace.ProjectManager;
       this.projectManager.onProjectsChanged(event => this.onProjectsChanged(event));
@@ -173,6 +208,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);
    }
@@ -201,16 +237,16 @@ 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: string[] = [`${contributions.length} contributions`];
-      let documentCount = 0;
+      const seeded: LangiumDocument[] = [];
       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 }
@@ -221,17 +257,18 @@ export 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>')`.
     */
@@ -241,17 +278,16 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       }
       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(', ')}); ` +
+         `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>")`.'
       );
    }
 
    protected override async performStartup(folders: WorkspaceFolder[]): Promise<LangiumDocument[]> {
-      // 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
@@ -272,11 +308,136 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
             discovered.push(document);
          }
       }
-      const documents = await super.performStartup(folders);
+      this.traversedUris.clear();
+      let documents: LangiumDocument[];
+      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.
+    */
+   protected override async loadWorkspaceDocuments(uris: Stream<URI>, collector: (document: LangiumDocument) => void): Promise<void> {
+      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.
+    */
+   protected async loadTraversedDocument(uri: URI): Promise<LangiumDocument | undefined> {
+      try {
+         return await this.langiumDocuments.getOrCreateDocument(uri);
+      } catch (error: unknown) {
+         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`.
+    */
+   protected async warnIfDocumentsUnserved(documents: readonly LangiumDocument[]): Promise<void> {
+      const unserved: URI[] = [];
+      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.
@@ -351,9 +512,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.
     */
@@ -396,22 +558,37 @@ 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.
     */
    override async initializeWorkspace(folders: WorkspaceFolder[], cancelToken?: CancellationToken): Promise<void> {
       try {
          await super.initializeWorkspace(folders, cancelToken);
          this.workspaceInitializedDeferred.resolve(undefined);
-      } catch (error) {
+      } catch (error: unknown) {
+         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.
     *
     * Subclasses can override for additional behaviour (e.g. logging,
     * telemetry, custom rebuild policies); call `super` to preserve the

package/src/langium/workspace/in-memory-file-system-provider.ts

@@ -9,21 +9,46 @@
 
 import { type FileSystemNode, URI } from '@hydranium/langium';
 import { defineMessage, type Tracer } from '@hydranium/protocol';
-import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { type WritableFileSystemProvider } from './file-system-provider.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
-import { serveVirtualDocument } from './virtual-document.js';
+import { notFound } from './file-not-found.js';
 
 /**
- * The browser host's spelling of "the document is not there". Its Node
- * counterpart is `NO_LOADABLE_CONTENT`: this provider has no `realpath`, so the
- * URI policy cannot answer the existence question ahead of the read and the miss
- * surfaces here instead.
+ * A provider's spelling of "the document is not there", raised wherever a read
+ * finds no content — this filesystem, or a URI naming no location a disk-backed
+ * provider can reach. Distinct from `NO_LOADABLE_CONTENT`, which the URI policy
+ * raises when it can settle the question AHEAD of the read; a provider with no
+ * `realpath` cannot, so the miss surfaces here instead.
  */
 export const NO_SUCH_FILE = defineMessage('hydranium/core/no-such-file', 'No such file: {uri}');
 
+/** The same for a node of any kind, so it also covers a directory. */
 export const NO_SUCH_PATH = defineMessage('hydranium/core/no-such-path', 'No such file or directory: {uri}');
 
+/**
+ * A write addressed a URI the provider cannot reach on disk.
+ *
+ * Deliberately not a not-found code: {@link NO_SUCH_FILE} reports something
+ * missing, which a caller may reasonably answer by creating it — exactly the
+ * wrong reading here. The destination is not missing; the URI names no disk
+ * location at all, and no retry makes it one.
+ *
+ * Declared here rather than beside the Node provider that raises it, so the
+ * message catalog stays reachable from the portable `.` entry — the Node
+ * module pulls `node:fs` and is server-only.
+ */
+export const UNSUPPORTED_WRITE = defineMessage(
+   'hydranium/core/unsupported-write',
+   'Cannot write {uri}: the scheme names no location on disk'
+);
+
+/** A delete addressed a URI the provider cannot reach on disk, as {@link UNSUPPORTED_WRITE} a write. */
+export const UNSUPPORTED_DELETE = defineMessage(
+   'hydranium/core/unsupported-delete',
+   'Cannot delete {uri}: the scheme names no location on disk'
+);
+
 /**
  * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
  *
@@ -117,41 +142,47 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       this.files.set(normalize(uri), content);
    }
 
-   /** Remove the file at `uri`. A no-op when nothing is there. */
-   deleteFile(uri: URI): void {
-      this.files.delete(normalize(uri));
+   /** Remove the file at `uri`. A no-op when nothing is there; a directory is refused. */
+   async deleteFile(uri: URI): Promise<void> {
+      const key = normalize(uri);
+      if (this.hasChildren(key)) {
+         throw new Error(`Cannot delete ${uri.toString()}: it is a directory`);
+      }
+      this.files.delete(key);
    }
 
    async writeFile(uri: URI, content: string): Promise<void> {
       this.setFile(uri, content);
    }
 
-   readFile(uri: URI): Promise<string> {
-      return Promise.resolve(this.readFileSync(uri));
+   // `async` on each read whose sync twin can throw, rather than
+   // `Promise.resolve(this.<x>Sync(uri))`. That form evaluates the sync call
+   // FIRST, so a miss throws before `Promise.resolve` is ever reached — and a
+   // synchronous throw escapes the promise chain: `.catch()` never attaches and
+   // `Promise.all` dies while its argument array is still being built, so a
+   // caller reading several URIs cannot handle the miss it asked about.
+   async readFile(uri: URI): Promise<string> {
+      return this.readFileSync(uri);
    }
 
    readFileSync(uri: URI): string {
-      const served = serveVirtualDocument(this.services, uri);
-      if (served !== undefined) {
-         return served;
-      }
       const content = this.files.get(normalize(uri));
       if (content === undefined) {
-         throw new Error(NO_SUCH_FILE.format({ uri: uri.toString() }));
+         throw notFound(NO_SUCH_FILE.format({ uri: uri.toString() }), uri);
       }
       return content;
    }
 
-   readBinary(uri: URI): Promise<Uint8Array> {
-      return Promise.resolve(this.readBinarySync(uri));
+   async readBinary(uri: URI): Promise<Uint8Array> {
+      return this.readBinarySync(uri);
    }
 
    readBinarySync(uri: URI): Uint8Array {
       return new TextEncoder().encode(this.readFileSync(uri));
    }
 
-   stat(uri: URI): Promise<FileSystemNode> {
-      return Promise.resolve(this.statSync(uri));
+   async stat(uri: URI): Promise<FileSystemNode> {
+      return this.statSync(uri);
    }
 
    statSync(uri: URI): FileSystemNode {
@@ -162,7 +193,7 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       if (this.hasChildren(path)) {
          return { isFile: false, isDirectory: true, uri };
       }
-      throw new Error(NO_SUCH_PATH.format({ uri: uri.toString() }));
+      throw notFound(NO_SUCH_PATH.format({ uri: uri.toString() }), uri);
    }
 
    exists(uri: URI): Promise<boolean> {
@@ -239,8 +270,8 @@ function normalize(uri: URI | string): string {
  * services context exactly where a Node host spreads `NodeFileSystem`.
  *
  * A host that needs to reach the provider afterwards — to seed or mutate it
- * mid-test — reads it back off `shared.workspace.FileSystemProvider`, since the
- * slot owns construction.
+ * mid-test — narrows `shared.workspace.FileSystemProvider.host` to this
+ * class, since the slot owns construction.
  */
 export function inMemoryFileSystem(options: InMemoryFileSystemOptions = {}): {
    fileSystemProvider: (services: unknown) => WritableFileSystemProvider;

package/src/langium/workspace/index.ts

@@ -11,6 +11,7 @@ export * from './document-uri-policy.js';
 export * from './file-system-provider.js';
 export * from './in-memory-file-system-provider.js';
 export * from './persistent-file-system-provider.js';
+export * from './self-save-registry.js';
 export * from './index-manager.js';
 export * from './initialize-workspace.js';
 export * from './langium-documents.js';

package/src/langium/workspace/initialize-workspace.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { UriUtils, URI } from '@hydranium/langium';
+import type { Locale } from '@hydranium/protocol';
 // Bare `'path'` (not `node:path`) so a browser bundle can alias it to a POSIX
 // shim — this is the only filesystem-path use left on the portable `.` entry,
 // and it's the headless/CLI string-input convenience of `toWorkspaceFolders`.
@@ -33,8 +34,16 @@ export interface ProgrammaticInitOptions {
     * Omitted means no locale, which the default renderer resolves as the
     * framework's English. That is the correct answer for a headless tool: it
     * has no reading user to have a language.
+    *
+    * **An IETF language tag, hyphenated — `de`, `de-CH`, `zh-Hant-TW` — and
+    * not the POSIX or Java spelling.** An LSP client is held to that syntax by
+    * the protocol, while a headless caller supplies the string itself and the
+    * obvious source is an environment variable holding `de_DE` or
+    * `en_US.UTF-8`. Neither is a tag, and the string is passed through
+    * unchecked, so a renderer that parses it finds nothing to match and every
+    * message renders in English.
     */
-   readonly locale?: string;
+   readonly locale?: Locale;
 }
 
 /**
@@ -72,20 +81,51 @@ function toWorkspaceFolders(folders: WorkspaceFolderInput | ReadonlyArray<Worksp
  * negotiation, `onInitialize`/`onInitialized` events) are intentionally not
  * reproduced — a headless server has no client and they degrade gracefully.
  *
- * Invoke once during headless startup; this is not a re-initialization API.
- * Errors from discovery/build propagate to the caller.
+ * Runs once per workspace manager: a later call naming the same folders, in
+ * any order, gets the first call's promise, and one naming others throws
+ * synchronously. A second initialisation would cancel the first one's build
+ * and leave the documents unbuilt, which happens as soon as a starter and its
+ * caller both bring the workspace up. Errors from discovery/build propagate to
+ * the caller.
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
  * @param options the message locale, when the caller has one
  */
-export async function initializeWorkspaceProgrammatically(
+export function initializeWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
    folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
    options: ProgrammaticInitOptions = {}
 ): Promise<void> {
    const workspaceFolders = toWorkspaceFolders(folders);
    const manager = services.workspace.WorkspaceManager;
+   const key = workspaceFolders
+      .map(folder => folder.uri)
+      .sort()
+      .join('\n');
+   const running = bringUps.get(manager);
+   if (running !== undefined) {
+      if (running.folders !== key) {
+         throw new Error(
+            `[hydranium] the workspace is already initialised from ${running.folders.replace(/\n/g, ', ')}; ` +
+               'every caller on one services tree has to name the same folders.'
+         );
+      }
+      return running.promise;
+   }
+   const promise = initialize(manager, workspaceFolders, options);
+   bringUps.set(manager, { folders: key, promise });
+   return promise;
+}
+
+/** The programmatic initialisation running on each workspace manager, with the folders it names. */
+const bringUps = new WeakMap<object, { readonly folders: string; readonly promise: Promise<void> }>();
+
+async function initialize(
+   manager: ServerSharedServicesMinimal['workspace']['WorkspaceManager'],
+   workspaceFolders: WorkspaceFolder[],
+   options: ProgrammaticInitOptions
+): Promise<void> {
    // `locale` goes through the synthesized params rather than a direct
    // `acceptLocale` call, so this seam and a real LSP `initialize` reach the
    // slot by the SAME path — an adopter overriding the capture in
@@ -99,6 +139,58 @@ export async function initializeWorkspaceProgrammatically(
    await manager.initialized({} as InitializedParams);
 }
 
+/**
+ * Whether the services were composed around an LSP connection, which is what
+ * makes an LSP head present: its client's `initialize`/`initialized` pair then
+ * brings the workspace up, and nothing else should.
+ */
+export function hasLspConnection(shared: ServerSharedServicesMinimal): boolean {
+   const lsp: unknown = 'lsp' in shared ? shared.lsp : undefined;
+   return typeof lsp === 'object' && lsp !== null && 'Connection' in lsp && lsp.Connection !== undefined;
+}
+
+/**
+ * The starters' workspace bring-up: {@link initializeWorkspaceProgrammatically}
+ * on `workspace` when no LSP head is present, nothing when one is.
+ *
+ * Without an LSP head nothing else initialises the workspace, and a head
+ * serving from it answers without an error but wrongly: a diagram loads with
+ * its cross-file references unresolved. So a missing `workspace` there throws,
+ * and so does one given beside an LSP head, whose client names the folders
+ * itself. Both throw synchronously, before anything starts, so a starter can
+ * tell its caller's mistake from a failed initialisation, which the workspace
+ * manager logs. The initialisation is queued on the workspace lock
+ * synchronously too: a request that settles before it is queued keeps its
+ * unresolved references for good.
+ *
+ * Two starters on one services tree each name the workspace, and share one
+ * initialisation: see {@link initializeWorkspaceProgrammatically}.
+ */
+export function initializeWorkspaceWithoutLsp(
+   shared: ServerSharedServicesMinimal,
+   workspace: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput> | undefined,
+   options: ProgrammaticInitOptions = {}
+): Promise<void> {
+   if (hasLspConnection(shared)) {
+      if (workspace !== undefined) {
+         throw new Error(
+            '[hydranium] a workspace was given to a starter beside an LSP head, whose client names the folders in `initialize`. ' +
+               "Drop the starter's `workspace`."
+         );
+      }
+      return Promise.resolve();
+   }
+   // An empty list too: Langium initialises zero folders without complaint,
+   // and the heads would serve an empty workspace.
+   if (workspace === undefined || toWorkspaceFolders(workspace).length === 0) {
+      throw new Error(
+         '[hydranium] no LSP head is composed, so nothing initialises the workspace. ' +
+            'Name its root to the starter: `workspace`, or `rootUri` on `hostHeadsInWorker`.'
+      );
+   }
+   return initializeWorkspaceProgrammatically(shared, workspace, options);
+}
+
 /**
  * {@link initializeWorkspaceProgrammatically} **and then build every registered
  * document to `Validated`** — the "fully-built workspace" convenience for