@hydranium/protocol 1.0.0-next.8 → 1.0.0-next.86

package/src/client/rpc-connection.ts

@@ -0,0 +1,230 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import type { MessageConnection } from 'vscode-jsonrpc';
+import { type ResolvedMessage, defineMessage, describeError, resolve } from '../messages/primitives';
+import { type RpcProxy, createRpcProxy } from '../rpc';
+import type { DataPort } from './data-port';
+
+/**
+ * The transport never opened. A complete sentence rather than a fragment: a
+ * fragment is nested inside a sentence the framework does not own, so no
+ * translator controls the whole and the composition cannot be made to read
+ * correctly in every language.
+ */
+export const DATA_SERVER_CONNECT_FAILED = defineMessage(
+   'hydranium/protocol/data-server-connect-failed',
+   'Could not connect to the data server: {detail}'
+);
+
+export const DATA_SERVER_NOT_READY = defineMessage(
+   'hydranium/protocol/data-server-not-ready',
+   'The data server did not become ready: {detail}'
+);
+
+/** The one method a connection needs of any server: its startup gate. */
+export interface ReadyServer {
+   waitForReady(): Promise<void>;
+}
+
+/**
+ * Lifecycle reporting, for a host that raises warm-up UI around the two waits.
+ *
+ * Nothing fires until something asks for the connection — the generation is
+ * built on the first {@link RpcConnection.connected}. A host that wants the
+ * sequence at startup drives that call itself, or a workspace where nobody
+ * opens a document reports neither the connect nor the readiness its UI waits
+ * on.
+ */
+export interface RpcConnectionLifecycle {
+   /** A generation is opening its transport, including on each reconnect. */
+   readonly onConnecting?: () => void;
+   /** The server's readiness gate has settled for a generation. */
+   readonly onReady?: () => void;
+   /**
+    * A generation failed to connect or to become ready. The failure is still
+    * reported through {@link DataPort.reportError} and still rejects the
+    * awaiting caller; this is for a host that also drives its own UI.
+    */
+   readonly onFailed?: (error: unknown) => void;
+}
+
+/** Everything {@link RpcConnection} needs once a subclass has resolved its defaults. */
+export interface ResolvedRpcConnectionOptions<TClient extends object> {
+   readonly methodNamespace: string;
+   readonly clientMethods: readonly (keyof TClient & string)[];
+   readonly lifecycle: RpcConnectionLifecycle;
+}
+
+/** One connection generation: its connection, its proxy, and its readiness. */
+interface Generation<TServer extends object> {
+   readonly connection: Promise<MessageConnection>;
+   readonly server: RpcProxy<TServer>;
+   /** Set on first use; the shared readiness gate for this generation. */
+   ready?: Promise<void>;
+}
+
+/**
+ * One JSON-RPC connection to a head, with the three jobs every host adapter
+ * would otherwise re-derive above {@link DataPort}:
+ *
+ * 1. **Build the typed proxy** over the port's connection, with the caller's
+ *    wire prefix and client-method allowlist.
+ * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
+ *    across concurrent callers. A client can connect before the workspace walk
+ *    finishes, and an early request is then answered correctly from an empty
+ *    registry, which reads as a broken project tier rather than as a race.
+ * 3. **Own the reconnect policy**, by dropping its generation when the port
+ *    disposes and building a fresh one on the next request.
+ *
+ * Bounded only by {@link ReadyServer}, so a head serving a slice of the data
+ * protocol — diagnostics alone, or one with methods excluded — is still a
+ * legal server here. `DataConnection` narrows the bound because its sessions
+ * call the document methods; nothing at this layer does.
+ */
+export class RpcConnection<TServer extends ReadyServer, TClient extends object> {
+   protected readonly methodNamespace: string;
+   protected readonly clientMethods: readonly (keyof TClient & string)[];
+   protected readonly lifecycle: RpcConnectionLifecycle;
+   /** The current generation, or `undefined` before the first request / after a teardown. */
+   protected generation?: Generation<TServer>;
+   protected disposed = false;
+   protected readonly portDisposeListener: { dispose(): void };
+
+   constructor(
+      protected readonly port: DataPort,
+      protected readonly client: TClient,
+      options: ResolvedRpcConnectionOptions<TClient>
+   ) {
+      this.methodNamespace = options.methodNamespace;
+      this.clientMethods = options.clientMethods;
+      this.lifecycle = options.lifecycle;
+      this.portDisposeListener = this.port.onDispose(() => this.dropGeneration());
+   }
+
+   /**
+    * The connected, READY server proxy.
+    *
+    * Returns the proxy rather than `void` on purpose. A reconnect replaces the
+    * proxy, so a caller that cached one from an earlier call would go on
+    * addressing a dead connection with no error — handing it back per call
+    * makes the stale reference unrepresentable.
+    *
+    * Concurrent callers share one readiness promise, so `waitForReady` is
+    * awaited once per generation and not once per caller.
+    */
+   async connected(): Promise<RpcProxy<TServer>> {
+      this.assertLive();
+      const generation = this.currentGeneration();
+      if (!generation.ready) {
+         generation.ready = this.awaitReady(generation);
+      }
+      await generation.ready;
+      return generation.server;
+   }
+
+   /**
+    * The current generation's proxy WITHOUT awaiting readiness — calls queue
+    * against the connection promise.
+    *
+    * **Protected, and that is the point.** An early request is answered
+    * correctly from a registry the workspace walk has not filled yet, which
+    * reads as a broken project tier rather than as a race — so every caller has
+    * to interpose the gate, and every caller forgetting to is a silent bug.
+    * {@link connected} is the public route and returns this same proxy once the
+    * gate has settled, which leaves nothing to forget. The one caller that
+    * cannot use it is {@link awaitReady}, whose whole job is running the gate.
+    *
+    * Read per access, never cached: a reconnect replaces the generation, and a
+    * held reference would address the dead one.
+    */
+   protected get server(): RpcProxy<TServer> {
+      this.assertLive();
+      return this.currentGeneration().server;
+   }
+
+   /**
+    * Surface a failure the way this host does, through the port's sink.
+    *
+    * Here rather than only on the port so every participant sharing the
+    * connection reports through one route without being handed the transport.
+    */
+   reportError(error: unknown, reported: ResolvedMessage): void {
+      this.port.reportError(error, reported);
+   }
+
+   /** Tear down the current connection and stop tracking the port. Idempotent. */
+   dispose(): void {
+      if (this.disposed) {
+         return;
+      }
+      this.disposed = true;
+      this.portDisposeListener.dispose();
+      this.dropGeneration();
+   }
+
+   /** The live generation, building one if there is none. */
+   protected currentGeneration(): Generation<TServer> {
+      if (this.generation) {
+         return this.generation;
+      }
+      this.lifecycle.onConnecting?.();
+      const connection = this.port.connect();
+      // Rejection is reported here rather than left to float: an unhandled
+      // rejection on a connection promise is the failure mode that reads as
+      // "the model is empty" instead of "the transport never opened".
+      connection.catch((error: unknown) =>
+         this.port.reportError(error, resolve(DATA_SERVER_CONNECT_FAILED, { detail: describeError(error) }))
+      );
+      const server = createRpcProxy<TServer, TClient>(connection, {
+         methodNamespace: this.methodNamespace,
+         localTarget: this.client,
+         localMethods: this.clientMethods
+      });
+      this.generation = { connection, server };
+      return this.generation;
+   }
+
+   /** Await the connection and the server's startup gate for one generation. */
+   protected async awaitReady(generation: Generation<TServer>): Promise<void> {
+      try {
+         await generation.connection;
+         await generation.server.waitForReady();
+         this.lifecycle.onReady?.();
+      } catch (error: unknown) {
+         this.lifecycle.onFailed?.(error);
+         // Drop the generation so the next request retries rather than
+         // re-awaiting a settled rejection forever.
+         if (this.generation === generation) {
+            this.generation = undefined;
+         }
+         this.port.reportError(error, resolve(DATA_SERVER_NOT_READY, { detail: describeError(error) }));
+         throw error;
+      }
+   }
+
+   /**
+    * Discard the current generation, disposing its connection if it opened.
+    * The next {@link connected} builds a fresh one.
+    */
+   protected dropGeneration(): void {
+      const generation = this.generation;
+      this.generation = undefined;
+      if (!generation) {
+         return;
+      }
+      generation.connection.then(connection => connection.dispose()).catch(() => undefined);
+   }
+
+   protected assertLive(): void {
+      if (this.disposed) {
+         throw new Error(`${this.constructor.name} is disposed`);
+      }
+   }
+}

package/src/client-ids.ts

@@ -0,0 +1,45 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Well-known values of the wire's `clientId` / `sourceClientId` field.
+ *
+ * The framework tracks each document as belonging to one or more "clients" —
+ * typically an LSP-text client (Monaco, VS Code, …), a GLSP diagram client,
+ * and/or a structured-form client — and keys its holds and watches per
+ * `(uri, clientId)`. These three values are not real participants, so a client
+ * minting its own id must avoid them.
+ *
+ * **Here rather than in the server package, because the side that has to
+ * RECOGNISE them is the client.** An inbound `onDocumentUpdated` carries
+ * `sourceClientId`, and a consumer deciding what to do with it is asking which
+ * of these it is — so a frontend would otherwise have to depend on the server
+ * tier to name three strings, and in practice retypes the literal instead.
+ */
+
+/** Identifier for an LSP-text client (Monaco, VS Code, …). */
+export const LANGUAGE_CLIENT_ID = 'language-client';
+
+/** Fallback identifier when a document's author is unknown (e.g. cold workspace-init load). */
+export const UNKNOWN_CLIENT_ID = 'unknown';
+
+/**
+ * Synthetic author id on the `onDocumentUpdated` broadcast a data-server
+ * emits after the LAST client closed a document and the framework rebuilt it
+ * from its disk content (discarding unsaved in-session edits). Not a real
+ * client: it lets consumers distinguish the revert broadcast from
+ * client-authored updates.
+ */
+export const REVERT_ON_CLOSE_CLIENT_ID = 'revert-on-close';
+
+/**
+ * Every id the framework reserves, for a client checking that the identity it
+ * is about to mint collides with none of them.
+ */
+export const FRAMEWORK_CLIENT_IDS: readonly string[] = [LANGUAGE_CLIENT_ID, UNKNOWN_CLIENT_ID, REVERT_ON_CLOSE_CLIENT_ID];

package/src/data/data-protocol-methods.ts

@@ -59,9 +59,12 @@ export const REFERENCE_SERVER_PROTOCOL_METHODS = [
 ] as const satisfies ReadonlyArray<keyof ReferenceServerProtocol<TransferElement> & string>;
 
 /** Notification-method names on {@link DocumentClientProtocol}. */
-export const DOCUMENT_CLIENT_PROTOCOL_METHODS = ['onDocumentUpdated', 'onDocumentSaved'] as const satisfies ReadonlyArray<
-   keyof DocumentClientProtocol<TransferElement> & string
->;
+export const DOCUMENT_CLIENT_PROTOCOL_METHODS = [
+   'onDocumentUpdated',
+   'onDocumentSaved',
+   'onDocumentDeleted',
+   'onDocumentsBuilt'
+] as const satisfies ReadonlyArray<keyof DocumentClientProtocol<TransferElement> & string>;
 
 /** Notification-method names on {@link ProjectClientProtocol}. */
 export const PROJECT_CLIENT_PROTOCOL_METHODS = ['onProjectsChanged'] as const satisfies ReadonlyArray<keyof ProjectClientProtocol & string>;

package/src/data/data-server-protocol.ts

@@ -13,7 +13,13 @@ 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 {
+   ProjectsChangedEvent,
+   TransferDocumentDeletedEvent,
+   TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
+   TransferDocumentUpdatedEvent
+} from './events';
 import type {
    GetModelDocumentArgs,
    GetProjectForUriArgs,
@@ -45,7 +51,7 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
     * (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
+    * the text-document store so the caller's first `basedOn` 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
@@ -194,6 +200,22 @@ export interface DataServerProtocol<
 >
    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
@@ -262,6 +284,28 @@ export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiag
     * codepath, not a subscription codepath).
     */
    onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): 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;
 }
 
 /**

package/src/data/events.ts

@@ -30,10 +30,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)
@@ -91,6 +95,73 @@ export type TransferDocumentSavedListener<
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > = (event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>) => 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/src/errors.ts

@@ -8,6 +8,20 @@
  ********************************************************************************/
 
 import { ResponseError } from 'vscode-jsonrpc';
+import { defineMessage, type HydraniumMessageData, messageData } 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 const STALE_BASED_UPDATE = defineMessage(
+   'hydranium/protocol/stale-based-update',
+   'Stale-based update for {uri}: expected v{expectedVersion}, server is at v{actualVersion}'
+);
 
 /**
  * Application-specific JSON-RPC error code for {@link ConflictError}.
@@ -24,12 +38,12 @@ export 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;
 }
 
 /**
@@ -46,11 +60,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 on
+ * `TransferUpdateArgs` / `TransferSaveArgs`; a caller with no meaningful
+ * based-on version passes `'anything'` and gets no gating.
  *
  * Three reasonable adopter recovery strategies:
  *
@@ -64,18 +76,19 @@ 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}`, {
-         uri,
-         expected,
-         actual
-      });
+   constructor(uri: string, expectedVersion: number, actualVersion: number) {
+      const params = { uri, expectedVersion, actualVersion };
+      // 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(params), { ...params, ...messageData(STALE_BASED_UPDATE, params) });
       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,12 +96,21 @@ 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;
    }
 
-   get actual(): number {
-      return this.data!.actual;
+   /** The server's version at the time of the throw. Not `actual` — see {@link expectedVersion}. */
+   get actualVersion(): number {
+      return this.data!.actualVersion;
    }
 }
 

package/src/index.ts

@@ -16,6 +16,7 @@
 
 export * from './abstract-logger';
 export * from './client';
+export * from './client-ids';
 export * from './clock';
 export * from './data';
 export * from './browser-runtime';
@@ -24,6 +25,10 @@ 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/messages/index.ts

@@ -0,0 +1,35 @@
+/********************************************************************************
+ * 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 { STALE_BASED_UPDATE } from '../errors';
+export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/rpc-connection';
+export {
+   RELAY_REPLAY_FAILED,
+   RELAY_TRANSPORT_OPEN_FAILED,
+   RELAY_TRANSPORT_READ_FAILED,
+   RELAY_TRANSPORT_WRITE_FAILED
+} from '../client/message-relay';