@hydranium/core 1.0.0-next.169 → 1.0.0-next.173

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

@@ -8,8 +8,16 @@
  ********************************************************************************/
 
 import { isPromiseLike, Logger, type ProfileSession, type Tracer } from '@hydranium/protocol';
-import { type AstNode, AstUtils, DocumentState, interruptAndCheck, type LangiumDocument, UriUtils } from '@hydranium/langium';
-import { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import {
+   type AstNode,
+   AstUtils,
+   DocumentState,
+   interruptAndCheck,
+   isOperationCancelled,
+   type LangiumDocument,
+   UriUtils
+} from '@hydranium/langium';
+import { CancellationToken, type Disposable } from 'vscode-languageserver';
 import { type HydraniumDocumentBuilder } from '../document-builder/document-builder.js';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
 import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
@@ -200,7 +208,8 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          const changed = await this.enforceIntegrity(document, phase, cancelToken, session);
          if (changed) {
             mutatedCount++;
-            await this.resyncDocument(document, cancelToken);
+            // Not cancellable: see `resyncDocument`.
+            await this.resyncDocument(document, CancellationToken.None);
          }
          await interruptAndCheck(cancelToken);
       }
@@ -261,8 +270,10 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
     * full rule sweep) — coarser than per (node × rule) to avoid a microtask
     * per inner iteration, finer than per-document so a long-running rule set
     * on a large file can still interrupt mid-stream. Throws
-    * `OperationCancelled` when the token is cancelled; Langium's build
-    * pipeline absorbs the throw at the lock-holder.
+    * `OperationCancelled` when the token is cancelled before any rule mutated
+    * the AST; Langium's build pipeline absorbs the throw at the lock-holder.
+    * After a mutation it stops the sweep and returns `true` instead, so the
+    * caller can resync what was mutated before the cancellation unwinds.
     */
    async enforceIntegrity(
       document: LangiumDocument,
@@ -296,7 +307,14 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
             }
          }
          if (cancelToken !== undefined) {
-            await interruptAndCheck(cancelToken);
+            try {
+               await interruptAndCheck(cancelToken);
+            } catch (err: unknown) {
+               if (changed && isOperationCancelled(err)) {
+                  return true;
+               }
+               throw err;
+            }
          }
       }
       return changed;
@@ -306,15 +324,11 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
     * Re-serialise the document text after AST mutations, propagate corrections,
     * and re-parse at Parsed phase (safe because linking hasn't occurred yet).
     *
-    * `cancelToken` is checked at entry so a preempted build skips the
-    * serialise / disk-write atomic; the steps inside resync are not further
-    * subdivided because each is a single fast operation that does not yield
-    * a natural interruption point.
+    * Runs to the end whatever `cancelToken` says: the AST is already mutated,
+    * and skipping the resync leaves it against unchanged text that the next
+    * build does not re-parse. `cancelToken` reaches only the re-parse.
     */
    protected async resyncDocument(document: LangiumDocument, cancelToken?: CancellationToken): Promise<void> {
-      if (cancelToken?.isCancellationRequested) {
-         return;
-      }
       const root = document.parseResult.value as TRoot;
       // Extracted while `document` still holds the text being replaced — the
       // resync that follows overwrites it with `newText`. Absent on a test

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

@@ -20,7 +20,7 @@ import {
 import { type AstNode, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
 import { type AstDiagnostic } from '../validation/document-validator.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
-import { ReentrantWriteLockError, isInsideWriteLock } from '../workspace/write-lock-scope.js';
+import { ReentrantWriteLockError, isInsideWriteLock, isWriteLockScopeInstalled } from '../workspace/write-lock-scope.js';
 import { type CancellationToken, type Disposable } from 'vscode-languageserver';
 import { AstDocument, type AstDocumentSavedEvent, type AstDocumentUpdatedEvent } from '../../documents/ast-document-manager.js';
 import { isConnectionGoneError } from '../../util/connection-liveness.js';
@@ -58,45 +58,32 @@ const SAVE_SETTLE_TIMEOUT_MS = 10_000;
  */
 export interface ModelServiceOptions extends LogNameOptions {
    /**
-    * Serialise the facade's own build under the workspace WRITE lock, through
-    * `HydraniumDocumentBuilder.scheduleUpdate` as the LSP update handler
-    * builds. Default `true`.
+    * Let the facade's build run without the workspace write lock when its
+    * caller already holds it: an integrity rule or build-phase pass that
+    * writes back through a session's `update` / `save`, or calls `rebuild`.
+    * Default `false`.
     *
-    * **Why it defaults on.** Unlocked, the facade's build races the LSP bridge's
-    * build of the same URI — both are legitimate (the bridge exists only under a
-    * `Connection`, so the facade stands in for it headless), but nothing
-    * serialises them, so both run a full validation pass and Langium appends the
-    * second onto the first. Every diagnostic is then duplicated, and the
-    * duplication compounds per rebuild. Serialised, the second request shares
-    * the first build where it carries both, so the redundant work goes too.
+    * `WorkspaceLock` is not reentrant. Taking it from inside a holder cancels
+    * that holder and then waits for it to end, while the holder waits for this
+    * call, so neither completes. On `false` that call fails with
+    * {@link ReentrantWriteLockError} instead, wherever a host installs a
+    * write-lock scope tracker (`@hydranium/core/node` does at entry load); on
+    * `true` its build takes no lock. The wait after that build can still hang,
+    * because a document no build will carry is re-queued through the lock, and
+    * the re-queue waits for the holder to end.
     *
-    * **What `false` costs.** The facade's build is then unserialised and can run
-    * concurrently with the bridge's build of the same URI, so the affected
-    * documents are validated twice per write — double the validation work.
-    * Reported diagnostics stay correct even then, because
-    * `HydraniumDocumentBuilder.dedupeDiagnostics` collapses the byte-identical
-    * duplicates a repeated pass produces before any listener sees them; what this
-    * option removes is the wasted pass, not just its visible symptom.
-    *
-    * **What `false` buys.** `WorkspaceLock` is not reentrant. A caller that
-    * reaches a session's `update` / `save` or `rebuild` while already holding
-    * the write lock — an integrity rule or build-phase pass that writes
-    * back — deadlocks: acquiring the lock cancels the running holder, and the new
-    * acquisition then waits for that holder to release while the holder waits
-    * for this call. On `true` that shape is DETECTED and rejected with
-    * {@link ReentrantWriteLockError} rather than hanging, wherever a host
-    * installs a write-lock scope tracker (`@hydranium/core/node` does at entry
-    * load; see {@link isInsideWriteLock}). Setting `false` is the escape hatch
-    * for an adopter whose reentrant shape is unavoidable: the facade's own
-    * build then takes no lock, so it cannot cancel the holder it runs inside.
-    * The wait after it can still hang there, because a document no build will
-    * carry is re-queued through the lock, and that re-queue waits for the
-    * holder to end. Prefer `false` over serialised builds only in that case.
+    * 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
+    * integrity repair still running in the other build then moves past. Without
+    * a tracker the two cases cannot be told apart (see
+    * {@link isWriteLockScopeInstalled}), so `true` builds without the lock every
+    * time and accepts both.
     *
     * Accepts a {@link MaybeObservableValue} so it can be bound to a setting and
     * flipped without a restart.
     */
-   readonly serializeBuilds?: MaybeObservableValue<boolean>;
+   readonly allowReentrantBuilds?: MaybeObservableValue<boolean>;
 }
 
 /**
@@ -289,8 +276,8 @@ export class DefaultModelService<
     * (see {@link DocumentUriPolicy}).
     */
    protected readonly uriPolicy: DocumentUriPolicy;
-   /** See {@link ModelServiceOptions.serializeBuilds}. Defaults to `true`. */
-   protected readonly serializeBuilds: ObservableValue<boolean>;
+   /** See {@link ModelServiceOptions.allowReentrantBuilds}. Defaults to `false`. */
+   protected readonly allowReentrantBuilds: ObservableValue<boolean>;
 
    /**
     * Per-URI applyEdit coalescing: at most one in-flight `applyEditToLanguageClient`
@@ -351,7 +338,7 @@ export class DefaultModelService<
    ) {
       this.tracer = services.Tracer.for(options.logName ?? 'ModelService').trace('instantiated');
       this.uriPolicy = services.workspace.DocumentUriPolicy;
-      this.serializeBuilds = ObservableValue.from(options.serializeBuilds ?? true);
+      this.allowReentrantBuilds = ObservableValue.from(options.allowReentrantBuilds ?? false);
       // Optional-chain so a harness that binds no WorkspaceManager awaits
       // `undefined` and resolves immediately; production hosts always have it
       // bound.
@@ -483,9 +470,9 @@ export class DefaultModelService<
     * where that build carries it. Langium alone does not coalesce concurrent
     * builds of one URI: two unserialised builds each run a full validation
     * pass and Langium appends the second set onto the first, duplicating every
-    * diagnostic. Opt out via
-    * {@link ModelServiceOptions.serializeBuilds} — see there for the
-    * non-reentrancy hazard that is the reason the opt-out exists.
+    * diagnostic. A caller that already holds the lock builds without it only
+    * under {@link ModelServiceOptions.allowReentrantBuilds} — see there for the
+    * non-reentrancy hazard.
     *
     * An override calls the base before it awaits. Under an LSP connection the
     * store's change event has already asked the update handler to build a
@@ -533,28 +520,19 @@ export class DefaultModelService<
       // meant for category-partitioned passes). The user-visible result is every
       // diagnostic duplicated, plus double the validation work per write.
       //
-      // Opt out via `ModelServiceOptions.serializeBuilds` — see there for
-      // the non-reentrancy hazard that opt-out exists for.
-      if (this.serializeBuilds.value) {
-         // Fail loudly on the one shape the lock cannot survive. `WorkspaceLock`
-         // is not reentrant: acquiring the write lock cancels the running holder,
-         // so a caller already inside one — an integrity rule or build-phase pass
-         // writing back through this facade — would cancel its own enclosing
-         // build and then likely stall in the phase wait below. The check is
-         // gated on `serializeBuilds` deliberately, because acquiring the lock IS
-         // the hazard: with serialisation off the build takes no lock, which
-         // makes the existing opt-out the guard's opt-out too.
-         // Detection needs async-context propagation, so it is inert until a host
-         // installs a tracker (`@hydranium/core/node` does) — see
-         // `isInsideWriteLock`.
-         if (isInsideWriteLock()) {
+      // A caller already inside the lock would cancel its own build and stall in
+      // the wait below; `allowReentrantBuilds` builds it unlocked, and without a
+      // tracker it cannot be told apart from any other caller.
+      const inside = isInsideWriteLock();
+      if (this.allowReentrantBuilds.value && (inside || !isWriteLockScopeInstalled())) {
+         await this.services.workspace.DocumentBuilder.update([documentUri], [], cancelToken);
+      } else {
+         if (inside) {
             throw new ReentrantWriteLockError(uri);
          }
          // The build runs on the lock's own token, which a later write cancels;
          // the caller's token governs only the phase wait below.
          await this.services.workspace.DocumentBuilder.scheduleUpdate([documentUri], []);
-      } else {
-         await this.services.workspace.DocumentBuilder.update([documentUri], [], cancelToken);
       }
       return this.waitForDocumentStateCanonical(uri, state ?? IntegrityService.SettledState, cancelToken);
    }

package/src/langium/module.ts

@@ -169,7 +169,7 @@ export interface ServerAddedSharedServices<
        * `ModelService.rebuild` build through this slot's
        * `scheduleUpdate`, so narrowing here is a load-bearing contract:
        * a builder without it fails every LSP-driven build, and every
-       * session write while `serializeBuilds` is on, at run time.
+       * session write that takes the lock, at run time.
        */
       /* override */ DocumentBuilder: HydraniumDocumentBuilder;
       /**
@@ -530,7 +530,7 @@ export function createServerSharedModule(
          DocumentBuilder: services => new HydraniumDocumentBuilder(services),
          // The write-lock scope this marks is inert unless a host installs a
          // scope tracker — `@hydranium/core/node` does.
-         WorkspaceLock: () => new HydraniumWorkspaceLock(),
+         WorkspaceLock: services => new HydraniumWorkspaceLock(services),
          ProjectManager: services => new SingleProjectManager(services),
          SelfSaveRegistry: services => new DefaultSelfSaveRegistry(services),
          DocumentUriPolicy: () => new DefaultDocumentUriPolicy(),

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

@@ -7,10 +7,31 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { type Clock, type Tracer } from '@hydranium/protocol';
 import { DefaultWorkspaceLock, type MaybePromise } from '@hydranium/langium';
-import { type CancellationToken } from 'vscode-languageserver-protocol';
+import { type CancellationToken, type Disposable } from 'vscode-languageserver-protocol';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { runInWriteLockScope } from './write-lock-scope.js';
 
+/** Constructor options for {@link HydraniumWorkspaceLock}. */
+export interface HydraniumWorkspaceLockOptions extends LogNameOptions {
+   /**
+    * How long a write may keep running after a later write cancelled it before
+    * the lock logs an error. Every write and read waits behind it meanwhile, so
+    * one that never ends stops the server. Defaults to 10 s; `0` turns the
+    * check off.
+    */
+   readonly stalledWriteWarnMs?: number;
+}
+
+const DEFAULT_STALLED_WRITE_WARN_MS = 10_000;
+
+/** The write action a {@link HydraniumWorkspaceLock} is running, with the timer its cancellation started. */
+export interface RunningWrite {
+   stallTimer?: Disposable;
+}
+
 /**
  * Langium's {@link DefaultWorkspaceLock} with the write action marked as a
  * write-lock scope, so anything it reaches can be asked whether the lock is
@@ -31,6 +52,17 @@ import { runInWriteLockScope } from './write-lock-scope.js';
 export class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
    /** Backs {@link writeCancellations}. */
    protected cancelledWriteCount = 0;
+   protected readonly clock: Clock;
+   protected readonly tracer: Tracer;
+   protected readonly stalledWriteWarnMs: number;
+   protected runningWrite?: RunningWrite;
+
+   constructor(services: Pick<ServerSharedServicesMinimal, 'Clock' | 'Tracer'>, options: HydraniumWorkspaceLockOptions = {}) {
+      super();
+      this.clock = services.Clock;
+      this.tracer = services.Tracer.for(options.logName ?? 'WorkspaceLock');
+      this.stalledWriteWarnMs = options.stalledWriteWarnMs ?? DEFAULT_STALLED_WRITE_WARN_MS;
+   }
 
    /**
     * How many calls have cancelled the lock's latest write: every `write`,
@@ -45,12 +77,43 @@ export class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
    }
 
    override write(action: (token: CancellationToken) => MaybePromise<void>): Promise<void> {
-      return super.write(token => runInWriteLockScope(() => action(token)));
+      return super.write(token => runInWriteLockScope(() => this.runWrite(action, token)));
+   }
+
+   /** Run `action` as {@link runningWrite}, so a cancellation while it runs can time it. */
+   protected async runWrite(action: (token: CancellationToken) => MaybePromise<void>, token: CancellationToken): Promise<void> {
+      const running: RunningWrite = {};
+      this.runningWrite = running;
+      try {
+         await action(token);
+      } finally {
+         running.stallTimer?.dispose();
+         if (this.runningWrite === running) {
+            this.runningWrite = undefined;
+         }
+      }
    }
 
-   /** Counted here rather than in {@link write}, because Langium's `write` cancels through this method too. */
+   /**
+    * Counted here rather than in {@link write}, because Langium's `write` cancels
+    * through this method too. A write running when this is called has been
+    * cancelled, by this call or an earlier one, so its timer starts here.
+    */
    override cancelWrite(): void {
       this.cancelledWriteCount++;
+      const running = this.runningWrite;
+      if (running && !running.stallTimer && this.stalledWriteWarnMs > 0) {
+         running.stallTimer = this.clock.setTimer(() => this.reportStalledWrite(), this.stalledWriteWarnMs);
+      }
       super.cancelWrite();
    }
+
+   protected reportStalledWrite(): void {
+      this.tracer.error(
+         `A write is still running ${this.stalledWriteWarnMs} ms after it was cancelled, and every write and read waits behind it. ` +
+            'Likely causes: a model-service write or rebuild from inside a build in a host with no write-lock scope tracker, ' +
+            'which waits for the build it runs in, or a write action that ignores its cancellation token. ' +
+            'See https://github.com/eclipse-emfcloud/hydranium/issues/245.'
+      );
+   }
 }

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,6 +68,14 @@ 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
@@ -72,9 +84,9 @@ export function isInsideWriteLock(): boolean {
  * 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`, which
- * keeps the facade's build from cancelling the holder but not its wait from
- * stalling on a document that needs a re-queue.
+ * 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.
  */
 export class ReentrantWriteLockError extends Error {
    constructor(readonly uri: string) {
@@ -82,7 +94,7 @@ export class ReentrantWriteLockError extends Error {
          `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.'
+            'ModelServiceOptions.allowReentrantBuilds: true to build without the lock from inside it.'
       );
       this.name = 'ReentrantWriteLockError';
    }

package/src/testing/make-test-services.ts

@@ -218,7 +218,7 @@ export interface MakeTestServicesOptions<
    modelService?: (services: ServerSharedServices<TProject>) => ModelService<TAst, TDiagnostic, TTransfer>;
    /**
     * Framework {@link ModelServiceOptions} for the DEFAULT stub service, so a
-    * test can reach an option-gated path (`serializeBuilds`) without supplying
+    * test can reach an option-gated path (`allowReentrantBuilds`) without supplying
     * a whole {@link modelService} factory. Ignored when `modelService` is
     * given — that factory owns its own construction.
     */
@@ -312,15 +312,15 @@ export function makeTestServices<
 ): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> {
    const documents = makeStubLangiumDocuments<TAst, TDiagnostic>(options.seedDocuments);
    const textDocuments = makeStubHydraniumTextDocuments();
-   const workspaceLock = new HydraniumWorkspaceLock();
+   const logger = options.logger ?? new NoopLogger();
+   const clock = options.clock ?? new SystemClock();
+   const tracer = new DefaultTracer(logger, clock);
+   const workspaceLock = new HydraniumWorkspaceLock({ Clock: clock, Tracer: tracer });
    const documentBuilder = makeStubDocumentBuilder(workspaceLock);
    const selfSaveRegistry = makeStubSelfSaveRegistry();
    const fileSystem = makeStubWritableFileSystem(selfSaveRegistry);
    const projectManager = makeStubProjectManager<TProject>(options.seedProjects);
    const astDocumentManager = makeStubAstDocumentManager<TAst, TDiagnostic>(textDocuments, fileSystem, documents);
-   const logger = options.logger ?? new NoopLogger();
-   const clock = options.clock ?? new SystemClock();
-   const tracer = new DefaultTracer(logger, clock);
    const documentUriPolicy = options.documentUriPolicy ?? new DefaultDocumentUriPolicy();
    const serviceRegistry = options.languages
       ? makeStubServiceRegistry(options.languages, { openLanguageIds: options.openLanguageIds })

package/src/testing/stub-model-service.ts

@@ -53,7 +53,7 @@ export type StubModelService<
  * `makeTestServices` wires this stub automatically.
  *
  * `options` are the framework {@link ModelServiceOptions}, forwarded verbatim, so
- * a test can exercise an option-gated code path (`serializeBuilds`) without
+ * a test can exercise an option-gated code path (`allowReentrantBuilds`) without
  * hand-rolling a subclass just to reach the constructor.
  *
  * Adopters that need richer override behaviour — the framework's own extension