@hydranium/core 1.0.0-next.19 → 1.0.0-next.192

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

@@ -9,42 +9,50 @@
 
 import {
    type CanonicalUri,
-   type CloseModelArgs,
-   ConflictError,
-   Logger,
+   defineMessage,
    type MaybeObservableValue,
    type MaybePromise,
    ObservableValue,
-   type TransferDiagnostic,
+   TIMED_OUT,
    type TransferElement,
-   type OpenModelArgs,
+   type TextVersion,
    type Tracer,
-   type TransferSaveArgs,
-   type TransferUpdateArgs
+   UNRECORDED_VERSION
 } from '@hydranium/protocol';
-import { type AstNode, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+import { type AstNode, DocumentState, type LangiumDocument, OperationCancelled, 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 { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import { ReentrantWriteLockError, isInsideWriteLock, isWriteLockScopeInstalled } from '../workspace/write-lock-scope.js';
+import { 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';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { IntegrityService } from '../integrity/integrity-service.js';
 import { labelPhaseListener } from '../document-builder/labeled-phase-listener.js';
 import { LANGUAGE_CLIENT_ID } from '../../documents/client-ids.js';
+import { type OpenOptions } from '../../documents/client-session-registry.js';
 import { type ServerSharedServices } from '../module.js';
-
-/** Max time {@link ModelService.settleSave} waits for the build to settle and the sync chain to drain. */
-const SAVE_SETTLE_TIMEOUT_MS = 10_000;
+import { type ClientSession } from './client-session.js';
 
 /**
- * Marks the {@link SAVE_SETTLE_TIMEOUT_MS} branch of
- * {@link ModelService.settleSave}'s race so it stays distinguishable from a
- * genuine rejection (a cancelled token, an `applyEdit` reverse-RPC error, a
- * build throw). With a plain `Error` the only log line an adopter has blames
- * the timeout for every one of them, which points debugging at the wrong layer.
+ * The undo-stack entry for a server-authored write pushed to the editor.
+ *
+ * **A user-facing LABEL, not a log string**, which is easy to miss because it
+ * travels as an options field rather than as a message: LSP specifies
+ * `ApplyWorkspaceEditParams.label` as "presented in the user interface for
+ * example on an undo stack to undo the workspace edit". So a user who edits
+ * through a form or drags a diagram node reads this in their editor's undo menu
+ * — which is why it is rendered like any other message the server sends rather
+ * than left as the English literal it was.
+ *
+ * Parameterless deliberately. The obvious improvement is to name the document,
+ * and it is the wrong one: an undo menu is already grouped under the file, so
+ * the URI would be noise in the one place it is redundant.
  */
-class SaveSettleTimeoutError extends Error {}
+export const MODEL_UPDATE_EDIT = defineMessage('hydranium/core/model-update-edit', 'Update Model');
+
+/** Max time {@link DefaultModelService.settleSave} waits for the build to settle and the sync chain to drain. */
+const SAVE_SETTLE_TIMEOUT_MS = 10_000;
 
 /**
  * Constructor options for {@link ModelService}. All fields are optional,
@@ -52,75 +60,57 @@ class SaveSettleTimeoutError extends Error {}
  */
 export interface ModelServiceOptions extends LogNameOptions {
    /**
-    * When set, {@link ModelService.update} logs a `warn` line if its
-    * end-to-end wait (serialise + content-change apply + rebuild +
-    * settled-phase wait) exceeds this many milliseconds. Default
-    * `undefined` (no warn line ever emitted; the underlying
-    * `Logger.time` debug timing log is unchanged either way).
-    *
-    * Pure observability — does NOT abort the update, does NOT change
-    * resolution semantics. Adopters wanting a hard timeout that throws
-    * instead override {@link ModelService.update} on their subclass and
-    * race the parent call against their own deadline.
-    *
-    * Recommended starting threshold: 2-5 seconds for interactive paths
-    * (form save, diagram edit). Workspaces with very large documents
-    * or slow validation may legitimately exceed 5s on the cold path —
-    * tune per workspace.
-    *
-    * Accepts a {@link MaybeObservableValue} so the threshold can be a
-    * fixed constant or bound to a user setting via `Settings.number`
-    * and retuned live. Leaving it unset disables the warn line entirely
-    * (and skips the per-update stopwatch).
-    */
-   readonly slowUpdateWarnMs?: MaybeObservableValue<number>;
-   /**
-    * Serialise the facade's own build under the workspace WRITE lock, the way
-    * Langium's `DefaultDocumentUpdateHandler` dispatches its build. 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.
+    * 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`.
     *
-    * **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.
+    * `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` buys.** `WorkspaceLock` is not reentrant. A caller that
-    * reaches `update` / `save` / `rebuild` while already holding the write lock —
-    * an integrity rule or build-phase pass that writes through this facade —
-    * 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 — nothing acquires the
-    * lock then, so there is nothing to be reentrant about; prefer it over
-    * unserialised 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>;
+}
+
+/** Options for a {@link DefaultModelService} wait on one document. */
+export interface SyncedWaitOptions {
+   /**
+    * Build a root parsed from text older than the store's at the call, and
+    * reject once that build, or one the builder re-queues, is given up. Without
+    * it, such a root is left to other builds, and a wait they never end stays
+    * pending until its token is cancelled.
+    */
+   readonly sync?: boolean;
 }
 
 /**
+ * The seam every non-LSP head talks to: the data server, the GLSP head and an
+ * adopter's own services reach documents through this slot rather than through
+ * the workspace stores.
+ *
  * In-process facade over the framework's document plumbing
  * (`HydraniumTextDocuments`, `LangiumDocuments`,
- * `DocumentBuilder`, `WritableFileSystemProvider`). Owns the
- * `open / request / update / save / ready` lifecycle that protocol heads
- * (LSP, data-server, GLSP) delegate to so coordinating those primitives
- * doesn't have to be re-implemented per-head.
+ * `DocumentBuilder`, `WritableFileSystemProvider`). Owns the document
+ * lifecycle the data-server and GLSP heads delegate to — client sessions that
+ * open, update, save and close documents, the phase reads, and `ready` — so
+ * coordinating those primitives doesn't have to be re-implemented per head.
+ * Every open and write goes through a session from {@link createSession}.
  *
  * "Model" here means the parsed AST — distinct from the wire-shape
  * `TransferDocument` in `@hydranium/protocol`.
@@ -130,9 +120,9 @@ export interface ModelServiceOptions extends LogNameOptions {
  * Multiple in-process consumers want the same workspace-level
  * operations:
  * - The data-server head turns these into typed RPC methods.
- * - The GLSP head uses the same lifecycle for diagram-driven edits;
- *   GModel operation handlers route through `update` for AST mutation,
- *   `waitForDocumentState` for indexed-phase waits before reads, etc.
+ * - The GLSP head uses the same lifecycle for diagram-driven edits: GModel
+ *   operation handlers write through the diagram's session and wait on phases
+ *   before reading.
  * - Server-internal callers (integrity service, ad-hoc bridges, tests)
  *   want the same operations without the wire serialisation step.
  *
@@ -145,15 +135,16 @@ export interface ModelServiceOptions extends LogNameOptions {
  *
  * **Read-latest supersession**
  *
- * The default `update` and `save` flows use Langium's per-URI
- * `DocumentBuilder.waitUntil` to wait for the integrity-settled landmark
- * ({@link IntegrityService.SettledState}), then read the post-build state. Concurrent
- * in-process callers on the same URI all see the latest post-build
- * snapshot — none deadlock waiting for a specific version's settled
- * event. Adopters wanting strict version-matched semantics (resolve
- * with vN's snapshot specifically, log "vN superseded by vM at vN+1")
- * override {@link update} to attach a phase-listener with explicit
- * version checks; the framework default doesn't need it for safety.
+ * A session's default `update` and `save` use Langium's per-URI
+ * `DocumentBuilder.waitUntil` to wait for `Validated` (the integrity-settled
+ * landmark {@link IntegrityService.SettledState} when rebuilds do not
+ * validate), then read the post-build state. Concurrent in-process callers
+ * on the same URI all see the latest post-build snapshot — none deadlock
+ * waiting for a specific version's settled event. Adopters wanting strict
+ * version-matched semantics (resolve with vN's snapshot specifically, log
+ * "vN superseded by vM at vN+1") override
+ * `DefaultClientSession.updateDocument` to attach a phase-listener with
+ * explicit version checks; the framework default doesn't need it for safety.
  *
  * **Returns AST snapshots, not wire envelopes**
  *
@@ -173,20 +164,129 @@ export interface ModelServiceOptions extends LogNameOptions {
  * by URI happens here so consumers can subscribe per-document without
  * implementing the URI gate at each callsite.
  *
+ * **Two families.** `waitFor*` only waits: it rejects for a URI with no
+ * document, and for a root behind the store's text it waits for whatever
+ * builds it next, so it never ends if nothing does. `ensureDocumentState` and
+ * the phase shorthands over it build a missing document, and build a root
+ * behind its text, rejecting when that build fails twice. Both re-queue a
+ * document the builder's last build left short of the state.
+ *
+ * Both resolve at the state with a root parsed from text no older than the
+ * store's version at the call; inside the write lock, at the state alone, since
+ * the build that would sync the document to that version cannot start until
+ * it is released.
+ *
+ * Do not await one inside a build phase listener: a browser host installs no
+ * write-lock scope, so the wait cannot tell it is inside a build and waits for
+ * one that cannot start. Nor inside a `WorkspaceLock.read`: the lock starts no
+ * write, the build included, while a read runs.
+ *
+ * **Diagnostics are typed `never` below `Validated`.** Validation is the last
+ * phase, so at any earlier landmark the array either is not yet computed or
+ * still holds the previous build's, and reading it would take stale results
+ * for fresh ones. A caller that needs diagnostics asks for {@link validated}.
+ *
+ * What the `never` buys, exactly: reading a field off an element is a compile
+ * error, and nothing can be appended. It does NOT stop a caller assigning an
+ * element to a typed variable, because `never` is assignable to everything — so
+ * this is a guard against reaching for diagnostics by accident, not a seal
+ * against doing it deliberately.
+ *
+ * The waits resolve at or ABOVE their target, so an already-validated document
+ * does carry usable diagnostics and the `never` over-forbids there. That
+ * direction is the safe one: the alternative permits stale reads silently. A
+ * member taking a phase as a PARAMETER returns `TDiagnostic`, and leaves them
+ * absent for a phase below `Validated`.
+ *
  * **Generic parameters.**
  * - `TAst` — the AST root type each consumer expects on the returned
  *   {@link AstDocument}. Constrained to {@link AstNode}.
- * - `TDiagnostic` — wire diagnostic shape used by the injected
- *   `TransferEncoder`. Defaults to {@link TransferDiagnostic}.
- * - `TTransfer` — transfer-model root accepted by `update` / `save`
+ * - `TDiagnostic` — the AST-layer diagnostic: whatever the build left on
+ *   `LangiumDocument.diagnostics`, carried through on the returned
+ *   {@link AstDocument}. Defaults to {@link AstDiagnostic}.
+ *   **Not the `TransferEncoder`'s parameter of the same name**, which is
+ *   that encoder's OUTPUT and so names the wire shape. This one names its
+ *   input, and an adopter binds the two to different types.
+ * - `TTransfer` — transfer-model root a session's `update` / `save` accept
  *   args. Constrained to {@link TransferElement}. Defaults to the
  *   structural base.
  */
-export class ModelService<
+export interface ModelService<
    TAst extends AstNode,
-   TDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
+   TTransfer extends TransferElement = TransferElement
+> {
+   /**
+    * Resolves once the workspace has been initialised and its first build has
+    * completed — the gate every read should wait behind, since a document
+    * queried before it may be unbuilt and reach no phase.
+    *
+    * A property rather than a method, matching `ProjectManager.ready` and
+    * Langium's `WorkspaceManager.ready`. An implementation needing a stricter
+    * gate supplies a Promise that awaits its own concern as well.
+    */
+   readonly ready: Promise<void>;
+
+   // Wait only; a root behind its text is left to another build.
+   waitForDocumentState(uri: string, state: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   waitForBuilderState(state: DocumentState, cancelToken?: CancellationToken): Promise<void>;
+
+   // Build what is missing or behind its text, then wait.
+   ensureDocumentState(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   rebuild(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   /**
+    * Throw where {@link rebuild} would reject as reentrant. A write calls it
+    * before applying its text: a text applied and then refused stays applied
+    * with no build to follow it.
+    */
+   assertCanBuild(uri: string): void;
+   parsed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   linked(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   settled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+
+   isOpen(uri: string): boolean;
+   snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined;
    /**
-    * Structured payload accepted by `update` / `save`. Constrained to
+    * The text a session's write of `model` to `uri` applies: a textual model
+    * as given, a structured one rewritten and serialised.
+    */
+   modelToText(uri: string, model: TTransfer | string, cancelToken?: CancellationToken): Promise<string>;
+   getDocument(uri: string): LangiumDocument | undefined;
+
+   onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onModelSaved(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
+
+   /**
+    * Start a client session, the only way to open and write documents through
+    * this service. Pass a `label` naming the participant; without one it is
+    * `session`. The id defaults to `label#` plus a random UUID; a fixed
+    * `clientId` is taken as given. Throws `ReservedClientIdError` when the id
+    * is reserved by the framework, and `DuplicateClientIdError` when it is
+    * held by another live session or has documents open under it as a client
+    * that is not a session.
+    *
+    * `TOpenOptions` types the options the session's `open` takes and its
+    * `openOptions` returns. The narrowing is an unchecked cast, and it holds
+    * only for the caller that started the session: a holder reached through
+    * {@link getSession} sees plain `OpenOptions`.
+    */
+   createSession<TOpenOptions extends OpenOptions = OpenOptions>(
+      label?: string,
+      clientId?: string
+   ): ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>;
+   /** The live session started under `clientId`, or `undefined` once it has ended or was never started. */
+   getSession(clientId: string): ClientSession<TAst, TDiagnostic, TTransfer> | undefined;
+}
+
+export class DefaultModelService<
+   TAst extends AstNode,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
+   /**
+    * Structured payload a session's `update` / `save` accept. Constrained to
     * {@link TransferElement} — the minimal `{ readonly $type: string }`
     * shape. Both transfer-model overlay roots (which extend
     * `TransferElement` explicitly) and AST root types (which have
@@ -195,7 +295,7 @@ export class ModelService<
     * integrity service) that pass AST roots remain compatible.
     */
    TTransfer extends TransferElement = TransferElement
-> {
+> implements ModelService<TAst, TDiagnostic, TTransfer> {
    protected readonly tracer: Tracer;
    /**
     * The single document-identity seam (`services.workspace.DocumentUriPolicy`),
@@ -206,14 +306,8 @@ export class ModelService<
     * (see {@link DocumentUriPolicy}).
     */
    protected readonly uriPolicy: DocumentUriPolicy;
-   /**
-    * Live slow-update-warn threshold cell, or `undefined` when the option
-    * was not supplied (warn line + stopwatch disabled). Reads `.value` per
-    * update so a setting-bound threshold retunes without reconstruction.
-    */
-   protected readonly slowUpdateWarn?: ObservableValue<number>;
-   /** 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`
@@ -224,6 +318,16 @@ export class ModelService<
    protected readonly syncChains = new Map<string, Promise<void>>();
    protected readonly pendingSync = new Map<string, string>();
 
+   /** The live sessions this service started, by client id, for {@link getSession}. */
+   protected readonly sessions = new Map<string, ClientSession<TAst, TDiagnostic, TTransfer>>();
+   /**
+    * Drops an ended session from {@link sessions}. Subscribed by the first
+    * {@link createSession} rather than at construction, so a services tree with
+    * no text store, or one that knows nothing of sessions, still constructs
+    * this service.
+    */
+   protected sessionCloseListener?: Disposable;
+
    /**
     * Workspace-level readiness gate. Resolves when the framework has
     * finished its first workspace build cycle and the `ModelService`
@@ -264,21 +368,17 @@ export class ModelService<
    ) {
       this.tracer = services.Tracer.for(options.logName ?? 'ModelService').trace('instantiated');
       this.uriPolicy = services.workspace.DocumentUriPolicy;
-      this.slowUpdateWarn = options.slowUpdateWarnMs !== undefined ? ObservableValue.from(options.slowUpdateWarnMs) : undefined;
-      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.
       // Deliberately NO fallback to Langium's `ready`: it resolves pre-build,
       // so falling back to it would silently reinstate the very gap this gate
       // exists to close.
-      // Captured rather than read off `this` inside the closure, which TS cannot
-      // prove runs after the field is assigned.
-      const tracer = this.tracer;
       this.ready = (async () => {
          try {
             await services.workspace.WorkspaceManager?.workspaceInitialized;
-         } catch (error: unknown) {
+         } catch {
             // NEVER rejects, deliberately. This gate is about TIMING — "the
             // initial build has finished" — not about whether it succeeded, and
             // Langium's `ready` (what it replaced) could not reject at all.
@@ -286,8 +386,8 @@ export class ModelService<
             // build (routine — any write preempts one) and on a failed one
             // (e.g. a disposed connection at teardown). Propagating either would
             // fail every `waitForReady` for the rest of the process lifetime,
-            // a far worse failure than the late gate this exists to fix.
-            tracer.debug(`Initial workspace build did not complete cleanly: ${error instanceof Error ? error.message : String(error)}`);
+            // a far worse failure than the late gate this exists to fix. The
+            // workspace manager logs the outcome.
          }
       })();
       // One persistent listener mirroring non-LSP-client changes back to the LSP
@@ -309,10 +409,12 @@ export class ModelService<
    // ============================================================
 
    /**
-    * 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.
+    * Wait for the document at `uri` to reach `state` with a root no older than
+    * the store's text at the call. Rejects if `uri` is not in the document
+    * registry. A root behind its text is not built: the wait lasts until
+    * something else builds it, so use {@link ensureDocumentState} where
+    * nothing may. Builds that keep failing leave the wait pending, to its
+    * cancellation token.
     *
     * Wrapped in a debug-level timing log via {@link Tracer.time} so
     * slow per-URI waits surface in build telemetry; the URI is
@@ -326,11 +428,12 @@ export class ModelService<
     * Wait for the document at `uri` to reach the integrity-settled landmark
     * ({@link IntegrityService.SettledState}) — the earliest phase at which the
     * AST + serialised text are stable post-integrity. Convenience wrapper over
-    * {@link waitForDocumentState} for the common "wait until content is stable"
-    * case (e.g. settling a save). Pure wait — does not trigger a build.
+    * {@link waitForDocumentState}, and like it builds nothing behind its text.
     */
-   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
-      return this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), IntegrityService.SettledState, cancelToken);
+   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
+      return this.withoutDiagnostics(
+         await this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), IntegrityService.SettledState, cancelToken)
+      );
    }
 
    /**
@@ -342,21 +445,108 @@ export class ModelService<
     * the identity once instead of re-running the (filesystem-touching) `realpath`
     * at every wait. The `CanonicalUri` parameter type enforces that — a raw
     * `string` cannot be passed without minting through the URI policy.
+    *
+    * With `options.sync`, a root behind the store's text is built, as in
+    * {@link ensureDocumentState}; without it, the root is left to other builds,
+    * as in {@link waitForDocumentState}. Below `Validated` the envelope has no
+    * diagnostics: see {@link withoutDiagnostics}.
     */
    protected async waitForDocumentStateCanonical(
       uri: CanonicalUri,
       state: DocumentState,
-      cancelToken?: CancellationToken
+      cancelToken?: CancellationToken,
+      options: SyncedWaitOptions = {}
    ): Promise<AstDocument<TAst, TDiagnostic>> {
       const documentUri = UriUtils.toUri(uri);
+      // Read at call time: a later edit must not extend this wait.
+      const textVersion = isInsideWriteLock() ? undefined : this.services.workspace.TextDocuments.textState(uri)?.version;
       await this.tracer
          .withUri(uri)
          .time(
             `Wait for document state '${DocumentState[state]}'`,
-            () => this.services.workspace.DocumentBuilder.waitUntil(state, documentUri, cancelToken),
+            () => this.waitUntilSynced(documentUri, state, textVersion, cancelToken, options),
             'debug'
          );
-      return this.toAstDocument(documentUri);
+      const document = this.toAstDocument(documentUri);
+      return state >= DocumentState.Validated ? document : this.withoutDiagnostics(document);
+   }
+
+   /**
+    * Wait for `state` with a root parsed from text at `textVersion` or later. A
+    * root no factory recorded counts as synced, since no build records it.
+    * With `options.sync`, a root still behind is built through
+    * `VersionSyncService.syncTo`, and the wait rejects once that build, or one
+    * the builder re-queues to reach `state`, is given up. Without it, the wait
+    * lasts until another build parses the text, and stays pending when the
+    * builder gives up re-queuing the document.
+    */
+   protected async waitUntilSynced(
+      uri: URI,
+      state: DocumentState,
+      textVersion: TextVersion | undefined,
+      cancelToken?: CancellationToken,
+      options: SyncedWaitOptions = {}
+   ): Promise<void> {
+      const builder = this.services.workspace.DocumentBuilder;
+      const sync = this.services.workspace.VersionSyncService;
+      const waitOptions = { rejectWhenStuck: options.sync === true };
+      await builder.waitUntil(state, uri, cancelToken, waitOptions);
+      if (textVersion === undefined) {
+         return;
+      }
+      while (!sync.isSyncedTo(uri, textVersion)) {
+         const build = options.sync === true ? sync.syncTo(uri, textVersion) : undefined;
+         this.tracer
+            .withUri(uri.toString())
+            .debug(`waiting for ${uri.toString()} to reach ${DocumentState[state]} at v${textVersion} or later`);
+         await this.nextParseOrDeletion(uri, cancelToken, build);
+         await builder.waitUntil(state, uri, cancelToken, waitOptions);
+      }
+   }
+
+   /**
+    * Resolves once a parse of `uri` has been recorded or a build has deleted
+    * it, rejecting with `OperationCancelled` when `cancelToken` is cancelled
+    * first, and with an error when `build`, the build requested for it, is
+    * given up. A `Parsed` phase listener cannot serve: a cancel right after the
+    * parse skips it, and the resumed build does not parse again.
+    */
+   protected nextParseOrDeletion(
+      uri: URI,
+      cancelToken: CancellationToken = CancellationToken.None,
+      build?: Promise<boolean>
+   ): Promise<void> {
+      const builder = this.services.workspace.DocumentBuilder;
+      return new Promise<void>((resolve, reject) => {
+         // A cancelled token's listener runs a macrotask later, after a build
+         // that started meanwhile may have parsed.
+         if (cancelToken.isCancellationRequested) {
+            reject(OperationCancelled);
+            return;
+         }
+         const done = (settle: () => void): void => {
+            parsed.dispose();
+            deleted.dispose();
+            cancelled.dispose();
+            settle();
+         };
+         const parsed = this.services.workspace.VersionSyncService.onDidRecordModel(document => {
+            if (UriUtils.equals(document.uri, uri)) {
+               done(resolve);
+            }
+         });
+         const deleted = builder.onUpdate((_changed, deletedUris) => {
+            if (deletedUris.some(deletedUri => UriUtils.equals(deletedUri, uri))) {
+               done(resolve);
+            }
+         });
+         const cancelled = cancelToken.onCancellationRequested(() => done(() => reject(OperationCancelled)));
+         void build?.then(built => {
+            if (!built) {
+               done(() => reject(new Error(`The build that would sync ${uri.toString()} to its text failed`)));
+            }
+         });
+      });
    }
 
    /**
@@ -380,31 +570,35 @@ export class ModelService<
     * 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
-    * diagnostic. Opt out via
-    * {@link ModelServiceOptions.serializeBuilds} — see there for the
-    * non-reentrancy hazard that is the reason the opt-out exists.
+    * 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. 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
+    * session's write; an override whose await outlasts that build makes the
+    * 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}
@@ -416,8 +610,8 @@ export class ModelService<
 
    /**
     * 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,
@@ -429,66 +623,61 @@ export class ModelService<
       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
       // 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 there is nothing to be reentrant
-         // about, 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()) {
-            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)
-         );
-      } else {
+      // 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.
+      if (this.allowReentrantBuilds.value && (isInsideWriteLock() || !isWriteLockScopeInstalled())) {
          await this.services.workspace.DocumentBuilder.update([documentUri], [], cancelToken);
+      } else {
+         this.assertCanBuild(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], []);
+      }
+      return this.waitForDocumentStateCanonical(uri, state ?? IntegrityService.SettledState, cancelToken, { sync: true });
+   }
+
+   assertCanBuild(uri: string): void {
+      if (isInsideWriteLock() && !this.allowReentrantBuilds.value) {
+         throw new ReentrantWriteLockError(uri);
       }
-      return this.waitForDocumentStateCanonical(uri, state ?? IntegrityService.SettledState, cancelToken);
    }
 
    /**
     * Per-state typed convenience methods. Each ensures the document at
     * `uri` reaches the named phase and returns the AST envelope with
-    * the narrowest accurate diagnostics type for that phase. Smart
-    * dispatch internally: warm path (URI already in the document
-    * registry) just waits via {@link waitForDocumentState}; cold path
-    * triggers a build via {@link rebuild}. Consumers do not need to
-    * know which path was taken.
+    * the narrowest accurate diagnostics type for that phase, building as
+    * {@link ensureDocumentState} does.
     *
     * Phase invariants encoded in the return type:
     * - `parsed` / `linked` / `settled` / `indexed` return
-    *   `AstDocument<TAst, never>` — diagnostics array is empty by phase
-    *   contract.
+    *   `AstDocument<TAst, never>` — no diagnostics have been computed at
+    *   those phases.
     * - `validated` returns `AstDocument<TAst, TDiagnostic>` — diagnostics
     *   are populated.
     *
+    * **The `never` is enforced, not merely declared.** The wait underneath
+    * resolves at or ABOVE the requested state, so a document something else
+    * already carried past `Validated` would otherwise come back from
+    * `settled()` carrying a full diagnostics array typed `never`; these four
+    * strip it. An empty array here therefore means "this read does not report
+    * diagnostics", never "this document is clean" — call {@link validated}
+    * when the answer has to mean the second.
+    *
     * `settled` is the integrity-overlay name for "all integrity rules
     * have fired"; it maps to {@link IntegrityService.SettledState} (which
     * equals `DocumentState.IndexedReferences`), but the dedicated method
@@ -496,19 +685,19 @@ export class ModelService<
     * ever moves.
     */
    async parsed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, DocumentState.Parsed, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.Parsed, cancelToken));
    }
 
    async linked(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, DocumentState.Linked, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.Linked, cancelToken));
    }
 
    async settled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, IntegrityService.SettledState, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, IntegrityService.SettledState, cancelToken));
    }
 
    async indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, DocumentState.IndexedReferences, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.IndexedReferences, cancelToken));
    }
 
    async validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
@@ -518,18 +707,13 @@ export class ModelService<
    /**
     * Ensure the document at `uri` reaches `state` (or the integrity-settled
     * landmark {@link IntegrityService.SettledState} if omitted) and return its
-    * AST envelope. Smart
-    * dispatch: warm path (URI already in `LangiumDocuments`) just waits
-    * via {@link waitForDocumentState}; cold path forces a build via
-    * {@link rebuild}.
-    *
-    * Pairs with {@link rebuild} — same default phase, but `rebuild`
-    * always builds while this skips the build for an already-loaded
-    * document. Also pairs with {@link waitForDocumentState} — the verb
-    * difference (`ensure` vs `waitFor`) signals the side-effect
-    * difference. The per-state convenience methods (`parsed` / `linked`
-    * / `settled` / `indexed` / `validated`) all delegate here with an
-    * explicit phase.
+    * AST envelope, with a root no older than the store's text at the call.
+    * A document not in `LangiumDocuments` is built via {@link rebuild}; a
+    * loaded one whose root is behind its text is built through
+    * `VersionSyncService.syncTo`. Until `state` is reached, the call rejects
+    * once that build, or one the builder re-queues, has failed twice, or the
+    * builder stops re-queuing the document. A loaded, current document is only
+    * awaited.
     */
    async ensureDocumentState(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
       return this.ensureDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), state, cancelToken);
@@ -552,120 +736,20 @@ export class ModelService<
    ): Promise<AstDocument<TAst, TDiagnostic>> {
       const target = state ?? IntegrityService.SettledState;
       if (this.services.workspace.LangiumDocuments.hasDocument(UriUtils.toUri(uri))) {
-         return this.waitForDocumentStateCanonical(uri, target, cancelToken);
+         return this.waitForDocumentStateCanonical(uri, target, cancelToken, { sync: true });
       }
       return this.rebuild(uri, target, cancelToken);
    }
 
    /**
-    * Apply an update for `uri`. The structured-or-textual `model` payload
-    * is serialised (via {@link serialize} after {@link rewriteModel} when
-    * structured), pushed into the multi-client text-document store with
-    * a fresh version, drives a build to the target phase, and returns
-    * the post-build AST snapshot.
-    *
-    * **Read-latest supersession**: concurrent callers on the same URI
-    * all see the same post-build state once `waitUntil` resolves; none
-    * deadlock waiting for a specific version's settled event. The
-    * framework emits a post-resolution `debug` log line distinguishing
-    * "vN ready" from "vN ready at vM (superseded)" so callers can
-    * observe when their write was overtaken by a newer one before
-    * settling — purely observability, doesn't change resolution
-    * semantics. Adopters wanting version-matched resolution (resolve
-    * with vN's specific settled snapshot, intermediate-phase
-    * observability, slow-warn / hard-timeout behaviour) override this
-    * method.
-    */
-   async update(args: TransferUpdateArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
-      const stopwatch = this.slowUpdateWarn !== undefined ? this.services.Clock.stopwatch() : undefined;
-      // Per-stage self-time breakdown of the update/reconcile chain (serialise →
-      // open → apply → rebuild), opt-in at debug — the default path skips the
-      // session and `run` calls the stage directly. `update` is a per-operation
-      // method (one user save / diagram edit), not a per-node hot loop, so the
-      // stage closures `run` allocates on the non-debug path are negligible.
-      // Canonicalize the write URI once at the door and thread the resulting
-      // CanonicalUri through the chain. The text store keys documents by their
-      // canonical identity, so any spelling of a file — a canonical
-      // (server-identity) URI from a GLSP cross-document save derived from
-      // `findDocument(node).uri`, or the symlink path an editor opened — collapses
-      // to the one registration; there is no second registration to fork. The
-      // build step reuses the canonical wait core (`rebuildCanonical`) so the
-      // identity is not re-resolved downstream.
-      const uri = this.uriPolicy.canonicalUri(args.uri);
-      const session = Logger.isLevelEnabled('debug') ? this.tracer.profile(`model-update ${uri}`) : undefined;
-      const run = async <T>(stage: string, fn: () => MaybePromise<T>): Promise<T> => (session ? session.scope(stage, fn) : fn());
-      // Open WITH the new text so a cold URI (no open editor, no file on disk) is
-      // created from the payload rather than read from the filesystem — `update`
-      // is an upsert. For an already-open document `open` refreshes content (the
-      // text is ignored on that branch), so existing-document behaviour is
-      // unchanged. `version` is intentionally NOT forwarded to `open`: a cold
-      // create stays at its initial version, so a based-on-`version` update of a
-      // not-yet-existing document still trips the conflict gate below.
-      const text = await run('serialize', () => this.modelToText(uri, args.model, cancelToken));
-      await run('open', () => this.open({ uri, clientId: args.clientId, text }));
-      if (args.baseVersion !== undefined) {
-         const current = this.services.workspace.TextDocuments.version(uri);
-         if (current !== args.baseVersion) {
-            // Distinct from the post-build "superseded" debug line below: this is a
-            // based-on-stale rejection (the write never applies), not two writes racing.
-            this.tracer.debug(`Conflict on ${uri}: based-on v${args.baseVersion} stale, server at v${current}`);
-            throw new ConflictError(uri, args.baseVersion, current);
-         }
-      }
-      const appliedVersion = await run('apply', () => this.services.workspace.AstDocumentManager.update(uri, text, args.clientId));
-      // Dispatch through the public `rebuild` (which re-canonicalizes the already-
-      // canonical `uri` once, idempotently) rather than `rebuildCanonical`, so an
-      // adopter `rebuild` override stays in the update path. The redundant call is
-      // a single kernel-cached `realpath`; correctness of the override contract
-      // wins over shaving it.
-      const doc = await run('rebuild', () => this.rebuild(uri, undefined, cancelToken));
-      const finalVersion = this.services.workspace.TextDocuments.version(uri);
-      if (finalVersion > appliedVersion) {
-         this.tracer.debug(`Update to v${appliedVersion} ready at v${finalVersion} (superseded)`);
-      } else {
-         this.tracer.debug(`Update to v${appliedVersion} ready`);
-      }
-      if (this.slowUpdateWarn !== undefined && stopwatch) {
-         const elapsed = Math.round(stopwatch.elapsedMs);
-         const threshold = this.slowUpdateWarn.value;
-         if (elapsed >= threshold) {
-            this.tracer.withUri(uri).warn(`Slow update: ${elapsed}ms ≥ ${threshold}ms (v${appliedVersion}, client=${args.clientId})`);
-         }
-      }
-      // One line per stage (serialise / open / apply / rebuild) + unaccounted — only when profiling.
-      session?.report('debug');
-      return doc;
-   }
-
-   /**
-    * Persist `uri` to disk. Same content-change + settled-phase flow as
-    * {@link update}, then writes via the
-    * `WritableFileSystemProvider` and notifies the multi-client
-    * text-document store of the save (so any open LSP-side editor sees
-    * the `onDidSave` event regardless of who originated the persist).
-    *
-    * Returns the post-save AST snapshot.
-    */
-   async save(args: TransferSaveArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
-      // Dispatch through `update` (not its internals) so an adopter `update`
-      // override — version-matched resolution, etc. — applies to saves too.
-      const doc = await this.update(args, cancelToken);
-      // Persist under the same canonical identity `update` operated on. Writing
-      // the canonical (real) path follows any symlink to the same file, and the
-      // `onDidSave` keys the one canonical registration.
-      const uri = this.uriPolicy.canonicalUri(args.uri);
-      await this.services.workspace.AstDocumentManager.save(uri, args.clientId);
-      return doc;
-   }
-
-   /**
-    * Wait for the document at `uri` to reach the integrity-settled landmark and
+    * Wait for the document at `uri` to reach the integrity-settled landmark,
+    * building a root behind its text as {@link ensureDocumentState} does, and
     * drain any in-flight write-path applyEdit sync chain (see {@link syncChains})
     * so every language client reflects the latest content before a save returns.
     * No-op tail for headless adopters — `syncChains` is empty without an LSP
     * client. Bounded by {@link SAVE_SETTLE_TIMEOUT_MS} so a hung build, or an
-    * applyEdit reverse-RPC deadlock, can't freeze the caller; on timeout it logs
-    * a warning and returns rather than throwing.
+    * applyEdit reverse-RPC deadlock, can't freeze the caller; on timeout or a
+    * failed wait it logs a warning and returns rather than throwing.
     *
     * Adopters with a save flow that must converge editor + disk before returning
     * (e.g. a dual form/code editor that would otherwise show a content-conflict
@@ -674,57 +758,24 @@ export class ModelService<
    protected async settleSave(uri: string, cancelToken?: CancellationToken): Promise<void> {
       const canonical = this.uriPolicy.canonicalUri(uri);
       const key = UriUtils.toUri(canonical).toString();
-      const timeout = new Promise<void>((_, reject) =>
-         setTimeout(() => reject(new SaveSettleTimeoutError('settle timeout')), SAVE_SETTLE_TIMEOUT_MS)
-      );
+      // One race over both waits, so the bound is one deadline for the pair;
+      // a race per wait would let the save take twice the bound.
+      const settled = (async (): Promise<void> => {
+         await this.waitForDocumentStateCanonical(canonical, IntegrityService.SettledState, cancelToken, { sync: true });
+         await this.syncChains.get(key);
+      })();
       try {
-         await Promise.race([this.waitForDocumentStateCanonical(canonical, IntegrityService.SettledState, cancelToken), timeout]);
-         const pending = this.syncChains.get(key);
-         if (pending) {
-            await Promise.race([pending, timeout]);
-         }
-      } catch (err: unknown) {
-         if (err instanceof SaveSettleTimeoutError) {
+         if ((await this.services.Clock.raceTimer(settled, SAVE_SETTLE_TIMEOUT_MS)) === TIMED_OUT) {
             this.tracer.withUri(key).warn(`Save settle exceeded ${SAVE_SETTLE_TIMEOUT_MS}ms — returning anyway`);
-         } else {
-            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
-            this.tracer.withUri(key).warn(`Save settle failed before the timeout — returning anyway. ${detail}`);
          }
+      } catch (err: unknown) {
+         // A failed wait, such as a cancelled token or a document the builder
+         // does not hold, gets its own line so it is not blamed on the bound.
+         const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+         this.tracer.withUri(key).warn(`Save settle failed before the timeout — returning anyway. ${detail}`);
       }
    }
 
-   /**
-    * Open the document at `args.uri` on behalf of `args.clientId`.
-    * Multi-client: each (uri, clientId) pair is tracked as one
-    * registration; the underlying document stays open until the last
-    * client closes it. If `args.text` is omitted the document content
-    * is read from the `FileSystemProvider`.
-    *
-    * Returns a {@link Disposable} that closes the registration when
-    * disposed — useful for `using` blocks and shutdown cleanup.
-    *
-    * Delegates to the framework-bound
-    * `services.workspace.AstDocumentManager`. Adopter subclasses with
-    * extra open-time behaviour (logging, sync-chain bootstrapping)
-    * override on their `ModelService` subclass and call `super.open`.
-    *
-    * The open path does not thread cancellation: `AstDocumentManager.open`
-    * and the filesystem read behind it take no token, so a cancelled caller
-    * still completes the open.
-    */
-   async open(args: OpenModelArgs): Promise<Disposable> {
-      return this.services.workspace.AstDocumentManager.open(args);
-   }
-
-   /**
-    * Close the document at `args.uri` for `args.clientId`. Counterpart
-    * to {@link open}; the underlying document stays open until every
-    * registered client has closed.
-    */
-   async close(args: CloseModelArgs): Promise<void> {
-      return this.services.workspace.AstDocumentManager.close(args);
-   }
-
    /**
     * True when the document at `uri` is currently open for at least one
     * client. Pure read; no side effects.
@@ -733,6 +784,33 @@ export class ModelService<
       return this.services.workspace.AstDocumentManager.isOpen(uri);
    }
 
+   /**
+    * Snapshot of `uri` as it stands RIGHT NOW — the synchronous sibling of the
+    * phase reads, which all wait. `undefined` when no document is registered,
+    * or only the builder's placeholder for one its build has not parsed yet:
+    * that root is no parse of any text, and its version gates no write.
+    *
+    * **This is what a writer wants, and {@link getDocument} is not.** The
+    * envelope's `version` is copied by value at projection time, so it cannot
+    * move afterwards; a version read off the live document at write time is
+    * whatever the server is at *now*, which is the number an optimistic gate is
+    * about to compare it against.
+    *
+    * Diagnostics only from a document that has reached `Validated`, and absent
+    * otherwise. Unlike the phase reads this one names no phase, so
+    * the state it finds is the only thing that can say whether the array
+    * describes the content being handed back or whatever an earlier build left.
+    * A caller that needs them unconditionally waits, via {@link validated}.
+    */
+   snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined {
+      const document = this.getDocument(uri);
+      if (!document || this.services.workspace.ModelLedger.isPlaceholder(document.parseResult.value)) {
+         return undefined;
+      }
+      const envelope = this.services.workspace.AstDocumentManager.toAstDocument(document) as AstDocument<TAst, TDiagnostic>;
+      return document.state >= DocumentState.Validated ? envelope : this.withoutDiagnostics(envelope);
+   }
+
    /**
     * The built {@link LangiumDocument} for `uri`, looked up by canonical identity —
     * the synchronous, phase-agnostic sibling of {@link ensureDocumentState} /
@@ -741,11 +819,92 @@ export class ModelService<
     * into `LangiumDocuments` directly: a symlinked / `..` / case-divergent URI
     * still resolves to the one document the build keys by its real path. Returns
     * `undefined` if no document is registered for `uri`.
+    *
+    * **Live, so do not take a base version off it.** `textDocument` is the
+    * store's own object rather than a copy, so `.version` read here answers for
+    * the moment of the READ, not the moment of the earlier content — pass it to
+    * a write and the server compares its current version against itself, the
+    * gate passes unconditionally, and a concurrent edit is overwritten with
+    * nothing logged. Use {@link snapshot} for that, or a phase read.
     */
    getDocument(uri: string): LangiumDocument | undefined {
       return this.services.workspace.AstDocumentManager.getDocument(uri);
    }
 
+   // ============================================================
+   // Client sessions
+   // ============================================================
+
+   createSession<TOpenOptions extends OpenOptions = OpenOptions>(
+      label?: string,
+      clientId?: string
+   ): ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions> {
+      const sessionLabel = label ?? 'session';
+      const id = clientId ?? `${sessionLabel}#${globalThis.crypto.randomUUID()}`;
+      const textDocuments = this.services.workspace.TextDocuments;
+      textDocuments.registerSession(id);
+      this.sessionCloseListener ??= textDocuments.onDidCloseSession(event => {
+         // Also reached when the store ends a session directly; disposing the
+         // handle makes its later calls fail rather than write under an id
+         // this service no longer treats as a session.
+         this.sessions.get(event.clientId)?.dispose();
+         this.sessions.delete(event.clientId);
+      });
+      let session: ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>;
+      try {
+         // Unchecked: the session keeps whatever options its `open` is handed,
+         // and the factory types it for every grammar, so the narrowed type
+         // holds only for the caller that started it.
+         session = this.services.model.ClientSessionFactory.create(id, sessionLabel) as ClientSession<
+            TAst,
+            TDiagnostic,
+            TTransfer,
+            TOpenOptions
+         >;
+      } catch (err: unknown) {
+         textDocuments.closeSession(id);
+         throw err;
+      }
+      this.sessions.set(id, session);
+      return session;
+   }
+
+   getSession(clientId: string): ClientSession<TAst, TDiagnostic, TTransfer> | undefined {
+      return this.sessions.get(clientId);
+   }
+
+   /**
+    * Convert a structured-or-textual `model` payload to its textual form.
+    *
+    * Textual payloads (LSP / pre-serialised callers) pass through untouched.
+    * Structured payloads run the per-language `UpdateRewriteService` chain
+    * (transfer-model transforms; diff-aware rewrites see the previous AST root),
+    * then serialise. The chain is the single transfer-model-transform seam — a
+    * unary normalisation is just a rewrite that ignores `previous`, as
+    * `NormalizeEmptyStringsContribution` does. The chain is empty by
+    * default, so this is a no-op for adopters that register none.
+    */
+   async modelToText(uri: string, model: TTransfer | string, cancelToken?: CancellationToken): Promise<string> {
+      if (typeof model === 'string') {
+         return model;
+      }
+      const rewritten = await this.rewriteModel(uri, model, cancelToken);
+      const target = UriUtils.toUri(uri);
+      const trivia = this.services.ServiceRegistry?.getServices(target)?.trivia?.TriviaService;
+      // Extracted BEFORE serializing, so it reads the document the write is
+      // about to replace rather than whatever a concurrent build left behind.
+      let document = this.services.workspace.LangiumDocuments.getDocument(target);
+      if (trivia !== undefined && document === undefined) {
+         const source = await this.textToTakeTriviaFrom(uri, target);
+         if (source !== undefined) {
+            document = this.services.workspace.LangiumDocumentFactory.fromString(source, target);
+         }
+      }
+      const extracted = trivia !== undefined && document !== undefined ? trivia.extract(document) : undefined;
+      const serialized = await this.serialize(uri, rewritten);
+      return extracted === undefined ? serialized : trivia!.apply(serialized, extracted, target);
+   }
+
    // ============================================================
    // LSP-client sync (mirror non-LSP-client changes back to Monaco)
    // ============================================================
@@ -754,18 +913,14 @@ export class ModelService<
     * Mirror a server-side change of `document` back to the LSP textual language
     * client, run per document as it reaches the post-integrity settled phase.
     * The single framework caller of
-    * `HydraniumTextDocuments.applyEditToLanguageClient` and
-    * `HydraniumTextDocuments.stagePendingContent`.
-    *
-    * Routes to one of two mechanisms by language-client registration, because
-    * an open and a closed document answer different questions:
+    * `HydraniumTextDocuments.applyEditToLanguageClient`.
     *
-    * - **Open in the language client** → {@link syncOpenDocument}: mirror the
-    *   settled text via a coalesced `applyEditToLanguageClient`, routed purely by
-    *   **content**.
-    * - **Closed in the language client** → {@link stageClosedDocument}: stage the
-    *   text for the eventual first `didOpen`, gated by **provenance**
-    *   ({@link isNonLanguageClientEdit}).
+    * Only a document open in the language client is mirrored, through
+    * {@link syncOpenDocument}, routed purely by **content**. A document open
+    * only in another client needs nothing: a language client opening it joins
+    * the existing entry and is refreshed from the store. A session writes only
+    * what it has open, so no session edit of a closed document waits here for
+    * the language client's next open.
     *
     * The decision is **re-derived from the current settled state every time** (it
     * is not a one-shot enrolment), which is what makes it self-healing: a doc
@@ -775,9 +930,9 @@ export class ModelService<
     */
    protected syncToLanguageClient(document: LangiumDocument): void {
       // `document.textDocument.uri` is the server-identity (canonical) URI off the
-      // build. Route by language-client registration (a presence question —
-      // `isOpenInLanguageClient` canonicalizes internally, so a divergent open path
-      // still resolves to the same record), but key the outbound sync by this
+      // build. Route by client registration (presence questions — both
+      // predicates canonicalize internally, so a divergent open path still
+      // resolves to the same record), but key the outbound sync by this
       // CANONICAL URI — the same key `settleSave` looks the chain up under —
       // so a save-settle can drain the in-flight applyEdit. The canonical→client-URI
       // translation (a symlinked path the client opened, or a dual-open fan-out)
@@ -787,8 +942,6 @@ export class ModelService<
       // the drain would miss for a divergent open path.
       if (this.services.workspace.TextDocuments.isOpenInLanguageClient(document.textDocument.uri)) {
          this.syncOpenDocument(document.textDocument.uri, document.textDocument.getText());
-      } else {
-         this.stageClosedDocument(document);
       }
    }
 
@@ -807,46 +960,6 @@ export class ModelService<
       this.queueSync(uri, text);
    }
 
-   /**
-    * Stage the settled text of a document closed in the language client so the
-    * eventual first `didOpen` sees this in-memory text instead of stale disk —
-    * but only for a {@link isNonLanguageClientEdit genuine non-language-client edit}.
-    * A document rebuilt by an internal build is skipped, leaving disk authoritative
-    * on the next open.
-    */
-   protected stageClosedDocument(document: LangiumDocument): void {
-      if (this.isNonLanguageClientEdit(document)) {
-         this.services.workspace.TextDocuments.stagePendingContent(document.textDocument.uri, document.textDocument.getText());
-      }
-   }
-
-   /**
-    * Whether `document`'s settled state is a genuine edit by a client *other than
-    * the language client* — a write a form / GLSP / integrity client actually made.
-    * Excludes two non-edits: the **language client** itself (the LSP/Monaco text
-    * client — it already holds its own edits, and the staging here exists to feed
-    * it) and an **internal build** (workspace startup, a cascade relink, a
-    * `didClose`-reload). This is the gate for {@link stageClosedDocument}: staging
-    * an internal build would
-    * (a) pre-stage every file on boot and (b) re-stage discarded content after
-    * close (e.g. a disposing GLSP session's debounced submit firing after close),
-    * which then shadows clean disk on the next open.
-    *
-    * The signal is "a known client other than the language client authored this
-    * version **and** the URI was in the last build's changed set
-    * (`isDirectChange`)". A framework-internal rebuild reports no author
-    * (`getAuthor` → `undefined`), so it fails `hasKnownAuthor` without comparing
-    * against a sentinel. This is NOT redundant with content/registration — it
-    * distinguishes "client edited" from "framework rebuilt", which neither the
-    * shadow nor `isDirectChange` alone can.
-    */
-   protected isNonLanguageClientEdit(document: LangiumDocument): boolean {
-      const documents = this.services.workspace.AstDocumentManager;
-      const author = documents.getAuthor(document);
-      const hasKnownAuthor = !!author && author !== LANGUAGE_CLIENT_ID;
-      return hasKnownAuthor && documents.isDirectChange(document.textDocument.uri);
-   }
-
    /**
     * Enqueue a sync to the language client. The pending slot per URI holds only
     * the latest text: if a newer settle fires while the current RPC is in
@@ -878,15 +991,28 @@ export class ModelService<
       this.syncChains.set(uri, chain);
    }
 
+   /**
+    * The undo-stack label for a server-authored write, in the locale the server
+    * was handed at init.
+    *
+    * One method rather than the literal at each `applyEdit`, because the two
+    * call sites are the same edit — a push and its full-replace retry — and an
+    * undo menu showing two different words for one operation would read as two
+    * operations.
+    */
+   protected editLabel(): string {
+      return this.services.MessageRenderer.renderMessage(MODEL_UPDATE_EDIT);
+   }
+
    protected async drainSyncQueue(uri: string): Promise<void> {
       const uriLogger = this.tracer.withUri(uri);
       while (this.pendingSync.has(uri)) {
          const text = this.pendingSync.get(uri)!;
          this.pendingSync.delete(uri);
          try {
-            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
             if (result?.applied === false && !this.pendingSync.has(uri)) {
-               // The push is addressed at the client's LAST DECLARED VERSION, so a
+               // The push is addressed at the client's last known version, so a
                // rejection normally means the client's buffer moved while the
                // line-keyed diff was in flight — exactly the case where applying it
                // would splice the file. Dropping the push there would leave the
@@ -904,8 +1030,8 @@ export class ModelService<
                // `pendingSync` check skips the retry when a newer settle has already
                // queued — best-effort, since a settle arriving later simply pushes
                // after this and still wins.
-               uriLogger.warn(`Language client rejected applyEdit at its declared version — re-pushing a full replace`);
-               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+               uriLogger.debug(`Re-pushing a full replace after the language client refused applyEdit`);
+               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
                if (result?.applied === false) {
                   uriLogger.warn(`Language client rejected the full-replace retry too — client content is stale`);
                }
@@ -935,9 +1061,8 @@ export class ModelService<
     * `HydraniumTextDocuments` — single listener registration shared with
     * any direct `HydraniumTextDocuments.onUpdate` subscriber, so the same
     * underlying `DocumentBuilder.onDocumentPhase` listener serves both
-    * call paths. `sourceClientId` is resolved from the multi-client
-    * author history; reason discrimination follows the manager's own
-    * `lastUpdate` snapshot (see `AstDocumentManager.onUpdate`).
+    * call paths. The event's reason, source and cause are
+    * {@link AstDocumentManager.attributeUpdate}'s.
     */
    onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable {
       return this.services.workspace.AstDocumentManager.onUpdate(uri, listener as never);
@@ -979,13 +1104,13 @@ export class ModelService<
     * Adopters whose serializer call shape differs (custom service
     * names, generator-driven YAML pretty printers, etc.) override this
     * method. Routes through `Serializer.serializeTransfer` because
-    * `ModelService.update` / `ModelService.save` always receive a
+    * a session's `update` / `save` always receive a
     * transfer-model shape (cross-references as plain strings) from
     * adopter callers — the AST-shape entry point is `serializeAst`.
     *
     * Returns {@link MaybePromise} so adopter `Serializer` overrides can be
     * async (remote schema lookup, external canonical-value resolution); the
-    * single caller ({@link modelToText} → {@link update}) is already `async`,
+    * single caller ({@link modelToText}) is already `async`,
     * so a naive `await` covers both branches without extra ceremony.
     */
    protected serialize(uri: string, root: TTransfer): MaybePromise<string> {
@@ -998,22 +1123,12 @@ export class ModelService<
    // ============================================================
 
    /**
-    * Convert a structured-or-textual `model` payload to its textual form.
-    *
-    * Textual payloads (LSP / pre-serialised callers) pass through untouched.
-    * Structured payloads run the per-language `UpdateRewriteService` chain
-    * (transfer-model transforms; diff-aware rewrites see the previous AST root),
-    * then serialise. The chain is the single transfer-model-transform seam — a
-    * unary normalisation is just a rewrite that ignores `previous`, as
-    * `NormalizeEmptyStringsContribution` does. The chain is empty by
-    * default, so this is a no-op for adopters that register none.
+    * The text a write into a document not yet built should take its trivia
+    * from: the store's, which a write always has, since it writes only a
+    * document its client has open.
     */
-   protected async modelToText(uri: string, model: TTransfer | string, cancelToken?: CancellationToken): Promise<string> {
-      if (typeof model === 'string') {
-         return model;
-      }
-      const rewritten = await this.rewriteModel(uri, model, cancelToken);
-      return this.serialize(uri, rewritten);
+   protected async textToTakeTriviaFrom(uri: string, _target: URI): Promise<string | undefined> {
+      return this.services.workspace.TextDocuments.get(uri)?.getText();
    }
 
    /**
@@ -1037,15 +1152,37 @@ export class ModelService<
 
    /**
     * Build an {@link AstDocument} envelope from the current
-    * {@link LangiumDocument} state via the shared {@link AstDocument.from}
-    * projection. Returns an empty envelope (built via
+    * {@link LangiumDocument} state via `AstDocumentManager.toAstDocument`,
+    * the projection events use too. Returns an empty envelope (built via
     * {@link AstDocument.create}) when the document is absent from the
-    * registry — adopters that prefer to throw override on their subclass.
+    * registry — adopters that prefer to throw override on their subclass. Its
+    * version is {@link UNRECORDED_VERSION}, so a write based on it conflicts.
     */
    protected toAstDocument(uri: URI): AstDocument<TAst, TDiagnostic> {
       const document = this.services.workspace.LangiumDocuments.getDocument(uri);
       return document
-         ? AstDocument.from<TAst, TDiagnostic>(document)
-         : AstDocument.create<TAst, TDiagnostic>(uri.toString(), 0, undefined as unknown as TAst, []);
+         ? (this.services.workspace.AstDocumentManager.toAstDocument(document) as AstDocument<TAst, TDiagnostic>)
+         : AstDocument.create<TAst, TDiagnostic>(uri.toString(), UNRECORDED_VERSION, undefined as unknown as TAst);
+   }
+
+   /**
+    * The same envelope with no diagnostics, for a read that names a phase below
+    * `Validated`. Absent rather than `[]`, which says the document was validated
+    * and found clean.
+    *
+    * Langium fills `LangiumDocument.diagnostics` from inside `validateDocument`
+    * and from nowhere else, so below that phase the array holds whatever an
+    * EARLIER build left — a verdict about text the document may no longer have.
+    * The wait underneath resolves at or above the phase asked for, so a document
+    * something else carried past `Validated` would otherwise hand a full array
+    * back from `parsed()`.
+    *
+    * A copy rather than a clear: the envelope is freshly built here, but
+    * {@link toAstDocument} is overridable and an adopter's version may return
+    * one it also keeps.
+    */
+   protected withoutDiagnostics(document: AstDocument<TAst, TDiagnostic>): AstDocument<TAst, never> {
+      const { diagnostics: _diagnostics, ...rest } = document;
+      return rest;
    }
 }