@hydranium/protocol 1.0.0-next.6 → 1.0.0-next.61

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/rpc-connection';
+export {
+   RELAY_REPLAY_FAILED,
+   RELAY_TRANSPORT_OPEN_FAILED,
+   RELAY_TRANSPORT_READ_FAILED,
+   RELAY_TRANSPORT_WRITE_FAILED
+} from '../client/message-relay';

package/src/messages/primitives.ts

@@ -0,0 +1,215 @@
+/********************************************************************************
+ * 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 { ResponseError } from 'vscode-jsonrpc';
+
+/**
+ * The framework externalizes user-facing strings and SELECTS no locale: it
+ * relays the one its client declared and renders with whatever templates the
+ * adopter installed, defaulting to its English. Every such string carries a
+ * stable code beside that English, and exactly one side renders it — the side
+ * that knows the reading user's language.
+ *
+ * Which side that is depends on the message, not on the package. A server
+ * message is rendered by the server, at the one seam every carrier passes
+ * through, in the locale it was handed at init. A message the client tier raises
+ * is rendered there, because those fire when the server is unreachable. Nothing
+ * is rendered twice: two renders of one sentence are two authorities over it,
+ * and they diverge on the first reword.
+ *
+ * Codes are `hydranium/<unscoped-package>/<name>`. The package segment locates
+ * the declaration, so a message is declared in the package that raises it and a
+ * code never names a package it does not live in. `.` and `:` are forbidden in a
+ * segment: they are i18next's default key and namespace separators, where either
+ * silently becomes a nested lookup that misses.
+ */
+export type MessageParams = Readonly<Record<string, string | number>>;
+
+type Placeholder<S extends string> = S extends `${string}{${infer Name}}${infer Rest}` ? Name | Placeholder<Rest> : never;
+
+export type ParamsOf<S extends string> = [Placeholder<S>] extends [never]
+   ? Record<never, never>
+   : Readonly<Record<Placeholder<S>, string | number>>;
+
+/** Required exactly when the text has placeholders, absent when it does not. */
+export type ParamsArg<S extends string> = [Placeholder<S>] extends [never] ? [] : [params: ParamsOf<S>];
+
+/**
+ * Rejects a text argument already widened to `string`. Load-bearing rather than
+ * defensive: the whole compile-time guarantee is conditional on `S` inferring a
+ * literal, and for a concatenated or pre-widened text the placeholder set
+ * silently becomes empty, `format()` accepts no arguments, and the missing
+ * substitution surfaces only at runtime.
+ */
+export type LiteralText<S extends string> = string extends S ? never : S;
+
+export interface MessageDefinition<S extends string> {
+   readonly code: string;
+   readonly text: S;
+   format(...args: ParamsArg<S>): string;
+}
+
+/**
+ * Declare a message. Placeholder names are inferred from `text` rather than
+ * declared again in a type argument: a second spelling of every name is the
+ * repetition that drifts, since adding a placeholder to the sentence and not to
+ * the type compiles.
+ */
+export function defineMessage<S extends string>(code: string, text: LiteralText<S>): MessageDefinition<S> {
+   const literal = text as S;
+   return { code, text: literal, format: (...args) => interpolate(literal, args[0] ?? {}) };
+}
+
+const PLACEHOLDER = /\{([^}]+)\}/g;
+
+/**
+ * Substitute `{name}` tokens, leaving an unfilled token in place.
+ *
+ * It must not throw. This runs over an adopter's translation as well as our own
+ * text, so a typo in a foreign catalogue has to degrade to a slightly wrong
+ * sentence rather than raise inside a toast render. Re-scanning the result to
+ * detect an unfilled token is what an earlier form did, and it cannot work:
+ * `String.replace` does not rescan replacement text, so the check could not tell
+ * an unfilled placeholder from user data shaped like one — an element literally
+ * named `{separator}` crashed at the authoring site.
+ */
+export function interpolate(template: string, params: MessageParams): string {
+   // Indexed rather than `key in params`: a hand-built or version-skewed
+   // identity can arrive with no params at all, and `in` throws on a non-object
+   // where a lookup degrades.
+   const lookup = params as Record<string, string | number | undefined> | undefined;
+   return template.replace(PLACEHOLDER, (match, key: string) => {
+      const value = lookup?.[key];
+      return value === undefined ? match : String(value);
+   });
+}
+
+export interface MessageIdentity {
+   readonly code: string;
+   readonly params: MessageParams;
+}
+
+/**
+ * Envelope for a protocol `data` field. Namespaced under one key so it co-exists
+ * with a carrier's own `data` conventions rather than occupying `data` itself.
+ */
+export interface HydraniumMessageData {
+   readonly hydranium: MessageIdentity;
+}
+
+/** An identity plus its resolved English — everything a renderer needs, on any carrier. */
+export interface ResolvedMessage extends MessageIdentity {
+   readonly text: string;
+}
+
+export function messageData<S extends string>(message: MessageDefinition<S>, ...args: ParamsArg<S>): HydraniumMessageData {
+   return { hydranium: { code: message.code, params: args[0] ?? {} } };
+}
+
+/**
+ * Identity plus resolved English, for a hand-off carrying a value rather than a
+ * protocol field. The result is structured-clone safe, so it survives a process
+ * hop where one intervenes and costs nothing where none does.
+ */
+export function resolve<S extends string>(message: MessageDefinition<S>, ...args: ParamsArg<S>): ResolvedMessage {
+   return { code: message.code, text: message.format(...args), params: args[0] ?? {} };
+}
+
+/**
+ * Validates every field {@link MessageIdentity} declares, `params` included.
+ * A guard over foreign input that checks only `code` while declaring `params`
+ * non-optional hands `undefined` to the renderer, which fails with the worst
+ * polarity available: invisible in English, crashing only once a translation is
+ * loaded.
+ */
+export function hasMessageIdentity(data: unknown): data is HydraniumMessageData {
+   if (typeof data !== 'object' || data === null || Array.isArray(data) || !('hydranium' in data)) {
+      return false;
+   }
+   const identity = (data as { hydranium: unknown }).hydranium;
+   if (typeof identity !== 'object' || identity === null || Array.isArray(identity)) {
+      return false;
+   }
+   const candidate = identity as Partial<MessageIdentity>;
+   return typeof candidate.code === 'string' && typeof candidate.params === 'object' && candidate.params !== null;
+}
+
+/**
+ * A type alias rather than a subclass. Only `code`, `message` and `data` cross
+ * the wire, so a subclass buys nothing there: `instanceof` does not survive
+ * reconstruction, and the subclass costs an `Object.setPrototypeOf` in every
+ * constructor purely to undo what `ResponseError`'s own constructor does.
+ */
+export type HydraniumResponseError = ResponseError<HydraniumMessageData>;
+
+/**
+ * The numeric `code` and the message's catalogue code are unrelated and both are
+ * needed: `ResponseError.code` is an `integer`, so it cannot hold a
+ * `hydranium/…` key, and it is what a caller switches on after reconstruction.
+ */
+export function messageError<S extends string>(
+   code: number,
+   message: MessageDefinition<S>,
+   ...params: ParamsArg<S>
+): HydraniumResponseError {
+   return new ResponseError(code, message.format(...params), messageData(message, ...params));
+}
+
+/**
+ * Render on the side that knows the reading user's locale. `translations` is
+ * whatever flat `code → template` map the host exposes; omitting it is how an
+ * adopter without i18n opts out, and yields the English.
+ */
+export function renderFrameworkMessage(message: ResolvedMessage, translations?: Record<string, string>): string {
+   const template = translations?.[message.code];
+   return template ? interpolate(template, message.params) : message.text;
+}
+
+export function resolvedFromResponseError(error: ResponseError<unknown>): ResolvedMessage | undefined {
+   return hasMessageIdentity(error.data) ? { ...error.data.hydranium, text: error.message } : undefined;
+}
+
+/**
+ * The detail half of a `{detail}` placeholder. A technical error string is safe
+ * to pass as a parameter for the same reason a number is: it is not itself
+ * translatable text, so it needs no code of its own. A PROSE fragment is not,
+ * and must become one code per value instead.
+ */
+export function describeError(error: unknown): string {
+   return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Recognises a declaration among a barrel's exports. The `format` check is what
+ * discriminates: a `code` + `text` pair alone admits any object that happens to
+ * carry both.
+ */
+export function isMessageDeclaration(value: unknown): value is MessageDefinition<string> {
+   const candidate = value as { code?: unknown; text?: unknown; format?: unknown } | null;
+   return (
+      typeof candidate === 'object' &&
+      candidate !== null &&
+      typeof candidate.code === 'string' &&
+      typeof candidate.text === 'string' &&
+      typeof candidate.format === 'function'
+   );
+}
+
+/**
+ * Every declaration a `./messages` barrel exports.
+ *
+ * A caller cannot get there with `Object.values(barrel).filter(isMessageDeclaration)`:
+ * a barrel's value type is a union of its declarations AND its functions, and
+ * `filter` will not narrow a function type down to a `MessageDefinition`, so the
+ * result stays the union and reading `.code` off it does not compile. Taking the
+ * barrel as an opaque object is what makes the one-liner work.
+ */
+export function collectMessages(barrel: object): MessageDefinition<string>[] {
+   return (Object.values(barrel) as unknown[]).filter(isMessageDeclaration);
+}

package/src/model-server.ts

@@ -64,8 +64,8 @@ export interface CloseModelArgs extends TransferClientArgs {}
 export interface TransferUpdatedEvent<TDocument> {
    document: TDocument;
    sourceClientId: string;
-   /** See `ModelDocumentUpdateReason` in `./data/events` for the canonical reason set + semantics. */
-   reason: 'changed' | 'deleted' | 'rebuilt' | 'saved';
+   /** See `TransferDocumentUpdateReason` in `./data/events` for the canonical reason set + semantics. */
+   reason: 'changed' | 'rebuilt' | 'saved';
 }
 
 export interface TransferSavedEvent<TDocument> {

package/src/rpc/bind-rpc-methods.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { MessageConnection } from 'vscode-jsonrpc';
+import { ResponseError, type MessageConnection } from 'vscode-jsonrpc';
 import type { LatencyCollector } from '../latency-collector';
 import { type Disposable, DisposableCollection } from '../util';
 import { defaultIsNotification } from './create-rpc-proxy';
@@ -70,6 +70,36 @@ export interface BindRpcMethodsOptions {
     * Requests and notifications are both timed. Absent by default (no overhead).
     */
    readonly latency?: LatencyCollector;
+
+   /**
+    * Produce the `message` an outgoing rejection carries, so a user-facing
+    * error is rendered by the side that knows the reading user's language.
+    * Applied at this one chokepoint, which is what covers a caller's
+    * additional methods as well as the framework's own.
+    *
+    * Only a `ResponseError` is routed through it — a plain `Error` carries no
+    * identity to render from, and rewriting its message would relabel a
+    * developer-facing failure as a translated one. The rejection is
+    * RECONSTRUCTED rather than mutated, because the thrown value may be a
+    * shared constant; nothing is lost, since only `code`, `message` and `data`
+    * cross the wire and `instanceof` does not survive reconstruction anyway.
+    *
+    * Notifications are not covered, and "they have no reply channel" is only
+    * half the reason — a notification's own PAYLOAD can carry prose. What makes
+    * this sound is where that prose comes from: the only user-facing text on
+    * the data head's client surface is the diagnostics riding the
+    * document-updated and document-saved events, and those are read off
+    * `LangiumDocument.diagnostics`, which the document builder has already
+    * rendered at `Validated`. So they arrive rendered rather than escaping
+    * unrendered. A notification that ever carries prose of its OWN needs its
+    * own render at the raise site, as GLSP's actions do.
+    */
+   readonly renderErrorMessage?: (error: ResponseError<unknown>) => string;
+}
+
+/** The rejection to throw in place of `err`, with its message rendered. */
+function renderRejection(err: unknown, render: (error: ResponseError<unknown>) => string): unknown {
+   return err instanceof ResponseError ? new ResponseError(err.code, render(err), err.data) : err;
 }
 
 /**
@@ -91,8 +121,10 @@ export interface BindRpcMethodsOptions {
  *
  * Errors thrown synchronously from a request handler — or surfaced as a
  * rejected promise — propagate back to the caller through vscode-jsonrpc's
- * standard error envelope. Errors from a notification handler cannot, and are
- * routed to {@link BindRpcMethodsOptions.onNotificationError} instead.
+ * standard error envelope, with the message rendered when
+ * {@link BindRpcMethodsOptions.renderErrorMessage} is supplied. Errors from a
+ * notification handler cannot propagate, and are routed to
+ * {@link BindRpcMethodsOptions.onNotificationError} instead.
  *
  * Accepts either a ready connection or a `Promise<MessageConnection>` —
  * registrations queue until the connection resolves, then attach. The
@@ -154,7 +186,20 @@ export function bindRpcMethods<T extends object>(
                })
             );
          } else {
-            disposables.push(resolved.onRequest(wireName, async (params: unknown) => dispatch(params)));
+            const render = options.renderErrorMessage;
+            disposables.push(
+               resolved.onRequest(wireName, async (params: unknown) => {
+                  if (!render) {
+                     return dispatch(params);
+                  }
+                  try {
+                     // Awaited inside the try, or a rejected promise escapes it.
+                     return await dispatch(params);
+                  } catch (err: unknown) {
+                     throw renderRejection(err, render);
+                  }
+               })
+            );
          }
       }
    };

package/src/rpc/create-rpc-proxy.ts

@@ -136,6 +136,14 @@ export interface CreateRpcProxyOptions<TLocal extends object = never> {
     * `bindRpcMethods` call) still capture per-method latency. Absent by default.
     */
    readonly latency?: BindRpcMethodsOptions['latency'];
+
+   /**
+    * Forwarded to the inbound {@link localTarget} binding: renders the message
+    * an outgoing rejection carries. Only the inbound direction has rejections
+    * to render — the outbound proxy is this side making requests, and a
+    * rejection it receives was rendered by whoever answered.
+    */
+   readonly renderErrorMessage?: BindRpcMethodsOptions['renderErrorMessage'];
 }
 
 /**
@@ -225,7 +233,12 @@ export function createRpcProxy<T extends object, TLocal extends object = never>(
    // connection; see `localTarget` for why no `Disposable` is surfaced.
    const { localTarget, localMethods } = options;
    if (localTarget && localMethods && localMethods.length > 0) {
-      const binding = bindRpcMethods(connection, localTarget, localMethods, { methodNamespace, isNotification, latency: options.latency });
+      const binding = bindRpcMethods(connection, localTarget, localMethods, {
+         methodNamespace,
+         isNotification,
+         latency: options.latency,
+         renderErrorMessage: options.renderErrorMessage
+      });
       resolvedConnection.then(conn => conn.onClose(() => binding.dispose())).catch(() => undefined);
    }