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

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

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

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type LangiumDocuments, type URI } from '@hydranium/langium';
+import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type LangiumDocuments, type URI, UriUtils } from '@hydranium/langium';
 import { defineMessage } from '@hydranium/protocol';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type DocumentUriPolicy } from './document-uri-policy.js';
@@ -132,6 +132,17 @@ export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implement
       return this.langiumDocumentFactory.fromString('', uri);
    }
 
+   /**
+    * Registers `document`, then reports it to `VersionSyncService.modelProduced`:
+    * a first load parses outside the build, so no build's re-parse reports it.
+    * That marks one below `Parsed`, such as the builder's placeholder for a new
+    * file, as a placeholder. A rejected duplicate is not reported.
+    */
+   override addDocument(document: LangiumDocument): void {
+      super.addDocument(document);
+      this.services.workspace.VersionSyncService.modelProduced(document);
+   }
+
    override async getOrCreateDocument(uri: URI): Promise<LangiumDocument<AstNode>> {
       const resolved = this.uriPolicy.loadUri(uri);
       if (resolved) {
@@ -160,6 +171,13 @@ export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implement
             throw error;
          }
       }
+      // No file, but possibly a document: one created and not yet saved is
+      // built from its text and registered under its canonical URI.
+      const created = this.getDocument(UriUtils.toUri(this.uriPolicy.canonicalUri(uri)));
+      if (created) {
+         this.services.workspace.CstResidencyService.rehydrate(created);
+         return created;
+      }
       // The seam reports no loadable content, so there is nothing to read and
       // no error from a read to carry.
       throw new Error(NO_LOADABLE_CONTENT.format({ uri: uri.toString() }));

package/src/langium/workspace/persistent-file-system-provider.ts

@@ -8,7 +8,8 @@
  ********************************************************************************/
 
 import { URI } from '@hydranium/langium';
-import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { describeErrorWithStack } from '@hydranium/protocol';
+import { type WritableFileSystemProvider } from './file-system-provider.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type FileSystemSeed, InMemoryFileSystemProvider, type InMemoryFileSystemOptions } from './in-memory-file-system-provider.js';
 
@@ -125,13 +126,6 @@ export interface PersistentFileSystemOptions extends InMemoryFileSystemOptions {
  * restored as deleted, which is why the marker is NUL-wrapped and text a grammar
  * can parse is not.
  *
- * # A registered virtual document still wins
- *
- * `readFileSync` consults the virtual-document seam before the map, so a stdlib
- * contributed in code keeps answering for its URI whether or not the store holds
- * one. The store cannot shadow it, which is what keeps a rebuild that re-reads
- * that URI from losing the stdlib.
- *
  * # What it deliberately does not answer
  *
  * The store is scoped to the ORIGIN, not to the page: two pages on the same
@@ -156,12 +150,21 @@ export class PersistentFileSystemProvider extends InMemoryFileSystemProvider {
     * of marking it — a deletion that quietly undoes itself on the next load.
     */
    protected readonly seededPaths: ReadonlySet<string>;
+   /**
+    * The store keys restored as CONTENT, in the store's order.
+    *
+    * A deletion marker is not listed: the store holds a key for a deleted seeded
+    * file, so a host counting stored keys would report that deletion as a
+    * restored file, and only this class can tell the two apart.
+    */
+   readonly restoredPaths: readonly string[];
 
    constructor(services: ServerSharedServicesMinimal, options: PersistentFileSystemOptions) {
       super(services, options);
       this.store = options.store;
       this.storeRoot = options.rootUri === undefined ? undefined : `${this.fileKey(options.rootUri)}/`;
       this.seededPaths = new Set(Object.keys(options.seed ?? {}).map(path => this.storeKey(this.storeUri(path))));
+      const restoredPaths: string[] = [];
       for (const [path, content] of Object.entries(options.restored ?? {})) {
          // `super.*`, so restoring does not mirror straight back into the store
          // it just came from — a write-back on every start, and one that would
@@ -173,11 +176,13 @@ export class PersistentFileSystemProvider extends InMemoryFileSystemProvider {
          // insertion order of a merged record.
          const uri = this.storeUri(path);
          if (content === TOMBSTONE) {
-            super.deleteFile(uri);
+            this.files.delete(this.fileKey(uri));
          } else {
             super.setFile(uri, content);
+            restoredPaths.push(path);
          }
       }
+      this.restoredPaths = restoredPaths;
    }
 
    /**
@@ -208,13 +213,20 @@ export class PersistentFileSystemProvider extends InMemoryFileSystemProvider {
       await this.persist(uri, content);
    }
 
-   override deleteFile(uri: URI): void {
-      super.deleteFile(uri);
-      this.forget(uri).catch((error: unknown) => this.reportStoreFailure('forget', uri, error));
+   /**
+    * Mirror the deletion into the store and REJECT if it refuses, as
+    * {@link writeFile} does. The store goes first, so one that refuses leaves
+    * the file it still holds; a directory is refused before the store is asked.
+    */
+   override async deleteFile(uri: URI): Promise<void> {
+      if (!this.hasChildren(this.fileKey(uri))) {
+         await this.forget(uri);
+      }
+      await super.deleteFile(uri);
    }
 
    /** The absolute URI a store-space `path` addresses. */
-   protected storeUri(path: string): URI {
+   storeUri(path: string): URI {
       return URI.parse(this.storeRoot === undefined ? path : `${this.storeRoot}${path}`);
    }
 
@@ -251,13 +263,13 @@ export class PersistentFileSystemProvider extends InMemoryFileSystemProvider {
          return key;
       }
       if (!key.startsWith(this.storeRoot)) {
-         throw new Error(`Cannot persist ${uri.toString()}: outside the store root ${this.storeRoot}`);
+         throw new Error(`${uri.toString()} is outside the store root ${this.storeRoot}`);
       }
       return key.slice(this.storeRoot.length);
    }
 
    protected reportStoreFailure(operation: string, uri: URI, error: unknown): void {
-      this.tracer.error(`Failed to ${operation} ${uri.toString()}: ${error instanceof Error ? error.message : String(error)}`);
+      this.tracer.error(`Failed to ${operation} ${uri.toString()}: ${describeErrorWithStack(error)}`);
    }
 }
 

package/src/{documents → langium/workspace}/self-save-registry.ts

@@ -7,9 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Clock } from '@hydranium/protocol';
-import { isCaseInsensitiveFileSystem } from '../util/environment.js';
-import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { type Clock, type Stopwatch } from '@hydranium/protocol';
+import { isCaseInsensitiveFileSystem } from '../../util/environment.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
 
 /** Default eligibility window for a self-save entry. */
 const DEFAULT_TTL_MS = 30_000;
@@ -48,13 +48,11 @@ export interface SelfSaveRegistry {
  * save whose content is unchanged is still recognised.
  */
 export class DefaultSelfSaveRegistry implements SelfSaveRegistry {
-   protected readonly entries = new Map<string, { mtimeMs: number; registeredAt: number }>();
+   protected readonly entries = new Map<string, { mtimeMs: number; sinceRegistered: Stopwatch }>();
    /**
-    * Read time through the shared {@link Clock} rather than `Date.now()`: the
-    * TTL gates whether an incoming watcher event still counts as a self-save
-    * echo, so tests advance a fake clock to exercise expiry without a real
-    * wait. Wall-clock `now()` is correct here — entries are compared against a
-    * file's `mtime`.
+    * Ages entries on a {@link Clock} stopwatch: the TTL is how long ago the
+    * write happened, which a wall-clock step would otherwise shorten or
+    * stretch. The `mtime` match compares the stored value only.
     */
    protected readonly clock: Clock;
    protected readonly ttlMs: number;
@@ -83,12 +81,12 @@ export class DefaultSelfSaveRegistry implements SelfSaveRegistry {
 
    register(fsPath: string, mtimeMs: number): void {
       this.evictExpired();
-      this.entries.set(this.key(fsPath), { mtimeMs, registeredAt: this.clock.now() });
+      this.entries.set(this.key(fsPath), { mtimeMs, sinceRegistered: this.clock.stopwatch() });
    }
 
    isRegistered(fsPath: string, mtimeMs: number): boolean {
       const entry = this.entries.get(this.key(fsPath));
-      if (!entry || this.isExpired(entry.registeredAt)) {
+      if (!entry || this.isExpired(entry.sinceRegistered)) {
          return false;
       }
       // Accept mtime equality (some filesystems have 1-second precision).
@@ -107,14 +105,14 @@ export class DefaultSelfSaveRegistry implements SelfSaveRegistry {
     */
    protected evictExpired(): void {
       for (const [key, entry] of this.entries) {
-         if (this.isExpired(entry.registeredAt)) {
+         if (this.isExpired(entry.sinceRegistered)) {
             this.entries.delete(key);
          }
       }
    }
 
    /** Strictly greater, so an entry aged exactly to the TTL is still eligible. */
-   protected isExpired(registeredAt: number): boolean {
-      return this.clock.now() - registeredAt > this.ttlMs;
+   protected isExpired(sinceRegistered: Stopwatch): boolean {
+      return sinceRegistered.elapsedMs > this.ttlMs;
    }
 }

package/src/langium/workspace/syntax-errors.ts

@@ -0,0 +1,34 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type LangiumDocument, type ParseResult } from '@hydranium/langium';
+
+/**
+ * Whether `parseResult` has a lexer error, a parser error or an error a token
+ * builder reported. The AST of such a parse lacks what the parser skipped, so
+ * text serialized from it deletes that. A client reads the same from
+ * diagnostics with `TransferDiagnostic.hasSyntaxErrors`, which can miss some.
+ */
+export function hasSyntaxErrors(parseResult: ParseResult): boolean {
+   const lexing = parseResult.lexerReport?.diagnostics ?? [];
+   return (
+      parseResult.parserErrors.length > 0 ||
+      parseResult.lexerErrors.length > 0 ||
+      lexing.some(diagnostic => (diagnostic.severity ?? 'error') === 'error')
+   );
+}
+
+/**
+ * Whether the parse of `document` lacks some of its text: it has syntax
+ * errors and the text is not blank. A model serialized from its AST deletes
+ * that text, so a write of one is refused. Blank text has nothing to lose.
+ */
+export function hasSkippedText(document: LangiumDocument): boolean {
+   return hasSyntaxErrors(document.parseResult) && document.textDocument.getText().trim() !== '';
+}

package/src/langium/workspace/virtual-document.ts

@@ -7,15 +7,20 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { URI } from '@hydranium/langium';
+import { type FileSystemNode, URI } from '@hydranium/langium';
+import { type Tracer } from '@hydranium/protocol';
+import { type WritableFileSystemProvider } from './file-system-provider.js';
+import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
+import { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_DELETE, UNSUPPORTED_WRITE } from './in-memory-file-system-provider.js';
+import { notFound } from './file-not-found.js';
 
 /**
  * URI scheme for virtual documents — LangiumDocuments that have no backing
  * file on disk (a language's stdlib, library types, built-in definitions,
  * mirrors, generated views). Chosen so it cannot collide with on-disk `file:`
- * URIs, and so the framework's FileSystemProvider can recognise and serve them
- * on re-read (see {@link serveVirtualDocument}).
+ * URIs, and so the framework can serve them on re-read through its own
+ * provider for the scheme (see {@link VirtualFileSystemProvider}).
  */
 export const VIRTUAL_SCHEME = 'virtual';
 
@@ -40,12 +45,12 @@ export const VIRTUAL_SCHEME = 'virtual';
  * `virtual:<contributor>`, which has no extension and so matches no registered
  * language — a trap. Every per-language service is resolved per URI, and a
  * virtual document is never open in `TextDocuments`, so the declared-languageId
- * lookup rung cannot serve it either: the document is indexed but inert,
- * contributing nothing to the scopes it was written to populate, with no error
- * anywhere. Pass the extension as the last segment,
- * `virtualUri(contributor, 'name.<ext>')`. `HydraniumWorkspaceManager` warns
- * when a seeded additional document fails to route, which is where this
- * usually surfaces.
+ * lookup rung cannot serve it either, and the startup build fails. A
+ * `fromString` document throws while parsing; a `fromModel` or
+ * `fromStringInLanguage` document is built, and throws as it is added to the
+ * workspace, after `HydraniumWorkspaceManager` warns that it matches no
+ * language. Pass the extension as the last segment,
+ * `virtualUri(contributor, 'name.<ext>')`.
  *
  * # Relationship to the `$synthetic` node marker
  *
@@ -72,23 +77,99 @@ export function isVirtualUri(uri: URI | string): boolean {
 }
 
 /**
- * Serve the text of a registered virtual document, or `undefined` when `uri`
- * is not virtual or no document is registered for it (so a FileSystemProvider
- * delegates to its real backing).
+ * The file system provider for the {@link VIRTUAL_SCHEME} scheme, registered by
+ * the framework in the shared `fileSystemProviders` group so every host serves
+ * `virtual:` whatever provider it binds for its own files.
  *
- * The framework's FileSystemProvider defaults call this at the top of
- * `readFile` / `readFileSync` so a virtual document survives a re-read:
- * `DocumentBuilder.update` / `LangiumDocumentFactory.update` re-read a changed
- * URI from the FileSystemProvider, and nothing on disk backs a virtual URI. The
- * text comes from the registered document — the original source for a
- * `fromString` document, or the serialized form retained by the framework's
- * `fromModel` (which fills in the text Langium leaves empty). No serializer is
- * consulted here; the text is already on the document.
+ * A virtual document has no backing outside the index, and a re-read still has
+ * to find it: `DocumentBuilder.update` and `LangiumDocumentFactory.update`
+ * re-read a changed URI from the provider, and the last close rebuilds a
+ * released document the provider says `exists`. So the text comes from the
+ * document `LangiumDocuments` holds — the original source for a `fromString`
+ * document, or the serialized form the framework's `fromModel` retains. An
+ * edited one answers with its edited text.
+ *
+ * **Every read method agrees.** Serving only the text methods would leave one
+ * provider answering "here is the content" and "nothing is there" about one
+ * URI, so a caller could not probe before reading. A registered document is
+ * always a FILE with no children: a workspace walk handed a directory would try
+ * to enumerate children it has none of.
+ *
+ * Read-only: a write or delete is refused, since nothing backs the scheme.
  */
-export function serveVirtualDocument(services: ServerSharedServicesMinimal, uri: URI): string | undefined {
-   if (!isVirtualUri(uri)) {
-      return undefined;
+export class VirtualFileSystemProvider implements WritableFileSystemProvider {
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerSharedServicesMinimal,
+      options: LogNameOptions = {}
+   ) {
+      this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+   }
+
+   async writeFile(uri: URI, _content: string): Promise<void> {
+      throw new Error(UNSUPPORTED_WRITE.format({ uri: uri.toString() }));
+   }
+
+   async deleteFile(uri: URI): Promise<void> {
+      throw new Error(UNSUPPORTED_DELETE.format({ uri: uri.toString() }));
+   }
+
+   async readFile(uri: URI): Promise<string> {
+      return this.readFileSync(uri);
+   }
+
+   readFileSync(uri: URI): string {
+      const text = this.text(uri);
+      if (text === undefined) {
+         throw notFound(NO_SUCH_FILE.format({ uri: uri.toString() }), uri);
+      }
+      return text;
+   }
+
+   async readBinary(uri: URI): Promise<Uint8Array> {
+      return this.readBinarySync(uri);
+   }
+
+   readBinarySync(uri: URI): Uint8Array {
+      return new TextEncoder().encode(this.readFileSync(uri));
+   }
+
+   async stat(uri: URI): Promise<FileSystemNode> {
+      return this.statSync(uri);
+   }
+
+   statSync(uri: URI): FileSystemNode {
+      if (this.text(uri) === undefined) {
+         throw notFound(NO_SUCH_PATH.format({ uri: uri.toString() }), uri);
+      }
+      return { isFile: true, isDirectory: false, uri };
+   }
+
+   async exists(uri: URI): Promise<boolean> {
+      return this.existsSync(uri);
+   }
+
+   existsSync(uri: URI): boolean {
+      return this.text(uri) !== undefined;
+   }
+
+   async readDirectory(_uri: URI): Promise<FileSystemNode[]> {
+      return [];
+   }
+
+   readDirectorySync(_uri: URI): FileSystemNode[] {
+      return [];
+   }
+
+   /**
+    * Text of the document registered at `uri`, if there is one.
+    *
+    * `LangiumDocuments` is resolved per call, not in the constructor: it reaches
+    * this provider back through the document factory, so resolving it eagerly
+    * is a construction cycle.
+    */
+   protected text(uri: URI): string | undefined {
+      return this.services.workspace.LangiumDocuments.getDocument(uri)?.textDocument.getText();
    }
-   const document = services.workspace.LangiumDocuments.getDocument(uri);
-   return document ? document.textDocument.getText() : undefined;
 }

package/src/langium/workspace/write-lock-scope.ts

@@ -22,13 +22,17 @@
  * Answering it needs async-context propagation, which has no browser-neutral
  * implementation: Node's `AsyncLocalStorage` is a `node:async_hooks` import (so
  * it cannot appear on the portable `.` entry, which `check:neutral` gates), and
- * TC39's `AsyncContext` is unshipped. Hence the same seam shape the log file-tee
- * uses: this module declares the contract and defaults to inert, and
- * `@hydranium/core/node` installs a real implementation at entry load. A browser
- * bundle therefore gets NO detection rather than a broken approximation, which
- * is the right degradation — the reentrant shape is a server-side build concern,
- * and a false negative costs the pre-existing stall while a false positive would
- * reject a legitimate write.
+ * TC39's `AsyncContext` is unshipped. Userland polyfills lose the context at a
+ * native `await` unless every awaited path, Langium's included, is transpiled.
+ * Hence the same seam shape the log file-tee uses: this module declares the
+ * contract and defaults to inert, and `@hydranium/core/node` installs a real
+ * implementation at entry load. A browser bundle therefore gets NO detection
+ * rather than a broken approximation, which is the right degradation — the
+ * reentrant shape is a server-side build concern, and a false negative costs
+ * the stall, which `HydraniumWorkspaceLock` reports once the stalled write
+ * outlives its cancellation, while a false positive would reject a legitimate
+ * write. Detection without a tracker is tracked in
+ * https://github.com/eclipse-emfcloud/hydranium/issues/245.
  */
 export interface WriteLockScope {
    /** Run `fn` marked as executing inside a write-lock holder. */
@@ -64,24 +68,35 @@ export function isInsideWriteLock(): boolean {
    return writeLockScope?.isInside() ?? false;
 }
 
+/**
+ * Whether a write-lock scope tracker is installed, which is what makes a
+ * `false` from {@link isInsideWriteLock} mean "outside" rather than "unknown".
+ */
+export function isWriteLockScopeInstalled(): boolean {
+   return writeLockScope !== undefined;
+}
+
 /**
  * Thrown when the model facade is reached from inside a workspace write-lock
  * holder — typically an integrity rule or build-phase pass writing through
- * `ModelService.update` / `save` / `rebuild` during a build.
+ * a session's `update` / `save` / `delete` or `ModelService.rebuild` during a
+ * build.
  *
  * Named rather than a bare `Error` because the remedy is specific and worth
  * pointing at: either move the write out of the build (integrity rules that
  * persist repairs should write through `FileSystemProvider.writeFile`, which
- * takes no lock), or set `ModelServiceOptions.serializeBuilds: false` to accept
- * unserialised builds in exchange for the reentrancy.
+ * takes no lock), or set `ModelServiceOptions.allowReentrantBuilds: true`,
+ * which keeps the facade's build from cancelling the holder but not its wait
+ * from stalling on a document that needs a re-queue. A delete is refused on
+ * either value.
  */
 export class ReentrantWriteLockError extends Error {
    constructor(readonly uri: string) {
       super(
          `Model facade reached for '${uri}' from inside a workspace write-lock holder. ` +
             'Acquiring the write lock would cancel the enclosing build and may stall this call. ' +
-            'Write through FileSystemProvider.writeFile from a build-phase pass, or set ' +
-            'ModelServiceOptions.serializeBuilds: false to opt out of build serialisation.'
+            'Write through FileSystemProvider.writeFile from a build-phase pass, or, for an update, save or rebuild, ' +
+            'set ModelServiceOptions.allowReentrantBuilds: true to build without the lock from inside it.'
       );
       this.name = 'ReentrantWriteLockError';
    }

package/src/launcher/integrated-server.ts

@@ -20,7 +20,9 @@
  *   primarily by tests waiting for tidy teardown.
  *
  * Either promise may reject if startup or shutdown encounters an error
- * the head can't recover from.
+ * the head can't recover from. A launcher given a logger logs its own startup
+ * failure, so a rejected `started` is control flow: the caller stops what
+ * depends on it without logging the failure again.
  */
 export interface IntegratedServer {
    readonly started: Promise<void>;