@hydranium/protocol 1.0.0-next.38 → 1.0.0-next.380

package/lib/errors.js

@@ -8,48 +8,92 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConflictError = exports.CONFLICT_ERROR_CODE = exports.STALE_BASED_UPDATE = void 0;
+exports.DocumentSyntaxError = exports.DOCUMENT_SYNTAX_ERROR = exports.SaveFailedError = exports.SAVE_FAILED = exports.ReservedClientIdError = exports.DuplicateClientIdError = exports.DUPLICATE_CLIENT_ID = exports.DocumentNotOpenError = exports.DOCUMENT_NOT_OPEN = exports.SessionClosedError = exports.SESSION_CLOSED = exports.DOCUMENT_SYNTAX_ERROR_CODE = exports.SAVE_FAILED_ERROR_CODE = exports.RESERVED_CLIENT_ID_ERROR_CODE = exports.DUPLICATE_CLIENT_ID_ERROR_CODE = exports.DOCUMENT_NOT_OPEN_ERROR_CODE = exports.SESSION_CLOSED_ERROR_CODE = exports.ConflictError = exports.CONFLICT_ERROR_CODE = exports.HYDRANIUM_ERROR_CODES = exports.STALE_BASE_VERSION_SAVE = exports.STALE_BASE_VERSION_UPDATE = void 0;
+exports.isResponseError = isResponseError;
+exports.reviveProtocolError = reviveProtocolError;
+exports.reviveProtocolErrorJson = reviveProtocolErrorJson;
+exports.isSessionClosedError = isSessionClosedError;
+exports.isDocumentNotOpenError = isDocumentNotOpenError;
+exports.isDuplicateClientIdError = isDuplicateClientIdError;
+exports.isReservedClientIdError = isReservedClientIdError;
+exports.isSaveFailedError = isSaveFailedError;
+exports.isDocumentSyntaxError = isDocumentSyntaxError;
 exports.isConflictError = isConflictError;
 const vscode_jsonrpc_1 = require("vscode-jsonrpc");
 const primitives_1 = require("./messages/primitives");
+const base_version_1 = require("./model-service/base-version");
+/*
+ * Every error here is a typed error: a caller reacts to it, so it has a class,
+ * a JSON-RPC code and an `is*` guard, and an English message. A typed error
+ * also carries a message identity where the framework can write an end-user
+ * sentence that needs no context. A URI may stay in that sentence; a client id
+ * or a raw version stays out of it, worded or left to `data`.
+ *
+ * An error nothing reacts to does not belong here: it stays a plain `Error`, or
+ * a named subclass without a code, at its throw site, since a code and a guard
+ * are public API that no caller would use.
+ */
+/**
+ * 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}.
+ */
+exports.STALE_BASE_VERSION_UPDATE = (0, primitives_1.defineMessage)('hydranium/protocol/stale-base-version-update', '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.
+ */
+exports.STALE_BASE_VERSION_SAVE = (0, primitives_1.defineMessage)('hydranium/protocol/stale-base-version-save', 'The save of {uri} was not applied: it was made to an older version of the document.');
 /**
- * The catalogue declaration behind {@link ConflictError}'s sentence.
+ * 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.
  */
-exports.STALE_BASED_UPDATE = (0, primitives_1.defineMessage)('hydranium/protocol/stale-based-update', 'Stale-based update for {uri}: expected v{expected}, server is at v{actual}');
+exports.HYDRANIUM_ERROR_CODES = {
+    conflict: 42001,
+    noActiveProfile: 42002,
+    referenceSettleTimeout: 42003,
+    sessionClosed: 42004,
+    documentNotOpen: 42005,
+    duplicateClientId: 42006,
+    reservedClientId: 42007,
+    saveFailed: 42008,
+    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.
  */
-exports.CONFLICT_ERROR_CODE = 1001;
+exports.CONFLICT_ERROR_CODE = exports.HYDRANIUM_ERROR_CODES.conflict;
 /**
- * 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:
  *
@@ -63,61 +107,362 @@ exports.CONFLICT_ERROR_CODE = 1001;
  * No auto-retry or auto-merge ships by default.
  */
 class ConflictError extends vscode_jsonrpc_1.ResponseError {
-    constructor(uri, expected, actual) {
-        const params = { uri, expected, actual };
+    /** `message` words what was refused: an edit, or with {@link STALE_BASE_VERSION_SAVE} a save. */
+    constructor(uri, baseVersion, actualVersion, message = exports.STALE_BASE_VERSION_UPDATE) {
         // The identity rides alongside the typed payload rather than replacing
-        // it: this class's getters and `isConflictError`'s name check are surface
-        // an adopter may bind, so the payload widens rather than changing shape.
-        super(exports.CONFLICT_ERROR_CODE, exports.STALE_BASED_UPDATE.format(params), { ...params, ...(0, primitives_1.messageData)(exports.STALE_BASED_UPDATE, params) });
+        // it. The getters, the guard and the reviver read the payload's fields,
+        // so adding the identity widens the payload rather than reshaping it.
+        super(exports.CONFLICT_ERROR_CODE, message.format({ uri }), {
+            uri,
+            baseVersion,
+            actualVersion,
+            ...(0, primitives_1.messageData)(message, { uri })
+        });
         this.name = 'ConflictError';
         // ResponseError's constructor calls `Object.setPrototypeOf(this,
         // ResponseError.prototype)` to keep its own prototype chain intact across
         // transpilation targets; that resets us to ResponseError, hiding the
         // ConflictError-specific getters. Restore the prototype here so
-        // `err.uri` / `.expected` / `.actual` resolve through this class.
+        // `err.uri` / `.baseVersion` / `.actualVersion` resolve through this
+        // class.
         Object.setPrototypeOf(this, ConflictError.prototype);
     }
+    /** The document whose version moved, see {@link ConflictErrorData.uri}. */
     get uri() {
         return this.data.uri;
     }
-    get expected() {
-        return this.data.expected;
+    /**
+     * 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() {
+        return this.data.baseVersion;
     }
-    get actual() {
-        return this.data.actual;
+    /** The server's version at the time of the throw. Not `actual`, see {@link baseVersion}. */
+    get actualVersion() {
+        return this.data.actualVersion;
     }
 }
 exports.ConflictError = ConflictError;
-/** Marker substring present in every {@link ConflictError} message, used by
- *  {@link isConflictError} as a fallback when a transport re-wraps the error
- *  and drops the JSON-RPC code. */
-const CONFLICT_ERROR_MESSAGE_MARKER = 'Stale-based update for ';
 /**
- * Type guard for {@link ConflictError}. Detection ladder:
+ * JSON-RPC code for {@link SessionClosedError}, beside {@link CONFLICT_ERROR_CODE}
+ * and for the same reason: the code survives reconstruction, the class does not.
+ */
+exports.SESSION_CLOSED_ERROR_CODE = exports.HYDRANIUM_ERROR_CODES.sessionClosed;
+/** JSON-RPC code for {@link DocumentNotOpenError}. */
+exports.DOCUMENT_NOT_OPEN_ERROR_CODE = exports.HYDRANIUM_ERROR_CODES.documentNotOpen;
+/** JSON-RPC code for {@link DuplicateClientIdError}. */
+exports.DUPLICATE_CLIENT_ID_ERROR_CODE = exports.HYDRANIUM_ERROR_CODES.duplicateClientId;
+/** JSON-RPC code for {@link ReservedClientIdError}. */
+exports.RESERVED_CLIENT_ID_ERROR_CODE = exports.HYDRANIUM_ERROR_CODES.reservedClientId;
+/** JSON-RPC code for {@link SaveFailedError}. */
+exports.SAVE_FAILED_ERROR_CODE = exports.HYDRANIUM_ERROR_CODES.saveFailed;
+/** JSON-RPC code for {@link DocumentSyntaxError}. */
+exports.DOCUMENT_SYNTAX_ERROR_CODE = exports.HYDRANIUM_ERROR_CODES.documentSyntaxError;
+/**
+ * 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.
+ */
+exports.SESSION_CLOSED = (0, primitives_1.defineMessage)('hydranium/protocol/session-closed', 'The editing session has ended.');
+/**
+ * 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.
+ */
+class SessionClosedError extends vscode_jsonrpc_1.ResponseError {
+    /**
+     * `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, message = exports.SESSION_CLOSED.format()) {
+        super(exports.SESSION_CLOSED_ERROR_CODE, message, { clientId, ...(0, primitives_1.messageData)(exports.SESSION_CLOSED) });
+        this.name = 'SessionClosedError';
+        // `ResponseError` resets the prototype to its own; see `ConflictError`.
+        Object.setPrototypeOf(this, SessionClosedError.prototype);
+    }
+    get clientId() {
+        return this.data.clientId;
+    }
+}
+exports.SessionClosedError = SessionClosedError;
+/**
+ * The catalogue declaration behind {@link DocumentNotOpenError}'s sentence. The
+ * client id stays in {@link DocumentNotOpenErrorData.clientId}.
+ */
+exports.DOCUMENT_NOT_OPEN = (0, primitives_1.defineMessage)('hydranium/protocol/document-not-open', 'The document {uri} is not open in this editing session.');
+/**
+ * Thrown when a client session writes a document it does not have open.
  *
- *  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).
+ * 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.
+ */
+class DocumentNotOpenError extends vscode_jsonrpc_1.ResponseError {
+    constructor(uri, clientId) {
+        super(exports.DOCUMENT_NOT_OPEN_ERROR_CODE, exports.DOCUMENT_NOT_OPEN.format({ uri }), {
+            uri,
+            clientId,
+            ...(0, primitives_1.messageData)(exports.DOCUMENT_NOT_OPEN, { uri })
+        });
+        this.name = 'DocumentNotOpenError';
+        Object.setPrototypeOf(this, DocumentNotOpenError.prototype);
+    }
+    get uri() {
+        return this.data.uri;
+    }
+    get clientId() {
+        return this.data.clientId;
+    }
+}
+exports.DocumentNotOpenError = DocumentNotOpenError;
+/**
+ * The catalogue declaration behind {@link DuplicateClientIdError}'s sentence.
+ * The client id stays in {@link DuplicateClientIdErrorData.clientId}.
+ */
+exports.DUPLICATE_CLIENT_ID = (0, primitives_1.defineMessage)('hydranium/protocol/duplicate-client-id', 'Could not start an editing session: its identifier is still in use by another editor.');
+/**
+ * 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.
  *
- * `instanceof ConflictError` alone would silently return `false` on the
- * reconstructed shape, so callers do not use it.
+ * 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.
  */
-function isConflictError(error) {
-    if (!(error instanceof Error)) {
-        return false;
+class DuplicateClientIdError extends vscode_jsonrpc_1.ResponseError {
+    constructor(clientId) {
+        super(exports.DUPLICATE_CLIENT_ID_ERROR_CODE, exports.DUPLICATE_CLIENT_ID.format(), { clientId, ...(0, primitives_1.messageData)(exports.DUPLICATE_CLIENT_ID) });
+        this.name = 'DuplicateClientIdError';
+        Object.setPrototypeOf(this, DuplicateClientIdError.prototype);
     }
-    if (error.name === 'ConflictError') {
-        return true;
+    get clientId() {
+        return this.data.clientId;
+    }
+}
+exports.DuplicateClientIdError = DuplicateClientIdError;
+/**
+ * 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.
+ *
+ * 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.
+ */
+class ReservedClientIdError extends vscode_jsonrpc_1.ResponseError {
+    constructor(clientId) {
+        super(exports.RESERVED_CLIENT_ID_ERROR_CODE, `Client id ${clientId} is reserved for a framework participant`, { clientId });
+        this.name = 'ReservedClientIdError';
+        Object.setPrototypeOf(this, ReservedClientIdError.prototype);
     }
-    const code = error.code;
-    if (code === exports.CONFLICT_ERROR_CODE) {
-        return true;
+    get clientId() {
+        return this.data.clientId;
     }
-    return typeof error.message === 'string' && error.message.includes(CONFLICT_ERROR_MESSAGE_MARKER);
+}
+exports.ReservedClientIdError = ReservedClientIdError;
+/**
+ * The catalogue declaration behind {@link SaveFailedError}'s message. Its
+ * `failures` names each document with the writer's own reason, which stays as
+ * written.
+ */
+exports.SAVE_FAILED = (0, primitives_1.defineMessage)('hydranium/protocol/save-failed', 'Could not save {failures}.');
+/**
+ * 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.
+ */
+class SaveFailedError extends vscode_jsonrpc_1.ResponseError {
+    constructor(failures) {
+        const named = failures.map(failure => `${failure.uri} (${failure.reason})`).join(', ');
+        super(exports.SAVE_FAILED_ERROR_CODE, exports.SAVE_FAILED.format({ failures: named }), {
+            failures,
+            ...(0, primitives_1.messageData)(exports.SAVE_FAILED, { failures: named })
+        });
+        this.name = 'SaveFailedError';
+        Object.setPrototypeOf(this, SaveFailedError.prototype);
+    }
+    get failures() {
+        return this.data.failures;
+    }
+}
+exports.SaveFailedError = SaveFailedError;
+/** The catalogue declaration behind {@link DocumentSyntaxError}'s sentence. */
+exports.DOCUMENT_SYNTAX_ERROR = (0, primitives_1.defineMessage)('hydranium/protocol/document-syntax-error', 'The edit to {uri} was not applied: the document has a syntax error. Fix it in the text first.');
+/**
+ * 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.
+ */
+class DocumentSyntaxError extends vscode_jsonrpc_1.ResponseError {
+    constructor(uri) {
+        super(exports.DOCUMENT_SYNTAX_ERROR_CODE, exports.DOCUMENT_SYNTAX_ERROR.format({ uri }), { uri, ...(0, primitives_1.messageData)(exports.DOCUMENT_SYNTAX_ERROR, { uri }) });
+        this.name = 'DocumentSyntaxError';
+        Object.setPrototypeOf(this, DocumentSyntaxError.prototype);
+    }
+    get uri() {
+        return this.data.uri;
+    }
+}
+exports.DocumentSyntaxError = DocumentSyntaxError;
+/** One entry per typed error class, keyed by its code; a class without one reaches a caller as a plain `ResponseError`. */
+const PROTOCOL_ERROR_REVIVERS = new Map([
+    [
+        exports.CONFLICT_ERROR_CODE,
+        data => (hasConflictFields(data) ? new ConflictError(data.uri, (0, base_version_1.asModelVersion)(data.baseVersion), data.actualVersion) : undefined)
+    ],
+    [exports.SESSION_CLOSED_ERROR_CODE, data => (hasClientId(data) ? new SessionClosedError(data.clientId) : undefined)],
+    [exports.DOCUMENT_NOT_OPEN_ERROR_CODE, data => (hasDocumentNotOpenFields(data) ? new DocumentNotOpenError(data.uri, data.clientId) : undefined)],
+    [exports.DUPLICATE_CLIENT_ID_ERROR_CODE, data => (hasClientId(data) ? new DuplicateClientIdError(data.clientId) : undefined)],
+    [exports.RESERVED_CLIENT_ID_ERROR_CODE, data => (hasClientId(data) ? new ReservedClientIdError(data.clientId) : undefined)],
+    [exports.SAVE_FAILED_ERROR_CODE, data => (hasSaveFailures(data) ? new SaveFailedError(data.failures) : undefined)],
+    [exports.DOCUMENT_SYNTAX_ERROR_CODE, data => (hasUri(data) ? new DocumentSyntaxError(data.uri) : undefined)]
+]);
+// One check per class of the fields its getters read, run by its reviver on
+// `data` and by its guard on the error, through the getters.
+function hasConflictFields(value) {
+    return (isRecord(value) && typeof value.uri === 'string' && typeof value.baseVersion === 'number' && typeof value.actualVersion === 'number');
+}
+function hasClientId(value) {
+    return isRecord(value) && typeof value.clientId === 'string';
+}
+function hasDocumentNotOpenFields(value) {
+    return isRecord(value) && typeof value.uri === 'string' && typeof value.clientId === 'string';
+}
+function hasUri(value) {
+    return isRecord(value) && typeof value.uri === 'string';
+}
+function hasSaveFailures(value) {
+    return isRecord(value) && isSaveFailureList(value.failures);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isSaveFailureList(value) {
+    return (Array.isArray(value) &&
+        value.every((failure) => typeof failure === 'object' &&
+            failure !== null &&
+            'uri' in failure &&
+            typeof failure.uri === 'string' &&
+            'reason' in failure &&
+            typeof failure.reason === '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.
+ */
+function isResponseError(error) {
+    return (error instanceof Error && 'code' in error && Number.isInteger(error.code) && 'toJson' in error && typeof error.toJson === 'function');
+}
+/**
+ * `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.
+ */
+function reviveProtocolError(error) {
+    if (!isResponseError(error) || error.data === null || typeof error.data !== 'object') {
+        return error;
+    }
+    const revived = PROTOCOL_ERROR_REVIVERS.get(error.code)?.({ ...error.data });
+    if (!revived) {
+        return error;
+    }
+    return Object.assign(revived, { message: error.message, data: error.data, stack: error.stack });
+}
+/**
+ * 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`.
+ */
+function reviveProtocolErrorJson(json) {
+    let envelope;
+    try {
+        envelope = JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof envelope !== 'object' || envelope === null || !('code' in envelope) || !('message' in envelope)) {
+        return undefined;
+    }
+    const { code, message } = envelope;
+    if (typeof code !== 'number' || !Number.isInteger(code) || typeof message !== 'string') {
+        return undefined;
+    }
+    const revived = reviveProtocolError(new vscode_jsonrpc_1.ResponseError(code, message, 'data' in envelope ? envelope.data : undefined));
+    return isResponseError(revived) ? revived : undefined;
+}
+/**
+ * Mark `errorClass`'s prototype with a brand its guard checks, so every
+ * instance and every subclass carries it, and nothing else does. `Symbol.for`
+ * gives each copy of this package the same symbol, which `instanceof` does
+ * not, so the key must stay the same across releases.
+ */
+function brand(errorClass, name) {
+    const key = Symbol.for(`hydranium/protocol/${name}`);
+    Object.defineProperty(errorClass.prototype, key, { value: true });
+    return key;
+}
+const CONFLICT_BRAND = brand(ConflictError, 'ConflictError');
+const SESSION_CLOSED_BRAND = brand(SessionClosedError, 'SessionClosedError');
+const DOCUMENT_NOT_OPEN_BRAND = brand(DocumentNotOpenError, 'DocumentNotOpenError');
+const DUPLICATE_CLIENT_ID_BRAND = brand(DuplicateClientIdError, 'DuplicateClientIdError');
+const RESERVED_CLIENT_ID_BRAND = brand(ReservedClientIdError, 'ReservedClientIdError');
+const SAVE_FAILED_BRAND = brand(SaveFailedError, 'SaveFailedError');
+const DOCUMENT_SYNTAX_ERROR_BRAND = brand(DocumentSyntaxError, 'DocumentSyntaxError');
+/**
+ * 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.
+ */
+function isSessionClosedError(error) {
+    return hasBrand(error, SESSION_CLOSED_BRAND) && hasClientId(error);
+}
+/** Whether `error` is a {@link DocumentNotOpenError}. See {@link isSessionClosedError}. */
+function isDocumentNotOpenError(error) {
+    return hasBrand(error, DOCUMENT_NOT_OPEN_BRAND) && hasDocumentNotOpenFields(error);
+}
+/** Whether `error` is a {@link DuplicateClientIdError}. See {@link isSessionClosedError}. */
+function isDuplicateClientIdError(error) {
+    return hasBrand(error, DUPLICATE_CLIENT_ID_BRAND) && hasClientId(error);
+}
+/** Whether `error` is a {@link ReservedClientIdError}. See {@link isSessionClosedError}. */
+function isReservedClientIdError(error) {
+    return hasBrand(error, RESERVED_CLIENT_ID_BRAND) && hasClientId(error);
+}
+/** Whether `error` is a {@link SaveFailedError}. See {@link isSessionClosedError}. */
+function isSaveFailedError(error) {
+    return hasBrand(error, SAVE_FAILED_BRAND) && hasSaveFailures(error);
+}
+/** Whether `error` is a {@link DocumentSyntaxError}. See {@link isSessionClosedError}. */
+function isDocumentSyntaxError(error) {
+    return hasBrand(error, DOCUMENT_SYNTAX_ERROR_BRAND) && hasUri(error);
+}
+/** Whether `error` is a {@link ConflictError}. See {@link isSessionClosedError}. */
+function isConflictError(error) {
+    return hasBrand(error, CONFLICT_BRAND) && hasConflictFields(error);
+}
+/**
+ * Whether `error` carries the brand `key` and the `data` record its getters
+ * read, so a guard can check the fields through them. A copy whose class
+ * lacks a getter fails that check, since the brand alone is public.
+ */
+function hasBrand(error, key) {
+    return isResponseError(error) && Reflect.get(error, key) === true && isRecord(error.data);
 }
 //# sourceMappingURL=errors.js.map

package/lib/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAyHlF,0CAYC;AAnID,mDAA+C;AAC/C,sDAA8F;AAE9F;;;;;;;GAOG;AACU,QAAA,kBAAkB,GAAG,IAAA,0BAAa,EAC5C,uCAAuC,EACvC,4EAA4E,CAC9E,CAAC;AAEF;;;;;;;;GAQG;AACU,QAAA,mBAAmB,GAAG,IAAI,CAAC;AAcxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAa,aAAc,SAAQ,8BAAgC;IAChE,YAAY,GAAW,EAAE,QAAgB,EAAE,MAAc;QACtD,MAAM,MAAM,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QACzC,uEAAuE;QACvE,0EAA0E;QAC1E,yEAAyE;QACzE,KAAK,CAAC,2BAAmB,EAAE,0BAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,GAAG,IAAA,wBAAW,EAAC,0BAAkB,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACzH,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,iEAAiE;QACjE,0EAA0E;QAC1E,qEAAqE;QACrE,gEAAgE;QAChE,kEAAkE;QAClE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,GAAG;QACJ,OAAO,IAAI,CAAC,IAAK,CAAC,GAAG,CAAC;IACzB,CAAC;IAED,IAAI,QAAQ;QACT,OAAO,IAAI,CAAC,IAAK,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED,IAAI,MAAM;QACP,OAAO,IAAI,CAAC,IAAK,CAAC,MAAM,CAAC;IAC5B,CAAC;CACH;AA3BD,sCA2BC;AAED;;mCAEmC;AACnC,MAAM,6BAA6B,GAAG,yBAAyB,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,SAAgB,eAAe,CAAC,KAAc;IAC3C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAI,KAAyC,CAAC,IAAI,CAAC;IAC7D,IAAI,IAAI,KAAK,2BAAmB,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACf,CAAC;IACD,OAAO,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,6BAA6B,CAAC,CAAC;AACrG,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/lib/format-log-arg.d.ts

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/** Options of {@link formatLogArg}. An object, so that a `map` index cannot be passed as one. */
+export interface FormatLogArgOptions {
+    /** The `space` argument of `JSON.stringify`; compact where omitted. */
+    readonly indent?: number;
+}
+/**
+ * Render a log argument as text for a log line:
+ * - a string as it is;
+ * - an error by its stack and causes;
+ * - another object as JSON, cut to a bounded size;
+ * - anything else by its description, as is an object JSON renders as nothing
+ *   or cannot render.
+ *
+ * The cut is needed because the log call serialises synchronously and every
+ * Langium AST node is cyclic. The JSON stops at `LOG_ARG_DEPTH` levels,
+ * `LOG_ARG_ITEMS` items or keys and `LOG_ARG_STRING_LENGTH` characters per
+ * string or key, and at about `LOG_ARG_LENGTH` in all. A reference back to an
+ * object that contains it reads `[Circular]`, and a BigInt its digits; the
+ * markers are JSON strings. `util.inspect` would cut too, but is Node-only.
+ *
+ * Never throws, since a log call that throws loses the line and interrupts its
+ * caller. A `%s`-style specifier is not substituted.
+ */
+export declare function formatLogArg(value: unknown, options?: FormatLogArgOptions): string;
+//# sourceMappingURL=format-log-arg.d.ts.map

package/lib/format-log-arg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-log-arg.d.ts","sourceRoot":"","sources":["../src/format-log-arg.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAgBlF,iGAAiG;AACjG,MAAM,WAAW,mBAAmB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAiBtF"}