@hydranium/core 1.0.0-next.35 → 1.0.0-next.351

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

@@ -0,0 +1,204 @@
+/********************************************************************************
+ * 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 the store last knew a file behind the document: `false` for one
+     * created from a session's text and never saved, or whose file a reload
+     * found gone; any other open counts as on disk. Unlike the queries, a
+     * snapshot taken at the release, since the store forgets it there.
+     */
+    readonly wasOnDisk: boolean;
+    /** 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`, `redecideRelease` or `applyReleaseDecision` to change the
+ * policy and keep the locking and the wait for the build.
+ *
+ * The provider decides, for every scheme, by `exists`, with a miss confirmed
+ * by `existsSettled`: 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 and the provider
+ * confirms it gone.
+ *
+ * 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. A rebuild that finds no file is redecided by
+     * {@link redecideRelease} within the same lock section: the build has
+     * already reset the document, so a build let in meanwhile would read the
+     * missing file and fail. Its answer is carried out unless a client
+     * reclaimed the document meanwhile. 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. A miss is settled outside
+     * the queue, so waiting it out holds up no write to the file, and only for
+     * a document the store knew on disk: one with no file has none to replace.
+     */
+    protected decideRelease(released: ReleasedDocument, target: URI): Promise<DocumentReleaseDecision>;
+    /**
+     * The policy for a rebuild that found no file, the `misses`-th of this
+     * release: what to carry out instead. Runs inside the release's write, so
+     * every build waits on it. The default settles the first miss through the
+     * provider's `existsSettled`, rebuilding again when the file is back, and
+     * removes the document on any later one. An override answering `rebuild`
+     * on every miss rebuilds for as long as the file stays missing.
+     */
+    protected redecideRelease(_released: ReleasedDocument, target: URI, misses: number): Promise<DocumentReleaseDecision>;
+    /**
+     * Carry `decision` out under the write lock. A rebuild that finds no file
+     * rejects with that error, and {@link redecideRelease} answers what to
+     * carry out 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; rejects with its error when it was given up. */
+    protected requestRecoveryBuild(released: ReleasedDocument, target: URI, deleted: boolean): Promise<void>;
+    /**
+     * 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":"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"}

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

@@ -0,0 +1,317 @@
+/********************************************************************************
+ * 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 { describeError, describeErrorWithStack } from '@hydranium/protocol';
+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. ${describeError(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`, `redecideRelease` or `applyReleaseDecision` to change the
+ * policy and keep the locking and the wait for the build.
+ *
+ * The provider decides, for every scheme, by `exists`, with a miss confirmed
+ * by `existsSettled`: 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 and the provider
+ * confirms it gone.
+ *
+ * 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: ${describeError(error)}`);
+            return;
+        }
+        if (outcome.kind === 'failed') {
+            // Handled below, by a recovery build or the client holding the document again; one that fails rejects on its own.
+            const { error } = outcome;
+            this.tracer.with(released.uri).warn(`Revert on release failed; building in its place. ${describeErrorWithStack(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 () => {
+            try {
+                await this.requestRecoveryBuild(released, target, 'decision' in outcome && outcome.decision === 'remove');
+            }
+            catch (err) {
+                throw new Error(`Build after a revert that stopped short failed; the build keeps the released text. ${describeError(err)}`, {
+                    cause: err
+                });
+            }
+        };
+        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. A rebuild that finds no file is redecided by
+     * {@link redecideRelease} within the same lock section: the build has
+     * already reset the document, so a build let in meanwhile would read the
+     * missing file and fail. Its answer is carried out unless a client
+     * reclaimed the document meanwhile. 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';
+                let applied = decided;
+                for (let misses = 1;; misses++) {
+                    try {
+                        await this.applyReleaseDecision(target, applied, token);
+                        break;
+                    }
+                    catch (err) {
+                        if (applied !== 'rebuild' || !isFileNotFound(err, target)) {
+                            throw err;
+                        }
+                        applied = await this.redecideRelease(released, target, misses);
+                        if (released.isReclaimed()) {
+                            progress = 'reclaimed';
+                            return;
+                        }
+                        decision = applied;
+                        this.tracer
+                            .with(released.uri)
+                            .debug(`Revert found no file; ${applied === 'rebuild' ? 'rebuilding again' : 'removing the document instead'}`);
+                    }
+                }
+                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 };
+            }
+            if (progress === 'building') {
+                return { kind: 'cancelled', decision, parsed };
+            }
+            return { kind: 'completed', decision, 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. A miss is settled outside
+     * the queue, so waiting it out holds up no write to the file, and only for
+     * a document the store knew on disk: one with no file has none to replace.
+     */
+    async decideRelease(released, target) {
+        const workspace = this.services.workspace;
+        const fileSystem = workspace.FileSystemProvider;
+        const served = await workspace.FileSystemTaskQueue.enqueue(released.uri, () => fileSystem.exists(target));
+        if (served || !released.wasOnDisk) {
+            return served ? 'rebuild' : 'remove';
+        }
+        return ((await fileSystem.existsSettled?.(target)) ?? false) ? 'rebuild' : 'remove';
+    }
+    /**
+     * The policy for a rebuild that found no file, the `misses`-th of this
+     * release: what to carry out instead. Runs inside the release's write, so
+     * every build waits on it. The default settles the first miss through the
+     * provider's `existsSettled`, rebuilding again when the file is back, and
+     * removes the document on any later one. An override answering `rebuild`
+     * on every miss rebuilds for as long as the file stays missing.
+     */
+    async redecideRelease(_released, target, misses) {
+        if (misses > 1) {
+            return 'remove';
+        }
+        const fileSystem = this.services.workspace.FileSystemProvider;
+        return (await (fileSystem.existsSettled?.(target) ?? fileSystem.exists(target))) ? 'rebuild' : 'remove';
+    }
+    /**
+     * Carry `decision` out under the write lock. A rebuild that finds no file
+     * rejects with that error, and {@link redecideRelease} answers what to
+     * carry out 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);
+        await (decision === 'rebuild' ? builder.update([target], [], token) : builder.update([], [target], token));
+    }
+    /** The build in place of a release that stopped short; rejects with its error when it was given up. */
+    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()) {
+            // The release got what it waits for, so a failed recovery build is diagnosis; its retry warned.
+            startRecovery?.().catch((err) => this.tracer.with(released.uri).debug(describeErrorWithStack(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 or removal that came first, so diagnosis; its retry warned.
+                if (ended) {
+                    this.tracer.with(released.uri).debug(describeErrorWithStack(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"}