@hydranium/core 1.0.0-next.22 → 1.0.0-next.220

package/lib/documents/document-release-handler.d.ts

@@ -0,0 +1,179 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { type URI } from '@hydranium/langium';
+import { type CanonicalUri, type Tracer } from '@hydranium/protocol';
+import { type CancellationToken } from 'vscode-languageserver';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import { type ServerSharedServices } from '../langium/module.js';
+/**
+ * A document the store has released: no client holds its text any more. Its
+ * queries read the store live, not a snapshot taken at the release.
+ */
+export interface ReleasedDocument {
+    readonly uri: CanonicalUri;
+    /** Whether `uri` names this document, under the store's own keying. */
+    isFor(uri: string): boolean;
+    /**
+     * Whether a client took the document back: it holds it again, or it waits
+     * out a new grace. Either way it is that client's, and the build keeps its text.
+     */
+    isReclaimed(): boolean;
+}
+/**
+ * The rejection of a release skipped because the connection or the workspace
+ * went away, with the error that showed it as `cause`. The store logs it at
+ * debug, as routine at teardown, and any other rejection as an error.
+ */
+export declare class DocumentReleaseSkippedError extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * Whether `error` is a {@link DocumentReleaseSkippedError}, by name, so one
+ * thrown by another installed copy of this package counts too.
+ */
+export declare function isDocumentReleaseSkippedError(error: unknown): error is DocumentReleaseSkippedError;
+/**
+ * Decides what the build keeps for a document the store has released. Called
+ * by the store at each release, for every head, after its release event.
+ *
+ * The returned promise settles the release: it resolves once the build holds
+ * what it keeps for the document, and rejects when that build failed and may
+ * still hold the released text. Until then, watchers keep a document released
+ * dirty marked dirty. On a resolve the store announces it clean, naming the
+ * store's last text while the build still has the document, and no text once
+ * it has none; on a rejection, no text. The store logs a throw or rejection; reject with a
+ * {@link DocumentReleaseSkippedError} for a release skipped at teardown.
+ *
+ * The data server announces the first build of a released document as the
+ * release, so a handler that builds nothing leaves that to whichever build
+ * comes next; one that carries a client's write keeps that client's name.
+ *
+ * Extend {@link DefaultDocumentReleaseHandler} to change only the policy: it
+ * keeps the locking and the wait for the build. An implementation written
+ * from scratch has to wait for that build itself before it resolves.
+ */
+export interface DocumentReleaseHandler {
+    didReleaseDocument(released: ReleasedDocument): Promise<void>;
+}
+/** What the build does with a released document: rebuild it from its file, or remove it. */
+export type DocumentReleaseDecision = 'rebuild' | 'remove';
+/** How {@link DefaultDocumentReleaseHandler.runRelease} went. */
+export type DocumentReleaseOutcome = 
+/** A client took the document back: what the build keeps is that client's. */
+{
+    readonly kind: 'reclaimed';
+}
+/**
+ * The lock resolved the write without running it, and the write that
+ * cancelled it does not build this document. The framework's lock always
+ * runs a cancelled write; a rebound `WorkspaceLock` may not.
+ */
+ | {
+    readonly kind: 'discarded';
+    readonly decision: DocumentReleaseDecision;
+}
+/** The build started and was cancelled; `parsed` when it parsed the document first. */
+ | {
+    readonly kind: 'cancelled';
+    readonly decision: DocumentReleaseDecision;
+    readonly parsed: boolean;
+}
+/** The decision was carried out. */
+ | {
+    readonly kind: 'completed';
+    readonly decision: DocumentReleaseDecision;
+    readonly parsed: boolean;
+}
+/** The decision or the build threw; `decision` is unset when deciding did. */
+ | {
+    readonly kind: 'failed';
+    readonly decision: DocumentReleaseDecision | undefined;
+    readonly parsed: boolean;
+    readonly error: unknown;
+}
+/** The connection or the workspace went away: nothing more is built. `parsed` when the build parsed the document first. */
+ | {
+    readonly kind: 'skipped';
+    readonly parsed: boolean;
+    readonly error: unknown;
+};
+/**
+ * Rebuilds a released document from the file system provider, so the build
+ * stops carrying the unsaved text of its last client. Override
+ * `decideRelease` or `applyReleaseDecision` to change the policy and keep the
+ * locking and the wait for the build.
+ *
+ * The provider decides, for every scheme, by `exists`: a document it can
+ * serve is rebuilt from its text, and any other — an editor's `untitled:`
+ * buffer, a file never saved, or one deleted meanwhile — is removed
+ * from the workspace. A `virtual:` document survives, since the framework's
+ * provider for that scheme serves it from the index, whatever provider the
+ * host passes as `context.fileSystemProvider`; an edited one therefore keeps
+ * its last client's text, and keeping it read-only is the client's job.
+ *
+ * The answer is read in the document's disk queue, so the rebuild follows
+ * any save still queued rather than reverting past it; a file that goes
+ * after that read is removed when its rebuild finds none.
+ *
+ * Whether the document is still released is checked again inside the write
+ * lock, as its holder: checked only before waiting for the lock, a client that
+ * opens or re-creates the document meanwhile would have its text rebuilt over,
+ * or the document removed. A document some client has open again, or that
+ * waits out a new grace, is left to that client.
+ *
+ * The promise resolves once the revert has parsed the file, even if it is
+ * then cancelled, or else once the build it requests in its place has parsed
+ * it or removed the document. It rejects when that build fails, and when the
+ * revert is skipped because the connection or the workspace went away before
+ * it parsed the file, with a {@link DocumentReleaseSkippedError}.
+ */
+export declare class DefaultDocumentReleaseHandler implements DocumentReleaseHandler {
+    protected readonly services: ServerSharedServices;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerSharedServices, options?: LogNameOptions);
+    didReleaseDocument(released: ReleasedDocument): Promise<void>;
+    /**
+     * Decide, then carry the decision out under the write lock unless a client
+     * holds the document again. Answers how that went; a parse of the document
+     * seen meanwhile counts even when the build was cancelled after it, since
+     * the build it yields to does not parse again.
+     */
+    protected runRelease(released: ReleasedDocument, target: URI): Promise<DocumentReleaseOutcome>;
+    /**
+     * `outcome` for the line each release logs at debug: its kind, the
+     * decision and whether the document was parsed.
+     */
+    protected formatReleaseOutcome(outcome: DocumentReleaseOutcome): string;
+    /**
+     * The policy: rebuild a document the file system provider can serve, and
+     * remove any other. Read in the document's disk queue, so it follows any
+     * save still queued rather than deciding past it.
+     */
+    protected decideRelease(released: ReleasedDocument, target: URI): Promise<DocumentReleaseDecision>;
+    /**
+     * Carry `decision` out under the write lock; a file gone since the decision
+     * is removed instead. An override must rebuild or remove the document:
+     * release settlement waits for its parse or removal, and one that does
+     * neither is followed by a recovery build that rebuilds it.
+     */
+    protected applyReleaseDecision(target: URI, decision: DocumentReleaseDecision, token: CancellationToken): Promise<void>;
+    /** The build in place of a release that stopped short; answers whether it ran. */
+    protected requestRecoveryBuild(released: ReleasedDocument, target: URI, deleted: boolean): Promise<boolean>;
+    /**
+     * Resolve now when the build holds the file's text of `target` or no longer
+     * has it, else once a parse or removal of `target` reaches the store:
+     * settled with the released text still in the build, the release would name
+     * that text. `startRecovery` requests the build in place of a revert that
+     * stopped short, started only once the parse and removal are watched, so a
+     * build that records the document at once is not missed. Rejects when that
+     * build fails, since no parse or removal is coming then.
+     */
+    protected waitForReleaseBuild(released: ReleasedDocument, target: URI, parsed: boolean, startRecovery: (() => Promise<void>) | undefined): Promise<void>;
+}
+//# sourceMappingURL=document-release-handler.d.ts.map

package/lib/documents/document-release-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-release-handler.d.ts","sourceRoot":"","sources":["../../src/documents/document-release-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,GAAG,EAAY,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,KAAK,iBAAiB,EAAmB,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEvE,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAIjE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC9B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,uEAAuE;IACvE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACnD,YAAY,KAAK,EAAE,OAAO,EAKzB;CACH;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,2BAA2B,CAElG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,sBAAsB;IACpC,kBAAkB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAED,4FAA4F;AAC5F,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3D,iEAAiE;AACjE,MAAM,MAAM,sBAAsB;AAC/B,8EAA8E;AAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE;AAChC;;;;GAIG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAA;CAAE;AAC5E,uFAAuF;GACrF;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE;AACtG,oCAAoC;GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE;AACtG,8EAA8E;GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AACxI,2HAA2H;GACzH;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,6BAA8B,YAAW,sBAAsB;IAItE,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB;IAHpD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAElC,YACsB,QAAQ,EAAE,oBAAoB,EACjD,OAAO,GAAE,cAAmB,EAG9B;IAEK,kBAAkB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4ClE;IAED;;;;;OAKG;IACH,UAAgB,UAAU,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAmDnG;IAED;;;OAGG;IACH,SAAS,CAAC,oBAAoB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAOtE;IAED;;;;OAIG;IACH,SAAS,CAAC,aAAa,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAKjG;IAED;;;;;OAKG;IACH,UAAgB,oBAAoB,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,uBAAuB,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5H;IAED,kFAAkF;IAClF,SAAS,CAAC,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ1G;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,mBAAmB,CAC1B,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,GAAG,EACX,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,GAChD,OAAO,CAAC,IAAI,CAAC,CA8Cf;CACH"}

package/lib/documents/document-release-handler.js

@@ -0,0 +1,283 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { UriUtils } from '@hydranium/langium';
+import { HYDRANIUM_BUILD_REASONS } from '../langium/document-builder/document-builder.js';
+import { isFileNotFound } from '../langium/workspace/file-not-found.js';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
+/**
+ * The rejection of a release skipped because the connection or the workspace
+ * went away, with the error that showed it as `cause`. The store logs it at
+ * debug, as routine at teardown, and any other rejection as an error.
+ */
+export class DocumentReleaseSkippedError extends Error {
+    constructor(cause) {
+        super(`Release skipped: the connection or the workspace went away. ${cause instanceof Error ? cause.message : String(cause)}`, {
+            cause
+        });
+        this.name = 'DocumentReleaseSkippedError';
+    }
+}
+/**
+ * Whether `error` is a {@link DocumentReleaseSkippedError}, by name, so one
+ * thrown by another installed copy of this package counts too.
+ */
+export function isDocumentReleaseSkippedError(error) {
+    return error instanceof Error && error.name === 'DocumentReleaseSkippedError';
+}
+/**
+ * Rebuilds a released document from the file system provider, so the build
+ * stops carrying the unsaved text of its last client. Override
+ * `decideRelease` or `applyReleaseDecision` to change the policy and keep the
+ * locking and the wait for the build.
+ *
+ * The provider decides, for every scheme, by `exists`: a document it can
+ * serve is rebuilt from its text, and any other — an editor's `untitled:`
+ * buffer, a file never saved, or one deleted meanwhile — is removed
+ * from the workspace. A `virtual:` document survives, since the framework's
+ * provider for that scheme serves it from the index, whatever provider the
+ * host passes as `context.fileSystemProvider`; an edited one therefore keeps
+ * its last client's text, and keeping it read-only is the client's job.
+ *
+ * The answer is read in the document's disk queue, so the rebuild follows
+ * any save still queued rather than reverting past it; a file that goes
+ * after that read is removed when its rebuild finds none.
+ *
+ * Whether the document is still released is checked again inside the write
+ * lock, as its holder: checked only before waiting for the lock, a client that
+ * opens or re-creates the document meanwhile would have its text rebuilt over,
+ * or the document removed. A document some client has open again, or that
+ * waits out a new grace, is left to that client.
+ *
+ * The promise resolves once the revert has parsed the file, even if it is
+ * then cancelled, or else once the build it requests in its place has parsed
+ * it or removed the document. It rejects when that build fails, and when the
+ * revert is skipped because the connection or the workspace went away before
+ * it parsed the file, with a {@link DocumentReleaseSkippedError}.
+ */
+export class DefaultDocumentReleaseHandler {
+    services;
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+    }
+    async didReleaseDocument(released) {
+        const target = UriUtils.toUri(released.uri);
+        const outcome = await this.runRelease(released, target);
+        this.tracer.with(released.uri).debug(`Release outcome: ${this.formatReleaseOutcome(outcome)}`);
+        if (outcome.kind === 'skipped') {
+            if (!outcome.parsed) {
+                throw new DocumentReleaseSkippedError(outcome.error);
+            }
+            // The build holds the file's text: only what followed its parse, such as the diagnostics publish, was lost.
+            const { error } = outcome;
+            this.tracer
+                .with(released.uri)
+                .debug(`Revert on release skipped after its parse: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
+        if (outcome.kind === 'failed') {
+            const { error } = outcome;
+            this.tracer
+                .with(released.uri)
+                .error(`Revert on release dropped. ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+        }
+        const parsed = 'parsed' in outcome && outcome.parsed;
+        // Without it, a revert stopped short, or an override that built nothing,
+        // leaves the root on the released text. A failed one also lost the change
+        // the update handler held back at the release; a document known to have
+        // no file is removed, as the revert would have.
+        const stoppedShort = ((outcome.kind === 'discarded' || outcome.kind === 'cancelled' || outcome.kind === 'completed') &&
+            !parsed &&
+            this.services.workspace.LangiumDocuments.getDocument(target) !== undefined) ||
+            outcome.kind === 'failed';
+        const recover = async () => {
+            const failure = 'Build after a revert that stopped short failed; the build keeps the released text';
+            let built;
+            try {
+                built = await this.requestRecoveryBuild(released, target, 'decision' in outcome && outcome.decision === 'remove');
+            }
+            catch (err) {
+                throw new Error(`${failure}. ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+            if (!built) {
+                throw new Error(failure);
+            }
+        };
+        await this.waitForReleaseBuild(released, target, parsed, stoppedShort && !released.isReclaimed() ? recover : undefined);
+    }
+    /**
+     * Decide, then carry the decision out under the write lock unless a client
+     * holds the document again. Answers how that went; a parse of the document
+     * seen meanwhile counts even when the build was cancelled after it, since
+     * the build it yields to does not parse again.
+     */
+    async runRelease(released, target) {
+        const workspace = this.services.workspace;
+        let decision;
+        let parsed = false;
+        let parses;
+        // Typed by assertion: the write's callback moves it, which narrowing does not see.
+        let progress = 'queued';
+        try {
+            // Decided before the lock: every build and read waits while the lock
+            // is held, and the default decision waits on the file's save I/O.
+            const decided = await this.decideRelease(released, target);
+            decision = decided;
+            await workspace.WorkspaceManager?.ready;
+            // Queuing the write cancels the running build, even when it then reverts nothing.
+            if (released.isReclaimed()) {
+                return { kind: 'reclaimed' };
+            }
+            await workspace.WorkspaceLock.write(async (token) => {
+                if (released.isReclaimed()) {
+                    progress = 'reclaimed';
+                    return;
+                }
+                parses = workspace.VersionSyncService.onDidRecordModel(document => {
+                    parsed ||= released.isFor(document.uri.toString());
+                });
+                progress = 'building';
+                await this.applyReleaseDecision(target, decided, token);
+                progress = 'built';
+            });
+            // A cancelled build throws inside the write, and the lock resolves.
+            if (progress === 'reclaimed') {
+                return { kind: 'reclaimed' };
+            }
+            if (progress === 'queued') {
+                return { kind: 'discarded', decision: decided };
+            }
+            if (progress === 'building') {
+                return { kind: 'cancelled', decision: decided, parsed };
+            }
+            return { kind: 'completed', decision: decided, parsed };
+        }
+        catch (error) {
+            // A revert that finishes after the LSP peer went away fails its
+            // diagnostics publish, and one that runs after its workspace was torn
+            // down finds no file: teardown races, not failed reverts.
+            if (isConnectionGoneError(error) || isFileNotFound(error, target)) {
+                return { kind: 'skipped', parsed, error };
+            }
+            return { kind: 'failed', decision, parsed, error };
+        }
+        finally {
+            parses?.dispose();
+        }
+    }
+    /**
+     * `outcome` for the line each release logs at debug: its kind, the
+     * decision and whether the document was parsed.
+     */
+    formatReleaseOutcome(outcome) {
+        if (outcome.kind === 'reclaimed') {
+            return 'reclaimed by a client, built nothing';
+        }
+        const decision = 'decision' in outcome && outcome.decision !== undefined ? ` ${outcome.decision}` : '';
+        const parsed = 'parsed' in outcome ? (outcome.parsed ? ', parsed' : ', not parsed') : '';
+        return `${outcome.kind}${decision}${parsed}`;
+    }
+    /**
+     * The policy: rebuild a document the file system provider can serve, and
+     * remove any other. Read in the document's disk queue, so it follows any
+     * save still queued rather than deciding past it.
+     */
+    decideRelease(released, target) {
+        const workspace = this.services.workspace;
+        return workspace.FileSystemTaskQueue.enqueue(released.uri, async () => (await workspace.FileSystemProvider.exists(target)) ? 'rebuild' : 'remove');
+    }
+    /**
+     * Carry `decision` out under the write lock; a file gone since the decision
+     * is removed instead. An override must rebuild or remove the document:
+     * release settlement waits for its parse or removal, and one that does
+     * neither is followed by a recovery build that rebuilds it.
+     */
+    async applyReleaseDecision(target, decision, token) {
+        const builder = this.services.workspace.DocumentBuilder;
+        builder.markNextReason(HYDRANIUM_BUILD_REASONS.didRelease);
+        try {
+            await (decision === 'rebuild' ? builder.update([target], [], token) : builder.update([], [target], token));
+        }
+        catch (err) {
+            if (decision !== 'rebuild' || !isFileNotFound(err, target)) {
+                throw err;
+            }
+            this.tracer.with(target.toString()).debug('Revert found no file; removing the document instead');
+            builder.markNextReason(HYDRANIUM_BUILD_REASONS.didRelease);
+            await builder.update([], [target], token);
+        }
+    }
+    /** The build in place of a release that stopped short; answers whether it ran. */
+    requestRecoveryBuild(released, target, deleted) {
+        return this.services.workspace.VersionSyncService.requestRecoveryBuild(target, {
+            deleted,
+            reason: HYDRANIUM_BUILD_REASONS.didRelease,
+            // The update handler dropped the change it held back at the release.
+            ignoreDeferred: true,
+            stillNeeded: () => !released.isReclaimed()
+        });
+    }
+    /**
+     * Resolve now when the build holds the file's text of `target` or no longer
+     * has it, else once a parse or removal of `target` reaches the store:
+     * settled with the released text still in the build, the release would name
+     * that text. `startRecovery` requests the build in place of a revert that
+     * stopped short, started only once the parse and removal are watched, so a
+     * build that records the document at once is not missed. Rejects when that
+     * build fails, since no parse or removal is coming then.
+     */
+    waitForReleaseBuild(released, target, parsed, startRecovery) {
+        const workspace = this.services.workspace;
+        // A client holding the document again keeps what the build holds for it.
+        if (parsed || workspace.LangiumDocuments.getDocument(target) === undefined || released.isReclaimed()) {
+            // Settled now, so a failed recovery build is only logged.
+            startRecovery?.().catch((err) => this.tracer.with(released.uri).error(err instanceof Error ? err.message : String(err)));
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            let ended = false;
+            const finish = (end) => {
+                if (ended) {
+                    return;
+                }
+                ended = true;
+                parses.dispose();
+                removals.dispose();
+                end();
+            };
+            const parses = workspace.VersionSyncService.onDidRecordModel(document => {
+                if (released.isFor(document.uri.toString())) {
+                    finish(resolve);
+                }
+            });
+            const removals = workspace.DocumentBuilder.onUpdate((_changed, deleted) => {
+                if (deleted.some(uri => released.isFor(uri.toString()))) {
+                    finish(resolve);
+                }
+            });
+            startRecovery?.().then(
+            // A recovery build no longer needed, for a reclaimed document, builds nothing.
+            () => {
+                if (released.isReclaimed()) {
+                    finish(resolve);
+                }
+            }, (err) => {
+                // Settled by a parse that came first, so only logged.
+                if (ended) {
+                    this.tracer.with(released.uri).error(err instanceof Error ? err.message : String(err));
+                }
+                else {
+                    finish(() => reject(err));
+                }
+            });
+        });
+    }
+}
+//# sourceMappingURL=document-release-handler.js.map

package/lib/documents/document-release-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-release-handler.js","sourceRoot":"","sources":["../../src/documents/document-release-handler.ts"],"names":[],"mappings":"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"}

package/lib/documents/document-release-scheduler.d.ts

@@ -0,0 +1,67 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { type CanonicalUri, type Clock, type Stopwatch } from '@hydranium/protocol';
+import { type Disposable } from 'vscode-languageserver';
+/** What an open of a document whose release is deferred means for it, as {@link DocumentReleaseScheduler.resolveOpen} decides. */
+export type DeferredReleaseOpenDecision = 
+/** The opener was lost from the document within its grace: it keeps the unsaved text. */
+'keep'
+/** Any other opener: the document is released first, and opens as a first open does. */
+ | 'release'
+/** No release was deferred. */
+ | 'none';
+/**
+ * Decides when the store releases a document no client holds: at once, or,
+ * when its last client's connection was lost, once a grace has passed, so a
+ * client that reconnects in time finds its unsaved text.
+ */
+export interface DocumentReleaseScheduler {
+    /** How long a deferred release waits; `0` releases at once. */
+    readonly graceMs: number;
+    /** `clientId` closed `key` because its connection was lost. */
+    recordLoss(key: CanonicalUri, clientId: string): void;
+    /** No client holds `key` after a loss: run `release` once the grace has passed, or now when there is none. */
+    defer(key: CanonicalUri, release: () => void): void;
+    isDeferred(key: CanonicalUri): boolean;
+    /** `clientId` opens `key`; a deferred release ends either way. */
+    resolveOpen(key: CanonicalUri, clientId: string): DeferredReleaseOpenDecision;
+    /** End a deferred release of `key` without running it. */
+    cancel(key: CanonicalUri): void;
+    /** `key` was released: drop the losses recorded for it. */
+    clearLosses(key: CanonicalUri): void;
+}
+export declare class DefaultDocumentReleaseScheduler implements DocumentReleaseScheduler {
+    protected readonly clock: Clock;
+    readonly graceMs: number;
+    protected readonly deferred: Map<CanonicalUri, Disposable>;
+    /**
+     * Per document, the clients whose close of it was caused by a lost
+     * connection and that have not opened it again, each with a stopwatch
+     * started at its loss. Every such client counts, not only the last to
+     * close: one connection's sessions all end lost together, and any of them
+     * may reopen first. A stopwatch rather than a `now()` reading, because a
+     * wall-clock step would otherwise expire a claim early or revive one past
+     * its grace, against a grace timer that the step leaves alone.
+     */
+    protected readonly lostClients: Map<CanonicalUri, Map<string, Stopwatch>>;
+    constructor(clock: Clock, graceMs: number);
+    recordLoss(key: CanonicalUri, clientId: string): void;
+    defer(key: CanonicalUri, release: () => void): void;
+    isDeferred(key: CanonicalUri): boolean;
+    /**
+     * A claim past its grace counts as any other client's: without the limit,
+     * a client that returns late inherits the unsaved text of a holder lost
+     * after it. Cancelling for every open instead hands a lost client's unsaved
+     * text to whoever opens next, with nothing marking it unsaved.
+     */
+    resolveOpen(key: CanonicalUri, clientId: string): DeferredReleaseOpenDecision;
+    cancel(key: CanonicalUri): void;
+    clearLosses(key: CanonicalUri): void;
+}
+//# sourceMappingURL=document-release-scheduler.d.ts.map

package/lib/documents/document-release-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-release-scheduler.d.ts","sourceRoot":"","sources":["../../src/documents/document-release-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,kIAAkI;AAClI,MAAM,MAAM,2BAA2B;AACpC,yFAAyF;AACvF,MAAM;AACR,wFAAwF;GACtF,SAAS;AACX,+BAA+B;GAC7B,MAAM,CAAC;AAEZ;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,8GAA8G;IAC9G,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACpD,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC;IACvC,kEAAkE;IAClE,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,2BAA2B,CAAC;IAC9E,0DAA0D;IAC1D,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,2DAA2D;IAC3D,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;CACvC;AAED,qBAAa,+BAAgC,YAAW,wBAAwB;IAc1E,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM;IAd3B,SAAS,CAAC,QAAQ,CAAC,QAAQ,gCAAuC;IAClE;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,4CAAmD;IAEjF,YACsB,KAAK,EAAE,KAAK,EACtB,OAAO,EAAE,MAAM,EACvB;IAEJ,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOpD;IAED,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAalD;IAED,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAErC;IAED;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,2BAA2B,CAgB5E;IAED,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAG9B;IAED,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEnC;CACH"}

package/lib/documents/document-release-scheduler.js

@@ -0,0 +1,80 @@
+/********************************************************************************
+ * Copyright (c) 2026 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
+ ********************************************************************************/
+export class DefaultDocumentReleaseScheduler {
+    clock;
+    graceMs;
+    deferred = new Map();
+    /**
+     * Per document, the clients whose close of it was caused by a lost
+     * connection and that have not opened it again, each with a stopwatch
+     * started at its loss. Every such client counts, not only the last to
+     * close: one connection's sessions all end lost together, and any of them
+     * may reopen first. A stopwatch rather than a `now()` reading, because a
+     * wall-clock step would otherwise expire a claim early or revive one past
+     * its grace, against a grace timer that the step leaves alone.
+     */
+    lostClients = new Map();
+    constructor(clock, graceMs) {
+        this.clock = clock;
+        this.graceMs = graceMs;
+    }
+    recordLoss(key, clientId) {
+        let lost = this.lostClients.get(key);
+        if (!lost) {
+            lost = new Map();
+            this.lostClients.set(key, lost);
+        }
+        lost.set(clientId, this.clock.stopwatch());
+    }
+    defer(key, release) {
+        this.cancel(key);
+        if (this.graceMs <= 0) {
+            release();
+            return;
+        }
+        this.deferred.set(key, this.clock.setTimer(() => {
+            this.deferred.delete(key);
+            release();
+        }, this.graceMs));
+    }
+    isDeferred(key) {
+        return this.deferred.has(key);
+    }
+    /**
+     * A claim past its grace counts as any other client's: without the limit,
+     * a client that returns late inherits the unsaved text of a holder lost
+     * after it. Cancelling for every open instead hands a lost client's unsaved
+     * text to whoever opens next, with nothing marking it unsaved.
+     */
+    resolveOpen(key, clientId) {
+        const lost = this.lostClients.get(key);
+        for (const [lostId, sinceLoss] of lost ?? []) {
+            if (sinceLoss.elapsedMs >= this.graceMs) {
+                lost?.delete(lostId);
+            }
+        }
+        const returning = lost?.delete(clientId) ?? false;
+        if (lost?.size === 0) {
+            this.lostClients.delete(key);
+        }
+        if (!this.deferred.has(key)) {
+            return 'none';
+        }
+        this.cancel(key);
+        return returning ? 'keep' : 'release';
+    }
+    cancel(key) {
+        this.deferred.get(key)?.dispose();
+        this.deferred.delete(key);
+    }
+    clearLosses(key) {
+        this.lostClients.delete(key);
+    }
+}
+//# sourceMappingURL=document-release-scheduler.js.map

package/lib/documents/document-release-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-release-scheduler.js","sourceRoot":"","sources":["../../src/documents/document-release-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAmClF,MAAM,OAAO,+BAA+B;IAcnB,KAAK;IACf,OAAO;IAdA,QAAQ,GAAG,IAAI,GAAG,EAA4B,CAAC;IAClE;;;;;;;;OAQG;IACgB,WAAW,GAAG,IAAI,GAAG,EAAwC,CAAC;IAEjF,YACsB,KAAY,EACtB,OAAe;qBADL,KAAK;uBACf,OAAO;IAChB,CAAC;IAEJ,UAAU,CAAC,GAAiB,EAAE,QAAgB;QAC3C,IAAI,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,EAAE,CAAC;YACT,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;YACjB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,GAAiB,EAAE,OAAmB;QACzC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjB,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,EAAE,CAAC;YACrB,OAAO,EAAE,CAAC;YACV,OAAO;QACV,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CACd,GAAG,EACH,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE;YACtB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,OAAO,EAAE,CAAC;QACb,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAClB,CAAC;IACL,CAAC;IAED,UAAU,CAAC,GAAiB;QACzB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,GAAiB,EAAE,QAAgB;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,KAAK,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;YAC5C,IAAI,SAAS,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACvC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC;QACJ,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC;QAClD,IAAI,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,CAAC;YACpB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjB,OAAO,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACzC,CAAC;IAED,MAAM,CAAC,GAAiB;QACrB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;QAClC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,WAAW,CAAC,GAAiB;QAC1B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;CACH"}