@hydranium/core 1.0.0-next.117 → 1.0.0-next.123

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

@@ -8,21 +8,13 @@
  ********************************************************************************/
 
 import {
-   type BasedOn,
    type CanonicalUri,
-   type CloseModelArgs,
-   ConflictError,
-   isSnapshotVersion,
    defineMessage,
-   Logger,
    type MaybeObservableValue,
    type MaybePromise,
    ObservableValue,
    type TransferElement,
-   type OpenModelArgs,
-   type Tracer,
-   type TransferSaveArgs,
-   type TransferUpdateArgs
+   type Tracer
 } from '@hydranium/protocol';
 import { type AstNode, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
 import { type AstDiagnostic } from '../validation/document-validator.js';
@@ -35,10 +27,9 @@ 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 { DocumentNotOpenError } from '../../documents/client-session-errors.js';
 import { type OpenOptions } from '../../documents/client-session-registry.js';
 import { type ServerSharedServices } from '../module.js';
-import { type ClientSession, DefaultClientSession } from './client-session.js';
+import { type ClientSession } from './client-session.js';
 
 /**
  * The undo-stack entry for a server-authored write pushed to the editor.
@@ -74,29 +65,6 @@ class SaveSettleTimeoutError extends Error {}
  * and the defaults are the behaviour described on each one.
  */
 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
@@ -119,9 +87,9 @@ export interface ModelServiceOptions extends LogNameOptions {
     * option removes is the wasted pass, not just its visible symptom.
     *
     * **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
+    * reaches a session's `update` / `save` or `rebuild` while already holding
+    * the write lock — an integrity rule or build-phase pass that writes
+    * back — deadlocks: acquiring the lock cancels the running holder, and the new
     * acquisition then waits for that holder to release while the holder waits
     * for this call. On `true` that shape is DETECTED and rejected with
     * {@link ReentrantWriteLockError} rather than hanging, wherever a host
@@ -144,10 +112,11 @@ export interface ModelServiceOptions extends LogNameOptions {
  *
  * 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`.
@@ -157,9 +126,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.
  *
@@ -172,15 +141,16 @@ export interface ModelServiceOptions extends LogNameOptions {
  *
  * **Read-latest supersession**
  *
- * The default `update` and `save` flows use Langium's per-URI
+ * A session's default `update` and `save` 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.
+ * 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**
  *
@@ -232,7 +202,7 @@ export interface ModelServiceOptions extends LogNameOptions {
  *   **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 accepted by `update` / `save`
+ * - `TTransfer` — transfer-model root a session's `update` / `save` accept
  *   args. Constrained to {@link TransferElement}. Defaults to the
  *   structural base.
  */
@@ -266,13 +236,13 @@ export interface ModelService<
    indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
    validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
 
-   update(args: TransferUpdateArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
-   save(args: TransferSaveArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
-
-   open(args: OpenModelArgs): Promise<Disposable>;
-   close(args: CloseModelArgs): Promise<void>;
    isOpen(uri: string): boolean;
    snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined;
+   /**
+    * 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;
@@ -280,12 +250,17 @@ export interface ModelService<
    onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
 
    /**
-    * Start a client session. The id defaults to `label#` plus a random UUID;
-    * a fixed `clientId` is taken as given. Throws `DuplicateClientIdError` when
-    * the id is reserved by the framework, held by another live session, or has
+    * 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 `DuplicateClientIdError` when the id
+    * is reserved by the framework, 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.
+    * `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,
@@ -299,7 +274,7 @@ export class DefaultModelService<
    TAst extends AstNode,
    TDiagnostic extends AstDiagnostic = AstDiagnostic,
    /**
-    * Structured payload accepted by `update` / `save`. Constrained to
+    * 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
@@ -319,12 +294,6 @@ export class DefaultModelService<
     * (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>;
 
@@ -337,11 +306,7 @@ export class DefaultModelService<
    protected readonly syncChains = new Map<string, Promise<void>>();
    protected readonly pendingSync = new Map<string, string>();
 
-   /**
-    * The live sessions this service started, by client id. {@link update}
-    * reads it to tell a session's write, which must find its document open,
-    * from a write under a plain client id, which opens it.
-    */
+   /** 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
@@ -391,7 +356,6 @@ export class DefaultModelService<
    ) {
       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);
       // Optional-chain so a harness that binds no WorkspaceManager awaits
       // `undefined` and resolves immediately; production hosts always have it
@@ -533,6 +497,12 @@ export class DefaultModelService<
     * {@link ModelServiceOptions.serializeBuilds} — see there for the
     * non-reentrancy hazard that is the reason the opt-out exists.
     *
+    * 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.
@@ -696,189 +666,6 @@ export class DefaultModelService<
       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.
-    *
-    * **Upsert, except for a session.** Under a plain client id the write opens
-    * the document for that client first, creating it from the payload when no
-    * file exists. Under the id of a live session from {@link createSession} it
-    * opens nothing, and fails with `DocumentNotOpenError` unless the session
-    * has the URI open at the moment the text is applied.
-    */
-   async update(args: TransferUpdateArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
-      // Read before the first await, while the call is still the caller's: a
-      // session that ends during the serialise would otherwise read as a plain
-      // client id here, and the write would open the document for an id no
-      // session owns any more and land there.
-      const bySession = this.sessions.has(args.clientId);
-      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` only attaches the
-      // client (the text is ignored on that branch), and the actual update is
-      // `AstDocumentManager.update`'s. `version` is intentionally NOT
-      // forwarded to `open`, so a cold create stays at its initial version
-      // rather than adopting a number the caller chose.
-      //
-      // The gate reads the version and decides BEFORE the open, and both halves
-      // of that matter.
-      //
-      // Reading first, because for a document no client holds open the open
-      // assigns the shared version from the INCOMING text, so a version read
-      // afterwards has already absorbed the caller's own write. Gating on it
-      // rejects every modifying write to a closed document, comparing the
-      // caller's `basedOn` against a number the caller itself produced — and a
-      // serialised round-trip that is not byte-identical to the stored text is
-      // enough to trigger that. Reading first keeps both cases the gate exists
-      // for: an unknown URI answers 0, so a based-on-version update of a
-      // not-yet-existing document still trips it, and a genuine conflict still
-      // trips it, another writer having advanced the sequence past the version
-      // the caller read.
-      //
-      // Deciding first, because the open is a mutation and `update` is an
-      // upsert: for a cold URI it installs the payload in the shared text store
-      // and records a hold for the writing client. Throwing after it hands the
-      // caller its rejection while the server keeps the refused text — and the
-      // hold outlives the call, because a client whose write failed has no
-      // reason to close a document it never asked to open. Serialisation is
-      // held back too; it is the adopter's code and need not be side-effect
-      // free.
-      const textDocuments = this.services.workspace.TextDocuments;
-      this.checkBasedOn(uri, args.basedOn, textDocuments.version(uri));
-      // Whether this call's own open is the one that creates the document, read
-      // in the same step as the check above so no other open can land between.
-      const opensCold = !bySession && textDocuments.get(uri) === undefined;
-      const text = await run('serialize', () => this.modelToText(uri, args.model, cancelToken));
-      if (!bySession) {
-         await run('open', () => this.open({ uri, clientId: args.clientId, text }));
-      }
-      const appliedVersion = await run('apply', () => {
-         // A session's write never opens its document. The check sits in the
-         // same synchronous step as the apply: made before the serialize await
-         // instead, it passes for a write whose session closes the document
-         // during that await, and the write then lands on a document the
-         // session no longer has open.
-         if (bySession && !textDocuments.isOpenInClient(uri, args.clientId)) {
-            throw new DocumentNotOpenError(uri, args.clientId);
-         }
-         // The gate again, in the same step as the apply: two writes based on
-         // one version both pass the check at the door while they serialise,
-         // and without this both apply. The version a cold open assigned from
-         // this write's own text is not a conflict; the store holding exactly
-         // that text is how it shows.
-         if (!(opensCold && textDocuments.get(uri)?.getText() === text)) {
-            this.checkBasedOn(uri, args.basedOn, textDocuments.version(uri));
-         }
-         return 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;
-   }
-
-   /**
-    * Throw {@link ConflictError} when `basedOn` names a version other than
-    * `currentVersion`. {@link update} calls it at the door and again in the
-    * synchronous step that applies the text, and has to call it synchronously
-    * there: a check separated from the apply by an await lets two writes based
-    * on one version both apply.
-    */
-   protected checkBasedOn(uri: string, basedOn: BasedOn, currentVersion: number): void {
-      if (isSnapshotVersion(basedOn) && currentVersion !== basedOn) {
-         // Distinct from the post-build "superseded" debug line in `update`: this
-         // is a based-on-stale rejection (the write never applies), not two
-         // writes racing.
-         this.tracer.debug(`Conflict on ${uri}: based-on v${basedOn} stale, server at v${currentVersion}`);
-         throw new ConflictError(uri, basedOn, currentVersion);
-      }
-   }
-
-   /**
-    * 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.
-    *
-    * Under the id of a live session the save also fails with
-    * `DocumentNotOpenError` when the session closes the URI while the text is
-    * being built, and writes nothing. Once the manager has taken the text, the
-    * write completes whatever the session does next.
-    */
-   async save(args: TransferSaveArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
-      // Read before the first await, as in `update`: a session that ends during
-      // the rebuild would otherwise read as a plain client id below.
-      const bySession = this.sessions.has(args.clientId);
-      // 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);
-      // In the same synchronous step as the manager taking the text: checked
-      // any earlier, a session that closes the URI during the rebuild still has
-      // the shared text, other clients' edits included, written in its name.
-      if (bySession && !this.services.workspace.TextDocuments.isOpenInClient(uri, args.clientId)) {
-         throw new DocumentNotOpenError(uri, args.clientId);
-      }
-      await this.services.workspace.AstDocumentManager.save(uri, args.clientId);
-      return doc;
-   }
-
    /**
     * Wait for the document at `uri` to reach the integrity-settled landmark and
     * drain any in-flight write-path applyEdit sync chain (see {@link syncChains})
@@ -914,38 +701,6 @@ export class DefaultModelService<
       }
    }
 
-   /**
-    * 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.
@@ -1020,7 +775,15 @@ export class DefaultModelService<
       });
       let session: ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>;
       try {
-         session = this.newSession<TOpenOptions>(id, sessionLabel);
+         // 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;
@@ -1034,18 +797,35 @@ export class DefaultModelService<
    }
 
    /**
-    * Build the handle for a session {@link createSession} has already
-    * registered. The override point for a custom session class; narrow the
-    * return type to it.
+    * Convert a structured-or-textual `model` payload to its textual form.
     *
-    * Registration and the uniqueness check have already happened when this
-    * runs, so an override cannot skip them.
+    * 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.
     */
-   protected newSession<TOpenOptions extends OpenOptions = OpenOptions>(
-      clientId: string,
-      label: string
-   ): ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions> {
-      return new DefaultClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>(this, this.services, clientId, label);
+   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);
    }
 
    // ============================================================
@@ -1056,23 +836,14 @@ export class DefaultModelService<
     * 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`.
+    * `HydraniumTextDocuments.applyEditToLanguageClient`.
     *
-    * Routes by client registration, because an open and a closed document
-    * answer different questions:
-    *
-    * - **Open in the language client** → {@link syncOpenDocument}: mirror the
-    *   settled text via a coalesced `applyEditToLanguageClient`, routed purely by
-    *   **content**.
-    * - **Open only in another client** (the data or GLSP head) → nothing. A
-    *   language client opening it joins the existing entry and is refreshed from
-    *   the store, and only a FIRST open reads a stage, so staging here would
-    *   leave text nothing reads.
-    * - **Closed in every client** → {@link stageClosedDocument}, gated by
-    *   **provenance** ({@link isNonLanguageClientEdit}). With the default text
-    *   store this never stages; see {@link stageClosedDocument} for why, and
-    *   for the store it serves.
+    * 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
@@ -1092,11 +863,8 @@ export class DefaultModelService<
       // 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.
-      const textDocuments = this.services.workspace.TextDocuments;
-      if (textDocuments.isOpenInLanguageClient(document.textDocument.uri)) {
+      if (this.services.workspace.TextDocuments.isOpenInLanguageClient(document.textDocument.uri)) {
          this.syncOpenDocument(document.textDocument.uri, document.textDocument.getText());
-      } else if (!textDocuments.isOpenInAnyClient(document.textDocument.uri)) {
-         this.stageClosedDocument(document);
       }
    }
 
@@ -1115,53 +883,6 @@ export class DefaultModelService<
       this.queueSync(uri, text);
    }
 
-   /**
-    * Stage the settled text of a document no client holds 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.
-    *
-    * The default `HydraniumTextDocuments` never gets this far. Its own paths
-    * record a version's author only while a client holds the document, and the
-    * last close drops that history with the tracking record, so a document no
-    * client holds reports no author and the provenance gate refuses. The stage
-    * is reachable for a text store that keeps authorship past the last close,
-    * or a subclass overriding {@link isNonLanguageClientEdit}.
-    */
-   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
-    * (`isTriggeringEdit`)". 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 `isTriggeringEdit` 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.isTriggeringEdit(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
@@ -1307,13 +1028,13 @@ export class DefaultModelService<
     * 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> {
@@ -1326,62 +1047,12 @@ export class DefaultModelService<
    // ============================================================
 
    /**
-    * 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.
-    */
-   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);
-      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);
-   }
-
-   /**
-    * The text a write into an unloaded document should take its trivia from —
-    * the open editor's if one holds it, the file's otherwise, and `undefined`
-    * when neither can supply it.
-    *
-    * **A read that fails answers `undefined` rather than throwing.** `getDocument`
-    * is a store read, so an ordinary create answers nothing here and must still
-    * write; letting a permission error or a path that turned into a directory
-    * escape would fail the user's write instead, having found nothing to preserve
-    * in a file the write is about to replace anyway. Losing the comments is
-    * recoverable, and traced; losing the write is neither.
+    * 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 textToTakeTriviaFrom(uri: string, target: URI): Promise<string | undefined> {
-      const open = this.services.workspace.TextDocuments.get(uri)?.getText();
-      if (open !== undefined) {
-         return open;
-      }
-      const fileSystem = this.services.workspace.FileSystemProvider;
-      try {
-         return (await fileSystem.exists(target)) ? await fileSystem.readFile(target) : undefined;
-      } catch (err: unknown) {
-         const detail = err instanceof Error ? err.message : String(err);
-         this.tracer.withUri(uri).debug(`Could not read the file to take trivia from; writing as emitted. ${detail}`);
-         return undefined;
-      }
+   protected async textToTakeTriviaFrom(uri: string, _target: URI): Promise<string | undefined> {
+      return this.services.workspace.TextDocuments.get(uri)?.getText();
    }
 
    /**