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

package/lib/langium/model-service/model-service.d.ts

@@ -6,87 +6,87 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { type CanonicalUri, type CloseModelArgs, type MaybeObservableValue, type MaybePromise, ObservableValue, type TransferDiagnostic, type TransferElement, type OpenModelArgs, type Tracer, type TransferSaveArgs, type TransferUpdateArgs } from '@hydranium/protocol';
+import { type CanonicalUri, type MaybeObservableValue, type MaybePromise, ObservableValue, type TransferElement, type TextVersion, type Tracer } from '@hydranium/protocol';
 import { type AstNode, DocumentState, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type AstDiagnostic } from '../validation/document-validator.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
-import { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import { CancellationToken, type Disposable } from 'vscode-languageserver';
 import { AstDocument, type AstDocumentSavedEvent, type AstDocumentUpdatedEvent } from '../../documents/ast-document-manager.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type OpenOptions } from '../../documents/client-session-registry.js';
 import { type ServerSharedServices } from '../module.js';
+import { type ClientSession } from './client-session.js';
+/**
+ * The undo-stack entry for a server-authored write pushed to the editor.
+ *
+ * **A user-facing LABEL, not a log string**, which is easy to miss because it
+ * travels as an options field rather than as a message: LSP specifies
+ * `ApplyWorkspaceEditParams.label` as "presented in the user interface for
+ * example on an undo stack to undo the workspace edit". So a user who edits
+ * through a form or drags a diagram node reads this in their editor's undo menu
+ * — which is why it is rendered like any other message the server sends rather
+ * than left as the English literal it was.
+ *
+ * Parameterless deliberately. The obvious improvement is to name the document,
+ * and it is the wrong one: an undo menu is already grouped under the file, so
+ * the URI would be noise in the one place it is redundant.
+ */
+export declare const MODEL_UPDATE_EDIT: import("@hydranium/protocol").MessageDefinition<"Update Model">;
 /**
  * Constructor options for {@link ModelService}. All fields are optional,
  * 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
-     * `true`.
-     *
-     * **Why it defaults on.** Unlocked, the facade's build races the LSP bridge's
-     * build of the same URI — both are legitimate (the bridge exists only under a
-     * `Connection`, so the facade stands in for it headless), but nothing
-     * serialises them, so both run a full validation pass and Langium appends the
-     * second onto the first. Every diagnostic is then duplicated, and the
-     * duplication compounds per rebuild. Serialised, Langium elides the second
-     * build entirely, so the redundant work goes too.
-     *
-     * **What `false` costs.** The facade's build is then unserialised and can run
-     * concurrently with the bridge's build of the same URI, so the affected
-     * documents are validated twice per write — double the validation work.
-     * Reported diagnostics stay correct even then, because
-     * `HydraniumDocumentBuilder.dedupeDiagnostics` collapses the byte-identical
-     * duplicates a repeated pass produces before any listener sees them; what this
-     * option removes is the wasted pass, not just its visible symptom.
-     *
-     * **What `false` buys.** `WorkspaceLock` is not reentrant. A caller that
-     * reaches `update` / `save` / `rebuild` while already holding the write lock —
-     * an integrity rule or build-phase pass that writes through this facade —
-     * deadlocks: acquiring the lock cancels the running holder, and the new
-     * acquisition then waits for that holder to release while the holder waits
-     * for this call. On `true` that shape is DETECTED and rejected with
-     * {@link ReentrantWriteLockError} rather than hanging, wherever a host
-     * installs a write-lock scope tracker (`@hydranium/core/node` does at entry
-     * load; see {@link isInsideWriteLock}). Setting `false` is the escape hatch
-     * for an adopter whose reentrant shape is unavoidable — nothing acquires the
-     * lock then, so there is nothing to be reentrant about; prefer it over
-     * unserialised builds only in that case.
+     * Let the facade's build run without the workspace write lock when its
+     * caller already holds it: an integrity rule or build-phase pass that
+     * writes back through a session's `update` / `save`, or calls `rebuild`.
+     * Default `false`.
+     *
+     * `WorkspaceLock` is not reentrant. Taking it from inside a holder cancels
+     * that holder and then waits for it to end, while the holder waits for this
+     * call, so neither completes. On `false` that call fails with
+     * {@link ReentrantWriteLockError} instead, wherever a host installs a
+     * write-lock scope tracker (`@hydranium/core/node` does at entry load); on
+     * `true` its build takes no lock. The wait after that build can still hang,
+     * because a document no build will carry is re-queued through the lock, and
+     * the re-queue waits for the holder to end.
+     *
+     * Every other facade build takes the lock on either value. Unlocked, it can
+     * overlap another build of the same document: both run a full validation
+     * pass that Langium appends, and a caller can be handed a version that an
+     * integrity repair still running in the other build then moves past. Without
+     * a tracker the two cases cannot be told apart (see
+     * {@link isWriteLockScopeInstalled}), so `true` builds without the lock every
+     * time and accepts both.
      *
      * Accepts a {@link MaybeObservableValue} so it can be bound to a setting and
      * flipped without a restart.
      */
-    readonly serializeBuilds?: MaybeObservableValue<boolean>;
+    readonly allowReentrantBuilds?: MaybeObservableValue<boolean>;
+}
+/** Options for a {@link DefaultModelService} wait on one document. */
+export interface SyncedWaitOptions {
+    /**
+     * Build a root parsed from text older than the store's at the call, and
+     * reject once that build, or one the builder re-queues, is given up. Without
+     * it, such a root is left to other builds, and a wait they never end stays
+     * pending until its token is cancelled.
+     */
+    readonly sync?: boolean;
 }
 /**
+ * The seam every non-LSP head talks to: the data server, the GLSP head and an
+ * adopter's own services reach documents through this slot rather than through
+ * the workspace stores.
+ *
  * In-process facade over the framework's document plumbing
  * (`HydraniumTextDocuments`, `LangiumDocuments`,
- * `DocumentBuilder`, `WritableFileSystemProvider`). Owns the
- * `open / request / update / save / ready` lifecycle that protocol heads
- * (LSP, data-server, GLSP) delegate to so coordinating those primitives
- * doesn't have to be re-implemented per-head.
+ * `DocumentBuilder`, `WritableFileSystemProvider`). Owns the document
+ * lifecycle the data-server and GLSP heads delegate to — client sessions that
+ * open, update, save and close documents, the phase reads, and `ready` — so
+ * coordinating those primitives doesn't have to be re-implemented per head.
+ * Every open and write goes through a session from {@link createSession}.
  *
  * "Model" here means the parsed AST — distinct from the wire-shape
  * `TransferDocument` in `@hydranium/protocol`.
@@ -96,9 +96,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.
  *
@@ -111,15 +111,16 @@ export interface ModelServiceOptions extends LogNameOptions {
  *
  * **Read-latest supersession**
  *
- * The default `update` and `save` flows use Langium's per-URI
- * `DocumentBuilder.waitUntil` to wait for the integrity-settled landmark
- * ({@link IntegrityService.SettledState}), then read the post-build state. Concurrent
- * in-process callers on the same URI all see the latest post-build
- * snapshot — none deadlock waiting for a specific version's settled
- * event. Adopters wanting strict version-matched semantics (resolve
- * with vN's snapshot specifically, log "vN superseded by vM at vN+1")
- * override {@link update} to attach a phase-listener with explicit
- * version checks; the framework default doesn't need it for safety.
+ * A session's default `update` and `save` use Langium's per-URI
+ * `DocumentBuilder.waitUntil` to wait for `Validated` (the integrity-settled
+ * landmark {@link IntegrityService.SettledState} when rebuilds do not
+ * validate), then read the post-build state. Concurrent in-process callers
+ * on the same URI all see the latest post-build snapshot — none deadlock
+ * waiting for a specific version's settled event. Adopters wanting strict
+ * version-matched semantics (resolve with vN's snapshot specifically, log
+ * "vN superseded by vM at vN+1") override
+ * `DefaultClientSession.updateDocument` to attach a phase-listener with
+ * explicit version checks; the framework default doesn't need it for safety.
  *
  * **Returns AST snapshots, not wire envelopes**
  *
@@ -139,18 +140,112 @@ export interface ModelServiceOptions extends LogNameOptions {
  * by URI happens here so consumers can subscribe per-document without
  * implementing the URI gate at each callsite.
  *
+ * **Two families.** `waitFor*` only waits: it rejects for a URI with no
+ * document, and for a root behind the store's text it waits for whatever
+ * builds it next, so it never ends if nothing does. `ensureDocumentState` and
+ * the phase shorthands over it build a missing document, and build a root
+ * behind its text, rejecting when that build fails twice. Both re-queue a
+ * document the builder's last build left short of the state.
+ *
+ * Both resolve at the state with a root parsed from text no older than the
+ * store's version at the call; inside the write lock, at the state alone, since
+ * the build that would sync the document to that version cannot start until
+ * it is released.
+ *
+ * Do not await one inside a build phase listener: a browser host installs no
+ * write-lock scope, so the wait cannot tell it is inside a build and waits for
+ * one that cannot start. Nor inside a `WorkspaceLock.read`: the lock starts no
+ * write, the build included, while a read runs.
+ *
+ * **Diagnostics are typed `never` below `Validated`.** Validation is the last
+ * phase, so at any earlier landmark the array either is not yet computed or
+ * still holds the previous build's, and reading it would take stale results
+ * for fresh ones. A caller that needs diagnostics asks for {@link validated}.
+ *
+ * What the `never` buys, exactly: reading a field off an element is a compile
+ * error, and nothing can be appended. It does NOT stop a caller assigning an
+ * element to a typed variable, because `never` is assignable to everything — so
+ * this is a guard against reaching for diagnostics by accident, not a seal
+ * against doing it deliberately.
+ *
+ * The waits resolve at or ABOVE their target, so an already-validated document
+ * does carry usable diagnostics and the `never` over-forbids there. That
+ * direction is the safe one: the alternative permits stale reads silently. A
+ * member taking a phase as a PARAMETER returns `TDiagnostic`, and leaves them
+ * absent for a phase below `Validated`.
+ *
  * **Generic parameters.**
  * - `TAst` — the AST root type each consumer expects on the returned
  *   {@link AstDocument}. Constrained to {@link AstNode}.
- * - `TDiagnostic` — wire diagnostic shape used by the injected
- *   `TransferEncoder`. Defaults to {@link TransferDiagnostic}.
- * - `TTransfer` — transfer-model root accepted by `update` / `save`
+ * - `TDiagnostic` — the AST-layer diagnostic: whatever the build left on
+ *   `LangiumDocument.diagnostics`, carried through on the returned
+ *   {@link AstDocument}. Defaults to {@link AstDiagnostic}.
+ *   **Not the `TransferEncoder`'s parameter of the same name**, which is
+ *   that encoder's OUTPUT and so names the wire shape. This one names its
+ *   input, and an adopter binds the two to different types.
+ * - `TTransfer` — transfer-model root a session's `update` / `save` accept
  *   args. Constrained to {@link TransferElement}. Defaults to the
  *   structural base.
  */
-export declare class ModelService<TAst extends AstNode, TDiagnostic = TransferDiagnostic, 
+export interface ModelService<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic, TTransfer extends TransferElement = TransferElement> {
+    /**
+     * Resolves once the workspace has been initialised and its first build has
+     * completed — the gate every read should wait behind, since a document
+     * queried before it may be unbuilt and reach no phase.
+     *
+     * A property rather than a method, matching `ProjectManager.ready` and
+     * Langium's `WorkspaceManager.ready`. An implementation needing a stricter
+     * gate supplies a Promise that awaits its own concern as well.
+     */
+    readonly ready: Promise<void>;
+    waitForDocumentState(uri: string, state: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+    waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+    waitForBuilderState(state: DocumentState, cancelToken?: CancellationToken): Promise<void>;
+    ensureDocumentState(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+    rebuild(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+    /**
+     * Throw where {@link rebuild} would reject as reentrant. A write calls it
+     * before applying its text: a text applied and then refused stays applied
+     * with no build to follow it.
+     */
+    assertCanBuild(uri: string): void;
+    parsed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+    linked(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+    settled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+    indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+    validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+    isOpen(uri: string): boolean;
+    snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined;
+    /**
+     * The text a session's write of `model` to `uri` applies: a textual model
+     * as given, a structured one rewritten and serialised.
+     */
+    modelToText(uri: string, model: TTransfer | string, cancelToken?: CancellationToken): Promise<string>;
+    getDocument(uri: string): LangiumDocument | undefined;
+    onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
+    onModelSaved(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void): Disposable;
+    onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
+    /**
+     * Start a client session, the only way to open and write documents through
+     * this service. Pass a `label` naming the participant; without one it is
+     * `session`. The id defaults to `label#` plus a random UUID; a fixed
+     * `clientId` is taken as given. Throws `ReservedClientIdError` when the id
+     * is reserved by the framework, and `DuplicateClientIdError` when it is
+     * held by another live session or has documents open under it as a client
+     * that is not a session.
+     *
+     * `TOpenOptions` types the options the session's `open` takes and its
+     * `openOptions` returns. The narrowing is an unchecked cast, and it holds
+     * only for the caller that started the session: a holder reached through
+     * {@link getSession} sees plain `OpenOptions`.
+     */
+    createSession<TOpenOptions extends OpenOptions = OpenOptions>(label?: string, clientId?: string): ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>;
+    /** The live session started under `clientId`, or `undefined` once it has ended or was never started. */
+    getSession(clientId: string): ClientSession<TAst, TDiagnostic, TTransfer> | undefined;
+}
+export declare 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
@@ -158,7 +253,7 @@ export declare class ModelService<TAst extends AstNode, TDiagnostic = TransferDi
  * constraint, so in-process callers (e.g. GLSP state or an
  * integrity service) that pass AST roots remain compatible.
  */
-TTransfer extends TransferElement = TransferElement> {
+TTransfer extends TransferElement = TransferElement> implements ModelService<TAst, TDiagnostic, TTransfer> {
     protected readonly services: ServerSharedServices;
     protected readonly tracer: Tracer;
     /**
@@ -170,14 +265,8 @@ TTransfer extends TransferElement = TransferElement> {
      * (see {@link DocumentUriPolicy}).
      */
     protected readonly uriPolicy: DocumentUriPolicy;
-    /**
-     * Live slow-update-warn threshold cell, or `undefined` when the option
-     * was not supplied (warn line + stopwatch disabled). Reads `.value` per
-     * update so a setting-bound threshold retunes without reconstruction.
-     */
-    protected readonly slowUpdateWarn?: ObservableValue<number>;
-    /** See {@link ModelServiceOptions.serializeBuilds}. Defaults to `true`. */
-    protected readonly serializeBuilds: ObservableValue<boolean>;
+    /** See {@link ModelServiceOptions.allowReentrantBuilds}. Defaults to `false`. */
+    protected readonly allowReentrantBuilds: ObservableValue<boolean>;
     /**
      * Per-URI applyEdit coalescing: at most one in-flight `applyEditToLanguageClient`
      * RPC per URI, newest text wins. A newer settle while the current RPC is in
@@ -186,6 +275,15 @@ TTransfer extends TransferElement = TransferElement> {
      */
     protected readonly syncChains: Map<string, Promise<void>>;
     protected readonly pendingSync: Map<string, string>;
+    /** The live sessions this service started, by client id, for {@link getSession}. */
+    protected readonly sessions: Map<string, ClientSession<TAst, TDiagnostic, TTransfer, object>>;
+    /**
+     * Drops an ended session from {@link sessions}. Subscribed by the first
+     * {@link createSession} rather than at construction, so a services tree with
+     * no text store, or one that knows nothing of sessions, still constructs
+     * this service.
+     */
+    protected sessionCloseListener?: Disposable;
     /**
      * Workspace-level readiness gate. Resolves when the framework has
      * finished its first workspace build cycle and the `ModelService`
@@ -221,10 +319,12 @@ TTransfer extends TransferElement = TransferElement> {
     readonly ready: Promise<void>;
     constructor(services: ServerSharedServices, options?: ModelServiceOptions);
     /**
-     * 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
@@ -235,10 +335,9 @@ TTransfer extends TransferElement = TransferElement> {
      * 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.
      */
-    waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+    waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
     /**
      * Internal wait core operating on an already-{@link CanonicalUri canonical}
      * URI. The public string doors ({@link waitForDocumentState} /
@@ -248,8 +347,31 @@ TTransfer extends TransferElement = TransferElement> {
      * the identity once instead of re-running the (filesystem-touching) `realpath`
      * at every wait. The `CanonicalUri` parameter type enforces that — a raw
      * `string` cannot be passed without minting through the URI policy.
+     *
+     * With `options.sync`, a root behind the store's text is built, as in
+     * {@link ensureDocumentState}; without it, the root is left to other builds,
+     * as in {@link waitForDocumentState}. Below `Validated` the envelope has no
+     * diagnostics: see {@link withoutDiagnostics}.
+     */
+    protected waitForDocumentStateCanonical(uri: CanonicalUri, state: DocumentState, cancelToken?: CancellationToken, options?: SyncedWaitOptions): Promise<AstDocument<TAst, TDiagnostic>>;
+    /**
+     * Wait for `state` with a root parsed from text at `textVersion` or later. A
+     * root no factory recorded counts as synced, since no build records it.
+     * With `options.sync`, a root still behind is built through
+     * `VersionSyncService.syncTo`, and the wait rejects once that build, or one
+     * the builder re-queues to reach `state`, is given up. Without it, the wait
+     * lasts until another build parses the text, and stays pending when the
+     * builder gives up re-queuing the document.
      */
-    protected waitForDocumentStateCanonical(uri: CanonicalUri, state: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+    protected waitUntilSynced(uri: URI, state: DocumentState, textVersion: TextVersion | undefined, cancelToken?: CancellationToken, options?: SyncedWaitOptions): Promise<void>;
+    /**
+     * Resolves once a parse of `uri` has been recorded or a build has deleted
+     * it, rejecting with `OperationCancelled` when `cancelToken` is cancelled
+     * first, and with an error when `build`, the build requested for it, is
+     * given up. A `Parsed` phase listener cannot serve: a cancel right after the
+     * parse skips it, and the resumed build does not parse again.
+     */
+    protected nextParseOrDeletion(uri: URI, cancelToken?: CancellationToken, build?: Promise<boolean>): Promise<void>;
     /**
      * Wait for the document builder to reach `state` across its currently-
      * queued documents. Pure wait — does not trigger a build. Used by
@@ -264,31 +386,35 @@ TTransfer extends TransferElement = TransferElement> {
      * 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.
-     *
-     * Returns an empty `{ root, diagnostics }` envelope when the document
-     * cannot be loaded; adopters that want to throw override this method
-     * on their subclass.
+     * fine: the LSP head builds from the LSP-driven event and the facade from
+     * its own RPC-driven event — both legitimate — and both go through
+     * `HydraniumDocumentBuilder.scheduleUpdate`, which serialises them under
+     * the workspace WRITE lock and lets the second share the first's build
+     * where that build carries it. Langium alone does not coalesce concurrent
+     * builds of one URI: two unserialised builds each run a full validation
+     * pass and Langium appends the second set onto the first, duplicating every
+     * diagnostic. A caller that already holds the lock builds without it only
+     * under {@link ModelServiceOptions.allowReentrantBuilds} — see there for the
+     * non-reentrancy hazard.
+     *
+     * An override calls the base before it awaits. Under an LSP connection the
+     * store's change event has already asked the update handler to build a
+     * session's write; an override whose await outlasts that build makes the
+     * base's request start a build of its own, so the write is built and
+     * delivered twice.
+     *
+     * 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}
@@ -297,30 +423,36 @@ TTransfer extends TransferElement = TransferElement> {
     rebuild(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
     /**
      * 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,
      * not a redundant identity canonicalisation.)
      */
     protected rebuildCanonical(uri: CanonicalUri, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+    assertCanBuild(uri: string): void;
     /**
      * 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
@@ -335,18 +467,13 @@ TTransfer extends TransferElement = TransferElement> {
     /**
      * 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.
      */
     ensureDocumentState(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
     /**
@@ -361,80 +488,44 @@ TTransfer extends TransferElement = TransferElement> {
      */
     protected ensureDocumentStateCanonical(uri: CanonicalUri, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
     /**
-     * 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.
-     */
-    update(args: TransferUpdateArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
-    /**
-     * 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.
-     */
-    save(args: TransferSaveArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
-    /**
-     * Wait for the document at `uri` to reach the integrity-settled landmark and
+     * Wait for the document at `uri` to reach the integrity-settled landmark,
+     * building a root behind its text as {@link ensureDocumentState} does, and
      * drain any in-flight write-path applyEdit sync chain (see {@link syncChains})
      * so every language client reflects the latest content before a save returns.
      * No-op tail for headless adopters — `syncChains` is empty without an LSP
      * client. Bounded by {@link SAVE_SETTLE_TIMEOUT_MS} so a hung build, or an
-     * applyEdit reverse-RPC deadlock, can't freeze the caller; on timeout it logs
-     * a warning and returns rather than throwing.
+     * applyEdit reverse-RPC deadlock, can't freeze the caller; on timeout or a
+     * failed wait it logs a warning and returns rather than throwing.
      *
      * Adopters with a save flow that must converge editor + disk before returning
      * (e.g. a dual form/code editor that would otherwise show a content-conflict
      * dialog on rapid save) call this after their `save`.
      */
     protected settleSave(uri: string, cancelToken?: CancellationToken): Promise<void>;
-    /**
-     * 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.
-     */
-    open(args: OpenModelArgs): Promise<Disposable>;
-    /**
-     * Close the document at `args.uri` for `args.clientId`. Counterpart
-     * to {@link open}; the underlying document stays open until every
-     * registered client has closed.
-     */
-    close(args: CloseModelArgs): Promise<void>;
     /**
      * True when the document at `uri` is currently open for at least one
      * client. Pure read; no side effects.
      */
     isOpen(uri: string): boolean;
+    /**
+     * Snapshot of `uri` as it stands RIGHT NOW — the synchronous sibling of the
+     * phase reads, which all wait. `undefined` when no document is registered,
+     * or only the builder's placeholder for one its build has not parsed yet:
+     * that root is no parse of any text, and its version gates no write.
+     *
+     * **This is what a writer wants, and {@link getDocument} is not.** The
+     * envelope's `version` is copied by value at projection time, so it cannot
+     * move afterwards; a version read off the live document at write time is
+     * whatever the server is at *now*, which is the number an optimistic gate is
+     * about to compare it against.
+     *
+     * Diagnostics only from a document that has reached `Validated`, and absent
+     * otherwise. Unlike the phase reads this one names no phase, so
+     * the state it finds is the only thing that can say whether the array
+     * describes the content being handed back or whatever an earlier build left.
+     * A caller that needs them unconditionally waits, via {@link validated}.
+     */
+    snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined;
     /**
      * The built {@link LangiumDocument} for `uri`, looked up by canonical identity —
      * the synchronous, phase-agnostic sibling of {@link ensureDocumentState} /
@@ -443,24 +534,41 @@ TTransfer extends TransferElement = TransferElement> {
      * into `LangiumDocuments` directly: a symlinked / `..` / case-divergent URI
      * still resolves to the one document the build keys by its real path. Returns
      * `undefined` if no document is registered for `uri`.
+     *
+     * **Live, so do not take a base version off it.** `textDocument` is the
+     * store's own object rather than a copy, so `.version` read here answers for
+     * the moment of the READ, not the moment of the earlier content — pass it to
+     * a write and the server compares its current version against itself, the
+     * gate passes unconditionally, and a concurrent edit is overwritten with
+     * nothing logged. Use {@link snapshot} for that, or a phase read.
      */
     getDocument(uri: string): LangiumDocument | undefined;
+    createSession<TOpenOptions extends OpenOptions = OpenOptions>(label?: string, clientId?: string): ClientSession<TAst, TDiagnostic, TTransfer, TOpenOptions>;
+    getSession(clientId: string): ClientSession<TAst, TDiagnostic, TTransfer> | undefined;
+    /**
+     * 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.
+     */
+    modelToText(uri: string, model: TTransfer | string, cancelToken?: CancellationToken): Promise<string>;
     /**
      * 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
@@ -481,35 +589,6 @@ TTransfer extends TransferElement = TransferElement> {
      * author-based skip is needed.
      */
     protected syncOpenDocument(uri: string, text: string): void;
-    /**
-     * Stage the settled text of a document closed in the language client so the
-     * eventual first `didOpen` sees this in-memory text instead of stale disk —
-     * but only for a {@link isNonLanguageClientEdit genuine non-language-client edit}.
-     * A document rebuilt by an internal build is skipped, leaving disk authoritative
-     * on the next open.
-     */
-    protected stageClosedDocument(document: LangiumDocument): void;
-    /**
-     * Whether `document`'s settled state is a genuine edit by a client *other than
-     * the language client* — a write a form / GLSP / integrity client actually made.
-     * Excludes two non-edits: the **language client** itself (the LSP/Monaco text
-     * client — it already holds its own edits, and the staging here exists to feed
-     * it) and an **internal build** (workspace startup, a cascade relink, a
-     * `didClose`-reload). This is the gate for {@link stageClosedDocument}: staging
-     * an internal build would
-     * (a) pre-stage every file on boot and (b) re-stage discarded content after
-     * close (e.g. a disposing GLSP session's debounced submit firing after close),
-     * which then shadows clean disk on the next open.
-     *
-     * The signal is "a known client other than the language client authored this
-     * version **and** the URI was in the last build's changed set
-     * (`isDirectChange`)". A framework-internal rebuild reports no author
-     * (`getAuthor` → `undefined`), so it fails `hasKnownAuthor` without comparing
-     * against a sentinel. This is NOT redundant with content/registration — it
-     * distinguishes "client edited" from "framework rebuilt", which neither the
-     * shadow nor `isDirectChange` alone can.
-     */
-    protected isNonLanguageClientEdit(document: LangiumDocument): boolean;
     /**
      * 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
@@ -518,6 +597,16 @@ TTransfer extends TransferElement = TransferElement> {
      * per URI so the shadow never drifts from Monaco.
      */
     protected queueSync(uri: string, text: string): void;
+    /**
+     * The undo-stack label for a server-authored write, in the locale the server
+     * was handed at init.
+     *
+     * One method rather than the literal at each `applyEdit`, because the two
+     * call sites are the same edit — a push and its full-replace retry — and an
+     * undo menu showing two different words for one operation would read as two
+     * operations.
+     */
+    protected editLabel(): string;
     protected drainSyncQueue(uri: string): Promise<void>;
     /**
      * Subscribe to AST-snapshot updates for `uri`. Fires after each
@@ -525,9 +614,8 @@ TTransfer extends TransferElement = TransferElement> {
      * `HydraniumTextDocuments` — single listener registration shared with
      * any direct `HydraniumTextDocuments.onUpdate` subscriber, so the same
      * underlying `DocumentBuilder.onDocumentPhase` listener serves both
-     * call paths. `sourceClientId` is resolved from the multi-client
-     * author history; reason discrimination follows the manager's own
-     * `lastUpdate` snapshot (see `AstDocumentManager.onUpdate`).
+     * call paths. The event's reason, source and cause are
+     * {@link AstDocumentManager.attributeUpdate}'s.
      */
     onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
     /**
@@ -556,28 +644,22 @@ TTransfer extends TransferElement = TransferElement> {
      * 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>;
     /**
-     * Convert a structured-or-textual `model` payload to its textual form.
-     *
-     * Textual payloads (LSP / pre-serialised callers) pass through untouched.
-     * Structured payloads run the per-language `UpdateRewriteService` chain
-     * (transfer-model transforms; diff-aware rewrites see the previous AST root),
-     * then serialise. The chain is the single transfer-model-transform seam — a
-     * unary normalisation is just a rewrite that ignores `previous`, as
-     * `NormalizeEmptyStringsContribution` does. The chain is empty by
-     * default, so this is a no-op for adopters that register none.
+     * The text a write into a document not yet built should take its trivia
+     * from: the store's, which a write always has, since it writes only a
+     * document its client has open.
      */
-    protected modelToText(uri: string, model: TTransfer | string, cancelToken?: CancellationToken): Promise<string>;
+    protected textToTakeTriviaFrom(uri: string, _target: URI): Promise<string | undefined>;
     /**
      * Run the per-language transfer-model rewrite chain. Resolves the
      * `UpdateRewriteService` per-URI (like {@link serialize}) and threads
@@ -588,11 +670,29 @@ TTransfer extends TransferElement = TransferElement> {
     protected rewriteModel(uri: string, model: TTransfer, cancelToken?: CancellationToken): Promise<TTransfer>;
     /**
      * Build an {@link AstDocument} envelope from the current
-     * {@link LangiumDocument} state via the shared {@link AstDocument.from}
-     * projection. Returns an empty envelope (built via
+     * {@link LangiumDocument} state via `AstDocumentManager.toAstDocument`,
+     * the projection events use too. Returns an empty envelope (built via
      * {@link AstDocument.create}) when the document is absent from the
-     * registry — adopters that prefer to throw override on their subclass.
+     * registry — adopters that prefer to throw override on their subclass. Its
+     * version is {@link UNRECORDED_VERSION}, so a write based on it conflicts.
      */
     protected toAstDocument(uri: URI): AstDocument<TAst, TDiagnostic>;
+    /**
+     * The same envelope with no diagnostics, for a read that names a phase below
+     * `Validated`. Absent rather than `[]`, which says the document was validated
+     * and found clean.
+     *
+     * Langium fills `LangiumDocument.diagnostics` from inside `validateDocument`
+     * and from nowhere else, so below that phase the array holds whatever an
+     * EARLIER build left — a verdict about text the document may no longer have.
+     * The wait underneath resolves at or above the phase asked for, so a document
+     * something else carried past `Validated` would otherwise hand a full array
+     * back from `parsed()`.
+     *
+     * A copy rather than a clear: the envelope is freshly built here, but
+     * {@link toAstDocument} is overridable and an adopter's version may return
+     * one it also keeps.
+     */
+    protected withoutDiagnostics(document: AstDocument<TAst, TDiagnostic>): AstDocument<TAst, never>;
 }
 //# sourceMappingURL=model-service.d.ts.map