@hydranium/core 1.0.0-next.18 → 1.0.0-next.180

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

@@ -0,0 +1,138 @@
+/********************************************************************************
+ * 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 { type Disposable, 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;
+}
+/**
+ * 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 revert 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>>;
+    protected readonly reservedIds: ReadonlySet<string>;
+    protected readonly sessionClosedEmitter: Emitter<ClientSessionClosedEvent>;
+    /**
+     * The documents whose last open closed with a lost connection and whose
+     * revert is deferred, each with the timer that runs it. Any open of such a
+     * document cancels its timer; the store decides whether the opener keeps the
+     * unsaved text.
+     */
+    protected readonly pendingReverts: Map<CanonicalUri, Disposable>;
+    /** 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 and announce it. A no-op for an id that is not registered. */
+    unregister(clientId: string): 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;
+    /** Record that `clientId` closed `uri`. Returns `false` when it did not have it open. */
+    removeOpen(uri: CanonicalUri, clientId: string): boolean;
+    /** 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[];
+    }>;
+    /** Record `timer` as the deferred revert of `uri`. */
+    deferRevert(uri: CanonicalUri, timer: Disposable): void;
+    /** Whether the revert of `uri` is deferred. */
+    isRevertPending(uri: CanonicalUri): boolean;
+    /** Cancel the deferred revert of `uri`, if one is pending. */
+    cancelRevert(uri: CanonicalUri): void;
+    /**
+     * Forget every session, open and deferred revert 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":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAwB,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,KAAK,UAAU,EAAE,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAI7E;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpD,oEAAoE;AACpE,MAAM,WAAW,wBAAwB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAmD,CAAC;AAErG;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,qBAAqB;IAC/B,SAAS,CAAC,QAAQ,CAAC,QAAQ,kCAAyC;IACpE,SAAS,CAAC,QAAQ,CAAC,YAAY,iCAAwC;IACvE,SAAS,CAAC,QAAQ,CAAC,aAAa,iCAAwC;IACxE,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAgC;IACnF,SAAS,CAAC,QAAQ,CAAC,oBAAoB,oCAA2C;IAClF;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,gCAAuC;IAExE,wFAAwF;IACxF,IAAI,iBAAiB,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAEvD;IAED;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ/B;IAED,mEAAmE;IACnE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEtC;IAED;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CAK3C;IAED,0GAA0G;IAC1G,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKjC;IAED;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAoBpD;IAED,yFAAyF;IACzF,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAcvD;IAED,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAErD;IAED,yCAAyC;IACzC,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAEjC;IAED,qEAAqE;IACrE,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,EAAE,CAErC;IAED,iEAAiE;IACjE,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CAExC;IAED,sFAAsF;IACtF,aAAa,IAAI,KAAK,CAAC;QAAE,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAEjF;IAED,sDAAsD;IACtD,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAEtD;IAED,+CAA+C;IAC/C,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAE1C;IAED,8DAA8D;IAC9D,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAGpC;IAED;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAQZ;CACH"}

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

@@ -0,0 +1,187 @@
+/********************************************************************************
+ * 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();
+    reservedIds = new Set(RESERVED_CLIENT_IDS);
+    sessionClosedEmitter = new Emitter();
+    /**
+     * The documents whose last open closed with a lost connection and whose
+     * revert is deferred, each with the timer that runs it. Any open of such a
+     * document cancels its timer; the store decides whether the opener keeps the
+     * unsaved text.
+     */
+    pendingReverts = new Map();
+    /** 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 and announce it. A no-op for an id that is not registered. */
+    unregister(clientId) {
+        if (!this.sessions.delete(clientId)) {
+            return;
+        }
+        this.sessionClosedEmitter.fire(Object.freeze({ clientId }));
+    }
+    /**
+     * 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) {
+        if (this.sessions.get(clientId) === 'closing') {
+            throw new SessionClosedError(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;
+    }
+    /** 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);
+        }
+        return true;
+    }
+    /** 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] }));
+    }
+    /** Record `timer` as the deferred revert of `uri`. */
+    deferRevert(uri, timer) {
+        this.pendingReverts.set(uri, timer);
+    }
+    /** Whether the revert of `uri` is deferred. */
+    isRevertPending(uri) {
+        return this.pendingReverts.has(uri);
+    }
+    /** Cancel the deferred revert of `uri`, if one is pending. */
+    cancelRevert(uri) {
+        this.pendingReverts.get(uri)?.dispose();
+        this.pendingReverts.delete(uri);
+    }
+    /**
+     * Forget every session, open and deferred revert 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();
+        for (const timer of this.pendingReverts.values()) {
+            timer.dispose();
+        }
+        this.pendingReverts.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/file-system-task-queue.d.ts

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * 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 { type ServerSharedServices } from '../langium/module.js';
+import { type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
+/**
+ * One queue of file-system tasks per file, shared by every server-side reader
+ * and writer of a file whose accesses must not interleave with its saves.
+ *
+ * Two writes of one file that bypass the queue can land in either order, and
+ * the older text then stays on disk. Tasks of different files run in
+ * parallel.
+ */
+export interface FileSystemTaskQueue {
+    /**
+     * Run `task` once every task already enqueued for `uri` has settled, and
+     * before any enqueued after it. `uri` is keyed by its canonical identity, so
+     * every spelling of one file shares a queue. A task that has nothing to do
+     * still resolves once the tasks before it have settled.
+     *
+     * A task must not await a build, nor a save, another task or an open of a
+     * document no client has open, all of the same file: a build's integrity
+     * repair enqueues its own write and the build waits for it, and such an
+     * open reads the file here, so a task waiting on either never resolves,
+     * which wedges the file's queue for good.
+     */
+    enqueue<T>(uri: string, task: () => Promise<T>): Promise<T>;
+}
+export declare class DefaultFileSystemTaskQueue implements FileSystemTaskQueue {
+    /**
+     * Per canonical URI, the settling of the last task enqueued for it; the next
+     * task chains behind it. An entry leaves once its file's queue is idle. Kept
+     * outside the workspace lock, whose `write` cancels the write before it: a
+     * save cancelled that way reports success for text it never wrote.
+     */
+    protected readonly queues: Map<CanonicalUri, Promise<void>>;
+    protected readonly uriPolicy: DocumentUriPolicy;
+    constructor(services: {
+        readonly workspace: Pick<ServerSharedServices['workspace'], 'DocumentUriPolicy'>;
+    });
+    enqueue<T>(uri: string, task: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=file-system-task-queue.d.ts.map

package/lib/documents/file-system-task-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-system-task-queue.d.ts","sourceRoot":"","sources":["../../src/documents/file-system-task-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IACjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9D;AAED,qBAAa,0BAA2B,YAAW,mBAAmB;IACnE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,mCAA0C;IAEnE,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEhD,YAAY,QAAQ,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,oBAAoB,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC,CAAA;KAAE,EAEzG;IAED,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAc1D;CACH"}

package/lib/documents/file-system-task-queue.js

@@ -0,0 +1,34 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export class DefaultFileSystemTaskQueue {
+    /**
+     * Per canonical URI, the settling of the last task enqueued for it; the next
+     * task chains behind it. An entry leaves once its file's queue is idle. Kept
+     * outside the workspace lock, whose `write` cancels the write before it: a
+     * save cancelled that way reports success for text it never wrote.
+     */
+    queues = new Map();
+    uriPolicy;
+    constructor(services) {
+        this.uriPolicy = services.workspace.DocumentUriPolicy;
+    }
+    enqueue(uri, task) {
+        const key = this.uriPolicy.canonicalUri(uri);
+        const result = (this.queues.get(key) ?? Promise.resolve()).then(task);
+        const settled = result.then(() => undefined, () => undefined);
+        this.queues.set(key, settled);
+        void settled.then(() => {
+            if (this.queues.get(key) === settled) {
+                this.queues.delete(key);
+            }
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=file-system-task-queue.js.map

package/lib/documents/file-system-task-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-system-task-queue.js","sourceRoot":"","sources":["../../src/documents/file-system-task-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AA8BlF,MAAM,OAAO,0BAA0B;IACpC;;;;;OAKG;IACgB,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEhD,SAAS,CAAoB;IAEhD,YAAY,QAA8F;QACvG,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,iBAAiB,CAAC;IACzD,CAAC;IAED,OAAO,CAAI,GAAW,EAAE,IAAsB;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CACxB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CACjB,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC9B,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE;YACpB,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC;gBACpC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IACjB,CAAC;CACH"}