@hydranium/core 1.0.0-next.140 → 1.0.0-next.148

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

@@ -58,17 +58,17 @@ const SAVE_SETTLE_TIMEOUT_MS = 10_000;
  */
 export interface ModelServiceOptions extends LogNameOptions {
    /**
-    * Serialise the facade's own build under the workspace WRITE lock, the way
-    * Langium's `DefaultDocumentUpdateHandler` dispatches its build. Default
-    * `true`.
+    * Serialise the facade's own build under the workspace WRITE lock, through
+    * `HydraniumDocumentBuilder.scheduleUpdate` as the LSP update handler
+    * builds. Default `true`.
     *
     * **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, Langium elides the second
-    * build entirely, so the redundant work goes too.
+    * duplication compounds per rebuild. Serialised, the second request shares
+    * the first build where it carries both, so the redundant work goes too.
     *
     * **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
@@ -165,10 +165,10 @@ export interface ModelServiceOptions extends LogNameOptions {
  * implementing the URI gate at each callsite.
  *
  * **Two families, and the distinction matters more than the names suggest.**
- * `waitFor*` is a pure wait — it never triggers a build, so a caller waiting on
- * a document no build has touched waits until something else builds it.
- * `ensureDocumentState` and the phase shorthands over it *dispatch*: warm
- * documents are awaited, cold ones are built.
+ * `waitFor*` requests no build of its own: a wait on a URI with no document
+ * rejects, and one on a document no build will carry is re-queued by the
+ * builder's wait. `ensureDocumentState` and the phase shorthands over it
+ * *dispatch*: warm documents are awaited, cold ones are built.
  *
  * **Diagnostics are typed `never` below `Validated`.** Validation is the last
  * phase, so at any earlier landmark the array either is not yet computed or
@@ -397,8 +397,7 @@ export class DefaultModelService<
    /**
     * Wait for the document at `uri` to reach `state`. Pure wait — does
     * not trigger a build. If `uri` is not yet in the document registry
-    * the call will hang until something else drives it through the
-    * pipeline; for the cold-start case use {@link rebuild} instead.
+    * the call rejects; for the cold-start case use {@link rebuild} instead.
     *
     * Wrapped in a debug-level timing log via {@link Tracer.time} so
     * slow per-URI waits surface in build telemetry; the URI is
@@ -470,24 +469,23 @@ export class DefaultModelService<
     * Force a fresh build of the document at `uri` and wait for it to
     * reach `state` (or the integrity-settled landmark
     * {@link IntegrityService.SettledState} if omitted).
-    * Always triggers `DocumentBuilder.update([uri], [])` regardless of
-    * whether the document is already in the registry — call this when
-    * you want to re-process from scratch.
+    * Always builds the document, whether or not it is already in the
+    * registry, in a build of its own or in one already scheduled that carries
+    * it — call this when you want to re-process from scratch.
     *
-    * The facade is responsible for firing `DocumentBuilder.update`
-    * directly because Langium's `DefaultDocumentUpdateHandler.didChangeContent`
+    * The facade is responsible for requesting the build itself because Langium's `DefaultDocumentUpdateHandler.didChangeContent`
     * (the standard text-document → builder bridge) only runs under an
     * LSP `Connection`. Running headless the bridge never fires; the
     * facade stands in for it on its own update path.
     *
     * Coexistence with an LSP head running on the same `DocumentBuilder` is
-    * fine, but not because the builder merges the two: Langium does NOT
-    * coalesce concurrent builds of the same URI. The LSP head fires `update`
-    * from the LSP-driven event and the facade fires it from its own RPC-driven
-    * event — both legitimate — so this method takes the workspace WRITE lock,
-    * the same one Langium's own text-change bridge builds under, to serialise
-    * them. Two unserialised builds of one URI each run a full validation pass
-    * and Langium appends the second set onto the first, duplicating every
+    * fine: the LSP head builds from the LSP-driven event and the facade from
+    * its own RPC-driven event — both legitimate — and both go through
+    * `HydraniumDocumentBuilder.scheduleUpdate`, which serialises them under
+    * the workspace WRITE lock and lets the second share the first's build
+    * 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.
@@ -498,9 +496,8 @@ export class DefaultModelService<
     * base's request start a build of its own, so the write is built and
     * delivered twice.
     *
-    * Returns an empty `{ root, diagnostics }` envelope when the document
-    * cannot be loaded; adopters that want to throw override this method
-    * on their subclass.
+    * Rejects when the build leaves no document for `uri`, as for a URI with
+    * neither a file nor text: the wait after it has nothing to wait on.
     *
     * Consumers wanting "give me this doc at state X, building only if
     * needed" — use the per-state methods ({@link parsed} / {@link linked}
@@ -512,8 +509,8 @@ export class DefaultModelService<
 
    /**
     * Internal build core operating on an already-{@link CanonicalUri canonical}
-    * URI — the build counterpart to {@link waitForDocumentStateCanonical}. Drives
-    * `DocumentBuilder.update` then waits via the canonical wait core, so the
+    * URI — the build counterpart to {@link waitForDocumentStateCanonical}.
+    * Requests the build, then waits via the canonical wait core, so the
     * identity is resolved once at the public door and neither sink re-runs the
     * `realpath`. (`DocumentBuilder.update` still resolves each URI internally for
     * directory flattening — that is the build's own existence-aware resolution,
@@ -525,15 +522,15 @@ export class DefaultModelService<
       cancelToken?: CancellationToken
    ): Promise<AstDocument<TAst, TDiagnostic>> {
       const documentUri = UriUtils.toUri(uri);
-      // Runs under the workspace WRITE lock, matching Langium's own
-      // `DefaultDocumentUpdateHandler`, which dispatches its build as
-      // `workspaceLock.write(token => documentBuilder.update(...))`.
+      // Runs under the workspace WRITE lock, through the builder's
+      // `scheduleUpdate` like the LSP update handler's build, so the build the
+      // store's change event already scheduled for this write carries this
+      // request too rather than being cancelled by it.
       //
       // Unlocked, this build races the LSP bridge's build of the same URI: both
       // are legitimate (the bridge only exists under a `Connection`, so the
-      // facade stands in for it headless), and the coexistence note above relied
-      // on Langium coalescing them by URI. It does not — nothing serialises the
-      // two, so both reach `Validated`, and because each computes its missing
+      // facade stands in for it headless), and nothing serialises the two, so
+      // both reach `Validated`, and because each computes its missing
       // validation categories before the other has recorded its own, both run a
       // FULL pass and Langium appends the second onto the first (its append is
       // meant for category-partitioned passes). The user-visible result is every
@@ -556,13 +553,9 @@ export class DefaultModelService<
          if (isInsideWriteLock()) {
             throw new ReentrantWriteLockError(uri);
          }
-         // The lock's OWN token, not the caller's: a later `write` cancels the
-         // running one through that token, so substituting the caller's would
-         // leave this build deaf to the lock's cancellation protocol. A caller
-         // token still governs the phase wait below.
-         await this.services.workspace.WorkspaceLock.write(lockToken =>
-            this.services.workspace.DocumentBuilder.update([documentUri], [], lockToken)
-         );
+         // 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);
       }

package/src/langium/module.ts

@@ -160,12 +160,11 @@ export interface ServerAddedSharedServices<
        * the `awaitDocumentState` bug-fix, framework-wired phase logs,
        * and the `markNextReason` observability primitive without
        * binding the slot explicitly. The
-       * `HydraniumDocumentUpdateHandler`'s `dispatch` calls this
-       * slot's `markNextReason` to stage the LSP event that triggered
-       * the build, for a subclass's build logging to tag its line with,
-       * so narrowing here is a load-bearing type contract — adopters who
-       * explicitly downgrade to Langium's default lose that call site's
-       * compile-time target.
+       * `HydraniumDocumentUpdateHandler`'s `dispatch` and
+       * `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.
        */
       /* override */ DocumentBuilder: HydraniumDocumentBuilder;
       /**

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

@@ -29,7 +29,28 @@ import { runInWriteLockScope } from './write-lock-scope.js';
  * would turn ordinary read-then-write sequences into false positives.
  */
 export class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
+   /** Backs {@link writeCancellations}. */
+   protected cancelledWriteCount = 0;
+
+   /**
+    * How many calls have cancelled the lock's latest write: every `write`,
+    * which cancels the write before it, and every `cancelWrite`. A caller that
+    * reads this right after queuing a write, and reads the same number later,
+    * holds a write nothing has cancelled, whether it is still queued or
+    * already running. Its token answers that only once the write runs, since
+    * a queued write has not been handed it yet.
+    */
+   get writeCancellations(): number {
+      return this.cancelledWriteCount;
+   }
+
    override write(action: (token: CancellationToken) => MaybePromise<void>): Promise<void> {
       return super.write(token => runInWriteLockScope(() => action(token)));
    }
+
+   /** Counted here rather than in {@link write}, because Langium's `write` cancels through this method too. */
+   override cancelWrite(): void {
+      this.cancelledWriteCount++;
+      super.cancelWrite();
+   }
 }

package/src/lsp/hydranium-document-update-handler.ts

@@ -81,10 +81,11 @@ export interface HydraniumDocumentUpdateHandlerOptions {
  *  3. **Build-reason stamping** — the LSP event overrides
  *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`)
  *     populate {@link nextReason} with a canonical reason string.
- *     {@link fireDocumentUpdate} captures the reason; {@link dispatch} stages
- *     it on the builder via {@link HydraniumDocumentBuilder.markNextReason},
- *     so a subclass that formats build logs can tag its line with the event
- *     that caused the build without per-adopter wiring to capture it.
+ *     {@link fireDocumentUpdate} captures the reason; {@link dispatch} hands
+ *     it to {@link HydraniumDocumentBuilder.scheduleUpdate}, which stages it
+ *     through {@link HydraniumDocumentBuilder.markNextReason} when the build
+ *     runs, so a subclass that formats build logs can tag its line with the
+ *     event that caused the build without per-adopter wiring to capture it.
  *  4. **Editor save gate** ({@link willSaveDocumentWaitUntil}) — the editor
  *     writes the file itself, so the server's disk writes of that document
  *     are ordered around it: the editor's save waits for the ones already
@@ -102,13 +103,12 @@ export interface HydraniumDocumentUpdateHandlerOptions {
  * Adopters with their own handler subclass should extend this class
  * (not Langium's `DefaultDocumentUpdateHandler`) so all of them are
  * preserved. The {@link dispatch} hook is the canonical override
- * point for adopters that need to stamp additional per-build metadata
- * inside the workspace-lock callback.
+ * point for adopters that need to stamp additional per-build metadata.
  */
 export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler {
    /**
     * Narrow Langium's `DefaultDocumentUpdateHandler.documentBuilder` typing to
-    * the framework subclass: `markNextReason` is the only method this handler
+    * the framework subclass: `scheduleUpdate` is the only method this handler
     * reaches for beyond the Langium interface.
     */
    declare protected readonly documentBuilder: HydraniumDocumentBuilder;
@@ -140,9 +140,9 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
    protected nextReason?: string;
    /**
     * Build-reason captured at `fireDocumentUpdate` time, drained by
-    * {@link dispatch} into `markNextReason`. Survives across debounced
-    * batches (`?? pendingReason` in `fireDocumentUpdate` retains the
-    * first reason in a coalesced burst).
+    * {@link dispatch} into the scheduled build. Survives across debounced
+    * batches: `fireDocumentUpdate` replaces it with each event's reason, so a
+    * coalesced burst carries its latest.
     */
    protected pendingReason?: string;
 
@@ -342,15 +342,13 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
     * flush immediately (`immediateFlush` or `debounceMs <= 0`) or restart
     * the trailing-edge timer. Subclasses that need to stamp per-build
     * metadata can override and inspect the merged sets — but the canonical
-    * override point for the workspace-lock callback is {@link dispatch},
-    * not this method.
+    * override point for the build is {@link dispatch}, not this method.
     */
    protected override fireDocumentUpdate(changed: URI[], deleted: URI[]): void {
       // Capture the reason set by the LSP event handler immediately before
-      // we merge into the pending sets. `?? pendingReason` keeps the
-      // first reason in a coalesced burst (LSP events arriving inside an
-      // active debounce window all stamp the same `pendingReason` once,
-      // because subsequent stamps see the field already non-undefined).
+      // we merge into the pending sets. Each event stamps its own reason, so
+      // a coalesced burst carries its latest; `?? pendingReason` keeps the
+      // earlier one only for a call no event stamped.
       this.pendingReason = this.nextReason ?? this.pendingReason;
       this.nextReason = undefined;
       for (const uri of changed) {
@@ -388,26 +386,25 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
    }
 
    /**
-    * Workspace-lock + `documentBuilder.update` call for the merged sets.
-    * Mirrors Langium's `super.fireDocumentUpdate` body plus
-    * `markNextReason(pendingReason)` inside the write-lock callback, so the
-    * build the lock is about to run carries the LSP event that triggered it.
-    * Adopters override to stamp additional per-build metadata — the canonical
-    * pattern is to read the reason via `this.pendingReason`, call
-    * `super.dispatch(...)` or replicate the
-    * `workspaceManager.ready -> workspaceLock.write` block, and add
-    * adopter-specific behaviour inside the write callback.
+    * Build the merged sets once the workspace is ready, through
+    * {@link HydraniumDocumentBuilder.scheduleUpdate} with the pending reason,
+    * so the build carries the LSP event that triggered it. A session's write
+    * fires the store's change event before the session rebuilds the document
+    * itself, and the scheduled build is what the two share.
+    *
+    * Adopters override to stamp additional per-build metadata: read the reason
+    * via `this.pendingReason` and call `super.dispatch(...)`; the build may
+    * be shared with other requests, so metadata stamped for it describes
+    * theirs too. An override that needs code inside the write action takes
+    * `workspaceLock.write` itself, as Langium's `fireDocumentUpdate` does, and
+    * stages the reason through `markNextReason` there; its build then cancels
+    * a scheduled one it coincides with rather than sharing it.
     */
    protected dispatch(changed: URI[], deleted: URI[]): void {
       const reason = this.pendingReason;
       this.pendingReason = undefined;
       this.workspaceManager.ready
-         .then(() =>
-            this.workspaceLock.write(token => {
-               this.documentBuilder.markNextReason(reason);
-               return this.documentBuilder.update(changed, deleted, token);
-            })
-         )
+         .then(() => this.documentBuilder.scheduleUpdate(changed, deleted, reason))
          .catch(err => {
             // A deferred rebuild can finish after the LSP peer has gone away.
             // Unless the head was started through `startLanguageServer`, whose

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

@@ -312,7 +312,8 @@ export function makeTestServices<
 ): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> {
    const documents = makeStubLangiumDocuments<TAst, TDiagnostic>(options.seedDocuments);
    const textDocuments = makeStubHydraniumTextDocuments();
-   const documentBuilder = makeStubDocumentBuilder();
+   const workspaceLock = new HydraniumWorkspaceLock();
+   const documentBuilder = makeStubDocumentBuilder(workspaceLock);
    const selfSaveRegistry = makeStubSelfSaveRegistry();
    const fileSystem = makeStubWritableFileSystem(selfSaveRegistry);
    const projectManager = makeStubProjectManager<TProject>(options.seedProjects);
@@ -366,7 +367,7 @@ export function makeTestServices<
          // Spread for the same reason as `ServiceRegistry` above — the slot must
          // be genuinely ABSENT, not present-and-undefined, when no index was seeded.
          ...(indexManager ? { IndexManager: indexManager } : {}),
-         WorkspaceLock: new HydraniumWorkspaceLock(),
+         WorkspaceLock: workspaceLock,
          FileSystemTaskQueue: new DefaultFileSystemTaskQueue({ workspace: { DocumentUriPolicy: documentUriPolicy } })
       },
       model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic>['model'],

package/src/testing/stub-document-builder.ts

@@ -14,7 +14,8 @@ import {
    type DocumentState,
    type DocumentUpdateListener,
    type LangiumDocument,
-   type URI
+   type URI,
+   type WorkspaceLock
 } from '@hydranium/langium';
 import { type CancellationToken, Disposable } from 'vscode-languageserver';
 import { type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
@@ -65,16 +66,17 @@ export interface StubWaitUntilGate {
  * Picks the methods the framework reads from {@link DocumentBuilder} on
  * the slot path — the compiler enforces those signatures stay aligned.
  * `update`, `onDocumentPhase`, `onUpdate`, and `waitUntil` carry stubbed
- * implementations; `build`, `onBuildPhase`, and `resetToState` are
- * implemented as loud-failing `notSupported` throwers so production code
- * that goes through the cast at the bind site (i.e. accesses methods the
+ * implementations, and `scheduleUpdate` calls `update` in one lock write per
+ * call (see {@link makeStubDocumentBuilder}); `build`, `onBuildPhase`, and
+ * `resetToState` are implemented as loud-failing `notSupported` throwers
+ * so production code that goes through the cast at the bind site (i.e. accesses methods the
  * stub claims but doesn't meaningfully implement) fails with a clear
  * message instead of "undefined is not a function".
  */
 export interface StubDocumentBuilder
    extends
       Pick<DocumentBuilder, 'update' | 'onDocumentPhase' | 'onUpdate' | 'build' | 'onBuildPhase' | 'resetToState' | 'updateBuildOptions'>,
-      Pick<HydraniumDocumentBuilder, 'onDocumentPhaseDelivered'> {
+      Pick<HydraniumDocumentBuilder, 'onDocumentPhaseDelivered' | 'scheduleUpdate'> {
    /**
     * Single-overload stub of {@link DocumentBuilder.waitUntil}. Real has
     * two overloads (`(state, cancelToken?): Promise<void>` and
@@ -138,8 +140,13 @@ function reraise(result: unknown): void {
  * want to observe rebuilt state should `set` the new root on the document
  * registry and then call `firePhase` to trigger the framework's post-build
  * read path.
+ *
+ * `workspaceLock` is the lock `scheduleUpdate` writes under, without the real
+ * builder's sharing: pass the services tree's own, so a caller's lock ordering
+ * and reentrancy behave as against the real builder. Without one,
+ * `scheduleUpdate` records the update unlocked.
  */
-export function makeStubDocumentBuilder(): StubDocumentBuilder {
+export function makeStubDocumentBuilder(workspaceLock?: WorkspaceLock): StubDocumentBuilder {
    const phaseListeners = new Map<DocumentState, DocumentPhaseListener[]>();
    const deliveredListeners = new Map<DocumentState, Array<(document: LangiumDocument, version: number) => void>>();
    const buildPhaseListeners = new Map<DocumentState, DocumentBuildListener[]>();
@@ -164,6 +171,9 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
       async update(changed: URI[], deleted: URI[]) {
          updateCalls.push({ args: [changed, deleted] });
       },
+      scheduleUpdate(changed: URI[], deleted: URI[]) {
+         return workspaceLock ? workspaceLock.write(() => stub.update(changed, deleted)) : stub.update(changed, deleted);
+      },
       async waitUntil(state: DocumentState, uri?: URI) {
          waitUntilCalls.push({ args: [state, uri] });
          const gate = gates.shift();