@hydranium/core 1.0.0-next.32 → 1.0.0-next.321

package/lib/langium/model-service/model-service.js

@@ -6,11 +6,12 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { ConflictError, defineMessage, Logger, ObservableValue } from '@hydranium/protocol';
-import { DocumentState, UriUtils } from '@hydranium/langium';
-import { ReentrantWriteLockError, isInsideWriteLock } from '../workspace/write-lock-scope.js';
+import { defineMessage, ObservableValue, randomUuid, TIMED_OUT, UNRECORDED_VERSION, describeErrorWithStack } from '@hydranium/protocol';
+import { DocumentState, OperationCancelled, isOperationCancelled, UriUtils } from '@hydranium/langium';
+import { ReentrantWriteLockError, isInsideWriteLock, isWriteLockScopeInstalled } from '../workspace/write-lock-scope.js';
+import { CancellationToken, Disposable } from 'vscode-languageserver';
 import { AstDocument } from '../../documents/ast-document-manager.js';
-import { isConnectionGoneError } from '../../util/connection-liveness.js';
+import { isClientGoneError } from '../../util/connection-liveness.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';
@@ -30,86 +31,13 @@ import { LANGUAGE_CLIENT_ID } from '../../documents/client-ids.js';
  * the URI would be noise in the one place it is redundant.
  */
 export const MODEL_UPDATE_EDIT = defineMessage('hydranium/core/model-update-edit', 'Update Model');
-/** Max time {@link ModelService.settleSave} waits for the build to settle and the sync chain to drain. */
-const SAVE_SETTLE_TIMEOUT_MS = 10_000;
 /**
- * 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.
+ * Max time {@link ModelService.settleLanguageClient} waits. A save answers up to
+ * this long after its persist, so a client timing out one save's answer must
+ * allow it plus the persist.
  */
-class SaveSettleTimeoutError extends Error {
-}
-/**
- * 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.
- *
- * "Model" here means the parsed AST — distinct from the wire-shape
- * `TransferDocument` in `@hydranium/protocol`.
- *
- * **Why a facade**
- *
- * 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.
- * - Server-internal callers (integrity service, ad-hoc bridges, tests)
- *   want the same operations without the wire serialisation step.
- *
- * Coordinating the primitives per-head drifts between heads — different
- * superseded-version handling, different settled-phase choices, different
- * content-change paths. The facade collapses that duplication and gives
- * adopters one extension surface — {@link rewriteModel},
- * {@link serialize} — to customise the in-process behaviour without
- * re-implementing the plumbing.
- *
- * **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.
- *
- * **Returns AST snapshots, not wire envelopes**
- *
- * The facade returns {@link AstDocument} (the in-process AST-typed
- * envelope), not `TransferDocument` (the lossy wire shape). In-
- * process callers consume `$container` / `Reference<T>` directly;
- * encoding-on-return would be wasteful and would force the wire-side
- * lossy `$refText` shape on every consumer. The wire-side caller
- * (`DataServer.updateModelDocument` etc.) encodes once on return via
- * the injected `TransferEncoder` — symmetric with the
- * `getModelDocument` envelope path.
- *
- * **Subscriptions** ({@link onModelUpdated} / {@link onModelSaved} /
- * {@link onClientClosed}) are thin pass-throughs over
- * `DocumentBuilder.onDocumentPhase` and
- * `HydraniumTextDocuments.onDidSave` / `onDidClose`. Filtering
- * by URI happens here so consumers can subscribe per-document without
- * implementing the URI gate at each callsite.
- *
- * **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`
- *   args. Constrained to {@link TransferElement}. Defaults to the
- *   structural base.
- */
-export class ModelService {
+const LANGUAGE_CLIENT_SETTLE_TIMEOUT_MS = 10_000;
+export class DefaultModelService {
     services;
     tracer;
     /**
@@ -121,14 +49,8 @@ export class ModelService {
      * (see {@link DocumentUriPolicy}).
      */
     uriPolicy;
-    /**
-     * 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.
-     */
-    slowUpdateWarn;
-    /** See {@link ModelServiceOptions.serializeBuilds}. Defaults to `true`. */
-    serializeBuilds;
+    /** See {@link ModelServiceOptions.allowReentrantBuilds}. Defaults to `false`. */
+    allowReentrantBuilds;
     /**
      * Per-URI applyEdit coalescing: at most one in-flight `applyEditToLanguageClient`
      * RPC per URI, newest text wins. A newer settle while the current RPC is in
@@ -137,6 +59,29 @@ export class ModelService {
      */
     syncChains = new Map();
     pendingSync = new Map();
+    /**
+     * The sync chains a settle timed out on, until the client answers their
+     * push. A later settle does not wait on one meanwhile: GLSP runs a diagram's
+     * saves one at a time, so each would add the full bound and a queued save
+     * outlast its client's timeout.
+     */
+    timedOutSyncChains = new WeakSet();
+    /** The live sessions this service started, by client id, for {@link getSession}. */
+    sessions = new Map();
+    /**
+     * 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.
+     */
+    sessionCloseListener;
+    /** The token each live session was started with, by client id, for a takeover by {@link createSession}. */
+    resumeTokens = new Map();
+    /**
+     * The {@link onModelUpdated} subscribers, by phase. One builder listener per
+     * phase serves them all, kept for the life of the service.
+     */
+    updateSubscribers = new Map();
     /**
      * Workspace-level readiness gate. Resolves when the framework has
      * finished its first workspace build cycle and the `ModelService`
@@ -174,31 +119,27 @@ export class ModelService {
         this.services = services;
         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) {
+            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.
-                // `workspaceInitialized` can: it rejects on a cancelled initial
-                // 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)}`);
+                // the workspace manager's `ready` (what it replaced) rejects only on
+                // a failed startup. `workspaceInitialized` also rejects on a
+                // cancelled initial 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. The workspace manager logs the outcome.
             }
         })();
         // One persistent listener mirroring non-LSP-client changes back to the LSP
@@ -215,10 +156,12 @@ export class ModelService {
     // Lifecycle (public API)
     // ============================================================
     /**
-     * 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
@@ -231,11 +174,10 @@ 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, cancelToken) {
-        return this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), IntegrityService.SettledState, cancelToken);
+        return this.withoutDiagnostics(await this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), IntegrityService.SettledState, cancelToken));
     }
     /**
      * Internal wait core operating on an already-{@link CanonicalUri canonical}
@@ -246,13 +188,105 @@ 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}.
      */
-    async waitForDocumentStateCanonical(uri, state, cancelToken) {
+    async waitForDocumentStateCanonical(uri, state, cancelToken, options = {}) {
         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), 'debug');
-        return this.toAstDocument(documentUri);
+            .time(`Wait for document state '${DocumentState[state]}'`, () => this.waitUntilSynced(documentUri, state, textVersion, cancelToken, options), 'debug');
+        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.
+     */
+    async waitUntilSynced(uri, state, textVersion, cancelToken, options = {}) {
+        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.
+     */
+    nextParseOrDeletion(uri, cancelToken = CancellationToken.None, build) {
+        const builder = this.services.workspace.DocumentBuilder;
+        return new Promise((resolve, reject) => {
+            let ended = false;
+            let cancelled = false;
+            // Handled before any return, so a build given up after the wait ended is not an unhandled rejection.
+            build?.catch((error) => {
+                const line = `The build that would sync the root to its text failed. ${describeErrorWithStack(error)}`;
+                if (cancelled) {
+                    // The waiter has gone, so nothing else reports this.
+                    this.tracer.withUri(uri.toString()).error(line);
+                }
+                else if (ended) {
+                    // A parse or deletion came first: the waiter goes on and reports its own outcome, and the retry warned.
+                    this.tracer.withUri(uri.toString()).debug(line);
+                }
+                else {
+                    done(() => reject(new Error(`The build that would sync ${uri.toString()} to its text failed`, { cause: error })));
+                }
+            });
+            // A cancelled token's listener runs a macrotask later, after a build
+            // that started meanwhile may have parsed.
+            if (cancelToken.isCancellationRequested) {
+                ended = true;
+                cancelled = true;
+                reject(OperationCancelled);
+                return;
+            }
+            const done = (settle) => {
+                ended = true;
+                parsed.dispose();
+                deleted.dispose();
+                cancelling.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 cancelling = cancelToken.onCancellationRequested(() => {
+                cancelled = true;
+                done(() => reject(OperationCancelled));
+            });
+        });
     }
     /**
      * Wait for the document builder to reach `state` across its currently-
@@ -270,31 +304,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.
      *
-     * Returns an empty `{ root, diagnostics }` envelope when the document
-     * cannot be loaded; adopters that want to throw override this method
-     * on their subclass.
+     * 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.
+     *
+     * 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}
@@ -305,8 +343,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,
@@ -314,64 +352,60 @@ export class ModelService {
      */
     async rebuildCanonical(uri, state, cancelToken) {
         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));
+        // 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 {
-            await this.services.workspace.DocumentBuilder.update([documentUri], [], cancelToken);
+            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) {
+        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
@@ -379,16 +413,16 @@ export class ModelService {
      * ever moves.
      */
     async parsed(uri, cancelToken) {
-        return this.ensureDocumentState(uri, DocumentState.Parsed, cancelToken);
+        return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.Parsed, cancelToken));
     }
     async linked(uri, cancelToken) {
-        return this.ensureDocumentState(uri, DocumentState.Linked, cancelToken);
+        return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.Linked, cancelToken));
     }
     async settled(uri, cancelToken) {
-        return this.ensureDocumentState(uri, IntegrityService.SettledState, cancelToken);
+        return this.withoutDiagnostics(await this.ensureDocumentState(uri, IntegrityService.SettledState, cancelToken));
     }
     async indexed(uri, cancelToken) {
-        return this.ensureDocumentState(uri, DocumentState.IndexedReferences, cancelToken);
+        return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.IndexedReferences, cancelToken));
     }
     async validated(uri, cancelToken) {
         return this.ensureDocumentState(uri, DocumentState.Validated, cancelToken);
@@ -396,18 +430,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, state, cancelToken) {
         return this.ensureDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), state, cancelToken);
@@ -425,173 +454,72 @@ export class ModelService {
     async ensureDocumentStateCanonical(uri, state, cancelToken) {
         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, cancelToken) {
-        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 (stage, fn) => (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, cancelToken) {
-        // 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.
+     * so the language client has answered the push of the latest content before
+     * this returns; a push it refused twice is logged, not retried. No-op tail
+     * for headless adopters — `syncChains` is empty without an LSP client.
+     * Bounded at 10 s so a hung build, or an applyEdit reverse-RPC deadlock,
+     * can't freeze the caller; it returns rather than throwing, warning on
+     * timeout. A failed wait is logged at `error`, at `debug` when cancelled and
+     * at `warn` when the document is gone.
      *
-     * 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
-     * dialog on rapid save) call this after their `save`.
+     * The framework's save handlers call this after their persist; an adopter's
+     * own save path that answers a client calls it after its `save` too.
      */
-    async settleSave(uri, cancelToken) {
+    async settleLanguageClient(uri, cancelToken) {
         const canonical = this.uriPolicy.canonicalUri(uri);
         const key = UriUtils.toUri(canonical).toString();
-        const timeout = new Promise((_, reject) => setTimeout(() => reject(new SaveSettleTimeoutError('settle timeout')), SAVE_SETTLE_TIMEOUT_MS));
-        try {
-            await Promise.race([this.waitForDocumentStateCanonical(canonical, IntegrityService.SettledState, cancelToken), timeout]);
-            const pending = this.syncChains.get(key);
-            if (pending) {
-                await Promise.race([pending, timeout]);
+        // One race over both waits, so the bound is one deadline for the pair;
+        // a race per wait would let the caller wait twice the bound.
+        let awaitedChain;
+        const settled = (async () => {
+            await this.waitForDocumentStateCanonical(canonical, IntegrityService.SettledState, cancelToken, { sync: true });
+            const chain = this.syncChains.get(key);
+            if (chain && this.timedOutSyncChains.has(chain)) {
+                this.tracer.withUri(key).debug('Language client settle not waiting again for a push the client has not answered');
+                return;
             }
-        }
-        catch (err) {
-            if (err instanceof SaveSettleTimeoutError) {
-                this.tracer.withUri(key).warn(`Save settle exceeded ${SAVE_SETTLE_TIMEOUT_MS}ms — returning anyway`);
+            awaitedChain = chain;
+            await chain;
+        })();
+        // The settle ends a failed wait, so it logs it, at one level whether the wait failed inside the bound or after it.
+        const reportFailedWait = (error, when) => {
+            const tracer = this.tracer.withUri(key);
+            if (isOperationCancelled(error)) {
+                tracer.debug(`Language client settle cancelled ${when}`);
+            }
+            else if (!this.services.workspace.LangiumDocuments.hasDocument(UriUtils.toUri(canonical))) {
+                tracer.warn(`Language client settle failed ${when}; the document is gone. ${describeErrorWithStack(error)}`);
             }
             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}`);
+                tracer.error(`Language client settle failed ${when}. ${describeErrorWithStack(error)}`);
+            }
+        };
+        try {
+            if ((await this.services.Clock.raceTimer(settled, LANGUAGE_CLIENT_SETTLE_TIMEOUT_MS)) === TIMED_OUT) {
+                this.tracer.withUri(key).warn(`Language client settle exceeded ${LANGUAGE_CLIENT_SETTLE_TIMEOUT_MS}ms — returning anyway`);
+                if (awaitedChain) {
+                    this.timedOutSyncChains.add(awaitedChain);
+                }
+                // The race has settled, so a later failure of the wait, such as a given-up sync build, reaches no one else.
+                void settled.catch((error) => reportFailedWait(error, 'after the timeout'));
             }
         }
+        catch (err) {
+            // Its own line, so the failure is not blamed on the bound.
+            reportFailedWait(err, 'before the timeout — returning anyway');
+        }
     }
-    /**
-     * 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) {
-        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) {
-        return this.services.workspace.AstDocumentManager.close(args);
+    isLanguageClientPushPending(uri) {
+        const chain = this.syncChains.get(UriUtils.toUri(this.uriPolicy.canonicalUri(uri)).toString());
+        return chain !== undefined && !this.timedOutSyncChains.has(chain);
     }
     /**
      * True when the document at `uri` is currently open for at least one
@@ -600,6 +528,35 @@ export class ModelService {
     isOpen(uri) {
         return this.services.workspace.AstDocumentManager.isOpen(uri);
     }
+    openedVersion(uri) {
+        return this.services.workspace.TextDocuments.openedVersion(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) {
+        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);
+        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} /
@@ -608,29 +565,108 @@ 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) {
         return this.services.workspace.AstDocumentManager.getDocument(uri);
     }
     // ============================================================
+    // Client sessions
+    // ============================================================
+    createSession(label, clientId, options = {}) {
+        const sessionLabel = label ?? 'session';
+        const id = clientId ?? `${sessionLabel}#${randomUuid()}`;
+        const textDocuments = this.services.workspace.TextDocuments;
+        if (options.resumeToken !== undefined && this.resumeTokens.get(id) === options.resumeToken) {
+            this.sessions.get(id)?.dispose('lost');
+        }
+        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. Forgotten first: a
+            // dispose listener may start a replacement under the same id.
+            const ended = this.sessions.get(event.clientId);
+            this.sessions.delete(event.clientId);
+            this.resumeTokens.delete(event.clientId);
+            ended?.dispose(event.cause);
+        });
+        let session;
+        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);
+        }
+        catch (err) {
+            textDocuments.closeSession(id);
+            throw err;
+        }
+        this.sessions.set(id, session);
+        if (options.resumeToken !== undefined) {
+            this.resumeTokens.set(id, options.resumeToken);
+        }
+        return session;
+    }
+    getSession(clientId) {
+        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.
+     *
+     * The serialised text then takes the trivia of the text it replaces, or of
+     * an empty one when `uri` has none, so a created document gets the
+     * preservers' defaults rather than the serializer's bare output.
+     */
+    async modelToText(uri, model, cancelToken) {
+        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) {
+            // With no text, an empty one: every preserver still runs, so a created
+            // document takes the defaults a blank one gets.
+            const source = (await this.textToTakeTriviaFrom(uri, target)) ?? '';
+            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)
     // ============================================================
     /**
      * 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
@@ -640,22 +676,19 @@ export class ModelService {
      */
     syncToLanguageClient(document) {
         // `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
-        // 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
+        // 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 `settleLanguageClient` looks the chain up
+        // under — so a settle can drain the in-flight applyEdit. The canonical→client-URI
         // translation (a symlinked path the client opened, or a dual-open fan-out)
         // happens at the `applyEditToLanguageClient` egress, where the text store maps
         // the canonical key to the recorded language-client URI(s); driving the chain
-        // in client space here would key it under a URI `settleSave` never computes, so
-        // the drain would miss for a divergent open path.
+        // in client space here would key it under a URI `settleLanguageClient`
+        // never computes, so 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);
-        }
     }
     /**
      * Mirror the settled text of a document open in the language client via a
@@ -671,44 +704,6 @@ export class ModelService {
     syncOpenDocument(uri, text) {
         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.
-     */
-    stageClosedDocument(document) {
-        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.
-     */
-    isNonLanguageClientEdit(document) {
-        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
@@ -757,17 +752,32 @@ export class ModelService {
             const text = this.pendingSync.get(uri);
             this.pendingSync.delete(uri);
             try {
-                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
+                const textDocuments = this.services.workspace.TextDocuments;
+                // An answer, or a failure, ends a hang a settle timed out on, so the
+                // chain's later pushes are waited for again.
+                const push = async () => {
+                    try {
+                        return await textDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
+                    }
+                    finally {
+                        const chain = this.syncChains.get(uri);
+                        if (chain) {
+                            this.timedOutSyncChains.delete(chain);
+                        }
+                    }
+                };
+                let result = await push();
+                if (result?.applied === false && !this.pendingSync.has(uri) && textDocuments.get(uri)?.getText() === text) {
+                    // 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
                     // editor showing text the server has already superseded, with no
                     // later settle guaranteed to correct it (a content-identical echo
-                    // mints no rebuild). The rejection invalidated the shadow, so the
-                    // retry is a full-range replace: position-independent, and therefore
-                    // correct against whatever the client now holds.
+                    // mints no rebuild). After a rejection the retry is a full-range
+                    // replace: position-independent, and therefore correct against
+                    // whatever the client now holds. It sends nothing when the client
+                    // was last heard to hold the text already.
                     //
                     // Retried INLINE rather than re-enqueued, and exactly once. Inline
                     // because a re-enqueue would have to out-order any settle that lands
@@ -776,9 +786,11 @@ export class ModelService {
                     // the workspace) must cost one extra RPC rather than spin. The
                     // `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: this.editLabel() });
+                    // after this and still wins. It is skipped too once the store holds
+                    // other text: the keystroke that made the client refuse replaced it,
+                    // and re-pushing would overwrite that keystroke in the editor.
+                    uriLogger.debug(`Re-pushing a full replace after the language client refused applyEdit`);
+                    result = await push();
                     if (result?.applied === false) {
                         uriLogger.warn(`Language client rejected the full-replace retry too — client content is stale`);
                     }
@@ -790,49 +802,136 @@ export class ModelService {
                 // ordinary shutdown. Reporting it at `error` makes routine teardown
                 // look like it needs investigating. A genuine applyEdit failure
                 // (client refused, request malformed) still surfaces at `error`.
-                if (isConnectionGoneError(err)) {
+                if (isClientGoneError(err)) {
                     uriLogger.debug(`applyEdit to ${LANGUAGE_CLIENT_ID} skipped: client disconnected`);
                 }
                 else {
-                    uriLogger.error(`applyEdit to ${LANGUAGE_CLIENT_ID} failed: ${err}`);
+                    uriLogger.error(`applyEdit to ${LANGUAGE_CLIENT_ID} failed: ${describeErrorWithStack(err)}`);
                 }
             }
         }
     }
     // ============================================================
-    // Subscription pass-throughs
+    // Subscriptions
     // ============================================================
-    /**
-     * Subscribe to AST-snapshot updates for `uri`. Fires after each
-     * rebuild that reaches the target phase. Delegates to the
-     * `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`).
-     */
-    onModelUpdated(uri, listener) {
-        return this.services.workspace.AstDocumentManager.onUpdate(uri, listener);
+    onModelUpdated(listener, filter = {}) {
+        const phase = filter.phase ?? DocumentState.Validated;
+        let subscribers = this.updateSubscribers.get(phase);
+        if (!subscribers) {
+            const created = new Set();
+            this.updateSubscribers.set(phase, created);
+            this.services.workspace.DocumentBuilder.onDocumentPhase(phase, labelPhaseListener((document, cancelToken) => this.deliverUpdate(phase, created, document, cancelToken), 'ModelService.onModelUpdated'));
+            subscribers = created;
+        }
+        const subscriber = { uri: this.filterUri(filter), listener };
+        subscribers.add(subscriber);
+        return Disposable.create(() => subscribers.delete(subscriber));
     }
-    /**
-     * Subscribe to save events for `uri`. Fires on every persist through
-     * the multi-client text-document store — including saves originated
-     * by other heads (LSP editor `Ctrl+S`, the data-server `save`, etc.)
-     * so subscribers see one consistent stream regardless of who wrote
-     * the file. Delegates to the manager — single listener registration
-     * shared with any direct `HydraniumTextDocuments.onSave` subscriber.
-     */
-    onModelSaved(uri, listener) {
-        return this.services.workspace.AstDocumentManager.onSave(uri, listener);
+    onModelsBuilt(listener, filter = {}) {
+        const phase = filter.phase ?? DocumentState.Validated;
+        return this.services.workspace.DocumentBuilder.onBuildPhase(phase, (built, cancelToken) => {
+            if (cancelToken.isCancellationRequested) {
+                return;
+            }
+            try {
+                listener(Object.freeze({ uris: built.map(document => this.uriPolicy.canonicalUri(document.uri.toString())), phase }));
+            }
+            catch (err) {
+                this.tracer.error(`onModelsBuilt listener threw: ${describeErrorWithStack(err)}`);
+            }
+        });
+    }
+    onModelSaved(listener, filter = {}) {
+        const target = this.filterUri(filter);
+        return this.services.workspace.TextDocuments.onDidSave(event => {
+            // LangiumDocuments keys by the canonical form, the saved event by the
+            // client-facing one.
+            const uri = this.uriPolicy.canonicalUri(event.document.uri);
+            if (this.matches(target, uri)) {
+                listener({ document: this.toAstDocument(UriUtils.toUri(uri)), sourceClientId: event.clientId });
+            }
+        });
+    }
+    onModelDeleted(listener, filter = {}) {
+        const target = this.filterUri(filter);
+        return this.services.workspace.DocumentBuilder.onUpdate((_changed, deleted) => {
+            for (const deletedUri of deleted) {
+                const uri = this.uriPolicy.canonicalUri(deletedUri.toString());
+                if (this.matches(target, uri)) {
+                    listener(Object.freeze({ uri, sourceClientId: this.services.workspace.AstDocumentManager.attributeDeletion(uri) }));
+                }
+            }
+        });
+    }
+    onDirtyChanged(listener, filter = {}) {
+        const target = this.filterUri(filter);
+        return this.services.workspace.TextDocuments.onDidChangeDirty(event => {
+            if (this.matches(target, event.uri)) {
+                listener(event);
+            }
+        });
+    }
+    onModelReleased(listener, filter = {}) {
+        const target = this.filterUri(filter);
+        return this.services.workspace.TextDocuments.onDidReleaseDocument(event => {
+            if (this.matches(target, event.uri)) {
+                listener(event);
+            }
+        });
+    }
+    onClientClosed(listener, filter) {
+        const target = this.uriPolicy.canonicalUri(filter.uri);
+        return this.services.workspace.TextDocuments.onDidClose(event => {
+            if (event.clientId === filter.clientId && this.uriPolicy.canonicalUri(event.document.uri) === target) {
+                listener();
+            }
+        });
+    }
+    filterUri(filter) {
+        return filter.uri === undefined ? undefined : this.uriPolicy.canonicalUri(filter.uri);
+    }
+    matches(target, uri) {
+        return target === undefined || target === uri;
     }
     /**
-     * Subscribe to the `(uri, clientId)` close event. Delegates to the
-     * manager so the listener registry is shared with any direct
-     * `HydraniumTextDocuments.onClientClosed` subscriber.
+     * Hand every subscriber of `phase` for `document` one event, built once, so
+     * all of them see the same attribution. Built inside the build's listener
+     * and handed out without an await: after one, another build can have reset
+     * the document.
      */
-    onClientClosed(uri, clientId, listener) {
-        return this.services.workspace.AstDocumentManager.onClientClosed(uri, clientId, listener);
+    deliverUpdate(phase, subscribers, document, cancelToken) {
+        if (cancelToken.isCancellationRequested || subscribers.size === 0) {
+            return;
+        }
+        const uri = this.uriPolicy.canonicalUri(document.uri.toString());
+        const matching = [...subscribers].filter(subscriber => this.matches(subscriber.uri, uri));
+        if (matching.length === 0) {
+            return;
+        }
+        const manager = this.services.workspace.AstDocumentManager;
+        const envelope = manager.toAstDocument(document);
+        const event = Object.freeze({
+            // Copied: a validation run without a reset, of further categories,
+            // appends to the live array.
+            document: phase >= DocumentState.Validated
+                ? { ...envelope, ...(envelope.diagnostics && { diagnostics: [...envelope.diagnostics] }) }
+                : this.withoutDiagnostics(envelope),
+            ...manager.attributeUpdate(document),
+            phase
+        });
+        for (const { listener } of matching) {
+            // A write queued by an earlier listener cancels this build. Thrown,
+            // so the builder leaves the version undelivered for those skipped.
+            if (cancelToken.isCancellationRequested) {
+                throw OperationCancelled;
+            }
+            try {
+                listener(event);
+            }
+            catch (err) {
+                this.tracer.with(uri).error(`onModelUpdated listener threw: ${describeErrorWithStack(err)}`);
+            }
+        }
     }
     // ============================================================
     // Adopter hooks (override on subclass)
@@ -848,13 +947,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.
      */
     serialize(uri, root) {
@@ -865,22 +964,15 @@ export class ModelService {
     // Protected plumbing (override sparingly)
     // ============================================================
     /**
-     * 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. `undefined` when the store holds no text
+     * for `uri`: a document not yet created, or a file on disk that the
+     * workspace has not read and no client has open. The preservers then run
+     * over empty text, as for a created document; no answer skips them.
      */
-    async modelToText(uri, model, cancelToken) {
-        if (typeof model === 'string') {
-            return model;
-        }
-        const rewritten = await this.rewriteModel(uri, model, cancelToken);
-        return this.serialize(uri, rewritten);
+    async textToTakeTriviaFrom(uri, _target) {
+        return this.services.workspace.TextDocuments.get(uri)?.getText();
     }
     /**
      * Run the per-language transfer-model rewrite chain. Resolves the
@@ -902,16 +994,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.
      */
     toAstDocument(uri) {
         const document = this.services.workspace.LangiumDocuments.getDocument(uri);
         return document
-            ? AstDocument.from(document)
-            : AstDocument.create(uri.toString(), 0, undefined, []);
+            ? this.services.workspace.AstDocumentManager.toAstDocument(document)
+            : AstDocument.create(uri.toString(), UNRECORDED_VERSION, undefined);
+    }
+    /**
+     * 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.
+     */
+    withoutDiagnostics(document) {
+        const { diagnostics: _diagnostics, ...rest } = document;
+        return rest;
     }
 }
 //# sourceMappingURL=model-service.js.map