@hydranium/glsp-server 1.0.0-next.31 → 1.0.0-next.315

package/lib/state/abstract-hydranium-glsp-state.js

@@ -16,10 +16,13 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 var AbstractHydraniumGlspState_1;
-import { DefaultModelState, SOURCE_URI_ARG } from '@eclipse-glsp/server';
+import { DefaultModelState, EditMode, SOURCE_URI_ARG } from '@eclipse-glsp/server';
 import { Emitter } from 'vscode-jsonrpc';
-import { inject, injectable, optional } from 'inversify';
-import { DocumentState, URI } from '@hydranium/langium';
+import { inject, injectable } from 'inversify';
+import { AstUtils, DocumentState, isAstNode, URI } from '@hydranium/langium';
+import { buildAstNode } from '@hydranium/core';
+import { asModelVersion, TIMED_OUT, UNRECORDED_VERSION, describeError, describeErrorWithStack } from '@hydranium/protocol';
+import { openOperationOf } from '../command/hydranium-glsp-operation-command.js';
 import { HydraniumTypes } from './hydranium-shared-core-services.js';
 import { ModelReadyTimeoutError } from './model-ready-timeout-error.js';
 /**
@@ -47,7 +50,7 @@ import { ModelReadyTimeoutError } from './model-ready-timeout-error.js';
  *   override only to change the error shape (richer per-adopter output comes
  *   from overriding `wsRelativePath` / `formatBuildStatus`).
  * - logging — see {@link baseTracer}. Adopters wanting a different label
- *   override `setSourceRoot` and derive via
+ *   override `captureSourceRoot` and derive via
  *   `this.baseTracer.for('Name').withUri(uri)`.
  *
  * **Lifecycle ordering.** Reading {@link sourceUri} or {@link sourceRoot}
@@ -56,7 +59,7 @@ import { ModelReadyTimeoutError } from './model-ready-timeout-error.js';
  * (typically from the storage `loadSourceModel` flow) before reading them.
  * The {@link logger}/{@link tracer} are the exception: the injected
  * {@link baseTracer} is always available, so the getters fall back to it
- * before {@link setSourceRoot} derives the URI-tagged {@link _tracer} —
+ * before {@link captureSourceRoot} derives the URI-tagged {@link _tracer} —
  * logging is never `undefined`.
  */
 let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends DefaultModelState {
@@ -72,18 +75,71 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
      * `updateSourceModel` implementations.
      */
     conflictResolver;
+    /**
+     * Writes of one diagram edit, the first included, that may conflict before
+     * the edit is dropped with a warning; each further write reconciles again.
+     */
+    maxSourceModelWrites = 3;
     /**
      * Per-class tracer, caller-tagged with this state's runtime subclass name by
-     * the `HydraniumTypes.Tracer` binding. {@link setSourceRoot} derives the
+     * the `HydraniumTypes.Tracer` binding. {@link captureSourceRoot} derives the
      * URI-tagged {@link _tracer} from it; the {@link tracer}/{@link logger}
      * getters fall back to it before then, so logging is never `undefined`.
      */
     baseTracer;
+    /**
+     * The client session this diagram works as, registered under `clientId` by
+     * the source-model storage's load and ended with the GLSP client session,
+     * or by a resume that takes it over. `undefined` before the load, for
+     * GLSP's placeholder client, and when another participant held the id, in
+     * which case the diagram does not load.
+     *
+     * Every write of the diagram goes through this session, which writes only a
+     * document it has open and opens nothing. A one-shot write to a document
+     * outside the write set goes through
+     * {@link ClientSession.withOpen}, and a document the diagram brings into
+     * existence through {@link ClientSession.create}.
+     */
+    modelSession;
+    /**
+     * {@link modelSession}, or a throw without one: the diagram never loaded or
+     * has ended. Looking `clientId` up through `ModelService.getSession` instead
+     * would write as whichever participant holds that id.
+     */
+    requireModelSession() {
+        if (!this.modelSession) {
+            throw new Error(`No client session is registered for ${this.clientId}; the diagram cannot write`);
+        }
+        return this.modelSession;
+    }
     _sourceUri;
+    /**
+     * The language {@link _sourceUri} routed to at the last capture, or
+     * `undefined` when it routes nowhere. Captured rather than looked up on
+     * each {@link diagramLanguage} read, which a GModel factory may make once
+     * per element, because the lookup parses the URI and walks the registry.
+     */
+    _sourceLanguage;
+    /**
+     * The root the last capture took, which every reader of the document
+     * shares. A projection that must see an operation's edits reads
+     * {@link sourceRoot}, which is a copy of it during an operation.
+     */
     _sourceRoot;
+    /** Settles when the last {@link runExclusive} call queued so far has. */
+    exclusiveTail = Promise.resolve();
     _tracer;
-    _version = 0;
-    /** Based-on versions of the secondary write set, keyed by URI. See {@link trackSecondaryDocument}. */
+    _baseVersion = asModelVersion(0);
+    /**
+     * The built root each secondary's version was read from, keyed by
+     * canonical URI, and during an operation the root of any other document it
+     * first reached. An operation copies a secondary from here, so the copy,
+     * the base a conflict reconciles from and the version its write is gated
+     * on describe one revision; the registry's current root can be a later
+     * build's.
+     */
+    capturedRoots = new Map();
+    /** Model versions of the secondary write set, keyed by URI. See {@link trackSecondaryDocument}. */
     _secondaryVersions = new Map();
     /** Backing emitter for {@link onSecondaryUrisChanged}; fired only on a membership change. */
     secondaryUrisChangedEmitter = new Emitter();
@@ -92,29 +148,54 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
     /** Maximum wait inside {@link readyWithTimeout} before raising {@link ModelReadyTimeoutError}. */
     readyTimeoutMs = AbstractHydraniumGlspState_1.DEFAULT_READY_TIMEOUT_MS;
     /**
-     * Capture a freshly built source root alongside its URI, refresh the
-     * logger to label log lines with the URI, and re-index the AST so
-     * downstream GModel projection can resolve elements back to nodes.
+     * Capture a freshly built source root alongside its URI through
+     * {@link captureSourceRoot}, and index the AST so downstream GModel
+     * projection can resolve elements back to nodes.
+     *
+     * Capturing the document already captured keeps what the last GModel build
+     * registered in the index, which only the next build makes again, and drops
+     * an id added through `indexSemanticElement` whose node a rebuild replaced.
      *
-     * Also mirrors `uri` into the inherited properties map under
-     * {@link SOURCE_URI_ARG} so legacy GLSP code paths (`state.get(...)`)
-     * stay consistent with the typed field.
+     * Throws during an operation: a capture there swaps the root out from under
+     * the nodes a handler resolved, and the operation captures when it ends.
      */
     setSourceRoot(uri, root) {
+        if (openOperationOf(this)) {
+            throw new Error(`setSourceRoot(${uri}) during an operation: the operation captures the source root when it ends`);
+        }
+        const recapture = uri === this._sourceUri;
+        this.captureSourceRoot(uri, root);
+        if (recapture) {
+            this.index.reindexSemanticElements(root, uri);
+            this.index.remapSemanticAliases(node => (this.isCurrentBuiltNode(node) ? node : undefined));
+        }
+        else {
+            this.index.indexSourceRoot(root, uri);
+        }
+    }
+    /**
+     * Take `root` as the source root and read everything derived from it: the
+     * base version, every tracked secondary version, the URI mirrored into the
+     * inherited properties map under {@link SOURCE_URI_ARG}, and the
+     * URI-labelled logger. Everything but the index, which
+     * {@link setSourceRoot} sets. Override to derive more from a capture.
+     */
+    captureSourceRoot(uri, root) {
         this._sourceUri = uri;
+        this._sourceLanguage = this.sharedServices.ServiceRegistry.getServicesFor(uri);
         this._sourceRoot = root;
-        this._version = this.readDocumentVersion(uri);
-        // Re-read the secondary write set for the same reason the primary is
-        // re-read: the write that brought us here advanced their versions too, and
-        // a stale based-on version would gate the NEXT command against a
-        // superseded number — reporting a conflict that is really this state's own
-        // last write.
+        // The root's own version: the registry's current root can be a later
+        // build's, and a write based on its version passes the gate over edits
+        // `root` never saw.
+        this._baseVersion = this.sharedServices.workspace.ModelLedger.versionOf(root);
+        // Re-read the secondary write set: the write that brought us here
+        // advanced their versions too, and a stale base version would gate the
+        // NEXT command against a superseded number — reporting a conflict that is
+        // really this state's own last write.
         this.refreshSecondaryVersions();
         this.set(SOURCE_URI_ARG, uri);
         this._tracer = this.baseTracer.withUri(uri);
-        this.tracer.debug(`Captured source root at doc.version=v${this._version}`);
-        this.checkDeclaredLanguage(uri);
-        this.index.indexSourceRoot(root, uri);
+        this.tracer.debug(`Captured source root at doc.version=v${this._baseVersion}`);
     }
     /**
      * Typed override of {@link DefaultModelState.sourceUri}. Narrows the
@@ -124,32 +205,226 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
     get sourceUri() {
         return this._sourceUri;
     }
+    /** The root operation handlers edit: during an operation a copy of the built root, outside one the built root. */
     get sourceRoot() {
-        return this._sourceRoot;
+        return openOperationOf(this) && this._sourceRoot !== undefined ? this.workingRootOf(this._sourceUri) : this._sourceRoot;
+    }
+    /**
+     * Run `run` once every earlier call has settled, thrown or not: the
+     * boundary that orders operations, undo and redo, and the storage's capture
+     * and render. Code running inside it never calls this again, since the
+     * call would wait for the section it runs in.
+     */
+    runExclusive(run) {
+        const result = this.exclusiveTail.then(() => run());
+        this.exclusiveTail = result.catch(() => undefined);
+        return result;
+    }
+    /**
+     * The root of `uri` that operation handlers edit: during an operation a
+     * copy made on the first request and returned for the rest of it, outside
+     * one the root itself. The root is the built root of `uri`, or `orElse()`
+     * when `uri` has no document; `undefined` when neither gives one.
+     *
+     * A handler that edits another document than the source reaches its root
+     * through this, or the edit lands on the root every reader shares. An id
+     * added through `indexSemanticElement` for a node of that root names the
+     * node's copy from then on.
+     */
+    workingRootOf(uri, orElse) {
+        const key = this.workingKey(uri);
+        const primary = this._sourceUri !== undefined && key === this.workingKey(this._sourceUri);
+        const operation = openOperationOf(this);
+        if (!operation) {
+            return primary ? this._sourceRoot : (this.sharedServices.model.ModelService.getDocument(uri)?.parseResult.value ?? orElse?.());
+        }
+        let built = primary ? this._sourceRoot : this.capturedRoots.get(key);
+        if (built === undefined) {
+            // First reached during the operation: frozen now, for the rest of it.
+            built = this.readBuiltRoot(uri);
+            if (built !== undefined) {
+                this.capturedRoots.set(key, built);
+            }
+        }
+        built ??= orElse?.();
+        return built === undefined ? undefined : operation.workingRootOf(key, built);
+    }
+    /** The copy of `uri` the open operation made, without making one. */
+    existingWorkingRootOf(uri) {
+        return openOperationOf(this)?.existingWorkingRootOf(this.workingKey(uri));
     }
     /**
-     * The language services of the grammar this DIAGRAM TYPE edits, as declared
-     * by `AbstractHydraniumGlspDiagramModule.declareLanguage`.
+     * The key of `uri` among an operation's copies: its canonical form, so two
+     * spellings of one document share one copy.
+     */
+    workingKey(uri) {
+        return this.sharedServices.workspace.DocumentUriPolicy.canonicalUri(uri);
+    }
+    /**
+     * The built node `node` was copied from during an operation; `node` itself
+     * for a built node, for a node the operation created, and outside one.
+     *
+     * A copy has no `$document`, so a lookup that reads its document, scope or
+     * project throws or answers for no document. Handlers pass the built node
+     * there and keep editing the copy. A candidate query takes
+     * {@link referenceInfoOf} instead, since a created node has no built node.
+     */
+    builtNodeOf(node) {
+        return openOperationOf(this)?.builtNodeOf(node) ?? node;
+    }
+    /**
+     * A reference to `target` whose `ref` is `target` itself, a copy node
+     * included, so an identity comparison later in the operation finds it.
+     * `undefined` when no reference can be formed. Outside an operation the
+     * nodes are built ones and this is the `ReferenceBuilder`'s answer as is.
+     *
+     * With `tier: 'own'` the `$refText` is the target's own name as
+     * `toOwnReference` gives it, read off `target` itself, so a name the
+     * operation edited is the one written; the builder is the target's
+     * language's, which a copy node, having no `$document`, would not otherwise
+     * reach. `source` plays no part in that tier.
      *
-     * **Named for what it is, not for "the language".** Reach for it only when
-     * the thing you are asking about lives in the diagram document itself.
-     * Anything reached *through* a reference is decided by its own document: use
-     * {@link languageServicesFor}. Making that choice explicit at the call site
-     * is the point; a neutral-looking `languageServices` invites the diagram's
-     * grammar to be applied to a foreign node, which is the defect this whole
-     * seam exists to prevent.
+     * By default it is `getReferenceName` from `source`'s context, with the
+     * builder of `source`'s language, since `$refText` encoding follows the
+     * grammar writing it. That call reads both nodes' projects, to pick the
+     * qualification and to refuse a reference across projects the target's is
+     * not visible to, and a copy node has none; so it is asked about the built
+     * target, which names a target as built, before any rename in the
+     * operation, and about {@link builtContextOf} the source. A target the
+     * operation created has no built node, and is asked about without a
+     * project.
+     */
+    referenceTo(target, source, options = {}) {
+        const refText = options.tier === 'own'
+            ? this.languageServicesFor(target)?.references.ReferenceBuilder.toOwnReference(target)?.$refText
+            : this.languageServicesFor(source ?? target)?.references.ReferenceBuilder.getReferenceName(this.builtNodeOf(target), source === undefined ? undefined : this.builtContextOf(source));
+        return refText === undefined ? undefined : { ref: target, $refText: refText };
+    }
+    /**
+     * A candidate query for `property` of `node`, to pass to
+     * `candidateProviderFor(node)?.find`. It is asked from the built node, and
+     * for a node the operation created from a stand-in of its type under the
+     * built containers it sits in, one per created level: a scope reads local
+     * names off every container up the chain, so anchoring higher drops them.
+     * A protocol context cannot express this: an element source resolves only
+     * through a `resolveElementByName` override, and through the index only
+     * for the nodes it exports. `undefined` for a node whose `$container` chain
+     * reaches no document and no copy, such as a node built with no
+     * `$container` that is not a document's root.
      *
-     * Injected rather than derived from {@link sourceUri} so it is available
-     * before the first {@link setSourceRoot} — GLSP constructs operation
-     * handlers at `InitializeClientSession`, well before `RequestModelAction`.
-     * `@optional()` so a harness that binds no diagram module still resolves;
-     * `undefined` then means no diagram module declared a grammar.
+     * A node not created yet is asked about through a stand-in built with
+     * `buildAstNode`: its type, `$container` the container it would join, and
+     * `$containerProperty`, left unattached.
+     */
+    referenceInfoOf(node, property) {
+        let container = this.builtContextOf(node);
+        if (!AstUtils.findRootNode(container).$document) {
+            return undefined;
+        }
+        const created = [];
+        for (let level = node; level && this.builtNodeOf(level) !== container; level = level.$container) {
+            created.unshift(level);
+        }
+        for (const level of created) {
+            container = buildAstNode(this.sharedServices.AstReflection, level.$type, {
+                $container: container,
+                $containerProperty: level.$containerProperty,
+                $containerIndex: level.$containerIndex
+            });
+        }
+        return { reference: { $refText: '', ref: undefined }, container, property };
+    }
+    /**
+     * The built node of `node`, or of its nearest container that has one: a
+     * node the operation created has no built node, but its container's
+     * document and project are its own.
+     */
+    builtContextOf(node) {
+        const operation = openOperationOf(this);
+        for (let current = node; current; current = current.$container) {
+            const built = this.builtNodeOf(current);
+            if (built !== current || operation?.workingUriOf(current) === undefined) {
+                return built;
+            }
+        }
+        return node;
+    }
+    /**
+     * Take `root`, which a write of this state's own produced, as the source
+     * root; during an operation the operation takes it and captures it when it
+     * ends.
+     */
+    captureWrittenRoot(root) {
+        const operation = openOperationOf(this);
+        if (operation) {
+            operation.recordWrittenRoot(root);
+        }
+        else {
+            this.setSourceRoot(this._sourceUri, root);
+        }
+    }
+    /**
+     * Resync after a write whose reconcile dropped the edit: during an
+     * operation the operation undoes its side effects, pushes nothing, and
+     * captures the document's current root when it ends.
      */
-    diagramLanguage;
+    writeDropped() {
+        const operation = openOperationOf(this);
+        if (operation) {
+            operation.recordDropped(this.sharedServices.model.ModelService.getDocument(this._sourceUri)?.parseResult.value);
+        }
+        else {
+            this.refreshSourceRoot();
+        }
+    }
+    /**
+     * Take the document's built root as the source root; during an operation,
+     * as the root the operation closes on. A write the document already held,
+     * and an undo or redo that wrote nothing while its steps may have rebuilt
+     * the document, leave this state on a root that predates the document. The
+     * built root can lag the text until the next build, whose refresh captures
+     * that, as after {@link writeDropped}.
+     */
+    captureBuiltRoot() {
+        const operation = openOperationOf(this);
+        if (!operation) {
+            this.refreshSourceRoot();
+            return;
+        }
+        const current = this.sharedServices.model.ModelService.getDocument(this._sourceUri)?.parseResult.value;
+        if (current !== undefined) {
+            operation.recordWrittenRoot(current);
+        }
+    }
+    /**
+     * Whether `node` belongs to the root its document is built to now, or to no
+     * document; a root a rebuild replaced holds only stale nodes.
+     */
+    isCurrentBuiltNode(node) {
+        const root = AstUtils.findRootNode(node);
+        const document = root.$document;
+        return (document === undefined || this.sharedServices.model.ModelService.getDocument(document.uri.toString())?.parseResult.value === root);
+    }
+    /**
+     * The language services of the diagram document: the language
+     * {@link sourceUri} routed to at the last {@link setSourceRoot}.
+     *
+     * `undefined` until a document is loaded, as GLSP builds a session's
+     * handlers at `InitializeClientSession`, before `RequestModelAction`
+     * supplies the URI: read it when called, not at construction.
+     *
+     * Reach for it only when the thing you are asking about lives in the
+     * diagram document itself. Anything reached through a reference is decided
+     * by its own document: use {@link languageServicesFor}.
+     */
+    get diagramLanguage() {
+        return this._sourceLanguage;
+    }
     /**
      * The language services owning `target` — an AST node (routed by its
-     * document), a URI, or a URI string — falling back to
-     * {@link diagramLanguage} when `target` routes nowhere.
+     * document), a URI, or a URI string — falling back, for a node, to the
+     * language the index read from the diagram's root, and otherwise to
+     * {@link diagramLanguage}, when `target` routes nowhere.
      *
      * Use this wherever the thing being named, keyed or completed may live in
      * another document than the diagram. Two registered languages are free to
@@ -159,8 +434,14 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
      * diagnostic. The fallback covers the genuinely unroutable case, a synthetic
      * node not yet attached to a document, where the diagram's own language is
      * the only defensible answer.
+     *
+     * A node routes through {@link HydraniumGlspIndex.languageServicesFor}, so
+     * an override of the index's routing applies here too.
      */
     languageServicesFor(target) {
+        if (isAstNode(target)) {
+            return this.index.languageServicesFor(target) ?? this.diagramLanguage;
+        }
         return this.sharedServices.ServiceRegistry.getServicesFor(target) ?? this.diagramLanguage;
     }
     /**
@@ -186,64 +467,46 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
     candidateProviderFor(target) {
         return this.languageServicesFor(target)?.references.CandidateProvider;
     }
-    /**
-     * Warn when the loaded document does not route to the grammar this diagram
-     * module declared.
-     *
-     * The declared language is the one fact the module states that the grammar
-     * itself does not, so it is the one that can drift — a diagram type pointed
-     * at the wrong `LanguageMetaData`, or a file extension reassigned. Both
-     * would otherwise surface much later as references resolving against the
-     * wrong scope. Only a warning, not a throw: the document is loaded and
-     * usable either way, and a hard failure here would take out a diagram over
-     * a mismatch that may be intentional in an adopter serving one diagram type
-     * over several grammars.
-     */
-    checkDeclaredLanguage(uri) {
-        const declared = this.diagramLanguage?.LanguageMetaData.languageId;
-        if (declared === undefined) {
-            return;
-        }
-        const actual = this.sharedServices.ServiceRegistry.getServicesFor(uri)?.LanguageMetaData.languageId;
-        if (actual !== undefined && actual !== declared) {
-            this.tracer.warn(`Diagram module declares language '${declared}' but this document routes to '${actual}'`);
-        }
-    }
     /** The observability handle as a plain {@link Logger} (a {@link Tracer} is-a Logger). */
     get logger() {
         return this.tracer;
     }
-    /** URI-tagged once {@link setSourceRoot} has run; the class-tagged injected {@link baseTracer} before that. */
+    /** URI-tagged once a source root is captured; the class-tagged injected {@link baseTracer} before that. */
     get tracer() {
         return this._tracer ?? this.baseTracer;
     }
     /**
-     * Text-document version captured at the last {@link setSourceRoot}
-     * call. Mirrors the server-side `TextDocuments.version(uri)` counter
-     * at that point in time — frozen until the next `setSourceRoot`, then
-     * re-read from `LangiumDocuments`.
+     * Model version of the root the last {@link captureSourceRoot} took,
+     * frozen until the next one.
      *
-     * Threaded by `HydraniumGlspRecordingCommand` into
-     * {@link updateSourceModel}'s optional `version` parameter so the
-     * downstream `ModelService.update` / `.save` call can opt into the
-     * conflict gate against the captured based-on version. See
+     * The base an operation's write is gated on, taken when the operation
+     * opens; nothing captures during an operation, so it is the version of the
+     * root the operation's copies were made from. See
      * `@hydranium/protocol#ConflictError` for the detection contract.
      *
-     * Falls back to `0` when the document is absent from `LangiumDocuments`
-     * at capture time — the same observable state callers see for a doc
-     * that was never opened. Callers that need to distinguish
-     * "never-versioned" from "v0" must consult the document registry
-     * directly.
+     * **This, not a number read at write time, is what a write must be gated
+     * on.** A version read when the write is issued is the store's current one,
+     * so it matches by construction and the gate can never fire.
+     */
+    get baseVersion() {
+        return this._baseVersion;
+    }
+    /**
+     * {@link baseVersion} as a plain number: the store's version of the text the
+     * root was parsed from.
+     *
+     * `UNRECORDED_VERSION` when the document was not built when the snapshot
+     * was taken, which no write matches.
      */
     get version() {
-        return this._version;
+        return this._baseVersion;
     }
     // ============================================================
     // Secondary documents — the write set beyond the primary
     // ============================================================
     /**
-     * Register `uri` as a document this state also writes, capturing its current
-     * text-document version.
+     * Register `uri` as a document this state also writes, snapshotting its
+     * current text-document version.
      *
      * A diagram whose layout lives in its own file, or whose canvas creates
      * elements in a referenced semantic document, writes more than the document
@@ -256,7 +519,7 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
      * identified once the operation names the node. What the framework supplies
      * is the part an adopter cannot reconstruct after the fact — the version each
      * document was at BEFORE the command mutated anything (see
-     * {@link capturedVersionOf}). Idempotent; registering the primary is ignored,
+     * {@link baseVersionOf}). Idempotent; registering the primary is ignored,
      * since {@link version} already tracks it. Registering a URI not already in
      * the set fires {@link onSecondaryUrisChanged}.
      */
@@ -265,7 +528,10 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
             return;
         }
         const added = !this._secondaryVersions.has(uri);
-        this._secondaryVersions.set(uri, this.readDocumentVersion(uri));
+        const key = this.workingKey(uri);
+        // During an operation, the root the operation copied or first reached, not a later build's.
+        const root = (openOperationOf(this) ? this.capturedRoots.get(key) : undefined) ?? this.readBuiltRoot(uri);
+        this.recordSecondary(uri, root);
         if (added) {
             this.secondaryUrisChangedEmitter.fire();
         }
@@ -283,14 +549,15 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
     }
     /**
      * Fires whenever the secondary write set gains or loses a URI — never when a
-     * tracked document's captured version is merely refreshed, which happens on
-     * every {@link setSourceRoot} and changes nothing a subscriber cares about.
+     * tracked document's model version is merely refreshed, which happens on
+     * every {@link captureSourceRoot} and changes nothing a subscriber cares about.
      *
      * **This exists so no caller has to know when the set can change.** The set is
      * usually discovered rather than known, and the discovery point is an
-     * operation handler naming a node — not a capture. A subscriber that instead
-     * re-derived the set after each capture would miss exactly that case, and miss
-     * it silently: the document would simply never be watched, with nothing logged.
+     * operation handler naming a node — not a read of the source root. A
+     * subscriber that instead re-derived the set after each such read would miss
+     * exactly that case, and miss it silently: the document would simply never be
+     * watched, with nothing logged.
      * Announcing the change here moves the obligation to the one place that can
      * always discharge it.
      *
@@ -306,37 +573,104 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
     get secondaryUris() {
         return [...this._secondaryVersions.keys()];
     }
+    /** Active statuses, least recently set first. See {@link setStatus}. */
+    statuses = new Map();
+    /** Backing emitter for {@link onStatusChanged}. */
+    statusChangedEmitter = new Emitter();
     /**
-     * Based-on version captured for `uri` — {@link version} for the primary, the
-     * value captured at {@link trackSecondaryDocument} (refreshed by
-     * {@link setSourceRoot}) for a secondary, `undefined` for anything untracked.
+     * Set `status`'s entry, or withdraw it with `undefined`, and recompute
+     * {@link currentStatus} and {@link editMode} from every active entry.
      *
-     * `undefined` rather than `0` for an untracked URI deliberately: `0` is a real
+     * `editMode` is derived here and nowhere else: a writer that assigns it
+     * directly is overwritten by the next status change, and its write is not
+     * announced on {@link onStatusChanged}.
+     */
+    setStatus(status, entry) {
+        const previousEntry = this.statuses.get(status);
+        if (previousEntry === undefined && entry === undefined) {
+            return;
+        }
+        const previousStatus = this.currentStatus;
+        const previousEditMode = this.editMode;
+        // Re-inserted so iteration order is recency, which breaks a severity tie.
+        this.statuses.delete(status);
+        if (entry !== undefined) {
+            this.statuses.set(status, entry);
+        }
+        this.editMode = [...this.statuses.values()].some(active => active.readonly) ? EditMode.READONLY : EditMode.EDITABLE;
+        this.logger.debug(`Status ${status}: ${describeStatusEntry(previousEntry)} → ${describeStatusEntry(entry)}`);
+        if (this.currentStatus !== previousStatus || this.editMode !== previousEditMode) {
+            this.statusChangedEmitter.fire();
+        }
+    }
+    /** The active entry whose message the client shows: highest severity, then most recently set. */
+    get currentStatus() {
+        let winner;
+        for (const entry of this.statuses.values()) {
+            if (entry.message !== undefined && (!winner || severityRank(entry) >= severityRank(winner))) {
+                winner = entry;
+            }
+        }
+        return winner;
+    }
+    /** The active statuses that block editing; empty while the diagram is editable. */
+    get readonlyStatuses() {
+        return [...this.statuses].filter(([, entry]) => entry.readonly).map(([status]) => status);
+    }
+    /** The status that supplies {@link currentStatus}, for a log line naming it. */
+    get currentStatusSource() {
+        const current = this.currentStatus;
+        return [...this.statuses].find(([, entry]) => entry === current)?.[0];
+    }
+    /** Fires when {@link currentStatus} or {@link editMode} changes. */
+    get onStatusChanged() {
+        return this.statusChangedEmitter.event;
+    }
+    /**
+     * The base version of a write of `uri`: {@link baseVersion} for the primary,
+     * the version taken at {@link trackSecondaryDocument} (refreshed by
+     * {@link captureSourceRoot}) for a secondary, `undefined` for anything untracked.
+     *
+     * `undefined` rather than v0 for an untracked URI deliberately: `0` is a real
      * version meaning "present but never edited", so collapsing the two would let
-     * a caller gate a write against a document it never captured.
+     * a caller gate a write against a document this state never read.
      */
-    capturedVersionOf(uri) {
+    baseVersionOf(uri) {
         if (uri === this._sourceUri) {
-            return this._version;
+            return this._baseVersion;
         }
         return this._secondaryVersions.get(uri);
     }
+    /** Re-take every registered secondary's built root and the model version of that root. */
+    refreshSecondaryVersions() {
+        this.capturedRoots.clear();
+        for (const uri of [...this._secondaryVersions.keys()]) {
+            this.recordSecondary(uri, this.readBuiltRoot(uri));
+        }
+    }
     /**
-     * Read a document's current text-document version through the model service's
-     * canonicalizing gateway, so a URI spelled through a symlink still resolves to
-     * the document keyed by its real path rather than stranding at `0` (which
-     * would silently weaken the conflict gate). Optional-chained on `textDocument`
-     * so a fixture that omits it does not throw; real Langium documents always
-     * populate it.
+     * The built root of `uri`, looked up through the model service's
+     * canonicalizing gateway so a symlinked URI does not strand without one;
+     * `undefined` for a URI with no parsed document, whose version is then
+     * `UNRECORDED_VERSION`, which no write matches. The store counts a file it
+     * has not built at `0`, and so does the placeholder the builder registers
+     * before its parse, and a write based on `0` overwrites text this state
+     * never read.
      */
-    readDocumentVersion(uri) {
-        return this.sharedServices.model.ModelService.getDocument(uri)?.textDocument?.version ?? 0;
+    readBuiltRoot(uri) {
+        const root = this.sharedServices.model.ModelService.getDocument(uri)?.parseResult.value;
+        return root && !this.sharedServices.workspace.ModelLedger.isPlaceholder(root) ? root : undefined;
     }
-    /** Re-read every registered secondary's version from the document store. */
-    refreshSecondaryVersions() {
-        for (const uri of [...this._secondaryVersions.keys()]) {
-            this._secondaryVersions.set(uri, this.readDocumentVersion(uri));
+    /** Take `root` as the secondary `uri` was read at, and its version, `UNRECORDED_VERSION` without one. */
+    recordSecondary(uri, root) {
+        if (root !== undefined) {
+            this.capturedRoots.set(this.workingKey(uri), root);
         }
+        this._secondaryVersions.set(uri, root ? this.sharedServices.workspace.ModelLedger.versionOf(root) : UNRECORDED_VERSION);
+    }
+    /** The root the secondary `uri` was read at; see {@link capturedRoots}. */
+    capturedRootOf(uri) {
+        return this.capturedRoots.get(this.workingKey(uri));
     }
     /**
      * Re-capture the source root from the current Langium document,
@@ -346,7 +680,8 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
      * handlers) must see the root the freshly built document carries.
      */
     refreshSourceRoot() {
-        if (!this._sourceUri) {
+        // The operation captures when it ends.
+        if (!this._sourceUri || openOperationOf(this)) {
             return;
         }
         const document = this.sharedServices.model.ModelService.getDocument(this._sourceUri);
@@ -359,48 +694,81 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
             this.setSourceRoot(this._sourceUri, root);
         }
     }
+    /**
+     * The root that `uri`'s text parses to (the text store's, or the built
+     * document's when the store holds none) and the store's version of that
+     * text, read once the document has validated; `undefined` when it cannot be
+     * read. The version is read in the tick the text is, so a write based on it
+     * conflicts with any edit made after.
+     *
+     * **Parsed afresh, never the built root.** The built root can lag the
+     * store, and a root behind the text it is versioned with makes the replay
+     * drop the edits it lacks. The root is parsed, not linked: an encoder hook
+     * reading a reference's `ref` sees `undefined` on it.
+     */
+    async readCurrentRoot(uri) {
+        const modelService = this.sharedServices.model.ModelService;
+        // Unreadable here is the conflict the caller then raises, which is logged where it ends; the reason is diagnosis.
+        const validated = await modelService.validated(uri).catch((error) => {
+            this.logger.debug(`The current text of ${uri} cannot be read: ${describeError(error)}`);
+            return undefined;
+        });
+        if (!validated) {
+            return undefined;
+        }
+        const store = this.sharedServices.workspace.TextDocuments;
+        const text = store.get(uri)?.getText() ?? modelService.getDocument(uri)?.textDocument.getText();
+        if (text === undefined) {
+            return undefined;
+        }
+        const version = asModelVersion(store.version(uri));
+        return { root: this.sharedServices.workspace.LangiumDocumentFactory.fromString(text, URI.parse(uri)).parseResult.value, version };
+    }
     /**
      * Wait until the captured document reaches `state`, then run
      * {@link onReadyRefreshed} so consumers see a fresh AST. Wraps the
      * wait in {@link Tracer.time} for observability.
+     *
+     * A source not in the document registry is built first, through
+     * `ModelService.rebuild`. For a source with neither a file nor text, that
+     * build leaves no document, and this rejects rather than timing out.
      */
     async ready(state) {
         await this.tracer.time(`Wait for state '${DocumentState[state]}'`, () => this.readyWithTimeout(state), 'debug');
         await this.onReadyRefreshed();
     }
     /**
-     * Race `ModelService.waitForDocumentState` against
-     * {@link readyTimeoutMs}. If the timeout fires but the document has
-     * already reached `state` silently (Langium build-phase event race),
-     * log a warning and resolve; otherwise raise
-     * {@link ModelReadyTimeoutError} via {@link buildReadyTimeoutError}.
+     * Race `ModelService.ensureDocumentState`, which builds a root behind its
+     * text, against {@link readyTimeoutMs}. If the timeout fires but the
+     * document has already reached `state`, log a warning naming the cause, a
+     * root behind its text or a missed phase event, and resolve; otherwise
+     * raise {@link ModelReadyTimeoutError} via {@link buildReadyTimeoutError}.
      */
     async readyWithTimeout(state) {
         const uri = this._sourceUri;
         const stopwatch = this.sharedServices.Clock.stopwatch();
-        let timer;
-        const timeout = new Promise((resolve, reject) => {
-            timer = this.sharedServices.Clock.setTimer(() => {
-                const elapsed = Math.round(stopwatch.elapsedMs);
-                // Via the canonicalizing gateway (see `readDocumentVersion`), so a
-                // symlinked `_sourceUri` is not reported as a hard timeout.
-                const doc = this.sharedServices.model.ModelService.getDocument(uri);
-                if (doc && doc.state >= state) {
-                    this.logger.warn(`Missed '${DocumentState[state]}' notification after ${elapsed}ms; document is already at state ` +
-                        `'${DocumentState[doc.state]}'. Likely a Langium build-phase event race.`);
-                    resolve();
-                }
-                else {
-                    reject(this.buildReadyTimeoutError(state, elapsed));
-                }
-            }, this.readyTimeoutMs);
-        });
-        try {
-            await Promise.race([this.sharedServices.model.ModelService.waitForDocumentState(uri, state), timeout]);
+        const reached = this.sharedServices.model.ModelService.ensureDocumentState(uri, state);
+        if ((await this.sharedServices.Clock.raceTimer(reached, this.readyTimeoutMs)) !== TIMED_OUT) {
+            return;
         }
-        finally {
-            timer?.dispose();
+        // The race has settled, so a later failure of the wait, such as a given-up sync build, reaches no one else.
+        void reached.catch((error) => this.logger.error(`The wait for '${DocumentState[state]}' failed after it timed out: ${describeErrorWithStack(error)}`));
+        const elapsed = Math.round(stopwatch.elapsedMs);
+        // Through the model service's canonicalizing gateway, so a symlinked
+        // `_sourceUri` is not reported as a hard timeout.
+        const doc = this.sharedServices.model.ModelService.getDocument(uri);
+        if (!doc || doc.state < state) {
+            throw this.buildReadyTimeoutError(state, elapsed);
+        }
+        const built = this.sharedServices.workspace.ModelLedger.versionOf(doc.parseResult.value);
+        const text = this.sharedServices.workspace.TextDocuments.version(uri);
+        if (built !== UNRECORDED_VERSION && built < text) {
+            this.logger.warn(`No build caught the root up after ${elapsed}ms: the document is at state '${DocumentState[doc.state]}', ` +
+                `but its root was parsed from v${built} and the text is at v${text}.`);
+            return;
         }
+        this.logger.warn(`Missed '${DocumentState[state]}' notification after ${elapsed}ms; document is already at state ` +
+            `'${DocumentState[doc.state]}'. Likely a Langium build-phase event race.`);
     }
     /**
      * Hook for post-{@link ready} work. Default refreshes the captured
@@ -426,6 +794,20 @@ let AbstractHydraniumGlspState = class AbstractHydraniumGlspState extends Defaul
         const status = workspace.DocumentBuilder.formatBuildStatus(URI.parse(this._sourceUri));
         return new ModelReadyTimeoutError(shortPath, DocumentState[state], elapsed, status);
     }
+    /**
+     * `transition` as the documents would hold both ends after a write. A
+     * serializer may normalize what it writes, provided normalizing again
+     * changes nothing; an end left as recorded makes an undo or redo conflict
+     * with the write it follows. Default: unchanged.
+     */
+    async normalizeTransition(transition) {
+        return transition;
+    }
+    /** The root `model` parses back to once serialized for `uri`, as a write would leave it; nothing is written. */
+    async roundTrip(uri, model) {
+        const text = await this.sharedServices.model.ModelService.modelToText(uri, model);
+        return this.sharedServices.workspace.LangiumDocumentFactory.fromString(text, URI.parse(uri)).parseResult.value;
+    }
 };
 __decorate([
     inject(HydraniumTypes.SharedCoreServices),
@@ -439,13 +821,21 @@ __decorate([
     inject(HydraniumTypes.Tracer),
     __metadata("design:type", Object)
 ], AbstractHydraniumGlspState.prototype, "baseTracer", void 0);
-__decorate([
-    inject(HydraniumTypes.DiagramLanguage),
-    optional(),
-    __metadata("design:type", Object)
-], AbstractHydraniumGlspState.prototype, "diagramLanguage", void 0);
 AbstractHydraniumGlspState = AbstractHydraniumGlspState_1 = __decorate([
     injectable()
 ], AbstractHydraniumGlspState);
 export { AbstractHydraniumGlspState };
+const SEVERITY_RANK = { INFO: 0, WARNING: 1, ERROR: 2, FATAL: 3 };
+/** A message without a severity ranks as `INFO`. */
+function severityRank(entry) {
+    return SEVERITY_RANK[entry.severity ?? 'INFO'];
+}
+function describeStatusEntry(entry) {
+    if (entry === undefined) {
+        return 'inactive';
+    }
+    const flags = [entry.message === undefined ? undefined : (entry.severity ?? 'INFO'), entry.readonly ? 'readonly' : undefined];
+    const message = entry.message === undefined ? '' : ` "${entry.message}"`;
+    return `${flags.filter(flag => flag !== undefined).join(' ') || 'active'}${message}`;
+}
 //# sourceMappingURL=abstract-hydranium-glsp-state.js.map