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

package/lib/documents/client-session-registry.d.ts

@@ -0,0 +1,146 @@
+/********************************************************************************
+ * 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 { type CanonicalUri } from '@hydranium/protocol';
+import { Emitter, type Event } from 'vscode-languageserver';
+/**
+ * What a client session states about one of its opens, kept by the session
+ * and readable only while that open lasts.
+ *
+ * Any object type: an adopter declares the fields its own open path reads and
+ * passes that type as a session's `TOpenOptions`. Kept per open rather than
+ * per document, so two sessions opening one document with different options
+ * each keep their own.
+ */
+export type OpenOptions = object;
+/**
+ * A session is `'live'` from its registration, which is synchronous, so no
+ * state comes before it. `'closing'` covers the span in which the session's
+ * opens are being closed: the id is still taken, and the session can open
+ * nothing more, so an open issued from a close listener cannot outlive the
+ * session that made it. An id with no state has no session: it was never
+ * registered, or has closed.
+ */
+export type ClientSessionState = 'live' | 'closing';
+/** Delivered by {@link ClientSessionRegistry.onDidCloseSession}. */
+export interface ClientSessionClosedEvent {
+    readonly clientId: string;
+    readonly cause: SessionEndCause;
+}
+/**
+ * Why a close happened. `'lost'` is a close caused by the client's connection
+ * going away rather than by the client, and only such a last close waits out
+ * the store's release grace: a client that closed or ended on purpose has
+ * discarded its unsaved edits, while one that lost its connection may be about
+ * to register again and open the document once more.
+ */
+export type SessionEndCause = 'closed' | 'lost';
+/**
+ * The ids no client session may be started under: the wire's well-known ids and
+ * the integrity author. Each names a framework participant rather than a
+ * client, and a session holding one would have its writes read as that
+ * participant's.
+ */
+export declare const RESERVED_CLIENT_IDS: readonly string[];
+/**
+ * Which client has which document open, and which client ids are registered
+ * sessions — the open facts every head shares, composed by
+ * `HydraniumTextDocuments`.
+ *
+ * Opens are recorded for every client id, registered or not. The language
+ * client opens under its reserved id without a session, over the LSP
+ * connection, and its opens are tracked exactly as a session's are; only the
+ * session table ignores it. Requiring registration before an open would refuse
+ * the editor.
+ *
+ * One open per `(client, uri)`, with no reference count: a repeat open changes
+ * nothing, and one close ends it.
+ *
+ * Pure bookkeeping. Closing a document is the store's job, because a close has
+ * to reach the text store and its listeners; the store asks this class what to
+ * close and records each close here.
+ */
+export declare class ClientSessionRegistry {
+    protected readonly sessions: Map<string, ClientSessionState>;
+    protected readonly clientsByUri: Map<CanonicalUri, Set<string>>;
+    protected readonly opensByClient: Map<string, Set<CanonicalUri>>;
+    /**
+     * Per document, the newest version id each client declared for its own
+     * buffer: the baseline of the store's per-client staleness guard. A
+     * client's goes when it closes the document, every one when the store
+     * releases it.
+     */
+    protected readonly clientVersions: Map<CanonicalUri, Map<string, number>>;
+    protected readonly reservedIds: ReadonlySet<string>;
+    protected readonly sessionClosedEmitter: Emitter<ClientSessionClosedEvent>;
+    /** Fires once a session has been removed from the table, after all its opens closed. */
+    get onDidCloseSession(): Event<ClientSessionClosedEvent>;
+    /**
+     * Enter `clientId` in the session table.
+     *
+     * Throws {@link ReservedClientIdError} for a reserved id, and
+     * {@link DuplicateClientIdError} when the id is live anywhere in the
+     * process: registered (including by a session that is still closing), or
+     * holding opens as a client that is not a session. The last matters because
+     * the id is the author label and the echo key, and a session sharing one
+     * with another client would take that client's writes for its own.
+     */
+    register(clientId: string): void;
+    /** Whether `clientId` is in the session table, live or closing. */
+    isRegistered(clientId: string): boolean;
+    /**
+     * Mark `clientId` as closing and return every URI it has open, as a copy the
+     * caller can close while this registry changes underneath it.
+     */
+    beginClose(clientId: string): CanonicalUri[];
+    /**
+     * Remove `clientId` from the session table, with every client version it
+     * declared, and announce it with `cause`. A no-op for an id that is not
+     * registered. The versions go too: a client registered again under the same
+     * id counts its versions afresh.
+     */
+    unregister(clientId: string, cause?: SessionEndCause): void;
+    /**
+     * Record that `clientId` opened `uri`. Returns `false` when
+     * it already had it open, in which case nothing changes.
+     *
+     * Throws {@link SessionClosedError} for a session that is closing.
+     */
+    addOpen(uri: CanonicalUri, clientId: string): boolean;
+    /** Throws {@link SessionClosedError} when `clientId` is a session that is closing, and so can open nothing more. */
+    assertCanOpen(clientId: string): void;
+    /** Record that `clientId` closed `uri`. Returns `false` when it did not have it open. */
+    removeOpen(uri: CanonicalUri, clientId: string): boolean;
+    /** Take `version` as the newest `clientId` declared for `uri`, whether or not it has `uri` open. */
+    setClientVersion(uri: CanonicalUri, clientId: string, version: number): void;
+    /** The newest version id `clientId` declared for `uri`. */
+    clientVersionOf(uri: CanonicalUri, clientId: string): number | undefined;
+    /** Drop every client version of `uri`, for a document the store released. */
+    forgetClientVersions(uri: CanonicalUri): void;
+    /** Whether `clientId` has `uri` open. */
+    isOpenIn(uri: CanonicalUri, clientId: string): boolean;
+    /** Whether any client has `uri` open. */
+    isOpen(uri: CanonicalUri): boolean;
+    /** The clients that have `uri` open, in the order they opened it. */
+    clientsOf(uri: CanonicalUri): string[];
+    /** The URIs `clientId` has open, in the order it opened them. */
+    opensOf(clientId: string): CanonicalUri[];
+    /** Every document open in at least one client, with the clients that have it open. */
+    openDocuments(): Array<{
+        readonly uri: CanonicalUri;
+        readonly clients: string[];
+    }>;
+    /**
+     * Forget every session and open without announcing
+     * anything, for a test double that resets between tests. Subscriptions
+     * stay, so a listener registered before the clear hears the sessions that
+     * end after it.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=client-session-registry.d.ts.map

package/lib/documents/client-session-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-session-registry.d.ts","sourceRoot":"","sources":["../../src/documents/client-session-registry.ts"],"names":[],"mappings":"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"}

package/lib/documents/client-session-registry.js

@@ -0,0 +1,207 @@
+/********************************************************************************
+ * 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 { FRAMEWORK_CLIENT_IDS } from '@hydranium/protocol';
+import { Emitter } from 'vscode-languageserver';
+import { INTEGRITY_CLIENT_ID } from '../langium/integrity/integrity-rule.js';
+import { DuplicateClientIdError, ReservedClientIdError, SessionClosedError } from './client-session-errors.js';
+/**
+ * The ids no client session may be started under: the wire's well-known ids and
+ * the integrity author. Each names a framework participant rather than a
+ * client, and a session holding one would have its writes read as that
+ * participant's.
+ */
+export const RESERVED_CLIENT_IDS = [...FRAMEWORK_CLIENT_IDS, INTEGRITY_CLIENT_ID];
+/**
+ * Which client has which document open, and which client ids are registered
+ * sessions — the open facts every head shares, composed by
+ * `HydraniumTextDocuments`.
+ *
+ * Opens are recorded for every client id, registered or not. The language
+ * client opens under its reserved id without a session, over the LSP
+ * connection, and its opens are tracked exactly as a session's are; only the
+ * session table ignores it. Requiring registration before an open would refuse
+ * the editor.
+ *
+ * One open per `(client, uri)`, with no reference count: a repeat open changes
+ * nothing, and one close ends it.
+ *
+ * Pure bookkeeping. Closing a document is the store's job, because a close has
+ * to reach the text store and its listeners; the store asks this class what to
+ * close and records each close here.
+ */
+export class ClientSessionRegistry {
+    sessions = new Map();
+    clientsByUri = new Map();
+    opensByClient = new Map();
+    /**
+     * Per document, the newest version id each client declared for its own
+     * buffer: the baseline of the store's per-client staleness guard. A
+     * client's goes when it closes the document, every one when the store
+     * releases it.
+     */
+    clientVersions = new Map();
+    reservedIds = new Set(RESERVED_CLIENT_IDS);
+    sessionClosedEmitter = new Emitter();
+    /** Fires once a session has been removed from the table, after all its opens closed. */
+    get onDidCloseSession() {
+        return this.sessionClosedEmitter.event;
+    }
+    /**
+     * Enter `clientId` in the session table.
+     *
+     * Throws {@link ReservedClientIdError} for a reserved id, and
+     * {@link DuplicateClientIdError} when the id is live anywhere in the
+     * process: registered (including by a session that is still closing), or
+     * holding opens as a client that is not a session. The last matters because
+     * the id is the author label and the echo key, and a session sharing one
+     * with another client would take that client's writes for its own.
+     */
+    register(clientId) {
+        if (this.reservedIds.has(clientId)) {
+            throw new ReservedClientIdError(clientId);
+        }
+        if (this.sessions.has(clientId) || this.opensByClient.has(clientId)) {
+            throw new DuplicateClientIdError(clientId);
+        }
+        this.sessions.set(clientId, 'live');
+    }
+    /** Whether `clientId` is in the session table, live or closing. */
+    isRegistered(clientId) {
+        return this.sessions.has(clientId);
+    }
+    /**
+     * Mark `clientId` as closing and return every URI it has open, as a copy the
+     * caller can close while this registry changes underneath it.
+     */
+    beginClose(clientId) {
+        if (this.sessions.has(clientId)) {
+            this.sessions.set(clientId, 'closing');
+        }
+        return this.opensOf(clientId);
+    }
+    /**
+     * Remove `clientId` from the session table, with every client version it
+     * declared, and announce it with `cause`. A no-op for an id that is not
+     * registered. The versions go too: a client registered again under the same
+     * id counts its versions afresh.
+     */
+    unregister(clientId, cause = 'closed') {
+        if (!this.sessions.delete(clientId)) {
+            return;
+        }
+        for (const [uri, versions] of this.clientVersions) {
+            if (versions.delete(clientId) && versions.size === 0) {
+                this.clientVersions.delete(uri);
+            }
+        }
+        this.sessionClosedEmitter.fire(Object.freeze({ clientId, cause }));
+    }
+    /**
+     * Record that `clientId` opened `uri`. Returns `false` when
+     * it already had it open, in which case nothing changes.
+     *
+     * Throws {@link SessionClosedError} for a session that is closing.
+     */
+    addOpen(uri, clientId) {
+        this.assertCanOpen(clientId);
+        let opens = this.opensByClient.get(clientId);
+        if (opens?.has(uri)) {
+            return false;
+        }
+        if (!opens) {
+            opens = new Set();
+            this.opensByClient.set(clientId, opens);
+        }
+        opens.add(uri);
+        let clients = this.clientsByUri.get(uri);
+        if (!clients) {
+            clients = new Set();
+            this.clientsByUri.set(uri, clients);
+        }
+        clients.add(clientId);
+        return true;
+    }
+    /** Throws {@link SessionClosedError} when `clientId` is a session that is closing, and so can open nothing more. */
+    assertCanOpen(clientId) {
+        if (this.sessions.get(clientId) === 'closing') {
+            throw new SessionClosedError(clientId);
+        }
+    }
+    /** Record that `clientId` closed `uri`. Returns `false` when it did not have it open. */
+    removeOpen(uri, clientId) {
+        const opens = this.opensByClient.get(clientId);
+        if (!opens?.delete(uri)) {
+            return false;
+        }
+        if (opens.size === 0) {
+            this.opensByClient.delete(clientId);
+        }
+        const clients = this.clientsByUri.get(uri);
+        clients?.delete(clientId);
+        if (!clients?.size) {
+            this.clientsByUri.delete(uri);
+        }
+        const versions = this.clientVersions.get(uri);
+        versions?.delete(clientId);
+        if (!versions?.size) {
+            this.clientVersions.delete(uri);
+        }
+        return true;
+    }
+    /** Take `version` as the newest `clientId` declared for `uri`, whether or not it has `uri` open. */
+    setClientVersion(uri, clientId, version) {
+        let versions = this.clientVersions.get(uri);
+        if (!versions) {
+            versions = new Map();
+            this.clientVersions.set(uri, versions);
+        }
+        versions.set(clientId, version);
+    }
+    /** The newest version id `clientId` declared for `uri`. */
+    clientVersionOf(uri, clientId) {
+        return this.clientVersions.get(uri)?.get(clientId);
+    }
+    /** Drop every client version of `uri`, for a document the store released. */
+    forgetClientVersions(uri) {
+        this.clientVersions.delete(uri);
+    }
+    /** Whether `clientId` has `uri` open. */
+    isOpenIn(uri, clientId) {
+        return !!this.clientsByUri.get(uri)?.has(clientId);
+    }
+    /** Whether any client has `uri` open. */
+    isOpen(uri) {
+        return this.clientsByUri.has(uri);
+    }
+    /** The clients that have `uri` open, in the order they opened it. */
+    clientsOf(uri) {
+        return [...(this.clientsByUri.get(uri) ?? [])];
+    }
+    /** The URIs `clientId` has open, in the order it opened them. */
+    opensOf(clientId) {
+        return [...(this.opensByClient.get(clientId) ?? [])];
+    }
+    /** Every document open in at least one client, with the clients that have it open. */
+    openDocuments() {
+        return [...this.clientsByUri].map(([uri, clients]) => ({ uri, clients: [...clients] }));
+    }
+    /**
+     * Forget every session and open without announcing
+     * anything, for a test double that resets between tests. Subscriptions
+     * stay, so a listener registered before the clear hears the sessions that
+     * end after it.
+     */
+    clear() {
+        this.sessions.clear();
+        this.clientsByUri.clear();
+        this.opensByClient.clear();
+        this.clientVersions.clear();
+    }
+}
+//# sourceMappingURL=client-session-registry.js.map

package/lib/documents/client-session-registry.js.map

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

package/lib/documents/dirty-state-tracker.d.ts

@@ -0,0 +1,79 @@
+/********************************************************************************
+ * 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 TextState } from '@hydranium/protocol';
+import { Emitter, type Event } from 'vscode-languageserver';
+import { type TextDocument } from 'vscode-languageserver-textdocument';
+import { type TextLedger } from './text-ledger.js';
+/** Delivered by the store's `onDidChangeDirty`, which forwards {@link DirtyStateTracker.onDidChangeDirty}. */
+export interface DocumentDirtyChangedEvent {
+    readonly uri: CanonicalUri;
+    /**
+     * The text the new answer of {@link DirtyStateTracker.isDirty} was decided
+     * on. The answer changes with the text, before any build, so it can name
+     * text whose model has not been sent yet. Absent when the document no longer
+     * exists, or when the build that follows its release failed.
+     */
+    readonly text?: TextState;
+}
+/**
+ * Owed by a document released dirty: the announcement that it is clean. A
+ * first open before it is made takes it over, and each release owes one of its
+ * own, so announcing for an earlier release cannot announce a later one clean.
+ */
+export interface CleanAnnouncement {
+    /** Whether it is still owed: neither made nor taken over. */
+    isOwed(): boolean;
+    /** Make it, naming `text`; a no-op once it is no longer owed. */
+    announce(text?: TextState): void;
+}
+/**
+ * Whether each tracked document differs from its disk baseline: what the
+ * server last knew the file to hold. The store reports every change of its
+ * text and of the baseline; this decides the answer and announces it when it
+ * changes.
+ */
+export interface DirtyStateTracker {
+    readonly onDidChangeDirty: Event<DocumentDirtyChangedEvent>;
+    /** `false` for a document not tracked. */
+    isDirty(key: CanonicalUri): boolean;
+    /**
+     * Track `key` from its first open, holding `document`, while its file
+     * holds `diskText`. Takes over the clean announcement a release still owes, so its
+     * own answer decides the flip.
+     */
+    track(key: CanonicalUri, document: TextDocument, diskText: string | undefined): void;
+    /** The text of `key` is now `document`'s. A no-op for a document not tracked. */
+    refreshDirty(key: CanonicalUri, document: TextDocument): void;
+    /** The file behind `key` holds `text`, `undefined` for none. A no-op for a document not tracked. */
+    setDiskBaseline(key: CanonicalUri, document: TextDocument, text: string | undefined): void;
+    /**
+     * The store released `key`. Answers the clean announcement a document
+     * released dirty now owes; `undefined` for one released clean.
+     */
+    release(key: CanonicalUri): CleanAnnouncement | undefined;
+}
+export declare class DefaultDirtyStateTracker implements DirtyStateTracker {
+    protected readonly textLedger: TextLedger;
+    protected readonly states: Map<CanonicalUri, {
+        baseline: string | undefined;
+        dirty: boolean;
+    }>;
+    /** Per document released dirty, the token of the announcement it owes. */
+    protected readonly owedClean: Map<CanonicalUri, object>;
+    protected readonly dirtyChangedEmitter: Emitter<DocumentDirtyChangedEvent>;
+    /** @param textLedger hashes the text an announcement names. */
+    constructor(textLedger: TextLedger);
+    get onDidChangeDirty(): Event<DocumentDirtyChangedEvent>;
+    isDirty(key: CanonicalUri): boolean;
+    track(key: CanonicalUri, document: TextDocument, diskText: string | undefined): void;
+    refreshDirty(key: CanonicalUri, document: TextDocument): void;
+    setDiskBaseline(key: CanonicalUri, document: TextDocument, text: string | undefined): void;
+    release(key: CanonicalUri): CleanAnnouncement | undefined;
+}
+//# sourceMappingURL=dirty-state-tracker.d.ts.map

package/lib/documents/dirty-state-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty-state-tracker.d.ts","sourceRoot":"","sources":["../../src/documents/dirty-state-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,8GAA8G;AAC9G,MAAM,WAAW,yBAAyB;IACvC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC/B,6DAA6D;IAC7D,MAAM,IAAI,OAAO,CAAC;IAClB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC5D,0CAA0C;IAC1C,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC;IACpC;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IACrF,iFAAiF;IACjF,YAAY,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9D,oGAAoG;IACpG,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAC3F;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,iBAAiB,GAAG,SAAS,CAAC;CAC5D;AAED,qBAAa,wBAAyB,YAAW,iBAAiB;IAOnD,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU;IANrD,SAAS,CAAC,QAAQ,CAAC,MAAM;kBAAqC,MAAM,GAAG,SAAS;eAAS,OAAO;OAAM;IACtG,0EAA0E;IAC1E,SAAS,CAAC,QAAQ,CAAC,SAAS,4BAAmC;IAC/D,SAAS,CAAC,QAAQ,CAAC,mBAAmB,qCAA4C;IAElF,+DAA+D;IAC/D,YAA+B,UAAU,EAAE,UAAU,EAAI;IAEzD,IAAI,gBAAgB,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAEvD;IAED,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAElC;IAED,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGnF;IAED,YAAY,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAY5D;IAED,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAOzF;IAED,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,iBAAiB,GAAG,SAAS,CAkBxD;CACH"}

package/lib/documents/dirty-state-tracker.js

@@ -0,0 +1,69 @@
+/********************************************************************************
+ * 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 { Emitter } from 'vscode-languageserver';
+export class DefaultDirtyStateTracker {
+    textLedger;
+    states = new Map();
+    /** Per document released dirty, the token of the announcement it owes. */
+    owedClean = new Map();
+    dirtyChangedEmitter = new Emitter();
+    /** @param textLedger hashes the text an announcement names. */
+    constructor(textLedger) {
+        this.textLedger = textLedger;
+    }
+    get onDidChangeDirty() {
+        return this.dirtyChangedEmitter.event;
+    }
+    isDirty(key) {
+        return this.states.get(key)?.dirty ?? false;
+    }
+    track(key, document, diskText) {
+        this.states.set(key, { baseline: diskText, dirty: this.owedClean.delete(key) });
+        this.refreshDirty(key, document);
+    }
+    refreshDirty(key, document) {
+        const state = this.states.get(key);
+        if (!state) {
+            return;
+        }
+        const dirty = document.getText() !== state.baseline;
+        if (dirty !== state.dirty) {
+            state.dirty = dirty;
+            this.dirtyChangedEmitter.fire(Object.freeze({ uri: key, text: { version: document.version, hash: this.textLedger.hashOf(document), dirty } }));
+        }
+    }
+    setDiskBaseline(key, document, text) {
+        const state = this.states.get(key);
+        if (!state) {
+            return;
+        }
+        state.baseline = text;
+        this.refreshDirty(key, document);
+    }
+    release(key) {
+        const dirty = this.states.get(key)?.dirty;
+        this.states.delete(key);
+        if (!dirty) {
+            return undefined;
+        }
+        const token = {};
+        this.owedClean.set(key, token);
+        const isOwed = () => this.owedClean.get(key) === token;
+        return {
+            isOwed,
+            announce: text => {
+                if (isOwed()) {
+                    this.owedClean.delete(key);
+                    this.dirtyChangedEmitter.fire(Object.freeze(text ? { uri: key, text } : { uri: key }));
+                }
+            }
+        };
+    }
+}
+//# sourceMappingURL=dirty-state-tracker.js.map

package/lib/documents/dirty-state-tracker.js.map

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