@source-repo/rpc 3.0.0 → 3.1.0

package/README.md

@@ -15,44 +15,48 @@
 
 # @source-repo/rpc
 
-Source RPC — TypeScript RPC over socket.io and MQTT 5. A class is the contract: the server hands one live instance
-to `exposeClassInstance`, the client gets a typed proxy of the same class, and calling a method on
-the proxy runs it on that instance. No code generation and no schema files required, though there is
-a schema when you want arguments checked at runtime.
+TypeScript RPC for a network of peers — a browser tab, a Node service, and a plant full of devices — over socket.io and MQTT 5, with one programming model across all of them.
+
+A class is the contract: the server hands one live instance to `exposeClassInstance`, the client gets a typed proxy of the same class, and calling a method on the proxy runs it on that instance. No code generation and no schema files required, though there is a schema when you want arguments checked at runtime.
 
 ```
 npm install @source-repo/rpc
 ```
 
-ESM only, Node 18.17 or later, and it runs in the browser. Contracts can be extracted from your
-source and checked for breaking changes with [`@source-repo/rpc-cli`](https://www.npmjs.com/package/@source-repo/rpc-cli), which also serves
-a browser console for a live network and ships the bus as a container.
+ESM only, Node 18.17 or later, and it runs in the browser.
 
-Upgrading from 1.x? [`CHANGELOG.md`](https://github.com/source-repo/rpc/blob/main/CHANGELOG.md) lists what breaks.
+**If all you need is a browser talking to a Node server, use [tRPC](https://trpc.io).** It is very good at that and far more widely used. This is for the case it does not cover: more than two parties, not all on the same kind of link, and commands where sending one twice is not free.
 
-### What is in it
+## What is in it
 
-- **Two transports, one programming model.** socket.io for browsers and anything that dials out;
-  MQTT 5 for the plant, with a [documented wire format](https://github.com/source-repo/rpc/blob/main/docs/mqtt5-frame-spec.md)
-  that a plain MQTT.js peer can speak without any of this code.
+- **Command semantics for machinery.** A method declares whether repeating it is free, harmless or dangerous, as part of the contract rather than as a comment; a caller can tell *did not run* from *may have run*; a durable idempotency hook makes a redelivered command run once; calls into one instance can be serialised. This is the part you will not find elsewhere — see [Commands](#commands).
+- **Deadlines that mean something.** A request carries the time its caller will wait, the broker is given the same deadline, and a server refuses to run a command whose caller has already gone.
+- **Two transports, one programming model.** socket.io for browsers and anything that dials out; MQTT 5 for the plant, with a [documented wire format](https://github.com/source-repo/rpc/blob/main/docs/mqtt5-frame-spec.md) that a plain MQTT.js peer can speak without any of this code.
+- **Any peer can be a bus, and a browser tab can host a server.** A frame is addressed to a name, not a socket, so a server that exposes nothing and forwards everything is a switchboard — and a peer that cannot listen is still addressable. See [Connecting](#connecting).
+- **Contracts checked at runtime**, and compared between versions so a change that would break a deployed caller fails a build rather than a plant.
 - **Events**, with subscriptions replayed after a reconnect so a dropped link does not go quiet.
-- **Contracts checked at runtime**, and compared between versions so a change that would break a
-  deployed caller fails a build rather than a plant.
-- **Command semantics for machinery.** A method says whether repeating it is free, harmless or
-  dangerous; a caller can tell *did not run* from *may have run*; a durable idempotency hook makes a
-  redelivered command run once; calls into one instance can be serialised. See [Commands](#commands).
-- **Deadlines that mean something.** A request carries the time its caller will wait, the broker is
-  given the same deadline, and a server refuses to run a command whose caller has already gone.
-- **Authentication both ways.** Per-connection tokens where there is a connection, per-frame
-  signing (HMAC or Ed25519) where there is not, with replay protection and pinned peer names.
-- **TLS**, including trusting a plant's own certificate authority rather than switching checks off.
+- **Authentication both ways.** Per-connection tokens where there is a connection, per-frame signing (HMAC or Ed25519) where there is not, with replay protection and pinned peer names. Plus TLS, including trusting a plant's own certificate authority rather than switching checks off.
 - **Introspection.** A server can describe itself — namespaces, methods, argument types, events.
-  That is what the browser console reads, and what lets the CLI serve a whole network to an AI
-  assistant over [MCP](https://modelcontextprotocol.io): list the peers, describe them, call them.
+
+That last one is what the tooling is built on. [`@source-repo/rpc-cli`](https://www.npmjs.com/package/@source-repo/rpc-cli) extracts a contract from your source and fails a build on a breaking change; it also serves a browser console for a live network, taps traffic crossing a bus, records and replays a session, and hands the whole network to an AI assistant over [MCP](https://modelcontextprotocol.io).
+
+Upgrading from 1.x? [`CHANGELOG.md`](https://github.com/source-repo/rpc/blob/main/CHANGELOG.md) lists what breaks.
+
+## Contents
+
+**Getting going** — [Quick start](#quick-start) · [Connecting](#connecting) · [Exposing methods](#exposing-methods)
+
+**Machinery** — [Commands](#commands) · [Errors](#errors) · [Events and reconnection](#events-and-reconnection)
+
+**Contracts** — [Checking arguments](#checking-arguments) · [Describing a server](#describing-a-server)
+
+**Security and transport** — [Authentication and authorization](#authentication-and-authorization) · [MQTT](#mqtt)
+
+**Reference** — [Options](#options) · [Browser use](#browser-use) · [Peer routing](#peer-routing) · [Low level: modules](#low-level-modules) · [Development](#development)
 
 ## Quick start
 
-The class both sides share. Nothing here is msgrpc-specific — no decorators, no base class:
+The class both sides share. Nothing here is Source RPC-specific — no decorators, no base class:
 
 ```typescript
 // calculator.ts
@@ -100,44 +104,25 @@ await client.close()
 
 Three things worth noticing:
 
-**The instance is a real, long-lived object.** It is constructed once, by you, and every call runs
-against that same object — which is why `add` accumulates. State lives where you would put it
-anyway, in fields. Nothing is constructed or discarded per call, and the instance you passed in is
-still yours to read and mutate locally. (A class can instead be *registered* for peers to
-instantiate remotely, but that is off by default and rarely what you want — see
-[The management surface](#the-management-surface).)
+**The instance is a real, long-lived object.** It is constructed once, by you, and every call runs against that same object — which is why `add` accumulates. State lives where you would put it anyway, in fields. Nothing is constructed or discarded per call, and the instance you passed in is still yours to read and mutate locally. (A class can instead be *registered* for peers to instantiate remotely, but that is off by default and rarely what you want — see [The management surface](#the-management-surface).)
 
-**`import type`** on the client is the point of the whole design: the client compiles against the
-class but imports none of its code, so the implementation never reaches the browser bundle. In a
-monorepo, put the class in a package both sides depend on. If the client cannot see the class at
-all — a different language, a different repo — describe the surface with an `interface` instead and
-pass that to `proxy<T>()`.
+**`import type`** on the client is the point of the whole design: the client compiles against the class but imports none of its code, so the implementation never reaches the browser bundle. In a monorepo, put the class in a package both sides depend on. If the client cannot see the class at all — a different language, a different repo — describe the surface with an `interface` instead and pass that to `proxy<T>()`.
 
-**`.remote!`** — `proxy()` returns a small record (`{ name, target?, remote? }`) whose `remote` is
-the typed proxy. The field is optional in the type because the record is assembled piece by piece;
-`proxy()` awaits `ready()` first, so what it hands back always has one, hence the `!`.
+**`.remote!`** — `proxy()` returns a small record (`{ name, target?, remote? }`) whose `remote` is the typed proxy. The field is optional in the type because the record is assembled piece by piece; `proxy()` awaits `ready()` first, so what it hands back always has one, hence the `!`.
 
 ## Connecting
 
-Before the table: it is worth ten lines on what a network of these looks like, because everything
-below follows from one idea.
+Before the table: it is worth ten lines on what a network of these looks like, because everything below follows from one idea.
 
-**An `RpcServer` exposes methods; an `RpcClient` calls them.** For a single link that is the whole
-API, and the quick start above has already shown it.
+**An `RpcServer` exposes methods; an `RpcClient` calls them.** For a single link that is the whole API, and the quick start above has already shown it.
 
-The rest comes from this: **a peer is anything on the network with a name**, and a frame is
-addressed to a *name*, not to a socket. A server has a name, a client has a name. Once addressing
-works that way, three things follow:
+The rest comes from this: **a peer is anything on the network with a name**, and a frame is addressed to a *name*, not to a socket. A server has a name, a client has a name. Once addressing works that way, three things follow:
 
-- **A server can call as well as answer.** `RpcServer.proxy()` is the same call as the client's, and
-  hands back the same typed object — it just travels over a link the server already has.
-- **A server can relay.** A frame addressed to a name it is not, but can see, is passed along
-  instead of executed. That is what makes a peer reachable *through* another peer.
+- **A server can call as well as answer.** `RpcServer.proxy()` is the same call as the client's, and hands back the same typed object — it just travels over a link the server already has.
+- **A server can relay.** A frame addressed to a name it is not, but can see, is passed along instead of executed. That is what makes a peer reachable *through* another peer.
 - **A peer that only relays is a bus.** Nothing else is needed to build one.
 
-So a **bus** — hub, broker, switchboard, whichever word you prefer — is not a different kind of
-program. It is an `RpcServer` that exposes nothing and forwards everything. An MQTT broker plays
-exactly the same part for an MQTT network; msgrpc just does not require you to have one.
+So a **bus** — hub, broker, switchboard, whichever word you prefer — is not a different kind of program. It is an `RpcServer` that exposes nothing and forwards everything. An MQTT broker plays exactly the same part for an MQTT network; msgrpc just does not require you to have one.
 
 The server's `transports` say where it listens; the client's url says where to reach it.
 
@@ -148,10 +133,7 @@ The server's `transports` say where it listens; the client's url says where to r
 | `transports: [{ server: httpServer }]` | `new RpcClient(origin)` — share an `http.Server` you already have, so the page and its RPC arrive on one port |
 | `transports: [{ brokerurl: 'mqtt://broker:1883' }]` | `new RpcClient('mqtt://broker:1883', { defaultTarget: 'plantServer' })` |
 
-**7843 is the Source RPC port**, exported as `defaultWebSocketPort`, and 7844 — `defaultWebPort` —
-is where anything serving a browser puts its HTTP port. Adjacent rather than an offset apart,
-because they are read together. Both are deliberately clear of the 80xx range, where a developer's
-other work already is.
+**7843 is the Source RPC port**, exported as `defaultWebSocketPort`, and 7844 — `defaultWebPort` — is where anything serving a browser puts its HTTP port. Adjacent rather than an offset apart, because they are read together. Both are deliberately clear of the 80xx range, where a developer's other work already is.
 
 | | | |
 | --- | --- | --- |
@@ -162,23 +144,13 @@ other work already is.
 | `8843` | `rpc-tls` | the same, with a certificate |
 | `8844` | `console-tls` | |
 
-The encrypted pair is a thousand above rather than beside: the last two digits still match, so it is
-one number to remember with a rule attached, but **no range covers a plain port and an encrypted
-one**. `allow 7843:7846` is the firewall rule somebody writes at the end of a long day, and it must
-not be able to publish the clear-text bus by fencepost while meaning to open only the encrypted one.
-MQTT draws the same line between 1883 and 8883, so the habit transfers.
+The encrypted pair is a thousand above rather than beside: the last two digits still match, so it is one number to remember with a rule attached, but **no range covers a plain port and an encrypted one**. `allow 7843:7846` is the firewall rule somebody writes at the end of a long day, and it must not be able to publish the clear-text bus by fencepost while meaning to open only the encrypted one. MQTT draws the same line between 1883 and 8883, so the habit transfers.
 
-These say where to *find* a service; nothing enforces them. A port carries TLS because it was given
-a certificate, never because of its number — and the CLI's `--cert`/`--key` move a server to its
-encrypted port on their own, so the convention holds without anyone having to remember it.
+These say where to *find* a service; nothing enforces them. A port carries TLS because it was given a certificate, never because of its number — and the CLI's `--cert`/`--key` move a server to its encrypted port on their own, so the convention holds without anyone having to remember it.
 
-**One process needs one port.** `{ server: httpServer }` above is how a page and its RPC arrive
-together: socket.io answers `/socket.io` on that listener and your own handler serves everything
-else. The console is built exactly this way. The second number is for running two programs on one
-host.
+**One process needs one port.** `{ server: httpServer }` above is how a page and its RPC arrive together: socket.io answers `/socket.io` on that listener and your own handler serves everything else. The console is built exactly this way. The second number is for running two programs on one host.
 
-A server may hold several at once, serving the same exposed instances to each. One server can face a
-browser over socket.io and a plant network over MQTT:
+A server may hold several at once, serving the same exposed instances to each. One server can face a browser over socket.io and a plant network over MQTT:
 
 ```typescript
 const server = new RpcServer({
@@ -190,9 +162,7 @@ server.exposeClassInstance(new Plant(), 'plant')     // reachable over both
 
 ### A bus without a broker
 
-Here is that bus, in full. It exposes nothing, so every frame that reaches it is addressed to
-somebody else and gets forwarded. Everything else dials *it*, and gets what MQTT would have given
-them: presence, addressing by name, and any peer able to call any other.
+Here is that bus, in full. It exposes nothing, so every frame that reaches it is addressed to somebody else and gets forwarded. Everything else dials *it*, and gets what MQTT would have given them: presence, addressing by name, and any peer able to call any other.
 
 ```typescript
 const bus = new RpcServer({ name: 'bus', transports: [{ port: 7843 }] })
@@ -205,14 +175,9 @@ const oven = await cellSrv.proxy<Oven>('oven', 'ovenSrv')
 await oven.remote!.temperature()
 ```
 
-Read the last two lines again, because they are the part that surprises people. `cellSrv` is a
-*server* — and it is calling out. `RpcServer.proxy()` takes the name of a namespace and the name of
-the peer holding it, and returns the same typed object `RpcClient.proxy()` would. The call leaves
-over the connection `cellSrv` already opened to the bus, the bus forwards it to `ovenSrv`, and the
-answer comes back the same way.
+Read the last two lines again, because they are the part that surprises people. `cellSrv` is a *server* — and it is calling out. `RpcServer.proxy()` takes the name of a namespace and the name of the peer holding it, and returns the same typed object `RpcClient.proxy()` would. The call leaves over the connection `cellSrv` already opened to the bus, the bus forwards it to `ovenSrv`, and the answer comes back the same way.
 
-Nothing here dialled `ovenSrv` directly. It may not even be dialable — it could be a browser tab.
-The bus is what they have in common, and that is enough.
+Nothing here dialled `ovenSrv` directly. It may not even be dialable — it could be a browser tab. The bus is what they have in common, and that is enough.
 
 ### One peer, several links
 
@@ -224,8 +189,7 @@ A peer holds one link per transport, and the two kinds are not interchangeable:
 | `{ connect: url }` | **opens** exactly one, to that url |
 | `{ brokerurl }` | opens one, to that broker |
 
-A socket cannot both accept and dial, so a Node service that serves browsers *and* joins a bus
-genuinely holds two:
+A socket cannot both accept and dial, so a Node service that serves browsers *and* joins a bus genuinely holds two:
 
 ```
 browsers ──▶ :8080 ┐
@@ -233,21 +197,16 @@ browsers ──▶ :8080 ┐
                    ┘
 ```
 
-But **every link carries traffic both ways**. `proxy()` picks whichever transport reaches the
-target, so:
+But **every link carries traffic both ways**. `proxy()` picks whichever transport reaches the target, so:
 
-- calling a browser that dialled in costs no new connection — the frame goes back down the socket
-  that browser opened;
+- calling a browser that dialled in costs no new connection — the frame goes back down the socket that browser opened;
 - calling a peer on the bus goes out over the link `nodeSrv` already holds.
 
-Which is why a peer that both serves and calls needs no `RpcClient` at all. Adding one to do the
-calling would open a *third* connection and put a second name on the network for what is really one
-program — and over MQTT, that means a second broker session too.
+Which is why a peer that both serves and calls needs no `RpcClient` at all. Adding one to do the calling would open a *third* connection and put a second name on the network for what is really one program — and over MQTT, that means a second broker session too.
 
 ### Serving over a connection you open
 
-A browser cannot listen, so a page that wants to *host* a service has to dial out. `connect` gives
-an `RpcServer` an outbound link, and it serves over it exactly as it would over one it accepted:
+A browser cannot listen, so a page that wants to *host* a service has to dial out. `connect` gives an `RpcServer` an outbound link, and it serves over it exactly as it would over one it accepted:
 
 ```typescript
 const panel = new RpcServer({ name: 'cellPanel', transports: [{ connect: 'https://hub.plant' }] })
@@ -258,53 +217,32 @@ Whatever it connects to relays calls to it — see [Discovery](#discovery).
 
 ### Names and targets
 
-Every peer has a `name`. A server's name is how callers address it; a client's name is how the
-server routes events back and, when authenticating, who it is.
+Every peer has a `name`. A server's name is how callers address it; a client's name is how the server routes events back and, when authenticating, who it is.
 
-Over a single socket there is one server, so the default target `'*'` finds it and names can be left
-alone. Over a broker there are many, so a caller has to say which — either once, with
-`defaultTarget`, or per proxy:
+Over a single socket there is one server, so the default target `'*'` finds it and names can be left alone. Over a broker there are many, so a caller has to say which — either once, with `defaultTarget`, or per proxy:
 
 ```typescript
 const plant = await client.proxy<Plant>('plant', 'plantServer')
 ```
 
-Client names must be unique among the peers sharing a server; the default is a UUID, which is unique
-but tells you nothing in a log. Over MQTT a name is also the broker client id, and a broker allows
-one connection per id, so two peers sharing a name disconnect each other in a loop.
+Client names must be unique among the peers sharing a server; the default is three words - `brisk-otter-cable` - rather than a UUID, because a name is also a log line, a peer-list entry and an MQTT client id, and a UUID tells you nothing in any of them. Over MQTT a name is also the broker client id, and a broker allows one connection per id, so two peers sharing a name disconnect each other in a loop.
 
 ### Discovery
 
-Every peer announces its name when it connects, and is told who else is there. The events are the
-same on both transports, so code that watches a network does not care which one it is on:
+Every peer announces its name when it connects, and is told who else is there. The events are the same on both transports, so code that watches a network does not care which one it is on:
 
 ```typescript
 transport.on(TransportEvent.peerOnline, (peer) => console.log(peer, 'is up'))
 transport.on(TransportEvent.peerGone, (peer) => console.log(peer, 'is gone'))
 ```
 
-Over MQTT this is retained presence: subscribing to `<prefix>/presence/+` hands over everyone
-already online, and a last will covers a peer that dies rather than leaves. Over socket.io the
-server keeps the list and sends it to each peer that announces itself.
-
-**A name is an address, so two peers must not share one.** Both transports report a collision as
-`TransportEvent.peerDisplaced`, and warn once. The newcomer takes the address either way: a peer
-reconnecting after a blip announces itself while the old connection may still look live, and
-refusing it would lock a peer out of its own name. What the event is for is the other case — two
-peers genuinely running under one name send each other's replies into the wrong place, which reads
-as calls timing out for no reason and is close to undiagnosable if nothing says so.
-
-Which end finds out differs, because the two protocols enforce it in different places. Over
-socket.io the **server** sees a second connection announce a name it already holds. Over MQTT there
-is no server in the middle and nothing has to detect anything: the client id is derived from the
-peer name, so the broker hands the session over and tells the **displaced peer** why, with reason
-code `0x8E` — which needs MQTT 5, since 3.1.1 has no reason codes and the connection simply closes.
-
-**A server relays for the peers connected to it.** A frame addressed to another peer it can see is
-forwarded rather than executed locally, which is what makes a peer that can only dial out reachable
-at all. A server holding both a socket.io listener and a broker connection therefore bridges them:
-a browser peer discovers a peer that exists only on the broker, and calls it, with the call arriving
-under the browser peer's own name rather than the bridge's.
+Over MQTT this is retained presence: subscribing to `<prefix>/presence/+` hands over everyone already online, and a last will covers a peer that dies rather than leaves. Over socket.io the server keeps the list and sends it to each peer that announces itself.
+
+**A name is an address, so two peers must not share one.** Both transports report a collision as `TransportEvent.peerDisplaced`, and warn once. The newcomer takes the address either way: a peer reconnecting after a blip announces itself while the old connection may still look live, and refusing it would lock a peer out of its own name. What the event is for is the other case — two peers genuinely running under one name send each other's replies into the wrong place, which reads as calls timing out for no reason and is close to undiagnosable if nothing says so.
+
+Which end finds out differs, because the two protocols enforce it in different places. Over socket.io the **server** sees a second connection announce a name it already holds. Over MQTT there is no server in the middle and nothing has to detect anything: the client id is derived from the peer name, so the broker hands the session over and tells the **displaced peer** why, with reason code `0x8E` — which needs MQTT 5, since 3.1.1 has no reason codes and the connection simply closes.
+
+**A server relays for the peers connected to it.** A frame addressed to another peer it can see is forwarded rather than executed locally, which is what makes a peer that can only dial out reachable at all. A server holding both a socket.io listener and a broker connection therefore bridges them: a browser peer discovers a peer that exists only on the broker, and calls it, with the call arriving under the browser peer's own name rather than the bridge's.
 
 ```typescript
 const bridge = new RpcServer({
@@ -324,65 +262,40 @@ const hub = new RpcServer({
 })
 ```
 
-The rule is asked once per pair of peers, and the answer covers the traffic going back — a call has
-a reply and usually events after it, and a rule written about the caller would otherwise strand
-them. Without `authenticate`, a relaying server prints a warning the first time it forwards
-anything: `source` is a claim until a connection vouches for it, so it passes on whatever it is
-told.
+The rule is asked once per pair of peers, and the answer covers the traffic going back — a call has a reply and usually events after it, and a rule written about the caller would otherwise strand them. Without `authenticate`, a relaying server prints a warning the first time it forwards anything: `source` is a claim until a connection vouches for it, so it passes on whatever it is told.
 
 ### More than one hop
 
-A peer announces not only its own name but the peers reachable **through** it, so a server that is a
-hub for its own peers and a member of a bus makes both sides visible to each other:
+A peer announces not only its own name but the peers reachable **through** it, so a server that is a hub for its own peers and a member of a bus makes both sides visible to each other:
 
 ```
 panel1 ── cellCtl ── bus ── hmi
 ```
 
-`cellCtl` advertises `panel1` upwards; the bus routes to `panel1` by handing frames to `cellCtl`,
-which passes them inwards. Calls, replies and events all traverse it, and `panel1` leaving
-propagates the same way. Verified to three hops.
+`cellCtl` advertises `panel1` upwards; the bus routes to `panel1` by handing frames to `cellCtl`, which passes them inwards. Calls, replies and events all traverse it, and `panel1` leaving propagates the same way. Covered by a test at two hops.
 
 Two rules keep that from eating itself:
 
-- **Split horizon.** A peer is never advertised back along the link it was learned from, and the
-  list a server hands a newly connected peer excludes whatever that peer reaches for it. Without
-  either, two hubs each conclude the other is the way to a peer and it disappears from everyone
-  further out.
-- **A hop limit.** Frames carry a count and are dropped after 8 relays. Split horizon keeps a tree's
-  tables loop-free, but a mesh that has just lost a link can hold a cycle until the tables settle,
-  and a frame going round one never stops on its own.
+- **Split horizon.** A peer is never advertised back along the link it was learned from, and the list a server hands a newly connected peer excludes whatever that peer reaches for it. Without either, two hubs each conclude the other is the way to a peer and it disappears from everyone further out.
+- **A hop limit.** Frames carry a count and are dropped after 8 relays. Split horizon keeps a tree's tables loop-free, but a mesh that has just lost a link can hold a cycle until the tables settle, and a frame going round one never stops on its own.
 
-A peer offered by two links keeps the first; the second is remembered, and used if the first goes
-away. A peer announcing *itself* always wins over one merely carried.
+A peer offered by two links keeps the first; the second is remembered, and used if the first goes away. A peer announcing *itself* always wins over one merely carried.
 
-**What relaying is not.** It does not make a server a broker in the MQTT sense. There is no
-store-and-forward, no queueing for a peer that is not connected, and no fan-out — a frame is passed
-to one peer that is there now, or reported as `unroutable`. Discovery is not a routing protocol
-either: there are no metrics and no shortest path, only reachability.
+**What relaying is not.** It does not make a server a broker in the MQTT sense. There is no store-and-forward, no queueing for a peer that is not connected, and no fan-out — a frame is passed to one peer that is there now, or refused - answered with a `TransportError` back down the link it arrived on, and reported as `unroutable` here. Refused rather than dropped, because a caller only ever saw a drop as an unexplained timeout. Discovery is not a routing protocol either: there are no metrics and no shortest path, only reachability.
 
 ### Ready and close
 
-`await server.ready()` and `await client.ready()` resolve when every transport is connected, and
-throw after `readyTimeout` (30 s; `0` waits forever) rather than hanging with no diagnostic. Expose
-your instances *before* `ready()`: a resumed MQTT session is handed its queued requests the moment it
-connects.
+`await server.ready()` and `await client.ready()` resolve when every transport is connected, and throw after `readyTimeout` (30 s; `0` waits forever) rather than hanging with no diagnostic. Expose your instances *before* `ready()`: a resumed MQTT session is handed its queued requests the moment it connects.
 
-`await client.close()` rejects any in-flight calls at once instead of leaving them to time out, and
-forgets the subscriptions it held. `await server.close()` closes every transport, which is what
-tells the peers on the other side that it went away.
+`await client.close()` rejects any in-flight calls at once instead of leaving them to time out, and forgets the subscriptions it held. `await server.close()` closes every transport, which is what tells the peers on the other side that it went away.
 
 ### Encoding
 
-MsgPack by default, so `Uint8Array` and `Date` cross the wire as themselves rather than as string
-encodings of themselves. `useMsgPack: false` selects JSON on both sides — readable in a broker
-inspector, at the cost of those two types. Both ends must agree.
+MsgPack by default, so `Uint8Array` and `Date` cross the wire as themselves rather than as string encodings of themselves. `useMsgPack: false` selects JSON on both sides — readable in a broker inspector, at the cost of those two types. Both ends must agree.
 
 ## Exposing methods
 
-`exposeClassInstance` walks the prototype chain and publishes every function it finds, so a helper
-a class never meant to offer becomes callable by anyone who can reach the transport. Marking the
-intended methods turns that into an allow-list.
+`exposeClassInstance` walks the prototype chain and publishes every function it finds, so a helper a class never meant to offer becomes callable by anyone who can reach the transport. Marking the intended methods turns that into an allow-list.
 
 ```typescript
 import { rpc, rpcNamespace } from '@source-repo/rpc'
@@ -397,20 +310,13 @@ class Plant {
 server.exposeClassInstance(new Plant())      // name taken from @rpcNamespace
 ```
 
-Standard ECMAScript decorators, so no `experimentalDecorators` is needed. Marks are inherited, so a
-subclass keeps its parent's. Without decorators, `exposeMethods(Plant, ['writeSetpoint'])` does the
-same and rejects names that are not methods.
+Standard ECMAScript decorators, so no `experimentalDecorators` is needed. Marks are inherited, so a subclass keeps its parent's. Without decorators, `exposeMethods(Plant, ['writeSetpoint'])` does the same and rejects names that are not methods.
 
-A class that marks nothing publishes every method on its prototype chain, which is what makes the
-plain style above work. Set `requireExplicitExposure` on `RpcServer` to refuse such a class instead,
-which makes the discipline enforceable across a project.
+A class that marks nothing publishes every method on its prototype chain, which is what makes the plain style above work. Set `requireExplicitExposure` on `RpcServer` to refuse such a class instead, which makes the discipline enforceable across a project.
 
-`@rpcNamespace` also tells the extraction CLI which namespace a class belongs to, since the name
-would otherwise exist only at the `exposeClassInstance` call site.
+`@rpcNamespace` also tells the extraction CLI which namespace a class belongs to, since the name would otherwise exist only at the `exposeClassInstance` call site.
 
-Both decorators take options: `@rpc({ semantics: 'non-repeatable-command' })` says what calling a
-method does to the world, and `@rpcNamespace('cell', { execution: 'serial' })` says whether calls
-into the instance may overlap. Both are in [Commands](#commands), which is where they matter.
+Both decorators take options: `@rpc({ semantics: 'non-repeatable-command' })` says what calling a method does to the world, and `@rpcNamespace('cell', { execution: 'serial' })` says whether calls into the instance may overlap. Both are in [Commands](#commands), which is where they matter.
 
 ### More than one, and without a class
 
@@ -425,62 +331,17 @@ const plant = await client.proxy<Plant>('plant')
 const history = await client.proxy<History>('history')
 ```
 
-`exposeObject` publishes an object's own function properties rather than a prototype chain, which
-suits a handful of functions that never wanted to be a class.
-
-## Errors
-
-A call rejects with an `RpcError` carrying a `code`, the remote `message`, and the remote stack in
-`remoteStack` when the peer sent one.
-
-```typescript
-import { RpcError } from '@source-repo/rpc'
-
-try {
-    await calculator.remote!.square(3)
-} catch (e) {
-    if (e instanceof RpcError) console.log(e.code, e.message, e.remoteStack)
-}
-```
-
-| code | meaning |
-| --- | --- |
-| `Exception` | the exposed method threw |
-| `MethodNotFound` | the instance exists but the method is not exposed |
-| `ClassNotFound` | nothing is exposed under that name |
-| `Timeout` | no response within `callTimeout`, or the server refused to run it that late |
-| `TransportError` | the link dropped, or the message could not be encoded or sent |
-| `Unauthorized` | the caller is not authenticated and the server requires it |
-| `Forbidden` | the caller is authenticated but not permitted this call |
-| `InvalidParams` | the arguments do not match the schema for that method |
-| `IncompatibleVersion` | the caller's contract cannot be served by this one |
-| `UnknownOutcome` | the request was sent and its fate is not known - it may have run |
-
-**A call that timed out will not run afterwards.** Every request carries the time its caller will
-still wait, so a server that reaches the method late answers `Timeout` instead of running it, and an
-MQTT broker is given the same deadline as its message expiry rather than a longer one of its own.
-Without that, a request queued for a restarting server arrives after the operator has already been
-told the call failed and acted on it - which for a read is wasted work and for `start pump` is a
-machine moving when nobody expects it to.
-
-It is a duration on the wire rather than a moment, so no two peers ever have to agree what time it
-is - a browser page's clock belongs to whoever is sitting at it. `refuseExpiredCalls` on the server
-handler turns the refusal off.
+`exposeObject` publishes an object's own function properties rather than a prototype chain, which suits a handful of functions that never wanted to be a class.
 
 ## Commands
 
-Most RPC libraries make it easy to call a function. Rather fewer distinguish *the call failed* from
-*I lost the answer to a command that may well have run*, and on a plant that is the distinction that
-matters: retrying a read costs a round trip, and retrying a start costs a second start.
+Most RPC libraries make it easy to call a function. Rather fewer distinguish *the call failed* from *I lost the answer to a command that may well have run*, and on a plant that is the distinction that matters: retrying a read costs a round trip, and retrying a start costs a second start.
 
 ### The honest statement
 
-> **Delivery and execution are at least once, unless the method is guarded by a durable idempotency
-> store.**
+> **Delivery and execution are at least once, unless the method is guarded by a durable idempotency store.**
 
-That is true of every RPC system without such a store; the difference is whether it is written down.
-QoS 1 is at-least-once by definition, the in-memory duplicate cache dies with the process that holds
-it, and a server can change something physical and then fail before it says so.
+That is true of every RPC system without such a store; the difference is whether it is written down. QoS 1 is at-least-once by definition, the in-memory duplicate cache dies with the process that holds it, and a server can change something physical and then fail before it says so.
 
 ### What a method does to the world
 
@@ -498,10 +359,7 @@ class Pump {
 | `idempotent-command` | leaves the same state as doing it once | `setSetpoint(1200)`, `close()` |
 | `non-repeatable-command` | does it again | `dispense()`, `advanceBatch()` |
 
-It is part of the contract, not a comment: `extract` reads it out of the decorator, `describe()`
-reports it, and `check` calls it a **breaking change** when a method becomes more dangerous to
-repeat than the version a caller was built against. Every type still lines up in that case, which is
-exactly why nothing else would catch it.
+It is part of the contract, not a comment: `extract` reads it out of the decorator, `describe()` reports it, and `check` calls it a **breaking change** when a method becomes more dangerous to repeat than the version a caller was built against. Every type still lines up in that case, which is exactly why nothing else would catch it.
 
 Undeclared stays undeclared. The library will not guess that a method is safe to repeat.
 
@@ -517,52 +375,37 @@ try {
 }
 ```
 
-`TransportError` now means the request never left - a failed encode, a closed link, a broker that
-refused the publish - so the command certainly did not run. `UnknownOutcome` means it did leave and
-nothing came back. `Timeout` is the same uncertainty with a more specific cause, and should be read
-the same way for a command.
+`TransportError` now means the request never left - a failed encode, a closed link, a broker that refused the publish - so the command certainly did not run. `UnknownOutcome` means it did leave and nothing came back. `Timeout` is the same uncertainty with a more specific cause, and should be read the same way for a command.
 
 ### Running a command once
 
-Give a server somewhere durable to record what a non-repeatable command did, and a redelivery after
-a crash is answered from the record instead of run again:
+Give a server somewhere durable to record what a non-repeatable command did, and a redelivery after a crash is answered from the record instead of run again:
 
 ```typescript
 const server = new RpcServer({ idempotency: myRedisStore })      // RpcIdempotencyStore
 ```
 
-The library ships the interface and a `MemoryIdempotencyStore` for tests - deliberately no database,
-and the memory one is not an answer to the problem, since it dies exactly when the durable one would
-earn its keep.
+The library ships the interface and a `MemoryIdempotencyStore` for tests - deliberately no database, and the memory one is not an answer to the problem, since it dies exactly when the durable one would earn its keep.
 
-The store is consulted only for `non-repeatable-command` methods, so reads pay nothing. What it
-records is keyed by the **request id**, which makes a redelivered packet the same command. An
-operator pressing the button again is a *different* request, and only the caller knows the two are
-one intent:
+The store is consulted only for `non-repeatable-command` methods, so reads pay nothing. What it records is keyed by the **request id**, which makes a redelivered packet the same command. An operator pressing the button again is a *different* request, and only the caller knows the two are one intent:
 
 ```typescript
 await pump.remote!.$with({ idempotencyKey: workOrder }).dispense()
 ```
 
-`$with` returns another proxy for the same instance, so the key never leaks into calls that did not
-ask for it. The outcome is recorded **before** the answer is sent - the other order leaves a window
-where the caller has the result and the store does not.
+`$with` returns another proxy for the same instance, so the key never leaks into calls that did not ask for it. The outcome is recorded **before** the answer is sent - the other order leaves a window where the caller has the result and the store does not.
 
-A store that cannot be reached refuses the command with `UnknownOutcome` rather than running it.
-Failing open would turn an unreachable guard into exactly the double execution it was installed to
-prevent.
+A store that cannot be reached refuses the command with `UnknownOutcome` rather than running it. Failing open would turn an unreachable guard into exactly the double execution it was installed to prevent.
 
 ### Calls that overlap
 
-Calls run side by side, which is right for stateless services and unrelated devices, and wrong for
-one long-lived object holding mutable state - where
+Calls run side by side, which is right for stateless services and unrelated devices, and wrong for one long-lived object holding mutable state - where
 
 ```
 setMode('manual'); start(); setSetpoint(80)
 ```
 
-from one caller can interleave with `stop(); setMode('automatic')` from another and leave a machine
-in a combination neither asked for.
+from one caller can interleave with `stop(); setMode('automatic')` from another and leave a machine in a combination neither asked for.
 
 ```typescript
 @rpcNamespace('cell', { execution: 'serial' })                     // one call at a time
@@ -573,29 +416,60 @@ server.exposeClassInstance(fleet, 'fleet', {                       // one call a
 })
 ```
 
-A key function is how a server fronting many devices keeps each device's commands in order without
-serialising itself behind the slowest of them.
+A key function is how a server fronting many devices keeps each device's commands in order without serialising itself behind the slowest of them.
 
-**`parallel` stays the default**, despite `serial` being the safer-sounding choice. A serial
-instance that calls back into itself over RPC deadlocks - the second call queues behind the first,
-which is waiting for it - so serialising by default would break re-entrant designs that work today,
-silently and only under load. It is one line to opt in, and the class that needs it knows.
+**`parallel` stays the default**, despite `serial` being the safer-sounding choice. A serial instance that calls back into itself over RPC deadlocks - the second call queues behind the first, which is waiting for it - so serialising by default would break re-entrant designs that work today, silently and only under load. It is one line to opt in, and the class that needs it knows.
 
-The queue is also where the deadline is read: a command that waited behind others until its caller
-gave up is refused rather than run late.
+The queue is also where the deadline is read: a command that waited behind others until its caller gave up is refused rather than run late.
 
 ### Not built
 
-- **Cancellation.** A deadline bounds a call, but nothing tells a running method to stop. Doing it
-  properly needs a cancel frame *and* handler cooperation, and a library cannot supply the second.
-- **`online-only` delivery.** Now that the broker's expiry is the caller's own timeout, a request
-  for an absent peer already dies when the caller stops waiting; failing immediately instead would
-  save the wait and little else.
-- **A per-call invocation context.** Handlers are plain methods, and threading a context through
-  every signature costs more than it returns. The store gets the full invocation; a method that
-  needs its own idempotency has the arguments it was called with.
-- **Global admission limits.** Concurrency caps and message-size bounds are about availability
-  rather than correctness, and belong with a production profile.
+- **Cancellation.** A deadline bounds a call, but nothing tells a running method to stop. Doing it properly needs a cancel frame *and* handler cooperation, and a library cannot supply the second.
+- **`online-only` delivery.** Now that the broker's expiry is the caller's own timeout, a request for an absent peer already dies when the caller stops waiting; failing immediately instead would save the wait and little else.
+- **A per-call invocation context.** Handlers are plain methods, and threading a context through every signature costs more than it returns. The store gets the full invocation; a method that needs its own idempotency has the arguments it was called with.
+- **Global admission limits.** Concurrency caps and message-size bounds are about availability rather than correctness, and belong with a production profile.
+
+## Errors
+
+A call rejects with an `RpcError` carrying a `code`, the remote `message`, and the remote stack in `remoteStack` when the peer sent one.
+
+```typescript
+import { RpcError } from '@source-repo/rpc'
+
+try {
+    await calculator.remote!.square(3)
+} catch (e) {
+    if (e instanceof RpcError) console.log(e.code, e.message, e.remoteStack)
+}
+```
+
+| code | meaning |
+| --- | --- |
+| `Exception` | the exposed method threw |
+| `MethodNotFound` | the instance exists but the method is not exposed |
+| `ClassNotFound` | nothing is exposed under that name |
+| `Timeout` | no response within `callTimeout`, or the server refused to run it that late |
+| `TransportError` | the link dropped, or the message could not be encoded or sent |
+| `Unauthorized` | the caller is not authenticated and the server requires it |
+| `Forbidden` | the caller is authenticated but not permitted this call |
+| `InvalidParams` | the arguments do not match the schema for that method |
+| `IncompatibleVersion` | the caller's contract cannot be served by this one |
+| `UnknownOutcome` | the request was sent and its fate is not known - it may have run |
+
+**A method can choose its own code.** Throwing an error whose `code` is one of the nine above — `Unauthorized`, `Forbidden`, `InvalidParams`, `IncompatibleVersion`, `ClassNotFound`, `MethodNotFound`, `TransportError`, `Timeout`, `UnknownOutcome` — sends that code rather than `Exception`:
+
+```typescript
+@rpc async writeSetpoint(value: number) {
+    if (!this.permitted) throw Object.assign(new Error('this cell is in local mode'), { code: 'Forbidden' })
+    if (await this.downstream.timedOut()) throw Object.assign(new Error('the drive did not answer'), { code: 'UnknownOutcome' })
+}
+```
+
+The list is an allow-list, so an ordinary Node error carrying `code: 'ENOENT'` stays `Exception` rather than becoming a protocol code that means something else. `UnknownOutcome` is the one worth reaching for: it is the honest reply from a gateway whose own downstream call was lost, where inventing a result and reporting a plain exception would both claim more than is known.
+
+**A call that timed out will not run afterwards.** Every request carries the time its caller will still wait, so a server that reaches the method late answers `Timeout` instead of running it, and an MQTT broker is given the same deadline as its message expiry rather than a longer one of its own. Without that, a request queued for a restarting server arrives after the operator has already been told the call failed and acted on it - which for a read is wasted work and for `start pump` is a machine moving when nobody expects it to.
+
+It is a duration on the wire rather than a moment, so no two peers ever have to agree what time it is - a browser page's clock belongs to whoever is sitting at it. `refuseExpiredCalls` on the server handler turns the refusal off.
 
 ## Events and reconnection
 
@@ -607,8 +481,7 @@ await plant.remote!.on('alarm', (message: string) => console.log(message))
 await plant.remote!.off('alarm', handler)     // same handler reference
 ```
 
-`RpcClient` is itself an `EventEmitter` reporting the state of its link, so an application can show
-it rather than infer it from failed calls:
+`RpcClient` is itself an `EventEmitter` reporting the state of its link, so an application can show it rather than infer it from failed calls:
 
 ```typescript
 import { TransportEvent } from '@source-repo/rpc'
@@ -621,22 +494,15 @@ client.on(TransportEvent.connected, ({ restoredSubscriptions }) =>
 Reconnection is handled for you:
 
 - The underlying transport reconnects on its own (socket.io and mqtt.js both do).
-- On every reconnect the client replays its event subscriptions. This restores server-side state if
-  the server restarted, and re-identifies the client so pushed events reach it again.
-- Replaying is idempotent: the server will not stack a second listener for a subscription it already
-  holds.
+- On every reconnect the client replays its event subscriptions. This restores server-side state if the server restarted, and re-identifies the client so pushed events reach it again.
+- Replaying is idempotent: the server will not stack a second listener for a subscription it already holds.
 - When a client's connection drops, the server releases the event subscriptions it held for it.
-- An event is delivered only to subscriptions taken out on the peer and namespace it came from.
-  Watching `alarm` on two instances, or on two peers over one MQTT transport, keeps them apart.
-- `off()` is not subject to `authorize`: a subscription is keyed by the peer that made it, so a peer
-  can only drop its own, and refusing to let someone stop receiving events would be strange.
+- An event is delivered only to subscriptions taken out on the peer and namespace it came from. Watching `alarm` on two instances, or on two peers over one MQTT transport, keeps them apart.
+- `off()` is not subject to `authorize`: a subscription is keyed by the peer that made it, so a peer can only drop its own, and refusing to let someone stop receiving events would be strange.
 
 ## Checking arguments
 
-Types are a compile-time promise between a client and a server that share a class. Nothing about
-MQTT or a browser page guarantees the caller is one of those — a Python historian or a Node-RED flow
-calling in over MQTT 5 shares none of your types — so a schema lets the server check what it was
-actually sent.
+Types are a compile-time promise between a client and a server that share a class. Nothing about MQTT or a browser page guarantees the caller is one of those — a Python historian or a Node-RED flow calling in over MQTT 5 shares none of your types — so a schema lets the server check what it was actually sent.
 
 ```typescript
 const schema: RpcSchema = {
@@ -654,25 +520,13 @@ const schema: RpcSchema = {
 const server = new RpcServer({ transports: [{ brokerurl }], schema })
 ```
 
-A call that does not match is refused with `InvalidParams` before it reaches the method, and the
-message names the offending position: `argument 0: expected number, got string (this server serves
-plant@3)`.
+A call that does not match is refused with `InvalidParams` before it reaches the method, and the message names the offending position: `argument 0: expected number, got string (this server serves plant@3)`.
 
-`source-rpc extract` writes this file from your source rather than you writing it by hand. Note what it
-can and cannot see: `value: number` becomes `{ kind: 'number' }`, because a range like `0..2000` is
-a runtime invariant that TypeScript does not carry. Extraction gives you shape checking — types,
-arity, whether an argument is required. Bounds have to be added to the schema or expressed in the
-type.
+`source-rpc extract` writes this file from your source rather than you writing it by hand. Note what it can and cannot see: `value: number` becomes `{ kind: 'number' }`, because a range like `0..2000` is a runtime invariant that TypeScript does not carry. Extraction gives you shape checking — types, arity, whether an argument is required. Bounds have to be added to the schema or expressed in the type.
 
-The type language is small on purpose. It describes what MsgPack actually carries, so `bytes`
-(`Uint8Array`) and `date` are values rather than string encodings, and it is checkable without
-pulling a validation engine into a package that ships to browsers and embedded targets. `ref` names
-a shared or recursive type; nesting beyond 32 levels is refused rather than exhausting the stack.
+The type language is small on purpose. It describes what MsgPack actually carries, so `bytes` (`Uint8Array`) and `date` are values rather than string encodings, and it is checkable without pulling a validation engine into a package that ships to browsers and embedded targets. `ref` names a shared or recursive type; nesting beyond 32 levels is refused rather than exhausting the stack.
 
-`object` describes a known shape and `record` an open one — `{ [tag: string]: Reading }`, which is
-how plant data usually arrives. A record checks every value against one type and leaves the keys
-open, or constrains them with `keyPattern`; `maxEntries` bounds it the way `maxItems` bounds an
-array, since a dictionary is the other shape a caller can grow without limit.
+`object` describes a known shape and `record` an open one — `{ [tag: string]: Reading }`, which is how plant data usually arrives. A record checks every value against one type and leaves the keys open, or constrains them with `keyPattern`; `maxEntries` bounds it the way `maxItems` bounds an array, since a dictionary is the other shape a caller can grow without limit.
 
 ```typescript
 readings: { params: [], returns: { kind: 'record', values: { kind: 'ref', name: 'Reading' } } }
@@ -685,9 +539,7 @@ readings: { params: [], returns: { kind: 'record', values: { kind: 'ref', name:
 | `validation: 'off'` | disable checking without removing the schema |
 | `validateResults` | check what handlers return too; off by default, since it is a self-check |
 
-Set `validate: false` on a namespace to skip a hot path where the cost is not worth paying.
-Validating `writeSetpoint(number)` is not the same proposition as validating a ten-thousand element
-telemetry array on every publish.
+Set `validate: false` on a namespace to skip a hot path where the cost is not worth paying. Validating `writeSetpoint(number)` is not the same proposition as validating a ten-thousand element telemetry array on every publish.
 
 ### Serving older callers
 
@@ -697,32 +549,20 @@ Give a client the contract it was built against and it declares the version on e
 const client = new RpcClient(url, { schema: contractTheClientWasBuiltAgainst })
 ```
 
-The server keeps earlier versions of a namespace under `history`, and compares the caller's contract
-with the one it now serves. It is a structural comparison, not an equality check, so a caller whose
-contract still holds keeps working and only a genuine incompatibility is refused — with
-`IncompatibleVersion` and the reason:
+The server keeps earlier versions of a namespace under `history`, and compares the caller's contract with the one it now serves. It is a structural comparison, not an equality check, so a caller whose contract still holds keeps working and only a genuine incompatibility is refused — with `IncompatibleVersion` and the reason:
 
 ```
 plant@1 is not compatible with plant@2: writeSetpoint argument 0 narrowed, so a value the
 caller may send is no longer accepted
 ```
 
-The rule is ordinary function subtyping. **Parameters are contravariant**: the current contract has
-to accept everything the old one allowed, so widening a parameter is safe and narrowing it is not.
-**Returns are covariant**: everything the current contract can return has to fit what the old caller
-expects, so narrowing a return is safe and widening it is not. Adding an optional field or an
-optional argument is safe; adding a required one is not. Events run the other way, since the server
-emits and the caller receives.
+The rule is ordinary function subtyping. **Parameters are contravariant**: the current contract has to accept everything the old one allowed, so widening a parameter is safe and narrowing it is not. **Returns are covariant**: everything the current contract can return has to fit what the old caller expects, so narrowing a return is safe and widening it is not. Adding an optional field or an optional argument is safe; adding a required one is not. Events run the other way, since the server emits and the caller receives.
 
-The comparison happens once per peer and version, not per call, and is conservative: where it cannot
-prove compatibility it reports incompatibility, since a false "safe" is the expensive direction.
+The comparison happens once per peer and version, not per call, and is conservative: where it cannot prove compatibility it reports incompatibility, since a false "safe" is the expensive direction.
 
-A caller that declares nothing is simply not version-checked — only its arguments are. A caller
-declaring a version the server has no history for is allowed by default, since truncating history is
-a legitimate operational choice; `unknownVersion: 'reject'` refuses it instead.
+A caller that declares nothing is simply not version-checked — only its arguments are. A caller declaring a version the server has no history for is allowed by default, since truncating history is a legitimate operational choice; `unknownVersion: 'reject'` refuses it instead.
 
-`source-rpc check` runs the same comparison at build time, so a change that would refuse a deployed peer
-fails the build instead of surfacing when that peer next calls.
+`source-rpc check` runs the same comparison at build time, so a change that would refuse a deployed peer fails the build instead of surfacing when that peer next calls.
 
 ## Describing a server
 
@@ -734,36 +574,21 @@ const server = new RpcServer({ transports: [{ brokerurl }], exposeIntrospection:
 const described = await (await client.proxy<Introspection>('msgrpc')).remote!.describe()
 ```
 
-It reports each namespace with its class, its contract version, whether the instance was created at
-runtime, its methods with types when a schema describes them, and its events with how many peers are
-currently subscribed. `source-rpc console` renders this in a browser.
+It reports each namespace with its class, its contract version, whether the instance was created at runtime, its methods with types when a schema describes them, and its events with how many peers are currently subscribed. `source-rpc console` renders this in a browser.
 
-`describe` describes itself: the `source-rpc` namespace comes with its own contract, so a peer reading a
-server sees the type it will get back, and `validation: 'required'` does not refuse the one call
-made to find out what is there. Its named types are prefixed — `msgrpc.ServerDescription` — because
-the schema has one type map shared by every namespace, and a plant defining its own `TypeNode`
-should not find `describe()` described against it. A schema that already defines `source-rpc` is left
-untouched.
+`describe` describes itself: the `msgrpc` namespace comes with its own contract, so a peer reading a server sees the type it will get back, and `validation: 'required'` does not refuse the one call made to find out what is there. Its named types are prefixed — `msgrpc.ServerDescription` — because the schema has one type map shared by every namespace, and a plant defining its own `TypeNode` should not find `describe()` described against it. A schema that already defines `msgrpc` is left untouched.
 
-**Off by default, and subject to `authorize` like any other call.** Listing every class, method and
-live instance is reconnaissance, and instance names on a plant network tend to encode plant
-structure.
+**Off by default, and subject to `authorize` like any other call.** Listing every class, method and live instance is reconnaissance, and instance names on a plant network tend to encode plant structure.
 
-This is msgrpc's own shape rather than a borrowed one. OpenAPI is HTTP-shaped and cannot describe a
-server pushing events; AsyncAPI models everything as a channel, which fights an RPC surface. Either
-would mean describing this system in someone else's concepts.
+This is msgrpc's own shape rather than a borrowed one. OpenAPI is HTTP-shaped and cannot describe a server pushing events; AsyncAPI models everything as a channel, which fights an RPC surface. Either would mean describing this system in someone else's concepts.
 
 ## Authentication and authorization
 
-Both are off by default, so an unconfigured server accepts any peer and allows any exposed call. The
-management surface is *not* off by default in the same sense — it is simply never published unless
-asked for. See below.
+Both are off by default, so an unconfigured server accepts any peer and allows any exposed call. The management surface is *not* off by default in the same sense — it is simply never published unless asked for. See below.
 
 ### Authenticating peers
 
-`authenticate` receives whatever the client sent as `credentials` and returns an identity to accept
-the peer, or `undefined` to reject it. Rejected peers never reach the RPC layer — the check runs as
-socket.io middleware, before the connection is established at all.
+`authenticate` receives whatever the client sent as `credentials` and returns an identity to accept the peer, or `undefined` to reject it. Rejected peers never reach the RPC layer — the check runs as socket.io middleware, before the connection is established at all.
 
 ```typescript
 const server = new RpcServer({
@@ -780,20 +605,13 @@ const client = new RpcClient('http://localhost:7843', {
 })
 ```
 
-**`RpcClientOptions.name` must match `RpcIdentity.name`.** The `source` field of a message is written
-by the sender, so it is a claim, not evidence. An authenticating transport pins each connection to
-the name it authenticated as and drops frames claiming any other source. Without that, an
-authenticated peer could address its calls as another peer and inherit its rights.
+**`RpcClientOptions.name` must match `RpcIdentity.name`.** The `source` field of a message is written by the sender, so it is a claim, not evidence. An authenticating transport pins each connection to the name it authenticated as and drops frames claiming any other source. Without that, an authenticated peer could address its calls as another peer and inherit its rights.
 
-It pins the peer *registry* to the same rule. A frame's source is normally learned as it is parsed,
-which is how discovery works over MQTT — the broker is the authority there and there is no
-connection to check. Where there is one, a name is registered only once the connection has been
-checked, so a rejected frame cannot leave a peer that does not exist in the routing table.
+It pins the peer *registry* to the same rule. A frame's source is normally learned as it is parsed, which is how discovery works over MQTT — the broker is the authority there and there is no connection to check. Where there is one, a name is registered only once the connection has been checked, so a rejected frame cannot leave a peer that does not exist in the routing table.
 
 ### Tokens, without writing the authenticator
 
-`createTokenAuthenticator` is the common case packaged: a map from bearer token to the peer it
-admits.
+`createTokenAuthenticator` is the common case packaged: a map from bearer token to the peer it admits.
 
 ```typescript
 import { createTokenAuthenticator, defaultWebSocketPort, RpcServer } from '@source-repo/rpc'
@@ -807,20 +625,13 @@ const server = new RpcServer({
 })
 ```
 
-**One token per peer, not one token for the bus.** A token that maps to a name is evidence of who is
-calling, and the rule above then does the rest: a holder that connects under any other name gets a
-socket and nothing else — its announcement is refused, so it is never listed, and its frames are
-dropped. A single token shared by everyone proves only that the caller is inside the fence, and any
-holder could then claim to be the peer whose commands matter. There is deliberately no
-single-secret form.
+**One token per peer, not one token for the bus.** A token that maps to a name is evidence of who is calling, and the rule above then does the rest: a holder that connects under any other name gets a socket and nothing else — its announcement is refused, so it is never listed, and its frames are dropped. A single token shared by everyone proves only that the caller is inside the fence, and any holder could then claim to be the peer whose commands matter. There is deliberately no single-secret form.
 
-Blank tokens, grants with no name and an empty map all throw rather than construct, because each one
-would quietly admit more than it looks like it does.
+Blank tokens, grants with no name and an empty map all throw rather than construct, because each one would quietly admit more than it looks like it does.
 
 ### Authorizing calls
 
-`authorize` runs for every call and every event subscription. Return false to reject with a
-`Forbidden` error.
+`authorize` runs for every call and every event subscription. Return false to reject with a `Forbidden` error.
 
 ```typescript
 const server = new RpcServer({
@@ -834,33 +645,25 @@ const server = new RpcServer({
 })
 ```
 
-An authorizer that throws denies the call. Failing open would turn a bug in the authorizer into an
-access-control bypass.
+An authorizer that throws denies the call. Failing open would turn a bug in the authorizer into an access-control bypass.
 
-`requireAuthenticatedPeers` defaults to true when `authenticate` is set, rejecting calls from peers
-no transport can vouch for with an `Unauthorized` error.
+`requireAuthenticatedPeers` defaults to true when `authenticate` is set, rejecting calls from peers no transport can vouch for with an `Unauthorized` error.
 
 ### The management surface
 
-`manageRpc` is **not exposed by default**. Enabling it publishes exactly one method,
-`createRpcInstance`, which constructs an instance of a class already passed to `exposeClass()`:
+`manageRpc` is **not exposed by default**. Enabling it publishes exactly one method, `createRpcInstance`, which constructs an instance of a class already passed to `exposeClass()`:
 
 ```typescript
 const server = new RpcServer({ transports: [{ port: 7843 }], exposeManagement: true })
 ```
 
-It is still subject to `authorize`, so you can restrict who may create instances. The `expose*`
-methods are never remotely reachable.
+It is still subject to `authorize`, so you can restrict who may create instances. The `expose*` methods are never remotely reachable.
 
-> Versions before 2.0.0 published all of `ManageRpc` under `manageRpc` with no authentication, so
-> any peer that could reach the transport could construct any `exposeClass`'d class with chosen
-> arguments, or overwrite an exposed name and deny service to every other client. If you are
-> upgrading, treat both as having been reachable.
+> Versions before 2.0.0 published all of `ManageRpc` under `manageRpc` with no authentication, so any peer that could reach the transport could construct any `exposeClass`'d class with chosen arguments, or overwrite an exposed name and deny service to every other client. If you are upgrading, treat both as having been reachable.
 
 ## MQTT
 
-Servers and clients addressed by name over a broker, which is how a network of them is usually put
-together. The different servers are addressed by their `name`.
+Servers and clients addressed by name over a broker, which is how a network of them is usually put together. The different servers are addressed by their `name`.
 
 ```typescript
 const server = new RpcServer({
@@ -875,9 +678,7 @@ const client = new RpcClient('mqtt://broker:1883', {
 })
 ```
 
-**Both ends must agree on the prefix.** An `mqtt://` url gives the client the default `msgrpc/v2`,
-so a server that sets its own is unreachable from a client that does not — and it fails as a call
-timeout, which says nothing about why. There is no client option for it, so build the transport:
+**Both ends must agree on the prefix.** An `mqtt://` url gives the client the default `msgrpc/v2`, so a server that sets its own is unreachable from a client that does not — and it fails as a call timeout, which says nothing about why. There is no client option for it, so build the transport:
 
 ```typescript
 import { MqttTransport } from '@source-repo/rpc'
@@ -886,14 +687,11 @@ const transport = new MqttTransport('hmi-1', 'mqtt://broker:1883', { prefix: 'si
 const client = new RpcClient(undefined, { name: 'hmi-1', transport, defaultTarget: 'plantServer' })
 ```
 
-The same applies to every `MqttTransportOptions` field: the url form takes the defaults, and
-anything else means constructing the transport yourself.
+The same applies to every `MqttTransportOptions` field: the url form takes the defaults, and anything else means constructing the transport yourself.
 
 ### Topics
 
-MQTT 5 is the default. Reply address, correlation and method travel as packet properties, so a peer
-with no msgrpc code can take part and standard tooling can read the traffic.
-[`docs/mqtt5-frame-spec.md`](https://github.com/source-repo/rpc/blob/main/docs/mqtt5-frame-spec.md) describes the layout in full.
+MQTT 5 is the default. Reply address, correlation and method travel as packet properties, so a peer with no msgrpc code can take part and standard tooling can read the traffic. [`docs/mqtt5-frame-spec.md`](https://github.com/source-repo/rpc/blob/main/docs/mqtt5-frame-spec.md) describes the layout in full.
 
 ```
 <prefix>/req/<peer>        calls and subscribe requests            default prefix msgrpc/v2
@@ -902,35 +700,19 @@ with no msgrpc code can take part and standard tooling can read the traffic.
 <prefix>/presence/<peer>   retained: "online", or "offline" via the last will
 ```
 
-Set `protocol: 4` for a broker that does not speak MQTT 5. That uses the older `$`-delimited header
-on `<prefix>/rpc/<peer>` under a default prefix of `msgrpc/v1`, so the two layouts never share a
-topic and can run side by side during a migration.
+Set `protocol: 4` for a broker that does not speak MQTT 5. That uses the older `$`-delimited header on `<prefix>/rpc/<peer>` under a default prefix of `msgrpc/v1`, so the two layouts never share a topic and can run side by side during a migration.
 
-**Peer names are validated.** A name is one topic level, so `#`, `+`, `/`, spaces, an empty name and
-names over 128 characters are rejected when the transport is constructed. Without this a peer named
-`#` subscribed to `<prefix>/#` and received every other peer's requests and replies.
+**Peer names are validated.** A name is one topic level, so `#`, `+`, `/`, spaces, an empty name and names over 128 characters are rejected when the transport is constructed. Without this a peer named `#` subscribed to `<prefix>/#` and received every other peer's requests and replies.
 
 ### Delivery and sessions
 
-**QoS 1 by default.** QoS 0 drops messages silently whenever the broker or link hiccups, which
-surfaces as an unexplained call timeout. At-least-once permits duplicate delivery, so the server
-suppresses repeats by request id and answers them from a cache rather than running the method again
-— a redelivered `writeSetpoint` must not execute twice. Publishes are awaited, so a failure to reach
-the broker rejects the call instead of vanishing.
-
-**Presence replaces the connection MQTT does not have.** Each peer registers a retained last will, so
-when it disappears the broker publishes `offline` on its behalf and servers release the event
-subscriptions they held for it. Without this those subscriptions leaked forever, because an MQTT
-server never sees a disconnect. A peer that closes gracefully announces `offline` and then clears its
-retained value, so it leaves nothing behind on the broker.
-
-**Sessions.** Servers connect with a stable client id and a persistent session, so requests published
-while they restart are queued rather than lost. Under MQTT 5 the session is bounded by
-`sessionExpirySeconds`; under 3.1.1, which has no expiry, clients use a clean session instead.
-
-> **Expose before awaiting `ready()`.** A resumed session is handed its queued requests the moment it
-> connects. Anything exposed after `await server.ready()` is registered too late for them, and those
-> callers get `ClassNotFound`. Construct, expose, then await:
+**QoS 1 by default.** QoS 0 drops messages silently whenever the broker or link hiccups, which surfaces as an unexplained call timeout. At-least-once permits duplicate delivery, so the server suppresses repeats by request id and answers them from a cache rather than running the method again — a redelivered `writeSetpoint` must not execute twice. Publishes are awaited, so a failure to reach the broker rejects the call instead of vanishing.
+
+**Presence replaces the connection MQTT does not have.** Each peer registers a retained last will, so when it disappears the broker publishes `offline` on its behalf and servers release the event subscriptions they held for it. Without this those subscriptions leaked forever, because an MQTT server never sees a disconnect. A peer that closes gracefully announces `offline` and then clears its retained value, so it leaves nothing behind on the broker.
+
+**Sessions.** Servers connect with a stable client id and a persistent session, so requests published while they restart are queued rather than lost. Under MQTT 5 the session is bounded by `sessionExpirySeconds`; under 3.1.1, which has no expiry, clients use a clean session instead.
+
+> **Expose before awaiting `ready()`.** A resumed session is handed its queued requests the moment it connects. Anything exposed after `await server.ready()` is registered too late for them, and those callers get `ClassNotFound`. Construct, expose, then await:
 >
 > ```typescript
 > const server = new RpcServer({ transports: [{ brokerurl }] })
@@ -938,41 +720,27 @@ while they restart are queued rather than lost. Under MQTT 5 the session is boun
 > await server.ready()
 > ```
 
-**Peer names must be unique.** A peer's MQTT client id derives from its name, and a broker allows one
-connection per client id, so a second peer using the same name disconnects the first.
+**Peer names must be unique.** A peer's MQTT client id derives from its name, and a broker allows one connection per client id, so a second peer using the same name disconnects the first.
 
 ### Replicas
 
-Set `sharedGroup` and several processes can serve one peer name, with the broker distributing
-requests among them. Each replica needs its own `replicaId`, because of the client id rule above.
-Only the request channel is shared — a reply has to reach the requester waiting for it. Replicas keep
-no session, since a dead replica's share of the queue would never be drained, and they observe
-presence without announcing it: one replica's will would otherwise declare the whole group offline.
-Event subscriptions still bind to the replica that handled them, so events do not fan out across a
-group.
+Set `sharedGroup` and several processes can serve one peer name, with the broker distributing requests among them. Each replica needs its own `replicaId`, because of the client id rule above. Only the request channel is shared — a reply has to reach the requester waiting for it. Replicas keep no session, since a dead replica's share of the queue would never be drained, and they observe presence without announcing it: one replica's will would otherwise declare the whole group offline. Event subscriptions still bind to the replica that handled them, so events do not fan out across a group.
 
 ### What the broker still has to do
 
-MQTT has no server-side handshake, so `authenticate` does not apply to MQTT transports and `identity`
-is undefined for MQTT callers unless frames are signed. Trust otherwise comes from the broker:
+MQTT has no server-side handshake, so `authenticate` does not apply to MQTT transports and `identity` is undefined for MQTT callers unless frames are signed. Trust otherwise comes from the broker:
 
 - Set broker credentials or TLS client certificates through the transport's `mqtt` options.
 - Restrict which peer may publish or subscribe to which topic with broker ACLs.
 - `authorize` still runs, but its `source` is only as trustworthy as those ACLs make it.
 
-A server mixing an authenticating socket.io transport with an MQTT transport will reject its MQTT
-peers, because `requireAuthenticatedPeers` turns on with `authenticate`. Set it `false` explicitly to
-allow both and rely on the broker for the MQTT half.
+A server mixing an authenticating socket.io transport with an MQTT transport will reject its MQTT peers, because `requireAuthenticatedPeers` turns on with `authenticate`. Set it `false` explicitly to allow both and rely on the broker for the MQTT half.
 
-**msgrpc cannot hide MQTT traffic.** Peer names can no longer widen their own subscription, but
-anyone holding broker credentials can subscribe to `<prefix>/#` and read everything. Only broker ACLs
-prevent that. Signing, below, makes a message's origin checkable — it does not make it private.
+**msgrpc cannot hide MQTT traffic.** Peer names can no longer widen their own subscription, but anyone holding broker credentials can subscribe to `<prefix>/#` and read everything. Only broker ACLs prevent that. Signing, below, makes a message's origin checkable — it does not make it private.
 
 ### Signing frames
 
-Without a connection to authenticate, `source` is a claim. Signing each frame makes it checkable, so
-a broker operator — or any peer whose ACLs let it publish to another peer's topic — cannot forge a
-message from someone else.
+Without a connection to authenticate, `source` is a claim. Signing each frame makes it checkable, so a broker operator — or any peer whose ACLs let it publish to another peer's topic — cannot forge a message from someone else.
 
 ```typescript
 import { createHmacSigner, createHmacVerifier } from '@source-repo/rpc'
@@ -997,35 +765,19 @@ const client = new RpcClient('mqtt://broker:1883', {
 })
 ```
 
-Once `verify` is set, a frame must be signed, fresh, unreplayed and signed by the key on file for the
-name it claims — otherwise it is dropped before reaching the RPC layer and a `rejected` event carries
-the reason. A verified peer becomes an `RpcIdentity`, so `requireAuthenticatedPeers` and `authorize`
-work over MQTT exactly as they do over WebSocket.
+Once `verify` is set, a frame must be signed, fresh, unreplayed and signed by the key on file for the name it claims — otherwise it is dropped before reaching the RPC layer and a `rejected` event carries the reason. A verified peer becomes an `RpcIdentity`, so `requireAuthenticatedPeers` and `authorize` work over MQTT exactly as they do over WebSocket.
 
-The signature covers everything that decides what a frame means and where it goes, encoded as a JSON
-array of those fields followed by the payload bytes. The array fixes field order and escapes values,
-so no combination of names can be made to look like a different frame. Under MQTT 5 that includes the
-destination topic, since the topic is what carries the addressing; the exact field list is in the
-frame spec.
+The signature covers everything that decides what a frame means and where it goes, encoded as a JSON array of those fields followed by the payload bytes. The array fixes field order and escapes values, so no combination of names can be made to look like a different frame. Under MQTT 5 that includes the destination topic, since the topic is what carries the addressing; the exact field list is in the frame spec.
 
-**Replay protection.** A signature does not stop a captured frame being sent again, which for RPC
-means replaying a command. Each frame carries a nonce, and a receiver rejects frames outside
-`maxClockSkew` (default 60 s) or whose nonce it has already seen. Peers therefore need clocks within
-that window of each other; the window also bounds how many nonces must be remembered.
+**Replay protection.** A signature does not stop a captured frame being sent again, which for RPC means replaying a command. Each frame carries a nonce, and a receiver rejects frames outside `maxClockSkew` (default 60 s) or whose nonce it has already seen. Peers therefore need clocks within that window of each other; the window also bounds how many nonces must be remembered.
 
-**HMAC is symmetric.** Whoever can verify a peer's messages can also forge them, so an HMAC secret
-must only be shared with parties allowed to act as that peer. Where a compromised server must not be
-able to impersonate its peers, use `createEd25519Signer` / `createEd25519Verifier`, which take
-WebCrypto keys directly and leave only public keys on the verifying side.
+**HMAC is symmetric.** Whoever can verify a peer's messages can also forge them, so an HMAC secret must only be shared with parties allowed to act as that peer. Where a compromised server must not be able to impersonate its peers, use `createEd25519Signer` / `createEd25519Verifier`, which take WebCrypto keys directly and leave only public keys on the verifying side.
 
-Both are built on WebCrypto, so the same signer works in Node and in the browser. To use an HSM or
-another algorithm, supply your own `MessageSigner` / `MessageVerifier` — the built-ins are only
-conveniences.
+Both are built on WebCrypto, so the same signer works in Node and in the browser. To use an HSM or another algorithm, supply your own `MessageSigner` / `MessageVerifier` — the built-ins are only conveniences.
 
 ## Options
 
-The types are the reference; these are the ones worth explaining. Anything not listed defaults to
-off or absent.
+The types are the reference; these are the ones worth explaining. Anything not listed defaults to off or absent.
 
 ### RpcServerOptions
 
@@ -1048,21 +800,15 @@ off or absent.
 | `relay` | `true` | forward frames addressed to another connected peer; `false`, or a predicate per connection |
 | `callTimeout` | `10000` | for this server's own outgoing calls, via `proxy()` |
 
-A transport entry is `{ port, tls?, path? }` for a socket.io server, `{ server, path? }` to attach
-to an existing `http.Server`, `{ connect, path?, credentials? }` to serve over a connection this
-server opens, `{ brokerurl, ...MqttTransportOptions }` for MQTT, or a `Transport` instance you built
-yourself. A `connect` entry also takes `ca` — the authority to trust when the hub serves TLS — and
-`allowInsecureTls` for a development hub whose certificate nobody signed.
+A transport entry is `{ port, tls?, path? }` for a socket.io server, `{ server, path? }` to attach to an existing `http.Server`, `{ connect, path?, credentials? }` to serve over a connection this server opens, `{ brokerurl, ...MqttTransportOptions }` for MQTT, or a `Transport` instance you built yourself. A `connect` entry also takes `ca` — the authority to trust when the hub serves TLS — and `allowInsecureTls` for a development hub whose certificate nobody signed.
 
-`tls` takes the certificate and key that `https.createServer` takes, and its presence is what makes
-the server HTTPS - there is no useful HTTPS server without key material, which is why there is no
-boolean for it.
+`tls` takes the certificate and key that `https.createServer` takes, and its presence is what makes the server HTTPS - there is no useful HTTPS server without key material, which is why there is no boolean for it.
 
 ### RpcClientOptions
 
 | option | default | meaning |
 | --- | --- | --- |
-| `name` | a UUID | how this client identifies itself; must be unique among peers sharing a server |
+| `name` | three readable words | how this client identifies itself; must be unique among peers sharing a server |
 | `transport` | built from the url | supply one to take full control of the link |
 | `defaultTarget` | `'*'` | which peer `proxy()` addresses when not told otherwise |
 | `callTimeout` | `10000` | before rejecting with `Timeout` |
@@ -1089,6 +835,7 @@ boolean for it.
 | `allowResponseTopic` | under the prefix | decides whether a request may have its reply published where it asks |
 | `allowInsecureTls` | `false` | accept any certificate from an `mqtts`/`wss` broker; unsafe by design |
 | `channels` | all three | which of `req`/`rsp`/`evt` to subscribe to |
+| `tap` | `false` | watch everything under the prefix and report it as `relayed` without acting on it; answers no calls and checks no signatures |
 | `sharedGroup` / `replicaId` | — | see [Replicas](#replicas) |
 | `sign` / `verify` | — | see [Signing frames](#signing-frames) |
 | `maxClockSkew` / `maxTrackedNonces` | `60000` / `5000` | replay window and how much of it to remember |
@@ -1096,51 +843,32 @@ boolean for it.
 
 ## Browser use
 
-The `browser` export condition resolves to a build whose static dependencies are `socket.io-client`,
-`@msgpack/msgpack`, `uint8array-extras`, `uuid` and `events`. The MQTT client is **not** among them:
-`RpcClient` imports it on demand, so a bundle only carries it if an `mqtt://` url is actually used,
-in which case bundlers place it in a separate chunk.
+The `browser` export condition resolves to a build whose static dependencies are `socket.io-client`, `@msgpack/msgpack`, `uint8array-extras`, `uuid` and `events`. The MQTT client is **not** among them: `RpcClient` imports it on demand, so a bundle only carries it if an `mqtt://` url is actually used, in which case bundlers place it in a separate chunk.
 
-`events` is a real dependency rather than a `node:` builtin so bundlers can substitute the browser
-shim. Signing uses WebCrypto, which browsers expose only in a secure context (https, or localhost).
+`events` is a real dependency rather than a `node:` builtin so bundlers can substitute the browser shim. Signing uses WebCrypto, which browsers expose only in a secure context (https, or localhost).
 
-A page can host an `RpcServer` as well as call one: `transports: [{ connect: url }]` serves over the
-connection it opens, and the hub relays calls to it. See
-[Serving over a connection you open](#serving-over-a-connection-you-open).
+A page can host an `RpcServer` as well as call one: `transports: [{ connect: url }]` serves over the connection it opens, and the hub relays calls to it. See [Serving over a connection you open](#serving-over-a-connection-you-open).
 
-**`RpcServer` means a different class here**, and deliberately. In Node it is `NodeRpcServer`, which
-adds `{ port }`, `{ server }` and `{ brokerurl }`; in a browser it is the portable base, which has
-none of them — a page cannot open a listening socket or speak MQTT. So the same source file is
-portable as long as it sticks to what a browser can do, and `{ port: 8080 }` in browser code is a
-compile error rather than a class that throws when constructed:
+**`RpcServer` means a different class here**, and deliberately. In Node it is `NodeRpcServer`, which adds `{ port }`, `{ server }` and `{ brokerurl }`; in a browser it is the portable base, which has none of them — a page cannot open a listening socket or speak MQTT. So the same source file is portable as long as it sticks to what a browser can do, and `{ port: 8080 }` in browser code is a compile error rather than a class that throws when constructed:
 
 ```
 Object literal may only specify known properties, and 'port' does not exist in
 type 'Transport | ConnectServerOptions'
 ```
 
-It also means nothing a browser resolves imports socket.io's server or the MQTT client, so neither
-reaches the bundle — no aliases and no bundler configuration. `NodeRpcServer` is exported under that
-name too, for code that would rather say where it runs.
+It also means nothing a browser resolves imports socket.io's server or the MQTT client, so neither reaches the bundle — no aliases and no bundler configuration. `NodeRpcServer` is exported under that name too, for code that would rather say where it runs.
 
 ## Peer routing
 
-Each `RpcServer` and `RpcClient` owns a `PeerRegistry`, shared by its own modules and nothing wider:
-transports record which peer a message arrived from, and the switch reads it back to send the reply
-out of the same transport. Entries are dropped when a peer disconnects, and the registry is bounded,
-since the keys arrive from remote peers.
+Each `RpcServer` and `RpcClient` owns a `PeerRegistry`, shared by its own modules and nothing wider: transports record which peer a message arrived from, and the switch reads it back to send the reply out of the same transport. Entries are dropped when a peer disconnects, and the registry is bounded, since the keys arrive from remote peers.
 
-Peer names must be unique within one graph. Across separate `RpcServer` instances they do not
-interfere.
+Peer names must be unique within one graph. Across separate `RpcServer` instances they do not interfere.
 
 ## Low level: modules
 
-`RpcServer` and `RpcClient` are assembled from smaller pieces, and the same pieces are available for
-building something else.
+`RpcServer` and `RpcClient` are assembled from smaller pieces, and the same pieces are available for building something else.
 
-A module receives, processes and sends messages. *Sending* here means from one module to the next
-within a process, not over a network, and a *message* is any JavaScript value. Modules are connected
-with `pipe`:
+A module receives, processes and sends messages. *Sending* here means from one module to the next within a process, not over a network, and a *message* is any JavaScript value. Modules are connected with `pipe`:
 
 ```typescript
 const first = new MyModule()
@@ -1154,23 +882,16 @@ const third = new MyModule([first])
 first.pipe((message) => console.log('first wanted to send:', message))
 ```
 
-To write one, extend `GenericModule` and call `this.send(message)`. Its `receive` may be async, and a
-rejection propagates back through the pipe to the original sender, where it can be caught either at
-the `send` call or with a `TryCatch` module:
+To write one, extend `GenericModule` and call `this.send(message)`. Its `receive` may be async, and a rejection propagates back through the pipe to the original sender, where it can be caught either at the `send` call or with a `TryCatch` module:
 
 ```typescript
 const tryCatch = new TryCatch([source])
 tryCatch.on('caught', (message, error) => console.log('caught', error))
 ```
 
-Included utilities: **Converter** (map each message through a function), **Filter** (pass those a
-predicate accepts), **Switch** (route to a named target; an unresolvable target is dropped) and
-**TryCatch**.
+Included utilities: **Converter** (map each message through a function), **Filter** (pass those a predicate accepts), **Switch** (route to a named target; an unresolvable target is dropped) and **TryCatch**.
 
-Transports own their wire format. A transport receives and emits `Message` objects and encodes them
-itself with a `FrameCodec`, which is what lets MQTT 5 carry the method and correlation as packet
-properties rather than burying them in an opaque payload. Wiring RPC by hand is therefore just the
-handler and a transport:
+Transports own their wire format. A transport receives and emits `Message` objects and encodes them itself with a `FrameCodec`, which is what lets MQTT 5 carry the method and correlation as packet properties rather than burying them in an opaque payload. Wiring RPC by hand is therefore just the handler and a transport:
 
 ```typescript
 import { RpcServerHandler, SocketIoServerTransport } from '@source-repo/rpc'
@@ -1182,8 +903,7 @@ handler.pipe(transport)                                        // handler -> tra
 handler.manageRpc.exposeObject({ hello: () => 'world' }, 'greeter')
 ```
 
-Before 2.0.0 a `Converter` sat on each side of the handler to encode and decode. Those converters
-are still exported, but they are no longer part of the RPC chain.
+Before 2.0.0 a `Converter` sat on each side of the handler to encode and decode. Those converters are still exported, but they are no longer part of the RPC chain.
 
 ## Development
 
@@ -1204,5 +924,4 @@ docker compose -f docker-compose/docker-compose.yml up -d
 
 Point them at a different broker with `MSGRPC_TEST_BROKER=mqtt://host:1883`.
 
-[`examples/`](https://github.com/source-repo/rpc/tree/main/packages/rpc/examples) is a small plant service showing the 2.0 idioms: `@rpcNamespace` and `@rpc`,
-an extracted contract, and a server that validates against it and exposes introspection.
+[`examples/`](https://github.com/source-repo/rpc/tree/main/packages/rpc/examples) is a small plant service showing the 2.0 idioms: `@rpcNamespace` and `@rpc`, an extracted contract, and a server that validates against it and exposes introspection.