@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,889 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { ConflictError, Logger, ObservableValue } from '@hydranium/protocol';
+import { DocumentState, UriUtils } from '@hydranium/langium';
+import { ReentrantWriteLockError, isInsideWriteLock } from '../workspace/write-lock-scope.js';
+import { AstDocument } from '../../documents/ast-document-manager.js';
+import { isConnectionGoneError } from '../../util/connection-liveness.js';
+import { IntegrityService } from '../integrity/integrity-service.js';
+import { labelPhaseListener } from '../document-builder/labeled-phase-listener.js';
+import { LANGUAGE_CLIENT_ID } from '../../documents/client-ids.js';
+/** Max time {@link ModelService.settleSave} waits for the build to settle and the sync chain to drain. */
+const SAVE_SETTLE_TIMEOUT_MS = 10_000;
+/**
+ * Marks the {@link SAVE_SETTLE_TIMEOUT_MS} branch of
+ * {@link ModelService.settleSave}'s race so it stays distinguishable from a
+ * genuine rejection (a cancelled token, an `applyEdit` reverse-RPC error, a
+ * build throw). With a plain `Error` the only log line an adopter has blames
+ * the timeout for every one of them, which points debugging at the wrong layer.
+ */
+class SaveSettleTimeoutError extends Error {
+}
+/**
+ * In-process facade over the framework's document plumbing
+ * (`HydraniumTextDocuments`, `LangiumDocuments`,
+ * `DocumentBuilder`, `WritableFileSystemProvider`). Owns the
+ * `open / request / update / save / ready` lifecycle that protocol heads
+ * (LSP, data-server, GLSP) delegate to so coordinating those primitives
+ * doesn't have to be re-implemented per-head.
+ *
+ * "Model" here means the parsed AST — distinct from the wire-shape
+ * `TransferDocument` in `@hydranium/protocol`.
+ *
+ * **Why a facade**
+ *
+ * Multiple in-process consumers want the same workspace-level
+ * operations:
+ * - The data-server head turns these into typed RPC methods.
+ * - The GLSP head uses the same lifecycle for diagram-driven edits;
+ *   GModel operation handlers route through `update` for AST mutation,
+ *   `waitForDocumentState` for indexed-phase waits before reads, etc.
+ * - Server-internal callers (integrity service, ad-hoc bridges, tests)
+ *   want the same operations without the wire serialisation step.
+ *
+ * Coordinating the primitives per-head drifts between heads — different
+ * superseded-version handling, different settled-phase choices, different
+ * content-change paths. The facade collapses that duplication and gives
+ * adopters one extension surface — {@link rewriteModel},
+ * {@link serialize} — to customise the in-process behaviour without
+ * re-implementing the plumbing.
+ *
+ * **Read-latest supersession**
+ *
+ * The default `update` and `save` flows use Langium's per-URI
+ * `DocumentBuilder.waitUntil` to wait for the integrity-settled landmark
+ * ({@link IntegrityService.SettledState}), then read the post-build state. Concurrent
+ * in-process callers on the same URI all see the latest post-build
+ * snapshot — none deadlock waiting for a specific version's settled
+ * event. Adopters wanting strict version-matched semantics (resolve
+ * with vN's snapshot specifically, log "vN superseded by vM at vN+1")
+ * override {@link update} to attach a phase-listener with explicit
+ * version checks; the framework default doesn't need it for safety.
+ *
+ * **Returns AST snapshots, not wire envelopes**
+ *
+ * The facade returns {@link AstDocument} (the in-process AST-typed
+ * envelope), not `TransferDocument` (the lossy wire shape). In-
+ * process callers consume `$container` / `Reference<T>` directly;
+ * encoding-on-return would be wasteful and would force the wire-side
+ * lossy `$refText` shape on every consumer. The wire-side caller
+ * (`DataServer.updateModelDocument` etc.) encodes once on return via
+ * the injected `TransferEncoder` — symmetric with the
+ * `getModelDocument` envelope path.
+ *
+ * **Subscriptions** ({@link onModelUpdated} / {@link onModelSaved} /
+ * {@link onClientClosed}) are thin pass-throughs over
+ * `DocumentBuilder.onDocumentPhase` and
+ * `HydraniumTextDocuments.onDidSave` / `onDidClose`. Filtering
+ * by URI happens here so consumers can subscribe per-document without
+ * implementing the URI gate at each callsite.
+ *
+ * **Generic parameters.**
+ * - `TAst` — the AST root type each consumer expects on the returned
+ *   {@link AstDocument}. Constrained to {@link AstNode}.
+ * - `TDiagnostic` — wire diagnostic shape used by the injected
+ *   `TransferEncoder`. Defaults to {@link TransferDiagnostic}.
+ * - `TTransfer` — transfer-model root accepted by `update` / `save`
+ *   args. Constrained to {@link TransferElement}. Defaults to the
+ *   structural base.
+ */
+export class ModelService {
+    services;
+    tracer;
+    /**
+     * The single document-identity seam (`services.workspace.DocumentUriPolicy`),
+     * cached for the public doors that canonicalize an incoming URI once before
+     * threading the resulting {@link CanonicalUri} through the internal cores. A
+     * field reference to the shared service, NOT a `canonicalUri` wrapper method —
+     * the wrapper was deliberately removed so canonicalisation has a single policy
+     * (see {@link DocumentUriPolicy}).
+     */
+    uriPolicy;
+    /**
+     * Live slow-update-warn threshold cell, or `undefined` when the option
+     * was not supplied (warn line + stopwatch disabled). Reads `.value` per
+     * update so a setting-bound threshold retunes without reconstruction.
+     */
+    slowUpdateWarn;
+    /** See {@link ModelServiceOptions.serializeBuilds}. Defaults to `true`. */
+    serializeBuilds;
+    /**
+     * 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
+     * flight overwrites {@link pendingSync}; the chain picks up the latest on its
+     * next iteration so the shadow never drifts from Monaco.
+     */
+    syncChains = new Map();
+    pendingSync = new Map();
+    /**
+     * Workspace-level readiness gate. Resolves when the framework has
+     * finished its first workspace build cycle and the `ModelService`
+     * methods will behave predictably: per-URI waits resolve, queries
+     * return current snapshots, and the build pipeline is driving
+     * documents through phases.
+     *
+     * The default delegates to
+     * `services.workspace.WorkspaceManager.workspaceInitialized`, NOT to
+     * Langium's `WorkspaceManager.ready`. The difference is load-bearing:
+     * Langium resolves `ready` inside `performStartup`, once the workspace
+     * documents have been created but BEFORE `documentBuilder.build` runs, so
+     * `ready` does not mean "the first build cycle finished". A caller that
+     * gated a write on it could land that write mid-initial-build, where two
+     * things go wrong at once — the write's `WorkspaceLock.write` cancels the
+     * initial build, and the cancelled build's non-validating options are then
+     * inherited by the write's own build (see
+     * `HydraniumDocumentBuilder.prepareBuild`), so cross-document dependents
+     * are silently never validated. `workspaceInitialized` resolves after
+     * `initializeWorkspace` completes, build included, which is what this
+     * gate has always claimed to mean.
+     *
+     * Adopters that need a stricter gate (post-warm-load, AI model
+     * initialised, plugin warm-up) rebind the slot with a subclass and replace
+     * this field with a Promise that awaits both the workspace and the extra
+     * concern.
+     *
+     * Property (not method) — matches `ProjectManager.ready` and Langium's
+     * `WorkspaceManager.ready` conventions; the shape difference signals
+     * "in-process readiness" vs the wire-side `DataServer.waitForReady()`
+     * method (RPC operation).
+     */
+    ready;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.tracer = services.Tracer.for(options.logName ?? 'ModelService').trace('instantiated');
+        this.uriPolicy = services.workspace.DocumentUriPolicy;
+        this.slowUpdateWarn = options.slowUpdateWarnMs !== undefined ? ObservableValue.from(options.slowUpdateWarnMs) : undefined;
+        this.serializeBuilds = ObservableValue.from(options.serializeBuilds ?? true);
+        // Optional-chain so a harness that binds no WorkspaceManager awaits
+        // `undefined` and resolves immediately; production hosts always have it
+        // bound.
+        // Deliberately NO fallback to Langium's `ready`: it resolves pre-build,
+        // so falling back to it would silently reinstate the very gap this gate
+        // exists to close.
+        // Captured rather than read off `this` inside the closure, which TS cannot
+        // prove runs after the field is assigned.
+        const tracer = this.tracer;
+        this.ready = (async () => {
+            try {
+                await services.workspace.WorkspaceManager?.workspaceInitialized;
+            }
+            catch (error) {
+                // NEVER rejects, deliberately. This gate is about TIMING — "the
+                // initial build has finished" — not about whether it succeeded, and
+                // Langium's `ready` (what it replaced) could not reject at all.
+                // `workspaceInitialized` can: it rejects on a cancelled initial
+                // build (routine — any write preempts one) and on a failed one
+                // (e.g. a disposed connection at teardown). Propagating either would
+                // fail every `waitForReady` for the rest of the process lifetime,
+                // a far worse failure than the late gate this exists to fix.
+                tracer.debug(`Initial workspace build did not complete cleanly: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        })();
+        // One persistent listener mirroring non-LSP-client changes back to the LSP
+        // textual language client. Fires per document as it reaches the
+        // post-integrity settled phase (post-integrity, pre-validation) so editors
+        // converge as soon as cross-references resolve. Self-healing: it re-derives
+        // the sync decision from the current settled state every time, so a doc
+        // that needs syncing on a later settle (re-open refresh, recovery build) is
+        // caught even though an earlier settle already synced it. See
+        // `syncToLanguageClient`.
+        this.services.workspace.DocumentBuilder.onDocumentPhase(IntegrityService.SettledState, labelPhaseListener(document => this.syncToLanguageClient(document), 'ModelService.syncToLanguageClient'));
+    }
+    // ============================================================
+    // Lifecycle (public API)
+    // ============================================================
+    /**
+     * Wait for the document at `uri` to reach `state`. Pure wait — does
+     * not trigger a build. If `uri` is not yet in the document registry
+     * the call will hang until something else drives it through the
+     * pipeline; for the cold-start case use {@link rebuild} instead.
+     *
+     * Wrapped in a debug-level timing log via {@link Tracer.time} so
+     * slow per-URI waits surface in build telemetry; the URI is
+     * attached via {@link Tracer.withUri} for callsite attribution.
+     */
+    async waitForDocumentState(uri, state, cancelToken) {
+        return this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), state, cancelToken);
+    }
+    /**
+     * 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.
+     */
+    async waitForDocumentSettled(uri, cancelToken) {
+        return this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), IntegrityService.SettledState, cancelToken);
+    }
+    /**
+     * Internal wait core operating on an already-{@link CanonicalUri canonical}
+     * URI. The public string doors ({@link waitForDocumentState} /
+     * {@link waitForDocumentSettled}) and the build/ensure cores
+     * ({@link rebuildCanonical} / {@link ensureDocumentStateCanonical}) canonicalize
+     * once at entry and thread the result here, so a single high-level op resolves
+     * 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.
+     */
+    async waitForDocumentStateCanonical(uri, state, cancelToken) {
+        const documentUri = UriUtils.toUri(uri);
+        await this.tracer
+            .withUri(uri)
+            .time(`Wait for document state '${DocumentState[state]}'`, () => this.services.workspace.DocumentBuilder.waitUntil(state, documentUri, cancelToken), 'debug');
+        return this.toAstDocument(documentUri);
+    }
+    /**
+     * Wait for the document builder to reach `state` across its currently-
+     * queued documents. Pure wait — does not trigger a build. Used by
+     * shutdown / cascade-rebuild observers / tests; per-URI callers
+     * should use {@link waitForDocumentState} instead.
+     *
+     * Timing log fires on the unattributed logger (no URI scope, since
+     * the wait spans the whole build queue).
+     */
+    async waitForBuilderState(state, cancelToken) {
+        await this.tracer.time(`Wait for builder state '${DocumentState[state]}'`, () => this.services.workspace.DocumentBuilder.waitUntil(state, cancelToken), 'debug');
+    }
+    /**
+     * 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.
+     *
+     * The facade is responsible for firing `DocumentBuilder.update`
+     * directly 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.
+     *
+     * Consumers wanting "give me this doc at state X, building only if
+     * needed" — use the per-state methods ({@link parsed} / {@link linked}
+     * / {@link settled} / {@link indexed} / {@link validated}) instead.
+     */
+    async rebuild(uri, state, cancelToken) {
+        return this.rebuildCanonical(this.uriPolicy.canonicalUri(uri), state, cancelToken);
+    }
+    /**
+     * 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
+     * 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.)
+     */
+    async rebuildCanonical(uri, state, cancelToken) {
+        const documentUri = UriUtils.toUri(uri);
+        // Runs under the workspace WRITE lock, matching Langium's own
+        // `DefaultDocumentUpdateHandler`, which dispatches its build as
+        // `workspaceLock.write(token => documentBuilder.update(...))`.
+        //
+        // Unlocked, this build races the LSP bridge's build of the same URI: both
+        // are legitimate (the bridge only exists under a `Connection`, so the
+        // facade stands in for it headless), and the coexistence note above relied
+        // on Langium coalescing them by URI. It does not — nothing serialises the
+        // two, so both reach `Validated`, and because each computes its missing
+        // validation categories before the other has recorded its own, both run a
+        // FULL pass and Langium appends the second onto the first (its append is
+        // meant for category-partitioned passes). The user-visible result is every
+        // diagnostic duplicated, plus double the validation work per write.
+        //
+        // Opt out via `ModelServiceOptions.serializeBuilds` — see there for
+        // the non-reentrancy hazard that opt-out exists for.
+        if (this.serializeBuilds.value) {
+            // Fail loudly on the one shape the lock cannot survive. `WorkspaceLock`
+            // is not reentrant: acquiring the write lock cancels the running holder,
+            // so a caller already inside one — an integrity rule or build-phase pass
+            // writing back through this facade — would cancel its own enclosing
+            // build and then likely stall in the phase wait below. The check is
+            // gated on `serializeBuilds` deliberately, because acquiring the lock IS
+            // the hazard: with serialisation off there is nothing to be reentrant
+            // about, which makes the existing opt-out the guard's opt-out too.
+            // Detection needs async-context propagation, so it is inert until a host
+            // installs a tracker (`@hydranium/core/node` does) — see
+            // `isInsideWriteLock`.
+            if (isInsideWriteLock()) {
+                throw new ReentrantWriteLockError(uri);
+            }
+            // The lock's OWN token, not the caller's: a later `write` cancels the
+            // running one through that token, so substituting the caller's would
+            // leave this build deaf to the lock's cancellation protocol. A caller
+            // token still governs the phase wait below.
+            await this.services.workspace.WorkspaceLock.write(lockToken => this.services.workspace.DocumentBuilder.update([documentUri], [], lockToken));
+        }
+        else {
+            await this.services.workspace.DocumentBuilder.update([documentUri], [], cancelToken);
+        }
+        return this.waitForDocumentStateCanonical(uri, state ?? IntegrityService.SettledState, cancelToken);
+    }
+    /**
+     * Per-state typed convenience methods. Each ensures the document at
+     * `uri` reaches the named phase and returns the AST envelope with
+     * the narrowest accurate diagnostics type for that phase. Smart
+     * dispatch internally: warm path (URI already in the document
+     * registry) just waits via {@link waitForDocumentState}; cold path
+     * triggers a build via {@link rebuild}. Consumers do not need to
+     * know which path was taken.
+     *
+     * Phase invariants encoded in the return type:
+     * - `parsed` / `linked` / `settled` / `indexed` return
+     *   `AstDocument<TAst, never>` — diagnostics array is empty by phase
+     *   contract.
+     * - `validated` returns `AstDocument<TAst, TDiagnostic>` — diagnostics
+     *   are populated.
+     *
+     * `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
+     * exists so consumers track the semantic stability even if the landmark
+     * ever moves.
+     */
+    async parsed(uri, cancelToken) {
+        return this.ensureDocumentState(uri, DocumentState.Parsed, cancelToken);
+    }
+    async linked(uri, cancelToken) {
+        return this.ensureDocumentState(uri, DocumentState.Linked, cancelToken);
+    }
+    async settled(uri, cancelToken) {
+        return this.ensureDocumentState(uri, IntegrityService.SettledState, cancelToken);
+    }
+    async indexed(uri, cancelToken) {
+        return this.ensureDocumentState(uri, DocumentState.IndexedReferences, cancelToken);
+    }
+    async validated(uri, cancelToken) {
+        return this.ensureDocumentState(uri, DocumentState.Validated, cancelToken);
+    }
+    /**
+     * 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.
+     */
+    async ensureDocumentState(uri, state, cancelToken) {
+        return this.ensureDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), state, cancelToken);
+    }
+    /**
+     * Internal smart-dispatch core operating on an already-{@link CanonicalUri canonical}
+     * URI. The `hasDocument` probe keys `LangiumDocuments` directly with the
+     * canonical URI — no re-canonicalisation — which is the reason the parameter is
+     * typed `CanonicalUri` rather than `string`. The warm path waits via the
+     * canonical wait core ({@link waitForDocumentStateCanonical}); the cold path
+     * dispatches through the public {@link rebuild} (which re-canonicalizes once,
+     * idempotently) so an adopter `rebuild` override stays in the build path — the
+     * one customization seam this chain deliberately preserves.
+     */
+    async ensureDocumentStateCanonical(uri, state, cancelToken) {
+        const target = state ?? IntegrityService.SettledState;
+        if (this.services.workspace.LangiumDocuments.hasDocument(UriUtils.toUri(uri))) {
+            return this.waitForDocumentStateCanonical(uri, target, cancelToken);
+        }
+        return this.rebuild(uri, target, cancelToken);
+    }
+    /**
+     * Apply an update for `uri`. The structured-or-textual `model` payload
+     * is serialised (via {@link serialize} after {@link rewriteModel} when
+     * structured), pushed into the multi-client text-document store with
+     * a fresh version, drives a build to the target phase, and returns
+     * the post-build AST snapshot.
+     *
+     * **Read-latest supersession**: concurrent callers on the same URI
+     * all see the same post-build state once `waitUntil` resolves; none
+     * deadlock waiting for a specific version's settled event. The
+     * framework emits a post-resolution `debug` log line distinguishing
+     * "vN ready" from "vN ready at vM (superseded)" so callers can
+     * observe when their write was overtaken by a newer one before
+     * settling — purely observability, doesn't change resolution
+     * semantics. Adopters wanting version-matched resolution (resolve
+     * with vN's specific settled snapshot, intermediate-phase
+     * observability, slow-warn / hard-timeout behaviour) override this
+     * method.
+     */
+    async update(args, cancelToken) {
+        const stopwatch = this.slowUpdateWarn !== undefined ? this.services.Clock.stopwatch() : undefined;
+        // Per-stage self-time breakdown of the update/reconcile chain (serialise →
+        // open → apply → rebuild), opt-in at debug — the default path skips the
+        // session and `run` calls the stage directly. `update` is a per-operation
+        // method (one user save / diagram edit), not a per-node hot loop, so the
+        // stage closures `run` allocates on the non-debug path are negligible.
+        // Canonicalize the write URI once at the door and thread the resulting
+        // CanonicalUri through the chain. The text store keys documents by their
+        // canonical identity, so any spelling of a file — a canonical
+        // (server-identity) URI from a GLSP cross-document save derived from
+        // `findDocument(node).uri`, or the symlink path an editor opened — collapses
+        // to the one registration; there is no second registration to fork. The
+        // build step reuses the canonical wait core (`rebuildCanonical`) so the
+        // identity is not re-resolved downstream.
+        const uri = this.uriPolicy.canonicalUri(args.uri);
+        const session = Logger.isLevelEnabled('debug') ? this.tracer.profile(`model-update ${uri}`) : undefined;
+        const run = async (stage, fn) => (session ? session.scope(stage, fn) : fn());
+        // Open WITH the new text so a cold URI (no open editor, no file on disk) is
+        // created from the payload rather than read from the filesystem — `update`
+        // is an upsert. For an already-open document `open` refreshes content (the
+        // text is ignored on that branch), so existing-document behaviour is
+        // unchanged. `version` is intentionally NOT forwarded to `open`: a cold
+        // create stays at its initial version, so a based-on-`version` update of a
+        // not-yet-existing document still trips the conflict gate below.
+        const text = await run('serialize', () => this.modelToText(uri, args.model, cancelToken));
+        await run('open', () => this.open({ uri, clientId: args.clientId, text }));
+        if (args.baseVersion !== undefined) {
+            const current = this.services.workspace.TextDocuments.version(uri);
+            if (current !== args.baseVersion) {
+                // Distinct from the post-build "superseded" debug line below: this is a
+                // based-on-stale rejection (the write never applies), not two writes racing.
+                this.tracer.debug(`Conflict on ${uri}: based-on v${args.baseVersion} stale, server at v${current}`);
+                throw new ConflictError(uri, args.baseVersion, current);
+            }
+        }
+        const appliedVersion = await run('apply', () => this.services.workspace.AstDocumentManager.update(uri, text, args.clientId));
+        // Dispatch through the public `rebuild` (which re-canonicalizes the already-
+        // canonical `uri` once, idempotently) rather than `rebuildCanonical`, so an
+        // adopter `rebuild` override stays in the update path. The redundant call is
+        // a single kernel-cached `realpath`; correctness of the override contract
+        // wins over shaving it.
+        const doc = await run('rebuild', () => this.rebuild(uri, undefined, cancelToken));
+        const finalVersion = this.services.workspace.TextDocuments.version(uri);
+        if (finalVersion > appliedVersion) {
+            this.tracer.debug(`Update to v${appliedVersion} ready at v${finalVersion} (superseded)`);
+        }
+        else {
+            this.tracer.debug(`Update to v${appliedVersion} ready`);
+        }
+        if (this.slowUpdateWarn !== undefined && stopwatch) {
+            const elapsed = Math.round(stopwatch.elapsedMs);
+            const threshold = this.slowUpdateWarn.value;
+            if (elapsed >= threshold) {
+                this.tracer.withUri(uri).warn(`Slow update: ${elapsed}ms ≥ ${threshold}ms (v${appliedVersion}, client=${args.clientId})`);
+            }
+        }
+        // One line per stage (serialise / open / apply / rebuild) + unaccounted — only when profiling.
+        session?.report('debug');
+        return doc;
+    }
+    /**
+     * Persist `uri` to disk. Same content-change + settled-phase flow as
+     * {@link update}, then writes via the
+     * `WritableFileSystemProvider` and notifies the multi-client
+     * text-document store of the save (so any open LSP-side editor sees
+     * the `onDidSave` event regardless of who originated the persist).
+     *
+     * Returns the post-save AST snapshot.
+     */
+    async save(args, cancelToken) {
+        // Dispatch through `update` (not its internals) so an adopter `update`
+        // override — version-matched resolution, etc. — applies to saves too.
+        const doc = await this.update(args, cancelToken);
+        // Persist under the same canonical identity `update` operated on. Writing
+        // the canonical (real) path follows any symlink to the same file, and the
+        // `onDidSave` keys the one canonical registration.
+        const uri = this.uriPolicy.canonicalUri(args.uri);
+        await this.services.workspace.AstDocumentManager.save(uri, args.clientId);
+        return doc;
+    }
+    /**
+     * Wait for the document at `uri` to reach the integrity-settled landmark and
+     * 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.
+     *
+     * 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`.
+     */
+    async settleSave(uri, cancelToken) {
+        const canonical = this.uriPolicy.canonicalUri(uri);
+        const key = UriUtils.toUri(canonical).toString();
+        const timeout = new Promise((_, reject) => setTimeout(() => reject(new SaveSettleTimeoutError('settle timeout')), SAVE_SETTLE_TIMEOUT_MS));
+        try {
+            await Promise.race([this.waitForDocumentStateCanonical(canonical, IntegrityService.SettledState, cancelToken), timeout]);
+            const pending = this.syncChains.get(key);
+            if (pending) {
+                await Promise.race([pending, timeout]);
+            }
+        }
+        catch (err) {
+            if (err instanceof SaveSettleTimeoutError) {
+                this.tracer.withUri(key).warn(`Save settle exceeded ${SAVE_SETTLE_TIMEOUT_MS}ms — returning anyway`);
+            }
+            else {
+                const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+                this.tracer.withUri(key).warn(`Save settle failed before the timeout — returning anyway. ${detail}`);
+            }
+        }
+    }
+    /**
+     * Open the document at `args.uri` on behalf of `args.clientId`.
+     * Multi-client: each (uri, clientId) pair is tracked as one
+     * registration; the underlying document stays open until the last
+     * client closes it. If `args.text` is omitted the document content
+     * is read from the `FileSystemProvider`.
+     *
+     * Returns a {@link Disposable} that closes the registration when
+     * disposed — useful for `using` blocks and shutdown cleanup.
+     *
+     * Delegates to the framework-bound
+     * `services.workspace.AstDocumentManager`. Adopter subclasses with
+     * extra open-time behaviour (logging, sync-chain bootstrapping)
+     * override on their `ModelService` subclass and call `super.open`.
+     *
+     * The open path does not thread cancellation: `AstDocumentManager.open`
+     * and the filesystem read behind it take no token, so a cancelled caller
+     * still completes the open.
+     */
+    async open(args) {
+        return this.services.workspace.AstDocumentManager.open(args);
+    }
+    /**
+     * Close the document at `args.uri` for `args.clientId`. Counterpart
+     * to {@link open}; the underlying document stays open until every
+     * registered client has closed.
+     */
+    async close(args) {
+        return this.services.workspace.AstDocumentManager.close(args);
+    }
+    /**
+     * True when the document at `uri` is currently open for at least one
+     * client. Pure read; no side effects.
+     */
+    isOpen(uri) {
+        return this.services.workspace.AstDocumentManager.isOpen(uri);
+    }
+    /**
+     * The built {@link LangiumDocument} for `uri`, looked up by canonical identity —
+     * the synchronous, phase-agnostic sibling of {@link ensureDocumentState} /
+     * {@link waitForDocumentState} (which await a build state). The single
+     * canonicalizing door for callers that need the live document without reaching
+     * 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`.
+     */
+    getDocument(uri) {
+        return this.services.workspace.AstDocumentManager.getDocument(uri);
+    }
+    // ============================================================
+    // LSP-client sync (mirror non-LSP-client changes back to Monaco)
+    // ============================================================
+    /**
+     * Mirror a server-side change of `document` back to the LSP textual language
+     * client, run per document as it reaches the post-integrity settled phase.
+     * The single framework caller of
+     * `HydraniumTextDocuments.applyEditToLanguageClient` and
+     * `HydraniumTextDocuments.stagePendingContent`.
+     *
+     * Routes to one of two mechanisms by language-client registration, because
+     * an open and a closed document answer different questions:
+     *
+     * - **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}).
+     *
+     * 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
+     * that still needs syncing on a later settle — a re-open refresh, a recovery
+     * build after cancellation — is caught even though an earlier settle already
+     * synced it.
+     */
+    syncToLanguageClient(document) {
+        // `document.textDocument.uri` is the server-identity (canonical) URI off the
+        // build. Route by language-client registration (a presence question —
+        // `isOpenInLanguageClient` canonicalizes internally, so a divergent open path
+        // still resolves to the same record), but key the outbound sync by this
+        // CANONICAL URI — the same key `settleSave` looks the chain up under —
+        // so a save-settle can drain the in-flight applyEdit. The canonical→client-URI
+        // translation (a symlinked path the client opened, or a dual-open fan-out)
+        // happens at the `applyEditToLanguageClient` egress, where the text store maps
+        // the canonical key to the recorded language-client URI(s); driving the chain
+        // in client space here would key it under a URI `settleSave` never computes, so
+        // the drain would miss for a divergent open path.
+        if (this.services.workspace.TextDocuments.isOpenInLanguageClient(document.textDocument.uri)) {
+            this.syncOpenDocument(document.textDocument.uri, document.textDocument.getText());
+        }
+        else {
+            this.stageClosedDocument(document);
+        }
+    }
+    /**
+     * Mirror the settled text of a document open in the language client via a
+     * coalesced `applyEditToLanguageClient`. `uri` is the document's CANONICAL identity
+     * (the chain key); the egress (`applyEditToLanguageClient`) translates it to the
+     * recorded language-client URI(s). Routed purely by **content**: the shadow
+     * no-ops the RPC when Monaco already matches, so a Monaco echo (the client's
+     * own edit coming back) and a cascade-affected doc whose serialized text is
+     * unchanged both cost nothing — a string compare, no RPC. Author is
+     * irrelevant here: the shadow suppresses the echo precisely, so no
+     * author-based skip is needed.
+     */
+    syncOpenDocument(uri, text) {
+        this.queueSync(uri, text);
+    }
+    /**
+     * Stage the settled text of a document closed in the language client so the
+     * eventual first `didOpen` sees this in-memory text instead of stale disk —
+     * but only for a {@link isNonLanguageClientEdit genuine non-language-client edit}.
+     * A document rebuilt by an internal build is skipped, leaving disk authoritative
+     * on the next open.
+     */
+    stageClosedDocument(document) {
+        if (this.isNonLanguageClientEdit(document)) {
+            this.services.workspace.TextDocuments.stagePendingContent(document.textDocument.uri, document.textDocument.getText());
+        }
+    }
+    /**
+     * Whether `document`'s settled state is a genuine edit by a client *other than
+     * the language client* — a write a form / GLSP / integrity client actually made.
+     * Excludes two non-edits: the **language client** itself (the LSP/Monaco text
+     * client — it already holds its own edits, and the staging here exists to feed
+     * it) and an **internal build** (workspace startup, a cascade relink, a
+     * `didClose`-reload). This is the gate for {@link stageClosedDocument}: staging
+     * an internal build would
+     * (a) pre-stage every file on boot and (b) re-stage discarded content after
+     * close (e.g. a disposing GLSP session's debounced submit firing after close),
+     * which then shadows clean disk on the next open.
+     *
+     * The signal is "a known client other than the language client authored this
+     * version **and** the URI was in the last build's changed set
+     * (`isDirectChange`)". A framework-internal rebuild reports no author
+     * (`getAuthor` → `undefined`), so it fails `hasKnownAuthor` without comparing
+     * against a sentinel. This is NOT redundant with content/registration — it
+     * distinguishes "client edited" from "framework rebuilt", which neither the
+     * shadow nor `isDirectChange` alone can.
+     */
+    isNonLanguageClientEdit(document) {
+        const documents = this.services.workspace.AstDocumentManager;
+        const author = documents.getAuthor(document);
+        const hasKnownAuthor = !!author && author !== LANGUAGE_CLIENT_ID;
+        return hasKnownAuthor && documents.isDirectChange(document.textDocument.uri);
+    }
+    /**
+     * Enqueue a sync to the language client. The pending slot per URI holds only
+     * the latest text: if a newer settle fires while the current RPC is in
+     * flight, the intermediate text is dropped and the chain picks up the latest
+     * on its next iteration. Coalescing guarantees a single in-flight applyEdit
+     * per URI so the shadow never drifts from Monaco.
+     */
+    queueSync(uri, text) {
+        this.pendingSync.set(uri, text);
+        if (this.syncChains.has(uri)) {
+            return;
+        }
+        // Start the drain a microtask late so `syncChains` is populated BEFORE the
+        // first push goes out. Calling `drainSyncQueue` directly would run its
+        // synchronous prologue — loop head plus the `applyEditToLanguageClient`
+        // call — ahead of the `set` below, so a `queueSync` re-entered from within
+        // that window would see no chain and start a SECOND one. Two concurrent
+        // chains break the single-in-flight-per-URI guarantee this coalescing
+        // exists to provide, and that guarantee is what keeps the shadow from
+        // drifting: overlapping pushes diff against each other's optimistic
+        // baseline and the later one can land stale text last.
+        const chain = Promise.resolve()
+            .then(() => this.drainSyncQueue(uri))
+            .finally(() => {
+            if (this.syncChains.get(uri) === chain) {
+                this.syncChains.delete(uri);
+            }
+        });
+        this.syncChains.set(uri, chain);
+    }
+    async drainSyncQueue(uri) {
+        const uriLogger = this.tracer.withUri(uri);
+        while (this.pendingSync.has(uri)) {
+            const text = this.pendingSync.get(uri);
+            this.pendingSync.delete(uri);
+            try {
+                let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+                if (result?.applied === false && !this.pendingSync.has(uri)) {
+                    // The push is addressed at the client's LAST DECLARED VERSION, so a
+                    // rejection normally means the client's buffer moved while the
+                    // line-keyed diff was in flight — exactly the case where applying it
+                    // would splice the file. Dropping the push there would leave the
+                    // editor showing text the server has already superseded, with no
+                    // later settle guaranteed to correct it (a content-identical echo
+                    // mints no rebuild). The rejection invalidated the shadow, so the
+                    // retry is a full-range replace: position-independent, and therefore
+                    // correct against whatever the client now holds.
+                    //
+                    // Retried INLINE rather than re-enqueued, and exactly once. Inline
+                    // because a re-enqueue would have to out-order any settle that lands
+                    // in the meantime, which nothing here can guarantee; once because a
+                    // client that refuses every edit (a read-only file, a modal holding
+                    // the workspace) must cost one extra RPC rather than spin. The
+                    // `pendingSync` check skips the retry when a newer settle has already
+                    // queued — best-effort, since a settle arriving later simply pushes
+                    // after this and still wins.
+                    uriLogger.warn(`Language client rejected applyEdit at its declared version — re-pushing a full replace`);
+                    result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+                    if (result?.applied === false) {
+                        uriLogger.warn(`Language client rejected the full-replace retry too — client content is stale`);
+                    }
+                }
+            }
+            catch (err) {
+                // A disconnected client is not a failure of this edit: pushing text
+                // to a peer that has gone is a no-op, and it happens on every
+                // ordinary shutdown. Reporting it at `error` makes routine teardown
+                // look like it needs investigating. A genuine applyEdit failure
+                // (client refused, request malformed) still surfaces at `error`.
+                if (isConnectionGoneError(err)) {
+                    uriLogger.debug(`applyEdit to ${LANGUAGE_CLIENT_ID} skipped: client disconnected`);
+                }
+                else {
+                    uriLogger.error(`applyEdit to ${LANGUAGE_CLIENT_ID} failed: ${err}`);
+                }
+            }
+        }
+    }
+    // ============================================================
+    // Subscription pass-throughs
+    // ============================================================
+    /**
+     * Subscribe to AST-snapshot updates for `uri`. Fires after each
+     * rebuild that reaches the target phase. Delegates to the
+     * `HydraniumTextDocuments` — single listener registration shared with
+     * any direct `HydraniumTextDocuments.onUpdate` subscriber, so the same
+     * underlying `DocumentBuilder.onDocumentPhase` listener serves both
+     * call paths. `sourceClientId` is resolved from the multi-client
+     * author history; reason discrimination follows the manager's own
+     * `lastUpdate` snapshot (see `AstDocumentManager.onUpdate`).
+     */
+    onModelUpdated(uri, listener) {
+        return this.services.workspace.AstDocumentManager.onUpdate(uri, listener);
+    }
+    /**
+     * Subscribe to save events for `uri`. Fires on every persist through
+     * the multi-client text-document store — including saves originated
+     * by other heads (LSP editor `Ctrl+S`, the data-server `save`, etc.)
+     * so subscribers see one consistent stream regardless of who wrote
+     * the file. Delegates to the manager — single listener registration
+     * shared with any direct `HydraniumTextDocuments.onSave` subscriber.
+     */
+    onModelSaved(uri, listener) {
+        return this.services.workspace.AstDocumentManager.onSave(uri, listener);
+    }
+    /**
+     * Subscribe to the `(uri, clientId)` close event. Delegates to the
+     * manager so the listener registry is shared with any direct
+     * `HydraniumTextDocuments.onClientClosed` subscriber.
+     */
+    onClientClosed(uri, clientId, listener) {
+        return this.services.workspace.AstDocumentManager.onClientClosed(uri, clientId, listener);
+    }
+    // ============================================================
+    // Adopter hooks (override on subclass)
+    // ============================================================
+    /**
+     * Serialise a transfer-model root via the language-specific
+     * `Serializer` bound at `services.serializer.Serializer`,
+     * resolved per-URI through `services.ServiceRegistry.getServices(uri)`
+     * so multi-grammar workspaces route to the right serializer per file.
+     * Adopters bind their own per-language; the framework default
+     * `UnboundSerializer` throws if none is bound.
+     *
+     * 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
+     * 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`,
+     * so a naive `await` covers both branches without extra ceremony.
+     */
+    serialize(uri, root) {
+        const services = this.services.ServiceRegistry.getServices(UriUtils.toUri(uri));
+        return services.serializer.Serializer.serializeTransfer(root);
+    }
+    // ============================================================
+    // Protected plumbing (override sparingly)
+    // ============================================================
+    /**
+     * Convert a structured-or-textual `model` payload to its textual form.
+     *
+     * Textual payloads (LSP / pre-serialised callers) pass through untouched.
+     * Structured payloads run the per-language `UpdateRewriteService` chain
+     * (transfer-model transforms; diff-aware rewrites see the previous AST root),
+     * then serialise. The chain is the single transfer-model-transform seam — a
+     * unary normalisation is just a rewrite that ignores `previous`, as
+     * `NormalizeEmptyStringsContribution` does. The chain is empty by
+     * default, so this is a no-op for adopters that register none.
+     */
+    async modelToText(uri, model, cancelToken) {
+        if (typeof model === 'string') {
+            return model;
+        }
+        const rewritten = await this.rewriteModel(uri, model, cancelToken);
+        return this.serialize(uri, rewritten);
+    }
+    /**
+     * Run the per-language transfer-model rewrite chain. Resolves the
+     * `UpdateRewriteService` per-URI (like {@link serialize}) and threads
+     * in the previous AST root — `document.parseResult.value`, or `undefined`
+     * for a not-yet-built document — so diff-based rewrites can distinguish a
+     * real user change from a stale echo.
+     */
+    async rewriteModel(uri, model, cancelToken) {
+        // Optional-chain so incomplete test stubs (no ServiceRegistry / no
+        // updateRewrite slot) degrade to the identity chain; production wiring
+        // always provides the slot via `createServerLanguageModule`.
+        const service = this.services.ServiceRegistry?.getServices(UriUtils.toUri(uri))?.updateRewrite?.UpdateRewriteService;
+        if (!service) {
+            return model;
+        }
+        const previous = this.services.workspace.AstDocumentManager.getDocument(uri)?.parseResult.value;
+        return (await service.apply(model, previous, cancelToken));
+    }
+    /**
+     * 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 AstDocument.create}) when the document is absent from the
+     * registry — adopters that prefer to throw override on their subclass.
+     */
+    toAstDocument(uri) {
+        const document = this.services.workspace.LangiumDocuments.getDocument(uri);
+        return document
+            ? AstDocument.from(document)
+            : AstDocument.create(uri.toString(), 0, undefined, []);
+    }
+}
+//# sourceMappingURL=model-service.js.map