# Capability Spec Delta: api-worker-rpc (api-worker-rpc) **Package**: `@suaveplan/api-worker-rpc` **Status**: PROPOSED > Every requirement below carries a `**Verified by:**` line at authoring time. (See `openspec/AGENTS.md` Section 13.) ## ADDED Requirements ### Requirement: Request/response correlation via monotonic message ids The package SHALL assign every `RpcRequest` a monotonically-increasing `bigint` id from a per-port counter. Responses SHALL include the same id; the caller's response-table lookup MUST match by exact id. A response whose id has no outstanding entry MUST be rejected with `RPC_ORPHAN_RESPONSE` (not silently dropped — orphans indicate a protocol bug worth surfacing). #### Scenario: ids are strictly monotonic per port - **WHEN** 1000 requests are issued on one port - **THEN** the issued ids form a strictly-increasing sequence with no gaps #### Scenario: orphan response is rejected loudly - **WHEN** a response arrives whose id has no outstanding entry - **THEN** the callee logs `RPC_ORPHAN_RESPONSE` AND no caller promise is settled by it **Verified by:** `src/correlation/correlation.test.ts::"ids are strictly monotonic per port"` AND `src/correlation/correlation.test.ts::"orphan response throws RPC_ORPHAN_RESPONSE"` --- ### Requirement: AbortSignal forwarding cancels in-flight calls The package SHALL accept an optional `AbortSignal` per `createRpcCaller` call. When the caller's signal aborts, the protocol MUST send an `RpcAbort` message and the in-flight caller promise MUST reject with `AbortError` (DOMException, name `"AbortError"`). The callee MUST surface a fresh `AbortSignal` to its implementation function so user code can react. Aborting after settlement MUST be a no-op. #### Scenario: caller abort rejects the promise - **WHEN** a caller issues a request with `signal: ac.signal` AND calls `ac.abort()` before the response arrives - **THEN** the promise rejects with an `AbortError` #### Scenario: abort after settle is a no-op - **WHEN** a request has already resolved AND `ac.abort()` is called - **THEN** no error is thrown AND no `RpcAbort` is sent **Verified by:** `src/abort/abort.test.ts::"caller abort rejects in-flight call"` AND `src/abort/abort.test.ts::"abort after settle is no-op"` --- ### Requirement: Streaming via Transferable ReadableStream The package SHALL marshal `ReadableStream` arguments and return values via `Transferable` so chunks transfer zero-copy. The protocol SHALL carry per-chunk `ack` so the producing side cannot outrun the consumer; missing acks within a configurable window count against backpressure budget. Consumer cancellation MUST propagate back to the producer. #### Scenario: large stream transfers in chunks - **WHEN** a 64 MiB stream is sent across the port - **THEN** the receiver observes the full byte sequence AND the producer is throttled by backpressure ack #### Scenario: consumer cancel propagates to producer - **WHEN** the receiver cancels the stream mid-transfer - **THEN** the producer's stream receives a cancellation signal **Verified by:** `src/streaming/streaming.test.ts::"large stream transfers in chunks"` AND `src/streaming/streaming.test.ts::"consumer cancel propagates to producer"` --- ### Requirement: SuaveplanError reconstruction across the wire The package SHALL reconstruct `SuaveplanError` on the receiving side with the same `code`, the same `details` (Zod-validated), and a depth-bounded `cause` chain (default depth 5). Throws that are NOT `SuaveplanError` MUST be wrapped on the receiving side in a `SuaveplanError` with code `RPC_REMOTE_THROW` carrying the original `name` and `message` in `details`. The original stack is preserved as a `details.remoteStack` string field — never as a live `Error.stack` (which would not survive structured-clone). #### Scenario: SuaveplanError round-trips with cause - **WHEN** the callee throws `new SuaveplanError("PLUGIN.X.Y", { cause: new SuaveplanError("PLUGIN.X.Z") })` - **THEN** the caller receives a `SuaveplanError` with `code === "PLUGIN.X.Y"` AND `(err.cause as SuaveplanError).code === "PLUGIN.X.Z"` #### Scenario: plain Error becomes RPC_REMOTE_THROW - **WHEN** the callee throws `new TypeError("boom")` - **THEN** the caller receives `SuaveplanError` with code `RPC_REMOTE_THROW` AND `details.remoteName === "TypeError"` **Verified by:** `src/error-reconstruction/error-reconstruction.test.ts::"SuaveplanError round-trips with cause"` AND `src/error-reconstruction/error-reconstruction.test.ts::"plain Error wraps as RPC_REMOTE_THROW"` --- ### Requirement: Backpressure rejects new calls before memory exhaustion The package SHALL enforce a configurable bounded outstanding-message budget per port (default 1024). When the budget is exhausted, new `createRpcCaller` method calls MUST throw `RPC_BACKPRESSURE` synchronously at the call site — they MUST NOT queue indefinitely or allocate without bound. Acks AND response receipts return capacity. #### Scenario: budget exceeded throws synchronously - **WHEN** 1025 simultaneous calls are issued against a budget of 1024 - **THEN** the 1025th call throws `RPC_BACKPRESSURE` synchronously (no microtask delay) **Verified by:** `src/backpressure/backpressure.test.ts::"budget exceeded throws RPC_BACKPRESSURE synchronously"` --- ### Requirement: Cloneable guard rejects non-structured-clone values at call site The package SHALL pre-check arguments and return values for structured-clone safety before sending. Values that are NOT structured-clone-safe (functions, class instances without an explicit `serialize` hook, `Symbol`s) MUST throw `RPC_NOT_CLONEABLE` synchronously at the call site, naming the offending path (e.g. `"args[0].onCallback"`). Silent corruption of the wire MUST NOT be possible. #### Scenario: function argument throws at call site - **WHEN** `caller.method({ onProgress: () => {} })` is invoked - **THEN** the call throws `RPC_NOT_CLONEABLE` synchronously AND `details.path === "args[0].onProgress"` #### Scenario: cloneable nested object passes - **WHEN** `caller.method({ a: { b: { c: 1 } } })` is invoked with a deeply-nested plain object - **THEN** the call proceeds without error **Verified by:** `src/cloneable-guard/cloneable-guard.test.ts::"function argument throws RPC_NOT_CLONEABLE"` AND `src/cloneable-guard/cloneable-guard.test.ts::"cloneable nested object passes"` --- ### Requirement: Caller type wraps every return type in Promise The package SHALL expose `createRpcCaller(port): WorkerProxyOf`. The proxy's method signatures SHALL match `WorkerProxyOf` from `api-types/worker-rpc`: every return type wrapped in `Promise`, every method name preserved, non-cloneable parameter types flagged via the type system. #### Scenario: every method's return type is Promise-wrapped - **WHEN** `expectTypeOf["someMethod"]>>()` is checked - **THEN** it equals `Promise` where `R` is the original return type **Verified by:** `src/caller/caller.spec-conformance.test.ts::"every method return is Promise-wrapped"` --- ### Requirement: Wire protocol versions explicitly with mismatch rejection The package SHALL embed a `protocolVersion` string (semver) in every `RpcRequest` and `RpcResponse`. Receivers MUST reject messages whose version is outside the supported range with `RPC_PROTOCOL_VERSION_MISMATCH`. The version is fixed at `"1.0.0"` for this Stage-3 ship; future incompatible changes MUST bump the major. #### Scenario: mismatched protocol version rejects - **WHEN** a message arrives with `protocolVersion: "2.0.0"` - **THEN** the receiver throws `RPC_PROTOCOL_VERSION_MISMATCH` AND no impl method runs **Verified by:** `tests/conformance/round-trip.test.ts::"mismatched protocol version is rejected"`