@hydranium/protocol 1.0.0-next.12 → 1.0.0-next.127

package/lib/data/data-protocol-methods.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-protocol-methods.js","sourceRoot":"","sources":["../../src/data/data-protocol-methods.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAalF,8DAA8D;AACjD,QAAA,gCAAgC,GAAG;IAC7C,mBAAmB;IACnB,oBAAoB;IACpB,kBAAkB;IAClB,qBAAqB;IACrB,mBAAmB;IACnB,oBAAoB;IACpB,sBAAsB;IACtB,cAAc;CACyE,CAAC;AAE3F,6DAA6D;AAChD,QAAA,+BAA+B,GAAG,CAAC,aAAa,EAAE,kBAAkB,CAEhF,CAAC;AAEF;;;;;GAKG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC;AAEvF;;;;;GAKG;AACU,QAAA,iCAAiC,GAAG;IAC9C,yBAAyB;IACzB,kBAAkB;IAClB,cAAc;CAC0E,CAAC;AAE5F,mEAAmE;AACtD,QAAA,gCAAgC,GAAG,CAAC,mBAAmB,EAAE,iBAAiB,CAEtF,CAAC;AAEF,kEAAkE;AACrD,QAAA,+BAA+B,GAAG,CAAC,mBAAmB,CAAwE,CAAC;AAE5I;;;;;;GAMG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC"}
+{"version":3,"file":"data-protocol-methods.js","sourceRoot":"","sources":["../../src/data/data-protocol-methods.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAalF,8DAA8D;AACjD,QAAA,gCAAgC,GAAG;IAC7C,eAAe;IACf,cAAc;IACd,qBAAqB;IACrB,sBAAsB;IACtB,mBAAmB;IACnB,oBAAoB;IACpB,kBAAkB;IAClB,qBAAqB;IACrB,mBAAmB;IACnB,oBAAoB;IACpB,sBAAsB;IACtB,cAAc;CACyE,CAAC;AAE3F,6DAA6D;AAChD,QAAA,+BAA+B,GAAG,CAAC,aAAa,EAAE,kBAAkB,CAEhF,CAAC;AAEF;;;;;GAKG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC;AAEvF;;;;;GAKG;AACU,QAAA,iCAAiC,GAAG;IAC9C,yBAAyB;IACzB,kBAAkB;IAClB,cAAc;CAC0E,CAAC;AAE5F,mEAAmE;AACtD,QAAA,gCAAgC,GAAG;IAC7C,mBAAmB;IACnB,iBAAiB;IACjB,wBAAwB;IACxB,mBAAmB;IACnB,kBAAkB;CACqE,CAAC;AAE3F,kEAAkE;AACrD,QAAA,+BAA+B,GAAG,CAAC,mBAAmB,CAAwE,CAAC;AAE5I;;;;;;GAMG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC"}

package/lib/data/data-server-protocol.d.ts

@@ -12,8 +12,8 @@ import type { Project } from '../project';
 import type { TransferDocument } from '../transfer-document';
 import type { CloseModelArgs, FindNextNameArgs, OpenModelArgs, ReferenceContext, ReferenceRequest } from '../model-server';
 import type { ReferenceCandidate, ReferenceTarget } from '../model-service/reference-candidate';
-import type { ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from './events';
-import type { GetModelDocumentArgs, GetProjectForUriArgs, TransferSaveDocumentArgs, WatchModelDocumentArgs, TransferUpdateDocumentArgs } from './requests';
+import type { ProjectsChangedEvent, TransferDocumentDeletedEvent, TransferDocumentDirtyChangedEvent, TransferDocumentSavedEvent, TransferDocumentsBuiltEvent, TransferDocumentUpdatedEvent } from './events';
+import type { CloseSessionArgs, CreateModelDocumentArgs, CreateSessionArgs, GetModelDocumentArgs, GetProjectForUriArgs, TransferSaveDocumentArgs, WatchModelDocumentArgs, TransferUpdateDocumentArgs, TransferUpdateDocumentsArgs } from './requests';
 /**
  * Document-scoped slice of the data-server wire contract: the per-document
  * lifecycle (get / update / save), the per-`(uri, clientId)` watch
@@ -32,34 +32,69 @@ import type { GetModelDocumentArgs, GetProjectForUriArgs, TransferSaveDocumentAr
  */
 export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
     /**
-     * Open a document for an editor session and return its current state.
-     * Registers `(uri, clientId)` with the multi-client document manager
-     * (so concurrent editors share one built document) and returns the
-     * document at the server's configured target phase — the same shape
-     * {@link getModelDocument} returns, except that `version` is taken from
-     * the text-document store so the caller's first `baseVersion` write
-     * cannot self-conflict. Idempotent in registration terms: opening an
-     * already-open document refreshes the client registration. Note it does
-     * NOT avoid a rebuild — a second client attaching triggers
-     * `refreshContent`, which fires a change event, so mounting a form on a
-     * document already open in a text editor rebuilds it.
+     * Register `args.clientId` as a client session owned by this connection.
+     * Rejects with a `DuplicateClientIdError` code when the id is live anywhere
+     * in the server process or reserved by the framework.
      *
-     * The default `DataServer` impl delegates to `ModelService.open` then
-     * reads the built state. Pair with {@link watchModelDocument} to receive
-     * subsequent build-phase events (open returns a one-shot snapshot;
-     * later validation diagnostics arrive on the watch channel).
+     * A request carrying a registered id acts as that session: it writes only
+     * what the session has open, failing with a `DocumentNotOpenError` code
+     * otherwise, and opens nothing implicitly; its open reads the file and takes
+     * no `languageId`, `version` or `text` seed. The session ends with
+     * {@link closeSession} or when the connection closes, and either closes
+     * every document it has open.
+     *
+     * A registration carrying the `resumeToken` an earlier registration of the
+     * same id carried ends that session first, from any connection, so a client
+     * whose connection dropped can register again before the server notices.
+     */
+    createSession(args: CreateSessionArgs): Promise<void>;
+    /**
+     * End a session this connection registered: close every document it has
+     * open, drop its watches, and free its id. A no-op for an id this
+     * connection did not register.
+     */
+    closeSession(args: CloseSessionArgs): Promise<void>;
+    /**
+     * Create a document with `args.text`, open for the session, and return it
+     * as {@link openModelDocument} does. It reaches disk with the first save.
+     * Fails when the file exists or any client has the URI open, and with a
+     * `SessionClosedError` code when `args.clientId` is not a session
+     * registered on this connection.
+     */
+    createModelDocument(args: CreateModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    /**
+     * Write several documents the session has open, all or none: a conflict or
+     * a document not open fails the whole set before any text applies.
+     * Resolves to the documents in the order given. Only for a session
+     * registered on this connection.
+     */
+    updateModelDocuments(args: TransferUpdateDocumentsArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>[]>;
+    /**
+     * Open a document for the client session `clientId` and return its current
+     * state. `clientId` must be a session this connection registered with
+     * {@link createSession}; any other id fails with the closed-session code,
+     * as every document request here does. The document is read from disk
+     * unless a client has it open already, so the request carries no
+     * `languageId`, `version` or `text` seed. Returns the document at
+     * the server's configured target phase — the same shape
+     * {@link getModelDocument} returns, except that `version` is taken from the
+     * text-document store so the caller's first `basedOn` write cannot
+     * self-conflict. A repeat open changes nothing.
+     *
+     * Pair with {@link watchModelDocument} to receive subsequent build-phase
+     * events (open returns a one-shot snapshot; later validation diagnostics
+     * arrive on the watch channel).
      */
-    openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    openModelDocument(args: Pick<OpenModelArgs, 'uri' | 'clientId' | 'options'>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
     /**
-     * Close an editor session for `(uri, clientId)`. Counterpart to
-     * {@link openModelDocument}; the underlying document stays built until
-     * every registered client has closed. The default `DataServer` impl
-     * delegates to `ModelService.close` and ALSO releases any watch for the
-     * same `(uri, clientId)` (closing a session frees its own watch — a
-     * forgotten {@link unwatchModelDocument} would otherwise leak dispatch;
-     * the implicit unwatch is idempotent). `watchModelDocument` is NOT
-     * coupled the other way: opening does not force a watch, so a snapshot
-     * reader can open without streaming.
+     * Close the session's open of `uri`. Counterpart to
+     * {@link openModelDocument}; the document stays open until every client
+     * has closed it, and the last close reverts it to disk. The default
+     * `DataServer` impl ALSO releases any watch for the same
+     * `(uri, clientId)` (a forgotten {@link unwatchModelDocument} would
+     * otherwise leak dispatch; the implicit unwatch is idempotent).
+     * `watchModelDocument` is NOT coupled the other way: opening does not force
+     * a watch, so a snapshot reader can open without streaming.
      */
     closeModelDocument(args: CloseModelArgs): Promise<void>;
     /**
@@ -70,13 +105,14 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
      */
     getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
     /**
-     * Update a document's content. The response carries the latest built
-     * state including diagnostics; callers observe convergence via that
-     * response.
+     * Update a document's content as the session `clientId`, which must have
+     * it open. The response carries the latest built state including
+     * diagnostics; callers observe convergence via that response.
      */
     updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
     /**
-     * Persist a document to disk. The response is the post-save document
+     * Write a document as the session `clientId`, which must have it open, and
+     * persist it to disk. The response is the post-save document
      * state (matches the file on disk). Save semantics depend on the
      * filesystem-provider wiring; rejection paths surface as awaited
      * promise rejections.
@@ -171,6 +207,19 @@ export interface ProjectServerProtocol<TProject extends Project = Project> {
  */
 export interface DataServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project> extends DocumentServerProtocol<TTransfer, TDiagnostic>, ProjectServerProtocol<TProject> {
 }
+/**
+ * The diagnostic shape a server answers with, read back off its own
+ * declaration.
+ *
+ * This is what lets a client tier stay generic over the server alone and still
+ * describe what it hands back. Both parameters must be inferred: naming
+ * {@link TransferElement} for the transfer instead fails to match while that
+ * parameter is still generic, and a default declared against the constraint
+ * then stops satisfying it.
+ */
+export type DiagnosticOf<TServer> = TServer extends DocumentServerProtocol<infer _TTransfer, infer TDiagnostic> ? TDiagnostic : TransferDiagnostic;
+/** The project shape a server answers with, read back off its own declaration. */
+export type ProjectOf<TServer> = TServer extends ProjectServerProtocol<infer TProject> ? TProject : Project;
 /**
  * Cross-reference / naming slice of the server surface — scope-aware
  * queries that resolve against the language's reference services. NOT part
@@ -235,6 +284,36 @@ export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiag
      * codepath, not a subscription codepath).
      */
     onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+    /**
+     * Delivered when a subscribed document's text starts or stops differing
+     * from its file, as the server last knew it. Gated like
+     * {@link onDocumentSaved}; the answer at any one moment is the `dirty` of
+     * the documents the server sends. After a reconnect, a `DataSession`
+     * delivers here the answer of each document it restored, when that differs
+     * from the last this client was told: the flips while the connection was
+     * down reached no one.
+     */
+    onDocumentDirtyChanged(event: TransferDocumentDirtyChangedEvent): void;
+    /**
+     * Delivered when a document's backing file was removed. Separate from
+     * {@link onDocumentUpdated} for the same reason as {@link onDocumentSaved},
+     * and more strongly: there is no built state to deliver, and the build-phase
+     * path cannot report a deletion at all.
+     *
+     * Ungated, because on a browser host — where the workspace lives behind the
+     * head — no other source can observe a file disappearing. Recipients that
+     * only care about their own documents filter by URI.
+     */
+    onDocumentDeleted(event: TransferDocumentDeletedEvent): void;
+    /**
+     * Delivered once per build, naming the documents that reached the
+     * subscription phase and that
+     * nobody on this connection watches — chiefly the ones rebuilt as a cascade
+     * from a dependency's change, which no filesystem watcher can see because
+     * their own files did not change. The complement of
+     * {@link onDocumentUpdated}; carries URIs and no documents.
+     */
+    onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void;
 }
 /**
  * Project-scoped slice of the client surface — the project-registry change

package/lib/data/data-server-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-server-protocol.d.ts","sourceRoot":"","sources":["../../src/data/data-server-protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"data-server-protocol.d.ts","sourceRoot":"","sources":["../../src/data/data-server-protocol.ts"],"names":[],"mappings":"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"}

package/lib/data/events.d.ts

@@ -28,10 +28,14 @@ import type { TransferDocument } from '../transfer-document';
  *   from both `onDocumentUpdated` and `onDocumentSaved`. The framework's own
  *   `dispatchPhaseEvent` does NOT emit `'saved'` — saves take the dedicated
  *   `DataClientProtocol.onDocumentSaved` channel.
- * - `'deleted'` — the URI appeared in `DocumentBuilder.onUpdate`'s
- *   `deleted` list. The backing file was removed.
+ *
+ * Deletion is deliberately NOT a member. An update event carries a built
+ * document, which a deleted one has none of, and the phase-driven path that
+ * produces these events never runs for a deleted URI — the builder drops the
+ * document before deriving the rebuild set. It travels as
+ * {@link TransferDocumentDeletedEvent} on its own channel instead.
  */
-export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved' | 'deleted';
+export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved';
 /**
  * Delivered on the data-server when a document's content (or existence)
  * changed. Subscribers receive this via `DocumentServerProtocol.watchModelDocument`.
@@ -72,6 +76,83 @@ export interface TransferDocumentSavedEvent<TTransfer extends TransferElement, T
 }
 /** Callback shape for `DataClientProtocol.onDocumentSaved`. */
 export type TransferDocumentSavedListener<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> = (event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>) => void;
+/**
+ * Delivered on the data-server when a watched document's text starts or stops
+ * differing from its file, as the server last knew the file. The current
+ * answer rides on every transfer document the server sends as `dirty`; this
+ * carries only its changes, so a client that follows it needs no rebuild to
+ * learn of a save.
+ */
+export interface TransferDocumentDirtyChangedEvent {
+    /** Canonical URI, keyed as the subscription is. */
+    readonly uri: string;
+    readonly dirty: boolean;
+}
+/** Callback shape for `DataClientProtocol.onDocumentDirtyChanged`. */
+export type TransferDocumentDirtyChangedListener = (event: TransferDocumentDirtyChangedEvent) => void;
+/**
+ * Delivered on the data-server when a document's backing file was removed.
+ * Carries no document, and cannot: the state a
+ * {@link TransferDocumentUpdatedEvent} would have to carry no longer exists by
+ * the time anyone can be told. That is also why deletion is not a `reason` on
+ * the update stream — `DocumentBuilder.update` drops the document before
+ * deriving the rebuild set, so the phase-driven path that produces update
+ * events never runs for it.
+ *
+ * **Delivered for EVERY document, not only watched ones**, unlike
+ * `onDocumentUpdated` and `onDocumentSaved`. The test that decides which
+ * channels are gated is whether any OTHER source can observe the fact on the
+ * least capable host: a browser-hosted client's workspace lives behind the
+ * head, so nothing there can see a file disappear, and gating the notification
+ * would leave it blind. (A Theia frontend's filesystem watcher would cover it,
+ * which is why this is a host argument and not a structure-versus-content one.)
+ * A watcher is told about its own document's deletion here too, the update
+ * channel being silent for deletions by construction. Filter on {@link uri} if
+ * the receiver only cares about documents it opened.
+ *
+ * A watch survives the deletion, so a file that comes back resumes delivering
+ * `onDocumentUpdated` to the same subscribers with no re-subscription. A
+ * client that responds by closing its editor releases the watch through
+ * `closeModelDocument` as usual.
+ */
+export interface TransferDocumentDeletedEvent {
+    /** Canonical URI of the removed document, keyed as the subscription is. */
+    readonly uri: string;
+}
+/** Callback shape for `DataClientProtocol.onDocumentDeleted`. */
+export type TransferDocumentDeletedListener = (event: TransferDocumentDeletedEvent) => void;
+/**
+ * Delivered on the data-server once per build, naming the documents that reached
+ * the configured subscription phase (`DataServerOptions.subscriptionPhase`,
+ * `Validated` by default) and that NO client on the connection is watching. Not
+ * the integrity-settled landmark, which is a different point and a different
+ * word in this framework.
+ *
+ * The complement of {@link TransferDocumentUpdatedEvent}, which is gated per
+ * URI: together the two cover every document a build touched. This one exists
+ * for the case no source outside the server can observe — a document rebuilt
+ * because something it DEPENDS ON changed. Its own file never changed, so a
+ * filesystem watcher cannot see it, and it has no subscriber, so the update
+ * channel does not report it. A consumer showing data derived from such a
+ * document (a tree label, a decorator) would otherwise hold a stale value with
+ * nothing to invalidate it.
+ *
+ * Carries URIs and no documents: a recipient re-reads what it displays, through
+ * `getModelDocument` or its own request. That keeps the bandwidth property the
+ * per-URI subscription exists for, without gating the message.
+ *
+ * Not sent when the set is empty, which is the normal case while editing — the
+ * document being edited is watched by its own editor and therefore excluded.
+ * Workspace initialisation sends nothing either: it does not build to the
+ * subscription phase. The largest message a workspace can produce is therefore
+ * a whole-workspace rebuild at that phase, which is one message of URIs.
+ */
+export interface TransferDocumentsBuiltEvent {
+    /** Canonical URIs, keyed as subscriptions are. Never empty. */
+    readonly uris: readonly string[];
+}
+/** Callback shape for `DataClientProtocol.onDocumentsBuilt`. */
+export type TransferDocumentsBuiltListener = (event: TransferDocumentsBuiltEvent) => void;
 /**
  * Why a project-change event fired. `added` — the project was newly
  * registered (descriptor discovered); `updated` — the project's

package/lib/data/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/data/events.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,4BAA4B,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,WAAW,4BAA4B,CAC1C,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IAE3D,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnD,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,4BAA4B,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,MAAM,+BAA+B,CACxC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,IAC1D,CAAC,KAAK,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,0BAA0B,CACxC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IAE3D,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnD;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,MAAM,6BAA6B,CACtC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,IAC1D,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAElE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IACrE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,MAAM,uBAAuB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/data/events.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,4BAA4B,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,WAAW,4BAA4B,CAC1C,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IAE3D,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnD,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,4BAA4B,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,MAAM,+BAA+B,CACxC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,IAC1D,CAAC,KAAK,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,0BAA0B,CACxC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IAE3D,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnD;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,MAAM,6BAA6B,CACtC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,IAC1D,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,WAAW,iCAAiC;IAC/C,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,MAAM,oCAAoC,GAAG,CAAC,KAAK,EAAE,iCAAiC,KAAK,IAAI,CAAC;AAEtG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,4BAA4B;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,MAAM,MAAM,+BAA+B,GAAG,CAAC,KAAK,EAAE,4BAA4B,KAAK,IAAI,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,2BAA2B;IACzC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,gEAAgE;AAChE,MAAM,MAAM,8BAA8B,GAAG,CAAC,KAAK,EAAE,2BAA2B,KAAK,IAAI,CAAC;AAE1F;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAElE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IACrE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,MAAM,uBAAuB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC"}

package/lib/data/requests.d.ts

@@ -6,7 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import type { TransferSaveArgs, TransferUpdateArgs } from '../model-service/args';
+import type { BasedOn } from '../model-service/based-on';
 /** Get the current state of a single document. The server returns the latest built version. */
 export interface GetModelDocumentArgs {
     /** Document URI. */
@@ -37,22 +37,78 @@ export interface GetProjectForUriArgs {
     uri: string;
 }
 /**
- * Update a document's content. Wire-side projection of the facade's
- * {@link TransferUpdateArgs}; structurally identical so the data-server RPC
- * handler can forward straight to the in-process `ModelService.update`
- * without an args mapping.
+ * Update a document the session `clientId` has open. Generic over `TTransfer`
+ * so adopters parameterise the structured shape against their grammar's
+ * transfer-model overlay; passing a string is always allowed.
  */
-export type TransferUpdateDocumentArgs<TTransfer> = TransferUpdateArgs<TTransfer>;
-/** Persist a document to disk. Wire-side projection of {@link TransferSaveArgs}. */
-export type TransferSaveDocumentArgs<TTransfer> = TransferSaveArgs<TTransfer>;
+export interface TransferUpdateDocumentArgs<TTransfer> {
+    /** Document URI. */
+    uri: string;
+    /** The id of a live session registered on this connection. */
+    clientId: string;
+    /** The whole structured model root, or its serialised textual form. */
+    model: TTransfer | string;
+    /**
+     * What this write was authored against. A `SnapshotVersion` is compared
+     * against the server's current text-document version for `uri` and throws
+     * `ConflictError` on mismatch; `'anything'` writes unconditionally.
+     *
+     * **Required so that an ungated write is a decision rather than an
+     * omission.** An optional gate is indistinguishable from a forgotten one at
+     * the call site, and a file of twenty writes hides the one that lost the
+     * field. Nothing else here can see that, since the defect is an absence.
+     */
+    basedOn: BasedOn;
+}
+/** Update a document the session `clientId` has open, then persist it to disk. */
+export interface TransferSaveDocumentArgs<TTransfer> extends TransferUpdateDocumentArgs<TTransfer> {
+}
+/** Register a client session on the connection. */
+export interface CreateSessionArgs {
+    /** The session's id, minted by the client; unique in the server process while the session is live. */
+    clientId: string;
+    /** What the participant is; kept as the server session's `label`. */
+    label?: string;
+    /**
+     * A token the client keeps for the session's lifetime. It is no secret: the
+     * wire carries no authentication. A later `createSession` for the same id
+     * carrying the same token, from any connection, ends the session it names
+     * and registers the id afresh, so a client whose connection dropped before
+     * the server noticed can register again. Without it the id stays refused
+     * until the server notices.
+     */
+    resumeToken?: string;
+}
+/** End a client session registered on the connection. */
+export interface CloseSessionArgs {
+    clientId: string;
+}
+/** Create a document that exists nowhere yet, open for the session creating it. */
+export interface CreateModelDocumentArgs {
+    uri: string;
+    /** The id of a live session registered on this connection. */
+    clientId: string;
+    /** The document's initial content; it reaches disk with the first save. */
+    text: string;
+}
+/**
+ * Write several documents a session has open, all or none. `clientId` is on
+ * the set rather than on each update: an id per update would allow a set
+ * mixing clients, which the server would have to refuse.
+ */
+export interface TransferUpdateDocumentsArgs<TTransfer> {
+    /** The id of a live session registered on this connection. */
+    clientId: string;
+    updates: Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>[];
+}
 /**
  * Identifies a per-document watch on the data server. Shared by both
  * `watchModelDocument` and `unwatchModelDocument` — the `(uri, clientId)`
  * pair is the watch key, so unwatching names the same watch that was
  * started. The `clientId` identifies the originator the same way it does
- * on facade-side mutations (`TransferUpdateArgs.clientId`,
- * `TransferSaveArgs.clientId`): it keys the per-`(uri, clientId)` watch
- * bucket so multiple watchers on the same wire stay distinct, AND it lets
+ * on the document writes (`TransferUpdateDocumentArgs.clientId`,
+ * `TransferSaveDocumentArgs.clientId`): it keys the per-`(uri, clientId)`
+ * watch bucket so multiple watchers on the same wire stay distinct, AND it lets
  * each watcher recognise its own echo on inbound `onDocumentUpdated` events
  * (the wire shape's `sourceClientId` carries the originating mutation's
  * `clientId`).

package/lib/data/requests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requests.d.ts","sourceRoot":"","sources":["../../src/data/requests.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAElF,+FAA+F;AAC/F,MAAM,WAAW,oBAAoB;IAClC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IAClC,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,CAAC,SAAS,IAAI,kBAAkB,CAAC,SAAS,CAAC,CAAC;AAElF,oFAAoF;AACpF,MAAM,MAAM,wBAAwB,CAAC,SAAS,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"requests.d.ts","sourceRoot":"","sources":["../../src/data/requests.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEzD,+FAA+F;AAC/F,MAAM,WAAW,oBAAoB;IAClC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IAClC,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B,CAAC,SAAS;IAClD,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B;;;;;;;;;OASG;IACH,OAAO,EAAE,OAAO,CAAC;CACnB;AAED,kFAAkF;AAElF,MAAM,WAAW,wBAAwB,CAAC,SAAS,CAAE,SAAQ,0BAA0B,CAAC,SAAS,CAAC;CAAG;AAErG,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAC/B,sGAAsG;IACtG,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC9B,QAAQ,EAAE,MAAM,CAAC;CACnB;AAED,mFAAmF;AACnF,MAAM,WAAW,uBAAuB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B,CAAC,SAAS;IACnD,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC,0BAA0B,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC;CACrE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CACnB"}

package/lib/errors.d.ts

@@ -7,6 +7,16 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { ResponseError } from 'vscode-jsonrpc';
+import { type HydraniumMessageData } from './messages/primitives';
+/**
+ * The catalogue declaration behind {@link ConflictError}'s sentence.
+ *
+ * Its English must keep containing {@link CONFLICT_ERROR_MESSAGE_MARKER}: the
+ * marker is tier 3 of {@link isConflictError}'s ladder, and it matches on text.
+ * That tier only ever works untranslated, which is why it is the last resort
+ * behind the numeric code rather than the primary check.
+ */
+export declare const STALE_BASED_UPDATE: import("./messages/primitives").MessageDefinition<"Stale-based update for {uri}: expected v{expectedVersion}, server is at v{actualVersion}">;
 /**
  * Application-specific JSON-RPC error code for {@link ConflictError}.
  * Outside the reserved range (-32768 .. -32000) per JSON-RPC 2.0.
@@ -21,15 +31,15 @@ export declare const CONFLICT_ERROR_CODE = 1001;
  * Structured payload carried in {@link ConflictError.data}, and the only place
  * a post-RPC caller can read the version mismatch from.
  */
-export interface ConflictErrorData {
+export interface ConflictErrorData extends HydraniumMessageData {
     readonly uri: string;
     /** The based-on version the caller authored against. */
-    readonly expected: number;
+    readonly expectedVersion: number;
     /** The server's current text-document version at the time of the throw. */
-    readonly actual: number;
+    readonly actualVersion: number;
 }
 /**
- * Thrown by `ModelService.update` / `ModelService.save` when the caller-
+ * Thrown by a client session's `update` / `save` when the caller-
  * supplied based-on version no longer matches the server's current text-
  * document version for the same URI — i.e. the snapshot the caller
  * authored against has been superseded by an intervening edit.
@@ -42,11 +52,9 @@ export interface ConflictErrorData {
  * `err.data` (the instance is reconstructed as a generic
  * `ResponseError`, so subclass getters / fields do not survive).
  *
- * Detection is opt-in via the optional `baseVersion` field on
- * `TransferUpdateArgs` / `TransferSaveArgs`; callers that omit the field get
- * no gating. This mirrors LSP's `OptionalVersionedTextDocumentIdentifier`
- * posture, so headless / CLI / batch tooling with no meaningful based-on
- * version can opt out explicitly.
+ * Detection is driven by the required `basedOn` field of every write
+ * request; a caller with no meaningful based-on version passes
+ * `'anything'` and gets no gating.
  *
  * Three reasonable adopter recovery strategies:
  *
@@ -60,11 +68,93 @@ export interface ConflictErrorData {
  * No auto-retry or auto-merge ships by default.
  */
 export declare class ConflictError extends ResponseError<ConflictErrorData> {
-    constructor(uri: string, expected: number, actual: number);
+    constructor(uri: string, expectedVersion: number, actualVersion: number);
     get uri(): string;
-    get expected(): number;
-    get actual(): number;
+    /**
+     * The based-on version the caller authored against.
+     *
+     * Must not be renamed to `expected`, nor its sibling to `actual`: a test
+     * reporter reads an error carrying both as an assertion failure, and
+     * vitest's formatter then ASSIGNS to them, which throws on an accessor and
+     * replaces the real failure with a `TypeError`.
+     */
+    get expectedVersion(): number;
+    /** The server's version at the time of the throw. Not `actual` — see {@link expectedVersion}. */
+    get actualVersion(): number;
+}
+/**
+ * JSON-RPC code for {@link SessionClosedError}, beside {@link CONFLICT_ERROR_CODE}
+ * and for the same reason: the code survives reconstruction, the class does not.
+ */
+export declare const SESSION_CLOSED_ERROR_CODE = 1004;
+/** JSON-RPC code for {@link DocumentNotOpenError}. */
+export declare const DOCUMENT_NOT_OPEN_ERROR_CODE = 1005;
+/** JSON-RPC code for {@link DuplicateClientIdError}. */
+export declare const DUPLICATE_CLIENT_ID_ERROR_CODE = 1006;
+/**
+ * The catalogue declaration behind {@link SessionClosedError}'s default
+ * sentence. It names no client id: the sentence can reach an end user, and the
+ * id stays in {@link SessionClosedErrorData.clientId} for whoever needs it.
+ */
+export declare const SESSION_CLOSED: import("./messages/primitives").MessageDefinition<"The editing session has ended.">;
+/** Structured payload carried in {@link SessionClosedError.data}. */
+export interface SessionClosedErrorData extends HydraniumMessageData {
+    readonly clientId: string;
+}
+/**
+ * Thrown by every call on a client session after it ended, and by an open that
+ * was still in flight when its session ended: by the server for its sessions,
+ * and by a client-side `DataSession` once disposed, so a caller handles both
+ * the same way. A caller recognises it with {@link isSessionClosedError}, never
+ * by its sentence.
+ */
+export declare class SessionClosedError extends ResponseError<SessionClosedErrorData> {
+    /**
+     * `message` replaces the default English, for a caller that knows more than
+     * that the session is gone. The identity stays {@link SESSION_CLOSED}'s, so a
+     * translating renderer renders the catalogue sentence in its place.
+     */
+    constructor(clientId: string, message?: string);
+    get clientId(): string;
 }
+/**
+ * Thrown when a client session writes a document it does not have open.
+ *
+ * A session writes only what it has open, so this is the answer both to a write
+ * that never opened and to one whose open was closed underneath it — by the
+ * session itself, or by the document being deleted.
+ */
+export declare class DocumentNotOpenError extends ResponseError<{
+    readonly uri: string;
+    readonly clientId: string;
+}> {
+    constructor(uri: string, clientId: string);
+    get uri(): string;
+    get clientId(): string;
+}
+/**
+ * Thrown when a client session is started under an id that is already live in
+ * the process, or that the framework reserves for itself.
+ *
+ * Ids are unique process-wide because the id is also the author label on every
+ * version and the key a client recognises its own echoes by; two participants
+ * sharing one would each take the other's writes for their own.
+ */
+export declare class DuplicateClientIdError extends ResponseError<{
+    readonly clientId: string;
+}> {
+    constructor(clientId: string);
+    get clientId(): string;
+}
+/**
+ * Whether `error` is a {@link SessionClosedError}: by name in-process, by code
+ * after an RPC, where it arrives as a plain `ResponseError`.
+ */
+export declare function isSessionClosedError(error: unknown): error is SessionClosedError;
+/** Whether `error` is a {@link DocumentNotOpenError}; see {@link isSessionClosedError}. */
+export declare function isDocumentNotOpenError(error: unknown): error is DocumentNotOpenError;
+/** Whether `error` is a {@link DuplicateClientIdError}; see {@link isSessionClosedError}. */
+export declare function isDuplicateClientIdError(error: unknown): error is DuplicateClientIdError;
 /**
  * Type guard for {@link ConflictError}. Detection ladder:
  *

package/lib/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,aAAc,SAAQ,aAAa,CAAC,iBAAiB,CAAC;gBACpD,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAezD,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;CACH;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAYtE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAiB,KAAK,oBAAoB,EAAe,MAAM,uBAAuB,CAAC;AAE9F;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,+IAG9B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,oBAAoB;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,aAAc,SAAQ,aAAa,CAAC,iBAAiB,CAAC;gBACpD,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;IAgBvE,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;;;;;OAOG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,iGAAiG;IACjG,IAAI,aAAa,IAAI,MAAM,CAE1B;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C,sDAAsD;AACtD,eAAO,MAAM,4BAA4B,OAAO,CAAC;AACjD,wDAAwD;AACxD,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,cAAc,qFAAuF,CAAC;AAEnH,qEAAqE;AACrE,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,aAAa,CAAC,sBAAsB,CAAC;IAC1E;;;;OAIG;gBACS,QAAQ,EAAE,MAAM,EAAE,OAAO,SAA0B;IAO/D,IAAI,QAAQ,IAAI,MAAM,CAErB;CACH;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,aAAa,CAAC;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;gBAC7F,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAMzC,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;CACH;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,aAAa,CAAC;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;gBACzE,QAAQ,EAAE,MAAM;IAM5B,IAAI,QAAQ,IAAI,MAAM,CAErB;CACH;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAEhF;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CAEpF;AAED,6FAA6F;AAC7F,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAExF;AAWD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAYtE"}