suaveplan/openspec/archive/2026-05-25-api-worker-rpc/specs/api-worker-rpc/spec.md

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, Symbols) 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<T>(port): WorkerProxyOf<T>. The proxy's method signatures SHALL match WorkerProxyOf<T> from api-types/worker-rpc: every return type wrapped in Promise<R>, every method name preserved, non-cloneable parameter types flagged via the type system.

Scenario: every method's return type is Promise-wrapped

• WHEN expectTypeOf<ReturnType<Caller<T>["someMethod"]>>() is checked
• THEN it equals Promise<R> 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"