@hydranium/core 1.0.0-next.272 → 1.0.0-next.275

package/src/documents/ast-document-manager.ts

@@ -24,6 +24,7 @@ import { type AstNode, DocumentState, type LangiumDocument, type LangiumDocument
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
 import { type AstDiagnostic } from '../langium/validation/document-validator.js';
 import { type WritableFileSystemProvider } from '../langium/workspace/file-system-provider.js';
+import { ReentrantWriteLockError, isInsideWriteLock } from '../langium/workspace/write-lock-scope.js';
 import { Disposable } from 'vscode-languageserver';
 import { TextDocumentIdentifier, type TextDocumentItem } from 'vscode-languageserver-protocol';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
@@ -151,6 +152,33 @@ export interface AstDocumentManager<TAst extends AstNode, TDiagnostic extends As
     * wrote.
     */
    save(uri: string, clientId: string): Promise<TextVersion>;
+   /**
+    * Remove the document's file through `FileSystemTaskQueue`, then the
+    * document, in a build that closes every open of it but the editor's.
+    * Resolves once that build has run, also when it fails after removing the
+    * document; rejects, having changed nothing, when the file cannot be
+    * removed.
+    *
+    * From the call until it settles, {@link isDeleting} answers `true`, which
+    * refuses every session's write of the document: one landing before the
+    * build would be lost with it, or, as a save, write the file back. Marked
+    * before the first await, so checks a caller runs in the same step as the
+    * call hold up to the removal. A second delete of the document while one is
+    * under way is refused, and so is a delete from inside a holder of the write
+    * lock, with `ReentrantWriteLockError`, since its builds take that lock.
+    *
+    * A change requested before the build starts merges over the deletion, and
+    * the document lives on with every open but `clientId`'s, which is closed.
+    */
+   delete(uri: string, clientId: string): Promise<void>;
+   /** Whether a {@link delete} of `uri` is under way. */
+   isDeleting(uri: string): boolean;
+   /**
+    * The client a deletion event for `uri` names: the one whose {@link delete}
+    * of it is under way, or the unknown-client id for a file removed outside
+    * any, as a file watcher reports one.
+    */
+   attributeDeletion(uri: string): string;
 
    getDocument(uri: string): LangiumDocument | undefined;
 
@@ -224,10 +252,11 @@ export class DefaultAstDocumentManager<
    /**
     * Whose writes the build under way carries, set when it starts: the author
     * of every open document's undelivered version, and the unknown-client id
-    * for a change no write explains, such as a deletion, a document no client
-    * has open, or a write that changed nothing. An undelivered version is one
-    * whose build has not validated it yet, so a write whose build was
-    * cancelled stays a cause of the build that takes over.
+    * for a change no write explains, such as a deletion no session's delete
+    * made, a document no client has open, or a write that changed nothing.
+    * An undelivered version is one whose build has not validated it yet, so a
+    * write whose build was cancelled stays a cause of the build that takes
+    * over.
     *
     * Errs toward more than one cause, and so toward the unknown client, which
     * a reader treats as foreign: an answer it repeats, never one it misses.
@@ -240,6 +269,9 @@ export class DefaultAstDocumentManager<
     */
    protected readonly buildCauses = new Set<string>();
 
+   /** Per canonical URI, the client whose {@link delete} of it is under way. */
+   protected readonly deletions = new Map<CanonicalUri, string>();
+
    /** Per canonical URI, the newest save queued for it, which {@link coalesceSaves} lets older queued saves defer to. */
    protected readonly newestSaves = new Map<CanonicalUri, Promise<TextVersion>>();
    protected readonly coalesceSaves: boolean;
@@ -279,9 +311,10 @@ export class DefaultAstDocumentManager<
             const textDocument = this.textDocuments.get(uri.toString());
             return textDocument === undefined || this.isDelivered(textDocument.uri, textDocument.version);
          });
-         if (unexplained || deleted.length > 0) {
+         if (unexplained) {
             this.buildCauses.add(UNKNOWN_CLIENT_ID);
          }
+         deleted.forEach(uri => this.buildCauses.add(this.attributeDeletion(uri.toString())));
          // The only place a deletion is observable: `DocumentBuilder.update`
          // removes a deleted document before it builds anything, so no phase
          // listener ever sees it.
@@ -440,7 +473,7 @@ export class DefaultAstDocumentManager<
             // Text the caller supplies was not read from the file, so no file
             // is assumed: the document is dirty until its first save, whatever
             // the file holds.
-            this.textDocuments.setDiskBaseline(args.uri, undefined);
+            this.textDocuments.markCreated(args.uri);
          }
          const built = this.getDocument(args.uri);
          if (creates && built) {
@@ -528,6 +561,53 @@ export class DefaultAstDocumentManager<
       return saved;
    }
 
+   async delete(uri: string, clientId: string): Promise<void> {
+      const canonical = this.uriPolicy.canonicalUri(uri);
+      const target = UriUtils.toUri(canonical);
+      // The builds below wait for a holder of the write lock, which would be
+      // waiting for this delete.
+      if (isInsideWriteLock()) {
+         throw new ReentrantWriteLockError(canonical);
+      }
+      // The mark holds one client: a second delete would share it, and the
+      // first to settle would clear it under the other.
+      if (this.deletions.has(canonical)) {
+         throw new Error(`Cannot delete ${uri}: a delete of it is under way`);
+      }
+      this.deletions.set(canonical, clientId);
+      try {
+         // A document no build has reached yet is not registered, and the
+         // deletion build would remove nothing and leave every open of it.
+         if (!this.langiumDocs.getDocument(target)) {
+            await this.documentBuilder.scheduleUpdate([target], []);
+         }
+         await this.services.workspace.FileSystemTaskQueue.enqueue(canonical, () => this.fileSystemProvider.deleteFile(target));
+         // Langium removes the document before the build's first await, so a
+         // failure is the dependents' build, and reaches no one else.
+         await this.documentBuilder
+            .scheduleUpdate([], [target])
+            .catch((error: unknown) =>
+               this.tracer.with(canonical).error(`The build after a deletion failed. ${describeErrorWithStack(error)}`)
+            );
+         // A change requested before that build started merges over the
+         // deletion, and the document lives on; the deleting client takes it as
+         // gone, so its open ends here.
+         if (this.textDocuments.isOpenInClient(canonical, clientId)) {
+            await this.close({ uri: canonical, clientId });
+         }
+      } finally {
+         this.deletions.delete(canonical);
+      }
+   }
+
+   isDeleting(uri: string): boolean {
+      return this.deletions.has(this.uriPolicy.canonicalUri(uri));
+   }
+
+   attributeDeletion(uri: string): string {
+      return this.deletions.get(this.uriPolicy.canonicalUri(uri)) ?? UNKNOWN_CLIENT_ID;
+   }
+
    /** Write `text` to `uri` unless the file already holds it, then announce the save. Runs inside the file's task queue. */
    protected async writeSave(uri: CanonicalUri, text: string, clientId: string): Promise<void> {
       if (!(await this.matchesDisk(uri, text))) {

package/src/documents/dirty-state-tracker.ts

@@ -62,6 +62,18 @@ export interface DirtyStateTracker {
     * and for a document not tracked. A first open takes the opener's text.
     */
    hasDiskBaseline(key: CanonicalUri): boolean;
+   /**
+    * `key` was created from a session's text, so no file is assumed: no
+    * baseline, and {@link isUnsavedCreation} answers `true`. A no-op for a
+    * document not tracked.
+    */
+   markCreated(key: CanonicalUri, document: TextDocument): void;
+   /**
+    * Whether `key` is marked created and no baseline with text has been set
+    * since, by a save or a reload that found the file. A reload that finds no
+    * file leaves the mark. `false` for a document not tracked.
+    */
+   isUnsavedCreation(key: CanonicalUri): boolean;
    /**
     * The store released `key`. Answers the clean announcement a document
     * released dirty now owes; `undefined` for one released clean.
@@ -70,7 +82,7 @@ export interface DirtyStateTracker {
 }
 
 export class DefaultDirtyStateTracker implements DirtyStateTracker {
-   protected readonly states = new Map<CanonicalUri, { baseline: string | undefined; dirty: boolean }>();
+   protected readonly states = new Map<CanonicalUri, { baseline: string | undefined; dirty: boolean; created: boolean }>();
    /** Per document released dirty, the token of the announcement it owes. */
    protected readonly owedClean = new Map<CanonicalUri, object>();
    protected readonly dirtyChangedEmitter = new Emitter<DocumentDirtyChangedEvent>();
@@ -87,7 +99,7 @@ export class DefaultDirtyStateTracker implements DirtyStateTracker {
    }
 
    track(key: CanonicalUri, document: TextDocument, diskText: string | undefined): void {
-      this.states.set(key, { baseline: diskText, dirty: this.owedClean.delete(key) });
+      this.states.set(key, { baseline: diskText, dirty: this.owedClean.delete(key), created: false });
       this.refreshDirty(key, document);
    }
 
@@ -111,6 +123,7 @@ export class DefaultDirtyStateTracker implements DirtyStateTracker {
          return;
       }
       state.baseline = text;
+      state.created &&= text === undefined;
       this.refreshDirty(key, document);
    }
 
@@ -118,6 +131,20 @@ export class DefaultDirtyStateTracker implements DirtyStateTracker {
       return this.states.get(key)?.baseline !== undefined;
    }
 
+   markCreated(key: CanonicalUri, document: TextDocument): void {
+      const state = this.states.get(key);
+      if (!state) {
+         return;
+      }
+      state.baseline = undefined;
+      state.created = true;
+      this.refreshDirty(key, document);
+   }
+
+   isUnsavedCreation(key: CanonicalUri): boolean {
+      return this.states.get(key)?.created ?? false;
+   }
+
    release(key: CanonicalUri): CleanAnnouncement | undefined {
       const dirty = this.states.get(key)?.dirty;
       this.states.delete(key);

package/src/documents/hydranium-text-documents.ts

@@ -1192,6 +1192,30 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
       }
    }
 
+   /**
+    * Record that `uri` was created from a session's text rather than read from
+    * its file: it has no disk baseline, so it is dirty until its first save,
+    * and {@link isUnsavedCreation} answers `true` until then. A no-op for a
+    * URI the store does not hold.
+    */
+   markCreated(uri: DocumentUri): void {
+      const key = this.documentKey(uri);
+      const document = this.__syncedDocuments.get(key);
+      if (document !== undefined) {
+         this.dirtyStateTracker.markCreated(key, document);
+      }
+   }
+
+   /**
+    * Whether `uri` was created from a session's text and the store has not
+    * seen its file since, by a save or a reload that found it. A baseline
+    * cleared because the file went missing does not count. `false` for a URI
+    * the store does not hold.
+    */
+   isUnsavedCreation(uri: DocumentUri): boolean {
+      return this.dirtyStateTracker.isUnsavedCreation(this.documentKey(uri));
+   }
+
    /**
     * Read the file behind `uri` through its disk queue and take it as the
     * baseline. A file that cannot be read counts as none, the side that

package/src/langium/bootstrap.ts

@@ -10,7 +10,7 @@
 import { type Logger } from '@hydranium/protocol';
 import { type LangiumSharedCoreServices } from '@hydranium/langium';
 import { type LangiumServices, type LangiumSharedServices } from '@hydranium/langium/lsp';
-import type { ServerSharedServicesMinimal } from './shared-services.js';
+import type { ServerSharedServices } from './module.js';
 import { collectProducibleTypes } from './language-types.js';
 import { assertSingleLangiumCopy } from './single-langium-copy.js';
 import { DefaultAstDocumentManager } from '../documents/ast-document-manager.js';
@@ -327,17 +327,24 @@ export function warnOnUnexpectedBindings(shared: LangiumSharedServices, language
  *   BuildPhasePass that sheds the CST of closed documents. The framework
  *   default strategy is `always-keep`, so the pass runs but sheds nothing
  *   until an adopter configures a shedding strategy.
+ * - **`workspace.AstDocumentManager`** — subscribes to the build pipeline
+ *   and the text store to track opens, deletions and each build's causes.
+ * - **`model.ModelService`** — subscribes to the settled document phase to
+ *   bring the language client up to date. A tree without an LSP `initialize`,
+ *   such as a headless init, may not resolve it before the first build.
  *
  * Consumers with no additional eager targets can omit the third argument
  * to {@link bootstrapLangium} — the parameter default is this exact set.
  * Adopters needing extra eager targets spread this constant into their own
  * array and append their accessors.
  */
-export const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServicesMinimal) => unknown> = [
+export const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServices) => unknown> = [
    services => services.workspace.ProjectManager,
    services => services.workspace.BuildPipelineIntegration,
    services => services.profilers.LangiumProfiler,
-   services => services.workspace.CstResidencyService
+   services => services.workspace.CstResidencyService,
+   services => services.workspace.AstDocumentManager,
+   services => services.model.ModelService
 ];
 
 /**
@@ -387,7 +394,7 @@ export const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServic
  * registers every language before validating slots or constructing the
  * eager set.
  */
-export function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServicesMinimal, TLang extends LangiumServices>(
+export function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(
    shared: TShared,
    language: TLang,
    eagerlyConstructedServices: ReadonlyArray<(services: TShared) => unknown> = DEFAULT_EAGER_SERVICES
@@ -420,22 +427,18 @@ export function bootstrapLangium<TShared extends LangiumSharedServices & ServerS
  *  4. {@link assertReflectionCoversLanguages} runs **once**, on the one
  *     shared `AstReflection`.
  *  5. Eager accessors run **once**, after all registrations. They take
- *     the shared tier, and the framework's eager set is shared-tier only
- *     (`ProjectManager`, `BuildPipelineIntegration`, `LangiumProfiler`,
- *     `CstResidencyService`) — `BuildPipelineIntegration` in particular
- *     routes per document URI to each language's `IntegrityService` /
- *     `AstExtensionService`, so it must be constructed knowing all of
- *     them. Running the set per language would attach its
- *     `documentBuilder` listeners N times and enforce each phase N times.
+ *     the shared tier, and the framework's eager set is shared-tier only —
+ *     `BuildPipelineIntegration` in particular routes per document URI to
+ *     each language's `IntegrityService` / `AstExtensionService`, so it
+ *     must be constructed knowing all of them. Running the set per language
+ *     would attach its `documentBuilder` listeners N times and enforce each
+ *     phase N times.
  *
  * Throws when `languages` is empty: a shared tier with no registered
  * language never validates its slots, which silently defers a
  * composition error to the first build.
  */
-export function bootstrapLangiumLanguages<
-   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
-   TLang extends LangiumServices
->(
+export function bootstrapLangiumLanguages<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(
    shared: TShared,
    languages: ReadonlyArray<TLang>,
    eagerlyConstructedServices: ReadonlyArray<(services: TShared) => unknown> = DEFAULT_EAGER_SERVICES

package/src/langium/integration-services.ts

@@ -18,8 +18,7 @@ import {
 } from '@hydranium/langium/lsp';
 import { DEFAULT_EAGER_SERVICES, bootstrapLangiumLanguages } from './bootstrap.js';
 import { createServerLanguageModule } from './language-module.js';
-import { createServerSharedModule, type ServerModuleContext } from './module.js';
-import type { ServerSharedServicesMinimal } from './shared-services.js';
+import { createServerSharedModule, type ServerModuleContext, type ServerSharedServices } from './module.js';
 
 /**
  * Options accepted by {@link createIntegrationServices}. Wraps the
@@ -40,7 +39,7 @@ import type { ServerSharedServicesMinimal } from './shared-services.js';
  */
 export interface IntegrationServicesOptions<
    TContext extends ServerModuleContext,
-   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
+   TShared extends LangiumSharedServices & ServerSharedServices,
    TLanguage extends LangiumServices
 > {
    /**
@@ -224,7 +223,7 @@ export interface IntegrationServicesOptions<
  * differs only in its grammar-generated module.
  */
 export interface AdditionalLanguageModules<
-   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
+   TShared extends LangiumSharedServices & ServerSharedServices,
    TLanguage extends LangiumServices
 > {
    /**
@@ -260,7 +259,7 @@ export interface AdditionalLanguageModules<
  */
 export function createIntegrationServices<
    TContext extends ServerModuleContext,
-   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
+   TShared extends LangiumSharedServices & ServerSharedServices,
    TLanguage extends LangiumServices
 >(
    options: IntegrationServicesOptions<TContext, TShared, TLanguage>

package/src/langium/model-service/client-session.ts

@@ -46,6 +46,9 @@ export interface ClientSessionWriteArgs<TTransfer> {
 /** What a session's `persist` writes: the text the store holds for `uri`. */
 export type ClientSessionPersistArgs = Omit<ClientSessionWriteArgs<never>, 'model'>;
 
+/** What a session's `delete` removes: the document at `uri`, at the version it was based on. */
+export type ClientSessionDeleteArgs = Omit<ClientSessionWriteArgs<never>, 'model'>;
+
 /** What a session's `updateAll` writes, all or none. */
 export interface ClientSessionUpdateAllArgs<TTransfer> {
    updates: ClientSessionWriteArgs<TTransfer>[];
@@ -55,11 +58,13 @@ export interface ClientSessionUpdateAllArgs<TTransfer> {
  * One participant's handle on the documents it works on, started by
  * `ModelService.createSession`.
  *
- * The session writes only what it has open: `update`, `save` and `persist`
- * fail with `DocumentNotOpenError` unless this session has the URI open in the
- * synchronous step that applies or takes the text, so a write either lands
- * while the document is open or fails. A document stays open until this
- * session closes it, the session ends, or the file is deleted.
+ * The session writes only what it has open: `update`, `save`, `persist` and
+ * `delete` fail with `DocumentNotOpenError` unless this session has the URI
+ * open in the synchronous step that applies or takes the text, or marks the
+ * document for deletion, so a write either lands while the document is open or
+ * fails. They fail the same way while any session's `delete` of the URI is
+ * under way. A document stays open until this session closes it, the session
+ * ends, or the file is deleted.
  *
  * One open per URI, without reference counting: opening a URI the session
  * already has open changes nothing, and one `close` ends it.
@@ -123,6 +128,22 @@ export interface ClientSession<
     * session, also when another client wrote the text.
     */
    persist(args: ClientSessionPersistArgs): Promise<TextVersion>;
+   /**
+    * Delete `args.uri` at once: its file, then the document, as a deletion a
+    * file watcher reports removes it. Every session's open of it closes, the
+    * editor's stays, and the deletion event names this session. Resolves once
+    * the build that removes the document has run. `args.baseVersion` is gated
+    * as {@link persist} gates it; a file already gone deletes only the
+    * document, and one that cannot be removed fails the call, deleting nothing.
+    * The file removed is the one the store keys the document by: under
+    * `RealpathDocumentUriPolicy`, a symlink's target rather than the link.
+    *
+    * A change requested before that build starts, by the editor or a file
+    * watcher, keeps the document, and only this session's open of it closes.
+    * From inside a build the call fails with `ReentrantWriteLockError`,
+    * whatever `ModelServiceOptions.allowReentrantBuilds` says.
+    */
+   delete(args: ClientSessionDeleteArgs): Promise<void>;
    /** Close this session's open of `uri`, at once. A no-op when it does not have `uri` open. */
    close(uri: string): Promise<void>;
    /**
@@ -258,6 +279,11 @@ export class DefaultClientSession<
       return this.closeDocument(uri);
    }
 
+   delete(args: ClientSessionDeleteArgs): Promise<void> {
+      this.assertLive();
+      return this.deleteDocument(args);
+   }
+
    withOpen<T>(uri: string, fn: () => MaybePromise<T>): Promise<T> {
       this.assertLive();
       return this.runWithOpen(uri, fn);
@@ -289,9 +315,10 @@ export class DefaultClientSession<
       }
    }
 
-   /** Throw `DocumentNotOpenError` unless this session has `uri` open. */
+   /** Throw `DocumentNotOpenError` unless this session has `uri` open and no delete of it is under way. */
    protected assertOpen(uri: string): void {
-      if (!this.services.workspace.TextDocuments.isOpenInClient(uri, this.clientId)) {
+      const workspace = this.services.workspace;
+      if (!workspace.TextDocuments.isOpenInClient(uri, this.clientId) || workspace.AstDocumentManager.isDeleting(uri)) {
          throw new DocumentNotOpenError(uri, this.clientId);
       }
    }
@@ -467,6 +494,20 @@ export class DefaultClientSession<
       return this.services.workspace.AstDocumentManager.save(uri, this.clientId);
    }
 
+   /**
+    * Delete `args.uri` under this session's id. The open check and the
+    * `baseVersion` gate sit in the same synchronous step as the manager's
+    * mark, which refuses every later write of the URI: an await between them
+    * lets another client's write land after the gate, and the delete then
+    * discards text this session never saw.
+    */
+   protected async deleteDocument(args: ClientSessionDeleteArgs): Promise<void> {
+      const uri = this.canonicalKey(args.uri);
+      this.assertOpen(uri);
+      this.assertBaseVersion(uri, args.baseVersion, this.services.workspace.TextDocuments.version(uri));
+      return this.services.workspace.AstDocumentManager.delete(uri, this.clientId);
+   }
+
    protected async closeDocument(uri: string): Promise<void> {
       await this.services.workspace.AstDocumentManager.close({ uri, clientId: this.clientId });
    }

package/src/langium/model-service/model-events.ts

@@ -60,6 +60,11 @@ export interface ModelsBuiltEvent {
  */
 export interface ModelDeletedEvent {
    readonly uri: CanonicalUri;
+   /**
+    * The session whose `delete` removed the file; the unknown-client id for a
+    * file removed outside any session, as a file watcher reports one.
+    */
+   readonly sourceClientId: string;
 }
 
 /** A document was saved: the AST manager's event, as `ModelService` hands it out. */

package/src/langium/model-service/model-service.ts

@@ -94,6 +94,9 @@ export interface ModelServiceOptions extends LogNameOptions {
     * because a document no build will carry is re-queued through the lock, and
     * the re-queue waits for the holder to end.
     *
+    * A session's delete is refused that way on either value, since its builds
+    * always take the lock.
+    *
     * Every other facade build takes the lock on either value. Unlocked, it can
     * overlap another build of the same document: both run a full validation
     * pass that Langium appends, and a caller can be handed a version that an
@@ -301,6 +304,10 @@ export interface ModelService<
     * at `UNRECORDED_VERSION`, whose `root` is `undefined` despite its type.
     */
    onModelSaved(listener: (event: ModelSavedEvent<TAst, TDiagnostic>) => void, filter?: ModelEventFilter): Disposable;
+   /**
+    * Fires for every document a build removes, with the session whose
+    * `delete` removed it, as `AstDocumentManager.attributeDeletion` names it.
+    */
    onModelDeleted(listener: (event: ModelDeletedEvent) => void, filter?: ModelEventFilter): Disposable;
    /** Fires when a document's text starts or stops differing from its file. */
    onDirtyChanged(listener: (event: ModelDirtyChangedEvent) => void, filter?: ModelEventFilter): Disposable;
@@ -1218,7 +1225,7 @@ export class DefaultModelService<
          for (const deletedUri of deleted) {
             const uri = this.uriPolicy.canonicalUri(deletedUri.toString());
             if (this.matches(target, uri)) {
-               listener(Object.freeze({ uri }));
+               listener(Object.freeze({ uri, sourceClientId: this.services.workspace.AstDocumentManager.attributeDeletion(uri) }));
             }
          }
       });

package/src/langium/module.ts

@@ -243,7 +243,9 @@ export interface ServerAddedSharedServices<
        * there is only one, and `'plaintext'` when there are several, rather
        * than naming a language the document demonstrably is not. Consumers
        * that need to narrow the diagnostic type or override lifecycle
-       * behaviour rebind this slot with a subclass.
+       * behaviour rebind this slot with a subclass. Subscribes to the build
+       * pipeline and the text store in its constructor, so it is eagerly
+       * constructed via `DEFAULT_EAGER_SERVICES`.
        */
       AstDocumentManager: AstDocumentManager<AstNode>;
       /**
@@ -317,6 +319,10 @@ export interface ServerAddedSharedServices<
     */
    model: {
       TransferEncoder: TransferEncoder<TDiagnostic>;
+      /**
+       * Subscribes to the settled document phase in its constructor, so it is
+       * eagerly constructed via `DEFAULT_EAGER_SERVICES`.
+       */
       ModelService: ModelService<AstNode>;
       /** Builds the handle of every session `ModelService.createSession` starts. */
       ClientSessionFactory: ClientSessionFactory;
@@ -559,6 +565,8 @@ export function createServerSharedModule(
                host: writable ? (fromContext as WritableFileSystemProvider) : new DefaultEmptyFileSystemProvider(services)
             });
          },
+         // Eagerly constructed, so its build-pipeline and text-store listeners
+         // attach before the first build.
          AstDocumentManager: services => new DefaultAstDocumentManager(services),
          FileSystemTaskQueue: services => new DefaultFileSystemTaskQueue(services),
          // Eagerly constructed, so its build-phase listeners attach before the
@@ -576,6 +584,8 @@ export function createServerSharedModule(
          // Generic walker — adopters with a typed `$type → wire shape` overlay
          // rebind this slot with a subclass.
          TransferEncoder: services => new DefaultTransferEncoder(services),
+         // Eagerly constructed, so its settled-phase listener attaches before
+         // the first build.
          ModelService: services => new DefaultModelService(services),
          ClientSessionFactory: services => new DefaultClientSessionFactory(services)
       },

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

@@ -28,6 +28,12 @@ import { type ServerSharedServicesMinimal } from '../shared-services.js';
  */
 export interface WritableFileSystemProvider extends FileSystemProvider {
    writeFile(uri: URI, content: string): Promise<void>;
+   /**
+    * Remove the file at `uri`: the name the URI gives, never the file a
+    * symlink there points at, leaving a parent directory it empties in place.
+    * A no-op when nothing is there; a directory is refused.
+    */
+   deleteFile(uri: URI): Promise<void>;
    /**
     * Last-modified time (ms) of the file at `uri`, or `undefined` if it can't
     * be determined (missing file, or a provider with no disk — in-memory /
@@ -78,11 +84,11 @@ export interface WritableFileSystemProvider extends FileSystemProvider {
 
 /**
  * Empty-filesystem {@link WritableFileSystemProvider}. For browser / test / CLI
- * hosts that don't have a real filesystem. All writes are no-ops. On the
- * portable `.` entry it is the {@link FileSystemProviderRegistry.host} when
- * `context.fileSystemProvider` gives no writable provider; the Node-backed
- * `DefaultFileSystemProvider` lives in `@hydranium/core/node` (it pulls
- * `node:fs`).
+ * hosts that don't have a real filesystem. All writes and deletes are no-ops.
+ * On the portable `.` entry it is the
+ * {@link FileSystemProviderRegistry.host} when `context.fileSystemProvider`
+ * gives no writable provider; the Node-backed `DefaultFileSystemProvider`
+ * lives in `@hydranium/core/node` (it pulls `node:fs`).
  */
 export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider implements WritableFileSystemProvider {
    protected readonly tracer: Tracer;
@@ -99,6 +105,10 @@ export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider impl
       // no-op
    }
 
+   async deleteFile(_uri: URI): Promise<void> {
+      // no-op
+   }
+
    // `async` so the base's refusal becomes a rejection: it throws
    // SYNCHRONOUSLY from a method declared to return a promise, and a
    // synchronous throw escapes the promise chain — `.catch()` never attaches
@@ -200,6 +210,10 @@ export class DefaultFileSystemProviderRegistry<
       return this.providerFor(uri).writeFile(uri, content);
    }
 
+   async deleteFile(uri: URI): Promise<void> {
+      return this.providerFor(uri).deleteFile(uri);
+   }
+
    async mtimeMs(uri: URI): Promise<number | undefined> {
       return this.providerFor(uri).mtimeMs?.(uri);
    }

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

@@ -43,6 +43,12 @@ export const UNSUPPORTED_WRITE = defineMessage(
    '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}.
  *
@@ -136,9 +142,13 @@ 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> {

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

@@ -167,7 +167,7 @@ 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);
          }
@@ -202,9 +202,16 @@ 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. */
@@ -245,7 +252,7 @@ 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);
    }