@hydranium/protocol 1.0.0-next.4 → 1.0.0-next.42

package/lib/transfer-diagnostic.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-diagnostic.js","sourceRoot":"","sources":["../src/transfer-diagnostic.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAqDlF,IAAiB,kBAAkB,CA+BlC;AA/BD,WAAiB,kBAAkB;IAChC,mEAAmE;IACtD,4CAAyB,GAAG,GAAG,CAAC;IAC7C,wDAAwD;IAC3C,0CAAuB,GAAG,GAAG,CAAC;IAC3C,sFAAsF;IACzE,6CAA0B,GAAG,GAAG,CAAC;IAE9C,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC1C,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,YAAY,CAAC,UAA8B;QACxD,OAAO,UAAU,CAAC,IAAI,KAAK,eAAe,CAAC;IAC9C,CAAC;IAFe,+BAAY,eAE3B,CAAA;IAED,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,GAAG,mBAAA,0BAA0B,GAAG,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;IAChI,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,MAAM,CAAC,WAAiC;QACrD,OAAO,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAFe,yBAAM,SAErB,CAAA;IAED,SAAgB,SAAS,CAAC,WAAiC;QACxD,OAAO,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAFe,4BAAS,YAExB,CAAA;IAED,SAAgB,cAAc,CAAC,WAAiC;QAC7D,OAAO,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;IAFe,iCAAc,iBAE7B,CAAA;AACJ,CAAC,EA/BgB,kBAAkB,kCAAlB,kBAAkB,QA+BlC"}
+{"version":3,"file":"transfer-diagnostic.js","sourceRoot":"","sources":["../src/transfer-diagnostic.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAsElF,IAAiB,kBAAkB,CAsDlC;AAtDD,WAAiB,kBAAkB;IAChC,mEAAmE;IACtD,4CAAyB,GAAG,GAAG,CAAC;IAC7C,wDAAwD;IAC3C,0CAAuB,GAAG,GAAG,CAAC;IAC3C,sFAAsF;IACzE,6CAA0B,GAAG,GAAG,CAAC;IAE9C,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC1C,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,YAAY,CAAC,UAA8B;QACxD,OAAO,UAAU,CAAC,IAAI,KAAK,eAAe,CAAC;IAC9C,CAAC;IAFe,+BAAY,eAE3B,CAAA;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAgB,QAAQ,CAAC,UAA8B;QACpD,IAAI,OAAO,UAAU,CAAC,IAAI,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1E,OAAO,SAAS,CAAC;QACpB,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC;IACzF,CAAC;IALe,2BAAQ,WAKvB,CAAA;IAED,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,GAAG,mBAAA,0BAA0B,GAAG,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;IAChI,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,MAAM,CAAC,WAAiC;QACrD,OAAO,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAFe,yBAAM,SAErB,CAAA;IAED,SAAgB,SAAS,CAAC,WAAiC;QACxD,OAAO,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAFe,4BAAS,YAExB,CAAA;IAED,SAAgB,cAAc,CAAC,WAAiC;QAC7D,OAAO,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;IAFe,iCAAc,iBAE7B,CAAA;AACJ,CAAC,EAtDgB,kBAAkB,kCAAlB,kBAAkB,QAsDlC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/protocol",
-  "version": "1.0.0-next.4",
+  "version": "1.0.0-next.42",
   "description": "Generic, language-agnostic types, constants, and pure utilities for the hydranium framework.",
   "keywords": [
     "hydranium",
@@ -41,6 +41,14 @@
       "types": "./lib/data/index.d.ts",
       "default": "./lib/data/index.js"
     },
+    "./messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
+    "./lib/messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
     "./testing": {
       "types": "./lib/testing/index.d.ts",
       "default": "./lib/testing/index.js"
@@ -88,7 +96,7 @@
     "vscode-jsonrpc": "9.0.1"
   },
   "peerDependencies": {
-    "vscode-jsonrpc": "^8.0.0 || ^9.0.0"
+    "vscode-jsonrpc": "9.0.1"
   },
   "engines": {
     "node": ">=22.13"
@@ -96,5 +104,6 @@
   "publishConfig": {
     "access": "public"
   },
+  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. It does NOT prevent a NESTED copy — `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship — so a consumer of the GLSP head must pin the chain in its own manifest.",
   "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error."
 }

package/src/client/data-events.ts

@@ -8,7 +8,14 @@
  ********************************************************************************/
 
 import { Emitter, type Event } from 'vscode-jsonrpc';
-import type { DataClientProtocol, ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from '../data';
+import type {
+   DataClientProtocol,
+   ProjectsChangedEvent,
+   TransferDocumentDeletedEvent,
+   TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
+   TransferDocumentUpdatedEvent
+} from '../data';
 import type { Project } from '../project';
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
@@ -40,12 +47,18 @@ export class DataEvents<
 > implements DataClientProtocol<TTransfer, TDiagnostic, TProject> {
    protected readonly documentUpdatedEmitter = new Emitter<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>();
    protected readonly documentSavedEmitter = new Emitter<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>();
+   protected readonly documentDeletedEmitter = new Emitter<TransferDocumentDeletedEvent>();
+   protected readonly documentsBuiltEmitter = new Emitter<TransferDocumentsBuiltEvent>();
    protected readonly projectsChangedEmitter = new Emitter<ProjectsChangedEvent<TProject>>();
 
    /** A build-phase event for a watched document. Carries the originating `sourceClientId`. */
    readonly onDidUpdateDocument: Event<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>> = this.documentUpdatedEmitter.event;
    /** A watched document was persisted to disk. */
    readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>> = this.documentSavedEmitter.event;
+   /** A document's backing file was removed, watched or not. Any watch survives. */
+   readonly onDidDeleteDocument: Event<TransferDocumentDeletedEvent> = this.documentDeletedEmitter.event;
+   /** Documents built that nobody watches — re-read anything derived from them. */
+   readonly onDidBuildDocuments: Event<TransferDocumentsBuiltEvent> = this.documentsBuiltEmitter.event;
    /** The project set changed. */
    readonly onDidChangeProjects: Event<ProjectsChangedEvent<TProject>> = this.projectsChangedEmitter.event;
 
@@ -59,6 +72,14 @@ export class DataEvents<
       this.documentSavedEmitter.fire(event);
    }
 
+   onDocumentDeleted(event: TransferDocumentDeletedEvent): void {
+      this.documentDeletedEmitter.fire(event);
+   }
+
+   onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void {
+      this.documentsBuiltEmitter.fire(event);
+   }
+
    onProjectsChanged(event: ProjectsChangedEvent<TProject>): void {
       this.projectsChangedEmitter.fire(event);
    }
@@ -66,6 +87,8 @@ export class DataEvents<
    dispose(): void {
       this.documentUpdatedEmitter.dispose();
       this.documentSavedEmitter.dispose();
+      this.documentDeletedEmitter.dispose();
+      this.documentsBuiltEmitter.dispose();
       this.projectsChangedEmitter.dispose();
    }
 }

package/src/client/data-port.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import type { Event, MessageConnection } from 'vscode-jsonrpc';
+import type { ResolvedMessage } from '../messages/primitives';
 
 /**
  * The one thing a host has to supply for the data head: a live JSON-RPC
@@ -77,10 +78,16 @@ export interface DataPort {
     *
     * It exists because the alternative is worse in both directions: this tier
     * cannot import a host's UI, and swallowing the error makes a dead
-    * connection look like an empty model. `context` names what was being
-    * attempted, not where in the code it happened.
+    * connection look like an empty model.
+    *
+    * `reported` is a complete sentence plus the identity needed to render it in
+    * another language. It carries a value rather than using a protocol field
+    * because this tier does not know whether a process hop intervenes — in a
+    * webview host the render happens across one — and a `ResolvedMessage` is
+    * structured-clone safe either way. Render it with `renderFrameworkMessage`;
+    * passing no translation map yields the English.
     */
-   reportError(error: unknown, context: string): void;
+   reportError(error: unknown, reported: ResolvedMessage): void;
 
    /**
     * Fires when the host tears the transport down and the current connection

package/src/client/data-session.ts

@@ -9,11 +9,28 @@
 
 import type { MessageConnection } from 'vscode-jsonrpc';
 import { DATA_CLIENT_PROTOCOL_METHODS, DATA_SERVER_WIRE_PREFIX, type DataClientProtocol, type DataServerProtocol } from '../data';
+import { defineMessage, describeError, resolve } from '../messages/primitives';
 import { type RpcProxy, createRpcProxy } from '../rpc';
 import type { TransferDocument } from '../transfer-document';
 import type { TransferElement } from '../transfer-element';
 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}'
+);
+
 /** Options for {@link DataSession}. */
 export interface DataSessionOptions {
    /**
@@ -168,7 +185,9 @@ export class DataSession<TTransfer extends TransferElement> {
       // 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, 'connecting to the data server'));
+      connection.catch((error: unknown) =>
+         this.port.reportError(error, resolve(DATA_SERVER_CONNECT_FAILED, { detail: describeError(error) }))
+      );
       const server = createRpcProxy<DataServerProtocol<TTransfer>, DataClientProtocol<TTransfer>>(connection, {
          methodNamespace: this.methodNamespace,
          localTarget: this.client,
@@ -189,7 +208,7 @@ export class DataSession<TTransfer extends TransferElement> {
          if (this.generation === generation) {
             this.generation = undefined;
          }
-         this.port.reportError(error, 'waiting for the data server to become ready');
+         this.port.reportError(error, resolve(DATA_SERVER_NOT_READY, { detail: describeError(error) }));
          throw error;
       }
    }

package/src/client/message-relay.ts

@@ -8,8 +8,29 @@
  ********************************************************************************/
 
 import { Emitter, type Disposable, type Event, type Message, type MessageReader, type MessageWriter } from 'vscode-jsonrpc';
+import { defineMessage, describeError, resolve, type ResolvedMessage } from '../messages/primitives';
 import type { PostMessageChannel } from './post-message-transport';
 
+export const RELAY_TRANSPORT_OPEN_FAILED = defineMessage(
+   'hydranium/protocol/relay-transport-open-failed',
+   'Could not open the transport to relay: {detail}'
+);
+
+export const RELAY_TRANSPORT_READ_FAILED = defineMessage(
+   'hydranium/protocol/relay-transport-read-failed',
+   'Could not read from the relayed transport: {detail}'
+);
+
+export const RELAY_TRANSPORT_WRITE_FAILED = defineMessage(
+   'hydranium/protocol/relay-transport-write-failed',
+   'Could not write to the relayed transport: {detail}'
+);
+
+export const RELAY_REPLAY_FAILED = defineMessage(
+   'hydranium/protocol/relay-replay-failed',
+   'Could not replay a buffered message to the relayed transport: {detail}'
+);
+
 /**
  * The framed side of a relay: the reader/writer pair over whatever transport the
  * host actually holds — a TCP socket to the data-server, a child process' stdio,
@@ -30,13 +51,14 @@ export interface RelayTransport {
 export interface MessageRelayOptions {
    /**
     * Surface a failure the way the host does. Same contract as
-    * `DataPort.reportError`: `context` names what was being attempted.
+    * `DataPort.reportError`: `reported` is a complete sentence plus the identity
+    * needed to render it in another language.
     *
     * A relay has no other way to report — it sits between two transports and
     * owns neither, so a swallowed error here presents as a form that never
     * populates.
     */
-   readonly reportError?: (error: unknown, context: string) => void;
+   readonly reportError?: (error: unknown, reported: ResolvedMessage) => void;
 }
 
 /** A live relay. Dispose to tear both directions down. */
@@ -143,7 +165,7 @@ export function relayToPostMessageChannel(
          bufferSubscription?.dispose();
          bufferSubscription = undefined;
          buffered.length = 0;
-         options.reportError?.(error, 'opening the transport to relay');
+         options.reportError?.(error, resolve(RELAY_TRANSPORT_OPEN_FAILED, { detail: describeError(error) }));
          closeFramedSide();
          return false;
       }
@@ -166,12 +188,12 @@ export function relayToPostMessageChannel(
          opened.reader.listen(message => channel.post(message)),
          opened.reader.onClose(() => closeFramedSide()),
          opened.reader.onError(error => {
-            options.reportError?.(error, 'reading from the relayed transport');
+            options.reportError?.(error, resolve(RELAY_TRANSPORT_READ_FAILED, { detail: describeError(error) }));
             closeFramedSide();
          }),
          channel.onMessage(message => {
             void opened.writer.write(message).catch((error: unknown) => {
-               options.reportError?.(error, 'writing to the relayed transport');
+               options.reportError?.(error, resolve(RELAY_TRANSPORT_WRITE_FAILED, { detail: describeError(error) }));
             });
          })
       );
@@ -183,7 +205,7 @@ export function relayToPostMessageChannel(
 
       for (const message of buffered) {
          void opened.writer.write(message).catch((error: unknown) => {
-            options.reportError?.(error, 'replaying a buffered message to the relayed transport');
+            options.reportError?.(error, resolve(RELAY_REPLAY_FAILED, { detail: describeError(error) }));
          });
       }
       buffered.length = 0;

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,
@@ -262,6 +268,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;
 }
 
 /**
@@ -64,18 +78,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 +98,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

@@ -24,6 +24,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/data-session';
+export {
+   RELAY_REPLAY_FAILED,
+   RELAY_TRANSPORT_OPEN_FAILED,
+   RELAY_TRANSPORT_READ_FAILED,
+   RELAY_TRANSPORT_WRITE_FAILED
+} from '../client/message-relay';