@hydranium/protocol 1.0.0-next.39 → 1.0.0-next.390

package/lib/debouncer.d.ts

@@ -6,7 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { type Clock } from './clock';
+import { type Clock, type Stopwatch } from './clock';
 import { ObservableValue, type MaybeObservableValue } from './observable-value';
 import { type Disposable } from './util';
 /** Construction options for {@link Debouncer}. */
@@ -49,11 +49,13 @@ export interface DebouncerOptions {
 export declare class Debouncer implements Disposable {
     protected readonly clock: Clock;
     protected readonly fn: () => void;
+    /** {@link DebouncerOptions.delayMs}, read at each {@link schedule}. An armed timer keeps the delay it was armed with. */
     protected readonly delay: ObservableValue<number>;
+    /** {@link DebouncerOptions.maxWaitMs}, fixed at construction unlike {@link delay}. */
     protected readonly maxWaitMs?: number;
     protected timer?: Disposable;
-    /** Virtual time of the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
-    protected firstScheduledAt?: number;
+    /** Running since the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
+    protected sinceFirstSchedule?: Stopwatch;
     constructor(clock: Clock, fn: () => void, options: DebouncerOptions);
     /** True while a fire is armed (scheduled, not yet fired or cancelled). */
     get pending(): boolean;
@@ -64,12 +66,13 @@ export declare class Debouncer implements Disposable {
      * elapses since the first pending call.
      */
     schedule(): void;
-    /** If a fire is pending, run {@link fn} now and clear the window; otherwise a no-op. */
+    /** Run {@link fn} now if a fire is pending, clearing the window first, and do nothing otherwise. */
     flush(): void;
     /** Drop a pending fire without running {@link fn}. */
     cancel(): void;
     /** Cancel any pending fire and release. */
     dispose(): void;
+    /** Clears the window before it runs {@link fn}, so a {@link schedule} from inside `fn` opens a new one. */
     protected fire(): void;
 }
 //# sourceMappingURL=debouncer.d.ts.map

package/lib/debouncer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debouncer.d.ts","sourceRoot":"","sources":["../src/debouncer.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAU,YAAW,UAAU;IAQtC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK;IAC/B,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI;IARpC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IACtC,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC7B,2HAA2H;IAC3H,SAAS,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;gBAGd,KAAK,EAAE,KAAK,EACZ,EAAE,EAAE,MAAM,IAAI,EACjC,OAAO,EAAE,gBAAgB;IAM5B,0EAA0E;IAC1E,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;OAKG;IACH,QAAQ,IAAI,IAAI;IAchB,wFAAwF;IACxF,KAAK,IAAI,IAAI;IAMb,sDAAsD;IACtD,MAAM,IAAI,IAAI;IAMd,2CAA2C;IAC3C,OAAO,IAAI,IAAI;IAIf,SAAS,CAAC,IAAI,IAAI,IAAI;CAMxB"}
+{"version":3,"file":"debouncer.d.ts","sourceRoot":"","sources":["../src/debouncer.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAU,YAAW,UAAU;IAUtC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK;IAC/B,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI;IAVpC,yHAAyH;IACzH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAClD,sFAAsF;IACtF,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IACtC,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC7B,yHAAyH;IACzH,SAAS,CAAC,kBAAkB,CAAC,EAAE,SAAS,CAAC;IAEzC,YACsB,KAAK,EAAE,KAAK,EACZ,EAAE,EAAE,MAAM,IAAI,EACjC,OAAO,EAAE,gBAAgB,EAI3B;IAED,0EAA0E;IAC1E,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;OAKG;IACH,QAAQ,IAAI,IAAI,CASf;IAED,oGAAoG;IACpG,KAAK,IAAI,IAAI,CAIZ;IAED,sDAAsD;IACtD,MAAM,IAAI,IAAI,CAIb;IAED,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAEd;IAED,2GAA2G;IAC3G,SAAS,CAAC,IAAI,IAAI,IAAI,CAKrB;CACH"}

package/lib/debouncer.js

@@ -30,11 +30,13 @@ const observable_value_1 = require("./observable-value");
 class Debouncer {
     clock;
     fn;
+    /** {@link DebouncerOptions.delayMs}, read at each {@link schedule}. An armed timer keeps the delay it was armed with. */
     delay;
+    /** {@link DebouncerOptions.maxWaitMs}, fixed at construction unlike {@link delay}. */
     maxWaitMs;
     timer;
-    /** Virtual time of the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
-    firstScheduledAt;
+    /** Running since the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
+    sinceFirstSchedule;
     constructor(clock, fn, options) {
         this.clock = clock;
         this.fn = fn;
@@ -52,19 +54,16 @@ class Debouncer {
      * elapses since the first pending call.
      */
     schedule() {
-        const now = this.clock.now();
-        if (this.firstScheduledAt === undefined) {
-            this.firstScheduledAt = now;
-        }
+        this.sinceFirstSchedule ??= this.clock.stopwatch();
         let wait = Math.max(0, this.delay.value);
         if (this.maxWaitMs !== undefined) {
-            const untilCeiling = this.firstScheduledAt + this.maxWaitMs - now;
+            const untilCeiling = this.maxWaitMs - this.sinceFirstSchedule.elapsedMs;
             wait = Math.min(wait, Math.max(0, untilCeiling));
         }
         this.timer?.dispose();
         this.timer = this.clock.setTimer(() => this.fire(), wait);
     }
-    /** If a fire is pending, run {@link fn} now and clear the window; otherwise a no-op. */
+    /** Run {@link fn} now if a fire is pending, clearing the window first, and do nothing otherwise. */
     flush() {
         if (this.timer !== undefined) {
             this.fire();
@@ -74,16 +73,17 @@ class Debouncer {
     cancel() {
         this.timer?.dispose();
         this.timer = undefined;
-        this.firstScheduledAt = undefined;
+        this.sinceFirstSchedule = undefined;
     }
     /** Cancel any pending fire and release. */
     dispose() {
         this.cancel();
     }
+    /** Clears the window before it runs {@link fn}, so a {@link schedule} from inside `fn` opens a new one. */
     fire() {
         this.timer?.dispose();
         this.timer = undefined;
-        this.firstScheduledAt = undefined;
+        this.sinceFirstSchedule = undefined;
         this.fn();
     }
 }

package/lib/debouncer.js.map

@@ -1 +1 @@
-{"version":3,"file":"debouncer.js","sourceRoot":"","sources":["../src/debouncer.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAGlF,yDAAgF;AAwBhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,SAAS;IAQG;IACA;IARH,KAAK,CAA0B;IAC/B,SAAS,CAAU;IAC5B,KAAK,CAAc;IAC7B,2HAA2H;IACjH,gBAAgB,CAAU;IAEpC,YACsB,KAAY,EACZ,EAAc,EACjC,OAAyB;QAFN,UAAK,GAAL,KAAK,CAAO;QACZ,OAAE,GAAF,EAAE,CAAY;QAGjC,IAAI,CAAC,KAAK,GAAG,kCAAe,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACtC,CAAC;IAED,0EAA0E;IAC1E,IAAI,OAAO;QACR,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACL,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACvC,IAAI,CAAC,gBAAgB,GAAG,GAAG,CAAC;QAC/B,CAAC;QACD,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC;YAClE,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7D,CAAC;IAED,wFAAwF;IACxF,KAAK;QACF,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,EAAE,CAAC;QACf,CAAC;IACJ,CAAC;IAED,sDAAsD;IACtD,MAAM;QACH,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;IACrC,CAAC;IAED,2CAA2C;IAC3C,OAAO;QACJ,IAAI,CAAC,MAAM,EAAE,CAAC;IACjB,CAAC;IAES,IAAI;QACX,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;QAClC,IAAI,CAAC,EAAE,EAAE,CAAC;IACb,CAAC;CACH;AAlED,8BAkEC"}
+{"version":3,"file":"debouncer.js","sourceRoot":"","sources":["../src/debouncer.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAGlF,yDAAgF;AAwBhF;;;;;;;;;;;;;;;;GAgBG;AACH;IAUyB,KAAK;IACL,EAAE;IAVxB,yHAAyH;IACtG,KAAK,CAA0B;IAClD,sFAAsF;IACnE,SAAS,CAAU;IAC5B,KAAK,CAAc;IAC7B,yHAAyH;IAC/G,kBAAkB,CAAa;IAEzC,YACsB,KAAY,EACZ,EAAc,EACjC,OAAyB;qBAFN,KAAK;kBACL,EAAE;QAGrB,IAAI,CAAC,KAAK,GAAG,kCAAe,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACtC,CAAC;IAED,0EAA0E;IAC1E,IAAI,OAAO;QACR,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACL,IAAI,CAAC,kBAAkB,KAAK,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACnD,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC;YACxE,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7D,CAAC;IAED,oGAAoG;IACpG,KAAK;QACF,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,EAAE,CAAC;QACf,CAAC;IACJ,CAAC;IAED,sDAAsD;IACtD,MAAM;QACH,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,kBAAkB,GAAG,SAAS,CAAC;IACvC,CAAC;IAED,2CAA2C;IAC3C,OAAO;QACJ,IAAI,CAAC,MAAM,EAAE,CAAC;IACjB,CAAC;IAED,2GAA2G;IACjG,IAAI;QACX,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,kBAAkB,GAAG,SAAS,CAAC;QACpC,IAAI,CAAC,EAAE,EAAE,CAAC;IACb,CAAC;CACH"}

package/lib/errors.d.ts

@@ -8,55 +8,80 @@
  ********************************************************************************/
 import { ResponseError } from 'vscode-jsonrpc';
 import { type HydraniumMessageData } from './messages/primitives';
+import { type ModelVersion, type TextVersion } from './model-service/base-version';
 /**
- * The catalogue declaration behind {@link ConflictError}'s sentence.
+ * The catalogue declaration behind {@link ConflictError}'s sentence. It words
+ * the version mismatch rather than stating it: the two numbers mean nothing to
+ * an end user, and they stay in {@link ConflictErrorData}.
+ */
+export declare const STALE_BASE_VERSION_UPDATE: import("./messages/primitives").MessageDefinition<"The edit to {uri} was not applied: it was made to an older version of the document.">;
+/**
+ * {@link STALE_BASE_VERSION_UPDATE}'s counterpart for an editor's save the
+ * server refused, since the editor's buffer is not the text it holds.
+ */
+export declare const STALE_BASE_VERSION_SAVE: import("./messages/primitives").MessageDefinition<"The save of {uri} was not applied: it was made to an older version of the document.">;
+/**
+ * Every JSON-RPC error code the framework raises, from any package, keyed by
+ * the error it identifies.
  *
- * 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.
+ * The framework reserves the block 42000 to 42999 for these, and an adopter's
+ * own codes stay outside it: after an RPC the proxy revives an error by its
+ * code, so an adopter's error carrying one of these can read as the
+ * framework's. A new code takes the next unused number in the block, whichever
+ * package raises it, and is declared here, where tests hold every code distinct
+ * and inside the block.
+ * The block sits clear of the range JSON-RPC 2.0 reserves for itself, -32768
+ * to -32000.
  */
-export declare const STALE_BASED_UPDATE: import("./messages/primitives").MessageDefinition<"Stale-based update for {uri}: expected v{expectedVersion}, server is at v{actualVersion}">;
+export declare const HYDRANIUM_ERROR_CODES: {
+    readonly conflict: 42001;
+    readonly noActiveProfile: 42002;
+    readonly referenceSettleTimeout: 42003;
+    readonly sessionClosed: 42004;
+    readonly documentNotOpen: 42005;
+    readonly duplicateClientId: 42006;
+    readonly reservedClientId: 42007;
+    readonly saveFailed: 42008;
+    readonly documentSyntaxError: 42009;
+};
 /**
- * Application-specific JSON-RPC error code for {@link ConflictError}.
- * Outside the reserved range (-32768 .. -32000) per JSON-RPC 2.0.
+ * JSON-RPC error code for {@link ConflictError}.
  *
  * The code is the load-bearing identifier across realm boundaries —
  * `code` is a first-class field on the JSON-RPC error envelope and
  * survives wire reconstruction; the custom `Error` subclass name does
  * not.
  */
-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 declare const CONFLICT_ERROR_CODE: 42001;
+/** Structured payload carried in {@link ConflictError.data}. */
 export interface ConflictErrorData extends HydraniumMessageData {
+    /**
+     * The document whose version moved. A write of several documents names
+     * the first stale one in request order, and others may be stale too.
+     */
     readonly uri: string;
-    /** The based-on version the caller authored against. */
-    readonly expectedVersion: number;
+    /** The base version the caller authored against. */
+    readonly baseVersion: ModelVersion;
     /** The server's current text-document version at the time of the throw. */
-    readonly actualVersion: number;
+    readonly actualVersion: TextVersion;
 }
 /**
- * Thrown by `ModelService.update` / `ModelService.save` when the caller-
- * supplied based-on version no longer matches the server's current text-
+ * Thrown by a client session's `update` / `save` when the caller-
+ * supplied base 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.
  *
  * Extends vscode-jsonrpc's {@link ResponseError} so the typed
  * {@link ConflictErrorData} payload rides on the standard JSON-RPC
  * error envelope (`code`, `message`, `data`) — all three fields are
- * preserved by RPC reconstruction. Adopters that catch the error on
- * the receiving side of an RPC call read the version mismatch from
- * `err.data` (the instance is reconstructed as a generic
- * `ResponseError`, so subclass getters / fields do not survive).
+ * preserved by RPC reconstruction. `createRpcProxy` revives it into
+ * this class on the receiving side; a path that does not leaves a
+ * plain `ResponseError`, readable through `err.data` only and refused
+ * by {@link isConflictError}.
  *
- * 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 `baseVersion` field of every write
+ * request; a caller with no meaningful base version passes
+ * `'any'` and gets no gating.
  *
  * Three reasonable adopter recovery strategies:
  *
@@ -70,34 +95,202 @@ export interface ConflictErrorData extends HydraniumMessageData {
  * No auto-retry or auto-merge ships by default.
  */
 export declare class ConflictError extends ResponseError<ConflictErrorData> {
-    constructor(uri: string, expectedVersion: number, actualVersion: number);
+    /** `message` words what was refused: an edit, or with {@link STALE_BASE_VERSION_SAVE} a save. */
+    constructor(uri: string, baseVersion: ModelVersion, actualVersion: TextVersion, message?: typeof STALE_BASE_VERSION_UPDATE | typeof STALE_BASE_VERSION_SAVE);
+    /** The document whose version moved, see {@link ConflictErrorData.uri}. */
     get uri(): string;
     /**
-     * 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`.
+     * The base version the caller authored against. Not `expected`, and its
+     * sibling not `actual`: a test reporter reads that pair as an assertion
+     * failure and reports nothing of the real one.
+     */
+    get baseVersion(): ModelVersion;
+    /** The server's version at the time of the throw. Not `actual`, see {@link baseVersion}. */
+    get actualVersion(): TextVersion;
+}
+/**
+ * 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: 42004;
+/** JSON-RPC code for {@link DocumentNotOpenError}. */
+export declare const DOCUMENT_NOT_OPEN_ERROR_CODE: 42005;
+/** JSON-RPC code for {@link DuplicateClientIdError}. */
+export declare const DUPLICATE_CLIENT_ID_ERROR_CODE: 42006;
+/** JSON-RPC code for {@link ReservedClientIdError}. */
+export declare const RESERVED_CLIENT_ID_ERROR_CODE: 42007;
+/** JSON-RPC code for {@link SaveFailedError}. */
+export declare const SAVE_FAILED_ERROR_CODE: 42008;
+/** JSON-RPC code for {@link DocumentSyntaxError}. */
+export declare const DOCUMENT_SYNTAX_ERROR_CODE: 42009;
+/**
+ * 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.
      */
-    get expectedVersion(): number;
-    /** The server's version at the time of the throw. Not `actual` — see {@link expectedVersion}. */
-    get actualVersion(): number;
+    constructor(clientId: string, message?: string);
+    get clientId(): string;
+}
+/**
+ * The catalogue declaration behind {@link DocumentNotOpenError}'s sentence. The
+ * client id stays in {@link DocumentNotOpenErrorData.clientId}.
+ */
+export declare const DOCUMENT_NOT_OPEN: import("./messages/primitives").MessageDefinition<"The document {uri} is not open in this editing session.">;
+/** Structured payload carried in {@link DocumentNotOpenError.data}. */
+export interface DocumentNotOpenErrorData extends HydraniumMessageData {
+    readonly uri: string;
+    readonly 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<DocumentNotOpenErrorData> {
+    constructor(uri: string, clientId: string);
+    get uri(): string;
+    get clientId(): string;
+}
+/**
+ * The catalogue declaration behind {@link DuplicateClientIdError}'s sentence.
+ * The client id stays in {@link DuplicateClientIdErrorData.clientId}.
+ */
+export declare const DUPLICATE_CLIENT_ID: import("./messages/primitives").MessageDefinition<"Could not start an editing session: its identifier is still in use by another editor.">;
+/** Structured payload carried in {@link DuplicateClientIdError.data}. */
+export interface DuplicateClientIdErrorData extends HydraniumMessageData {
+    readonly clientId: string;
 }
 /**
- * Type guard for {@link ConflictError}. Detection ladder:
+ * Thrown when a client session is started under an id that is already live in
+ * the process. The id frees up once its holder ends or closes its last
+ * document, so a caller may retry.
  *
- *  1. `error.name === 'ConflictError'` — direct in-process throw, no
- *     RPC round-trip.
- *  2. `(error as ResponseError).code === CONFLICT_ERROR_CODE` — the
- *     canonical wire-side check; the JSON-RPC `code` field is preserved
- *     across reconstruction, so any adopter catching after an RPC call
- *     hits this branch.
- *  3. `error.message.includes('Stale-based update for ')` — fallback
- *     for transports that re-wrap the message and drop the code (rare).
+ * 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<DuplicateClientIdErrorData> {
+    constructor(clientId: string);
+    get clientId(): string;
+}
+/**
+ * Thrown when a client session is started under an id the framework reserves
+ * for one of its own participants. A reserved id never frees up, so a caller
+ * that retries on {@link DuplicateClientIdError} stops on this one.
  *
- * `instanceof ConflictError` alone would silently return `false` on the
- * reconstructed shape, so callers do not use it.
+ * It carries no message identity: a host that picks a reserved id has a bug,
+ * and no sentence addressed to an end user is true for it.
+ */
+export declare class ReservedClientIdError extends ResponseError<{
+    readonly clientId: string;
+}> {
+    constructor(clientId: string);
+    get clientId(): string;
+}
+/**
+ * The catalogue declaration behind {@link SaveFailedError}'s message. Its
+ * `failures` names each document with the writer's own reason, which stays as
+ * written.
+ */
+export declare const SAVE_FAILED: import("./messages/primitives").MessageDefinition<"Could not save {failures}.">;
+/** One document a save could not write, and why. */
+export interface SaveFailure {
+    readonly uri: string;
+    readonly reason: string;
+}
+/** Structured payload carried in {@link SaveFailedError.data}. */
+export interface SaveFailedErrorData extends HydraniumMessageData {
+    readonly failures: readonly SaveFailure[];
+}
+/**
+ * Thrown by a save that could not write one or more of its documents. A save
+ * of several documents writes the others, so the files on disk can be a mix
+ * until a later save succeeds.
+ */
+export declare class SaveFailedError extends ResponseError<SaveFailedErrorData> {
+    constructor(failures: readonly SaveFailure[]);
+    get failures(): readonly SaveFailure[];
+}
+/** The catalogue declaration behind {@link DocumentSyntaxError}'s sentence. */
+export declare const DOCUMENT_SYNTAX_ERROR: import("./messages/primitives").MessageDefinition<"The edit to {uri} was not applied: the document has a syntax error. Fix it in the text first.">;
+/** Structured payload carried in {@link DocumentSyntaxError.data}. */
+export interface DocumentSyntaxErrorData extends HydraniumMessageData {
+    readonly uri: string;
+}
+/**
+ * Thrown when a write would serialize a model over text that does not parse.
+ * A model read from a build with lexer or parser errors lacks what the parser
+ * skipped, so writing it would delete that text. A client session refuses a
+ * model write while the document's last build has such errors and its text
+ * is not blank, unless the write is a `restore`. A diagram refuses an edit,
+ * undo or redo that would write such a document, or whose merge or collision
+ * reads one. A client's write of text is not refused, since that is how the
+ * text is repaired.
+ */
+export declare class DocumentSyntaxError extends ResponseError<DocumentSyntaxErrorData> {
+    constructor(uri: string);
+    get uri(): string;
+}
+/**
+ * Whether `error` is a `ResponseError` from any copy of `vscode-jsonrpc`. An
+ * install holds several copies, and `instanceof` recognises only its own. An
+ * error that merely carries an integer `code` has no `toJson`, and is not one.
+ */
+export declare function isResponseError(error: unknown): error is ResponseError<unknown>;
+/**
+ * `error` as an instance of the typed error class its code names, with its
+ * message, data and stack kept, or `error` itself when its code names none or
+ * its data lacks the fields that class reads.
+ * An RPC reconstructs every rejection as a plain `ResponseError`, which has
+ * none of the class getters.
+ */
+export declare function reviveProtocolError(error: unknown): unknown;
+/**
+ * The error the JSON text `json` describes, as `JSON.stringify(error.toJson())`
+ * writes it, revived to its typed class as {@link reviveProtocolError} does, or
+ * `undefined` when `json` is not a JSON-RPC error envelope. For a transport
+ * that carries the error as text, such as a GLSP `RejectAction`'s `detail`.
+ */
+export declare function reviveProtocolErrorJson(json: string): ResponseError<unknown> | undefined;
+/**
+ * Whether `error` is a {@link SessionClosedError} whose getters read valid
+ * fields: one thrown, or one {@link reviveProtocolError revived}, from any
+ * copy of this package, or a subclass. A bare `ResponseError` is not one,
+ * whatever its name and fields, since it lacks the class's brand.
+ * `createRpcProxy` revives every rejection, so only a caller on a connection
+ * of its own needs to revive first. Each guard below works the same way.
  */
+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;
+/** Whether `error` is a {@link ReservedClientIdError}. See {@link isSessionClosedError}. */
+export declare function isReservedClientIdError(error: unknown): error is ReservedClientIdError;
+/** Whether `error` is a {@link SaveFailedError}. See {@link isSessionClosedError}. */
+export declare function isSaveFailedError(error: unknown): error is SaveFailedError;
+/** Whether `error` is a {@link DocumentSyntaxError}. See {@link isSessionClosedError}. */
+export declare function isDocumentSyntaxError(error: unknown): error is DocumentSyntaxError;
+/** Whether `error` is a {@link ConflictError}. See {@link isSessionClosedError}. */
 export declare function isConflictError(error: unknown): error is ConflictError;
 //# sourceMappingURL=errors.d.ts.map

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;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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;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":"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"}