@hydranium/protocol 1.0.0-next.17 → 1.0.0-next.173

package/src/errors.ts

@@ -8,32 +8,81 @@
  ********************************************************************************/
 
 import { ResponseError } from 'vscode-jsonrpc';
+import { defineMessage, type HydraniumMessageData, messageData } from './messages/primitives';
+
+/*
+ * 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}.
+ *
+ * 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 const STALE_BASED_UPDATE = defineMessage(
+   'hydranium/protocol/stale-based-update',
+   'The edit to {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.
+ *
+ * The framework reserves the block 42000 to 42999 for these, and an adopter's
+ * own codes stay outside it: after an RPC a guard matches on the code alone, so
+ * an adopter's error carrying one of these reads 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 const HYDRANIUM_ERROR_CODES = {
+   conflict: 42001,
+   noActiveProfile: 42002,
+   referenceSettleTimeout: 42003,
+   sessionClosed: 42004,
+   documentNotOpen: 42005,
+   duplicateClientId: 42006,
+   reservedClientId: 42007
+} as const;
 
 /**
- * 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 const CONFLICT_ERROR_CODE = 1001;
+export const CONFLICT_ERROR_CODE = HYDRANIUM_ERROR_CODES.conflict;
 
 /**
  * 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.
@@ -46,11 +95,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:
  *
@@ -64,18 +111,23 @@ export interface ConflictErrorData {
  * No auto-retry or auto-merge ships by default.
  */
 export class ConflictError extends ResponseError<ConflictErrorData> {
-   constructor(uri: string, expected: number, actual: number) {
-      super(CONFLICT_ERROR_CODE, `Stale-based update for ${uri}: expected v${expected}, server is at v${actual}`, {
+   constructor(uri: string, expectedVersion: number, actualVersion: number) {
+      // The identity rides alongside the typed payload rather than replacing
+      // it: `isConflictError`'s name check is surface an adopter may bind, so
+      // adding the identity widens the payload rather than reshaping it.
+      super(CONFLICT_ERROR_CODE, STALE_BASED_UPDATE.format({ uri }), {
          uri,
-         expected,
-         actual
+         expectedVersion,
+         actualVersion,
+         ...messageData(STALE_BASED_UPDATE, { 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` / `.expectedVersion` / `.actualVersion` resolve through this
+      // class.
       Object.setPrototypeOf(this, ConflictError.prototype);
    }
 
@@ -83,19 +135,201 @@ export class ConflictError extends ResponseError<ConflictErrorData> {
       return this.data!.uri;
    }
 
-   get expected(): number {
-      return this.data!.expected;
+   /**
+    * 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 {
+      return this.data!.expectedVersion;
+   }
+
+   /** The server's version at the time of the throw. Not `actual` — see {@link expectedVersion}. */
+   get actualVersion(): number {
+      return this.data!.actualVersion;
+   }
+}
+
+/**
+ * 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 const SESSION_CLOSED_ERROR_CODE = HYDRANIUM_ERROR_CODES.sessionClosed;
+/** JSON-RPC code for {@link DocumentNotOpenError}. */
+export const DOCUMENT_NOT_OPEN_ERROR_CODE = HYDRANIUM_ERROR_CODES.documentNotOpen;
+/** JSON-RPC code for {@link DuplicateClientIdError}. */
+export const DUPLICATE_CLIENT_ID_ERROR_CODE = HYDRANIUM_ERROR_CODES.duplicateClientId;
+/** JSON-RPC code for {@link ReservedClientIdError}. */
+export const RESERVED_CLIENT_ID_ERROR_CODE = HYDRANIUM_ERROR_CODES.reservedClientId;
+
+/**
+ * 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 const SESSION_CLOSED = defineMessage('hydranium/protocol/session-closed', '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 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 = SESSION_CLOSED.format()) {
+      super(SESSION_CLOSED_ERROR_CODE, message, { clientId, ...messageData(SESSION_CLOSED) });
+      this.name = 'SessionClosedError';
+      // `ResponseError` resets the prototype to its own; see `ConflictError`.
+      Object.setPrototypeOf(this, SessionClosedError.prototype);
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
    }
+}
+
+/**
+ * The catalogue declaration behind {@link DocumentNotOpenError}'s sentence. The
+ * client id stays in {@link DocumentNotOpenErrorData.clientId}.
+ */
+export const DOCUMENT_NOT_OPEN = defineMessage(
+   'hydranium/protocol/document-not-open',
+   '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;
+}
 
-   get actual(): number {
-      return this.data!.actual;
+/**
+ * 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 class DocumentNotOpenError extends ResponseError<DocumentNotOpenErrorData> {
+   constructor(uri: string, clientId: string) {
+      super(DOCUMENT_NOT_OPEN_ERROR_CODE, DOCUMENT_NOT_OPEN.format({ uri }), {
+         uri,
+         clientId,
+         ...messageData(DOCUMENT_NOT_OPEN, { uri })
+      });
+      this.name = 'DocumentNotOpenError';
+      Object.setPrototypeOf(this, DocumentNotOpenError.prototype);
    }
+
+   get uri(): string {
+      return this.data!.uri;
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
+   }
+}
+
+/**
+ * The catalogue declaration behind {@link DuplicateClientIdError}'s sentence.
+ * The client id stays in {@link DuplicateClientIdErrorData.clientId}.
+ */
+export const DUPLICATE_CLIENT_ID = defineMessage(
+   'hydranium/protocol/duplicate-client-id',
+   '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;
+}
+
+/**
+ * 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.
+ *
+ * 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 class DuplicateClientIdError extends ResponseError<DuplicateClientIdErrorData> {
+   constructor(clientId: string) {
+      super(DUPLICATE_CLIENT_ID_ERROR_CODE, DUPLICATE_CLIENT_ID.format(), { clientId, ...messageData(DUPLICATE_CLIENT_ID) });
+      this.name = 'DuplicateClientIdError';
+      Object.setPrototypeOf(this, DuplicateClientIdError.prototype);
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
+   }
+}
+
+/**
+ * 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.
+ */
+export class ReservedClientIdError extends ResponseError<{ readonly clientId: string }> {
+   constructor(clientId: string) {
+      super(RESERVED_CLIENT_ID_ERROR_CODE, `Client id ${clientId} is reserved for a framework participant`, { clientId });
+      this.name = 'ReservedClientIdError';
+      Object.setPrototypeOf(this, ReservedClientIdError.prototype);
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
+   }
+}
+
+/**
+ * Whether `error` is a {@link SessionClosedError}: by name in-process, by code
+ * after an RPC, where it arrives as a plain `ResponseError`.
+ */
+export function isSessionClosedError(error: unknown): error is SessionClosedError {
+   return hasErrorIdentity(error, 'SessionClosedError', SESSION_CLOSED_ERROR_CODE);
+}
+
+/** Whether `error` is a {@link DocumentNotOpenError}; see {@link isSessionClosedError}. */
+export function isDocumentNotOpenError(error: unknown): error is DocumentNotOpenError {
+   return hasErrorIdentity(error, 'DocumentNotOpenError', DOCUMENT_NOT_OPEN_ERROR_CODE);
+}
+
+/** Whether `error` is a {@link DuplicateClientIdError}; see {@link isSessionClosedError}. */
+export function isDuplicateClientIdError(error: unknown): error is DuplicateClientIdError {
+   return hasErrorIdentity(error, 'DuplicateClientIdError', DUPLICATE_CLIENT_ID_ERROR_CODE);
+}
+
+/** Whether `error` is a {@link ReservedClientIdError}; see {@link isSessionClosedError}. */
+export function isReservedClientIdError(error: unknown): error is ReservedClientIdError {
+   return hasErrorIdentity(error, 'ReservedClientIdError', RESERVED_CLIENT_ID_ERROR_CODE);
+}
+
+function hasErrorIdentity(error: unknown, name: string, code: number): boolean {
+   return error instanceof Error && (error.name === name || (error as Partial<ResponseError<unknown>>).code === code);
 }
 
 /** 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 ';
+const CONFLICT_ERROR_MESSAGE_MARKER = ': it was made to an older version of the document';
 
 /**
  * Type guard for {@link ConflictError}. Detection ladder:
@@ -106,8 +340,9 @@ const CONFLICT_ERROR_MESSAGE_MARKER = 'Stale-based update for ';
  *     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).
+ *  3. `error.message` contains the marker {@link STALE_BASED_UPDATE}'s
+ *     English carries — fallback for transports that re-wrap the message
+ *     and drop the code (rare).
  *
  * `instanceof ConflictError` alone would silently return `false` on the
  * reconstructed shape, so callers do not use it.

package/src/glsp-save-model-actions.ts

@@ -0,0 +1,59 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+// Declared field by field rather than extending GLSP's action types: this
+// package carries no GLSP dependency, and both GLSP heads already depend on it.
+// The fields are GLSP's own, so both actions are assignable to GLSP's
+// `RequestAction` and `ResponseAction`.
+
+/**
+ * A save of a diagram's model that the server answers, with a
+ * {@link ModelSavedAction} once the save has finished or a GLSP
+ * `RejectAction` when it fails.
+ *
+ * It carries what GLSP's `SaveModelAction` carries, and the server saves it the
+ * same way. GLSP's `SaveModelAction` is not answered: the server's only
+ * reply is a dirty-state change, which the client drops when the dirty flag
+ * does not change, so a client cannot tell which save an answer belongs to or
+ * whether a save failed.
+ */
+export interface RequestSaveModelAction {
+   kind: typeof RequestSaveModelAction.KIND;
+   /** The id the response echoes as its `responseId`. Empty until the dispatcher assigns one. */
+   requestId: string;
+   /** How long the receiver waits for its own handler, in milliseconds. */
+   timeout?: number;
+   /** The file to save to, as in GLSP's `SaveModelAction`; absent saves to the diagram's source. */
+   fileUri?: string;
+   /** GLSP's typing marker for the response. Never set. */
+   readonly _?: ModelSavedAction;
+}
+
+export namespace RequestSaveModelAction {
+   export const KIND = 'hydraniumRequestSaveModel';
+
+   export function create(options: { fileUri?: string; requestId?: string } = {}): RequestSaveModelAction {
+      return { kind: KIND, requestId: '', ...options };
+   }
+}
+
+/** The server's answer to a {@link RequestSaveModelAction} that saved. */
+export interface ModelSavedAction {
+   kind: typeof ModelSavedAction.KIND;
+   /** The `requestId` of the save this answers. The server's dispatcher sets it. */
+   responseId: string;
+}
+
+export namespace ModelSavedAction {
+   export const KIND = 'hydraniumModelSaved';
+
+   export function create(options: { responseId?: string } = {}): ModelSavedAction {
+      return { kind: KIND, responseId: '', ...options };
+   }
+}

package/src/index.ts

@@ -16,14 +16,20 @@
 
 export * from './abstract-logger';
 export * from './client';
+export * from './client-ids';
 export * from './clock';
 export * from './data';
 export * from './browser-runtime';
 export * from './debouncer';
+export * from './glsp-save-model-actions';
 export * from './errors';
 export * from './host-diagnostics';
 export * from './logger';
 export * from './latency-collector';
+// The primitives only. The `./messages` subpath additionally enumerates this
+// package's own declarations, which the root barrel already re-exports through
+// the modules that raise them.
+export * from './messages/primitives';
 export * from './patch-merge';
 export * from './noop-logger';
 export * from './observable-value';

package/src/latency-collector.ts

@@ -87,8 +87,13 @@ export interface LatencyReport {
  */
 export type LatencyRetention = { readonly kind: 'keep-all' } | { readonly kind: 'ring-buffer'; readonly maxSamplesPerMethod: number };
 
-/** Per-method state: retained samples (bounded in ring-buffer mode) plus lifetime totals. */
-interface MethodAccumulator {
+/**
+ * Per-method state: retained samples (bounded in ring-buffer mode) plus lifetime
+ * totals. The mutable tally behind {@link MethodLatency}, which is the derived
+ * report row. Held by the `protected` {@link LatencyCollector.durations}, so a
+ * subclass recording its own samples has to name it.
+ */
+export interface MethodLatencyTally {
    /** Retained durations for percentile estimation; capped in ring-buffer mode. Order is irrelevant (report sorts). */
    readonly samples: number[];
    /** Next slot to overwrite once the ring buffer is full (ring-buffer mode only). */
@@ -119,7 +124,7 @@ function percentile(sortedAscending: readonly number[], percent: number): number
  * deterministic on a fake clock.
  */
 export class LatencyCollector {
-   protected readonly durations = new Map<string, MethodAccumulator>();
+   protected readonly durations = new Map<string, MethodLatencyTally>();
    protected window: Stopwatch;
 
    constructor(

package/src/messages/index.ts

@@ -0,0 +1,36 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/**
+ * The message-externalization mechanism, plus every user-facing message
+ * `@hydranium/protocol` itself raises.
+ *
+ * Declarations stay beside their call sites and are re-exported here, so this is
+ * enumeration rather than centralization: a code's package segment has to name
+ * the package that raises it, and a shared module would make that segment a lie
+ * for every message in it. Adding a message therefore touches the file that
+ * raises it and this list, and nothing else.
+ *
+ * A barrel makes every code and English default public API, so renaming a code
+ * is a breaking change. That was already true — an adopter's catalogue keys on
+ * these codes either way — but it is now in the type system rather than implicit.
+ * The English is a fallback, not a contract; the code is the contract.
+ */
+
+export * from './primitives';
+
+export { DOCUMENT_NOT_OPEN, DUPLICATE_CLIENT_ID, SESSION_CLOSED, STALE_BASED_UPDATE } from '../errors';
+export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/rpc-connection';
+export { DATA_SESSION_RESTORE_FAILED, DATA_SESSION_UNSAVED_LOST } from '../client/data-session';
+export {
+   RELAY_REPLAY_FAILED,
+   RELAY_TRANSPORT_OPEN_FAILED,
+   RELAY_TRANSPORT_READ_FAILED,
+   RELAY_TRANSPORT_WRITE_FAILED
+} from '../client/message-relay';