Initial Commit

openspec/archive/2026-05-25-api-worker-rpc/proposal.md

@@ -0,0 +1,64 @@
+# `@suaveplan/api-worker-rpc` — MessagePort protocol for capability marshalling
+
+**Package**: `@suaveplan/api-worker-rpc`
+**Status**: PROPOSED
+**Type**: new-package
+**Stage**: 3 (Worker isolation infrastructure)
+
+## Why
+
+Every capability adapter ships two callable surfaces: a direct in-process one for `trusted` plugins and a `MessagePort`-marshalled one for `isolated` / `sandboxed` plugins (design doc §2.2, §5.2a). Hand-rolling that marshalling once per capability is how plugin frameworks accrete subtly-different RPC layers that diverge on cancellation, streaming, and error reconstruction. `api-worker-rpc` is the single, shared protocol every worker-proxy package builds on. Getting it right once means every capability — `db`, `events`, `secrets`, `jobs`, `logger`, future ones — gets cancellation, backpressure, streaming, and error reconstruction for free.
+
+Per design doc §5.2a: every conformance suite runs against both surfaces. The proxy surface MUST behave identically to the direct surface from the plugin's perspective.
+
+## What changes
+
+Net-new package. Universal-tier (uses `MessagePort` from `worker_threads` on Node/Bun; the same `MessagePort` shape is also available in browsers, so the protocol is portable even though Stage-3 callers are all server-side).
+
+**ADDED exports:**
+
+- `./protocol` — wire types: `RpcRequest`, `RpcResponse`, `RpcError`, `RpcStreamChunk`, `RpcAbort`. All Zod-validated at the receive boundary.
+- `./correlation` — monotonic message-id generator (`bigint`); request/response matching table; orphan-response detection.
+- `./abort` — `AbortSignal` forwarding: caller-side `AbortController.signal` triggers an `RpcAbort` message; worker-side handler receives an `AbortSignal` that fires accordingly.
+- `./streaming` — `ReadableStream` marshalling via `Transferable` (zero-copy chunk transfer); back-pressure carried in `RpcStreamChunk.ack`.
+- `./error-reconstruction` — `SuaveplanError` rebuilt on the receiving side with the same `code`, `cause` chain (depth-bounded), and serialisable `details`. Non-`SuaveplanError` throws are wrapped in `RPC_REMOTE_THROW`.
+- `./backpressure` — bounded outstanding-message budget per port; exceeding triggers `RPC_BACKPRESSURE` at the caller BEFORE exhausting memory.
+- `./cloneable-guard` — pre-send check for structured-clone safety; non-cloneable values (functions, class instances without `serialize` hooks) throw `RPC_NOT_CLONEABLE` at the call site, not silently corrupting the wire.
+- `./caller` — `createRpcCaller<T>(port)` returns a typed proxy of `T` whose method signatures are `WorkerProxyOf<T>` (return types wrapped in `Promise`).
+- `./callee` — `serveRpc<T>(port, impl)` mounts an implementation on the receiving side; handles dispatch, abort wiring, and stream lifecycle.
+- `./error-codes` — `RPC_*` codes via `defineCodes` (`RPC_BACKPRESSURE`, `RPC_NOT_CLONEABLE`, `RPC_REMOTE_THROW`, `RPC_TIMEOUT`, `RPC_PORT_CLOSED`, `RPC_ORPHAN_RESPONSE`, `RPC_PROTOCOL_VERSION_MISMATCH`).
+- `./testing` — paired `MessageChannel` factory for in-process conformance suites.
+
+## Out of scope
+
+- **Capability-specific marshalling logic** — query-cursor handling for DB, log-record batching for logger, etc. Each worker-proxy package layers its own semantics on top of this protocol.
+- **Process-level isolation** — `api-worker-rpc` is transport-only; spawning the worker is `api-worker-host`'s job.
+- **Cross-host transport** — this is in-process `MessagePort` only. Cross-host fan-out is `api-ws-broker-*`'s domain.
+
+## Source mapping
+
+Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.
+
+| Requirement | Design doc section |
+|---|---|
+| Request/response correlation via monotonic ids | §5.2a |
+| `AbortSignal` forwarding | §5.2a |
+| Streaming via `Transferable` `ReadableStream` | §5.2a |
+| Error reconstruction (`SuaveplanError` rebuilt) | §5.2a |
+| Backpressure → `RPC_BACKPRESSURE` | §5.2a |
+| Structured-clone-safe boundary → `RPC_NOT_CLONEABLE` | §5.2a |
+
+## Verification approach
+
+- `src/correlation/correlation.test.ts` — monotonic ids; request/response match; orphan detection.
+- `src/abort/abort.test.ts` — caller-side abort propagates to worker `AbortSignal`; in-flight call rejects with `AbortError`.
+- `src/streaming/streaming.test.ts` — large stream marshals in zero-copy chunks; backpressure ack throttles producer.
+- `src/error-reconstruction/error-reconstruction.test.ts` — `SuaveplanError` round-trips with code + cause depth ≤ N; non-Suaveplan throw → `RPC_REMOTE_THROW`.
+- `src/backpressure/backpressure.test.ts` — outstanding budget enforced; exceeding → `RPC_BACKPRESSURE`.
+- `src/cloneable-guard/cloneable-guard.test.ts` — function argument → `RPC_NOT_CLONEABLE` at call site.
+- `src/caller/caller.spec-conformance.test.ts` — `expectTypeOf` proves caller methods return `Promise<R>`.
+- `tests/conformance/round-trip.test.ts` — pair `createRpcCaller` + `serveRpc` over `MessageChannel`; 50+ scenarios; every code in `error-codes.ts` reachable from at least one path.
+
+## Migration impact
+
+None — additive only. Stage-3 worker-proxy packages and `api-worker-host` will depend on this.

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

@@ -0,0 +1,137 @@
+<!-- markdownlint-disable MD024 -->
+
+# 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<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"`

openspec/archive/2026-05-25-api-worker-rpc/tasks.md

@@ -0,0 +1,77 @@
+# Tasks — `@suaveplan/api-worker-rpc`
+
+> Every checkbox MUST reflect work actually done in this change.
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Spec authoring
+
+- [x] 1.1 Read design doc §2.2, §5.2a, §6 (worker-marshalling paragraph)
+- [x] 1.2 Read umbrella `openspec/changes/api-plugin-foundation/proposal.md`
+- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
+- [x] 1.4 Draft `proposal.md`
+- [x] 1.5 Draft `specs/api-worker-rpc/spec.md`
+- [ ] 1.6 Every requirement carries a `**Verified by:**` line
+
+## 2. Implementation
+
+- [ ] 2.1 Scaffold `packages/api/api-worker-rpc/` (`0.1.0`, `sideEffects: false`, deps: `@suaveplan/error`, `@suaveplan/types`, `zod`)
+- [ ] 2.2 `src/protocol/` — Zod-validated wire types
+- [ ] 2.3 `src/correlation/` — monotonic id generator + request/response table + orphan detection
+- [ ] 2.4 `src/abort/` — `AbortSignal` forwarding (caller `AbortController` → wire → callee `AbortController`)
+- [ ] 2.5 `src/streaming/` — `ReadableStream` marshal via `Transferable`; backpressure ack
+- [ ] 2.6 `src/error-reconstruction/` — `SuaveplanError` rebuild with depth-bounded cause chain
+- [ ] 2.7 `src/backpressure/` — outstanding-message budget + `RPC_BACKPRESSURE`
+- [ ] 2.8 `src/cloneable-guard/` — pre-send clone check + `RPC_NOT_CLONEABLE`
+- [ ] 2.9 `src/caller/` — `createRpcCaller<T>(port): WorkerProxyOf<T>`
+- [ ] 2.10 `src/callee/` — `serveRpc<T>(port, impl)`
+- [ ] 2.11 `src/error-codes.ts` — every `RPC_*` code via `defineCodes`
+- [ ] 2.12 `src/testing/index.ts` — paired `MessageChannel` factory for conformance harness
+- [ ] 2.13 `src/index.ts` — namespace re-exports
+
+## 3. Tests
+
+- [ ] 3.1 `src/correlation/correlation.test.ts` — monotonic ids; orphan response detection (`RPC_ORPHAN_RESPONSE`)
+- [ ] 3.2 `src/abort/abort.test.ts` — caller abort propagates; in-flight call rejects with `AbortError`; abort after settle is a no-op
+- [ ] 3.3 `src/streaming/streaming.test.ts` — large stream chunked zero-copy; ack throttles producer; consumer cancel propagates
+- [ ] 3.4 `src/error-reconstruction/error-reconstruction.test.ts` — round-trip preserves `code` AND cause chain AND `details`; non-Suaveplan → `RPC_REMOTE_THROW`
+- [ ] 3.5 `src/backpressure/backpressure.test.ts` — outstanding budget enforced; exceeding throws `RPC_BACKPRESSURE` at caller BEFORE memory exhaustion
+- [ ] 3.6 `src/cloneable-guard/cloneable-guard.test.ts` — function argument throws `RPC_NOT_CLONEABLE` synchronously at call site
+- [ ] 3.7 `src/caller/caller.spec-conformance.test.ts` — `expectTypeOf<ReturnType<Caller<T>["m"]>>().toEqualTypeOf<Promise<R>>()`
+- [ ] 3.8 `tests/conformance/round-trip.test.ts` — pair caller + callee over `MessageChannel`; every `RPC_*` code reachable
+- [ ] 3.9 Every `it(...)` carries `{ timeout: 5000 }`
+
+## 4. Documentation
+
+- [ ] 4.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
+- [ ] 4.2 README links every co-located `.md` under `## Modules`; explains the call/serve pair pattern
+- [ ] 4.3 Update CLAUDE.md "Network / IO" package listing once shipped
+
+## 5. Pre-archive verification (the 5-gate triple)
+
+- [ ] 5.1 `bun run check` — Biome 0 errors / 0 warnings / 0 info
+- [ ] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-worker-rpc` — green
+- [ ] 5.3 `bunx turbo test:coverage --filter=@suaveplan/api-worker-rpc` — 100/100/100/100
+- [ ] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/api-worker-rpc` — exit 0
+- [ ] 5.5 `bunx turbo build --filter=@suaveplan/api-worker-rpc` — green
+
+## 6. Pre-archive 7-row checklist (AGENTS.md Section 13)
+
+- [ ] 6.1 Generics threaded (`createRpcCaller<T>`, `serveRpc<T>`); `expectTypeOf` on `WorkerProxyOf<T>` derivation
+- [ ] 6.2 Zod schemas at every wire boundary (`RpcRequest` / `RpcResponse` / etc.)
+- [ ] 6.3 Every `RPC_*` code thrown by at least one production path
+- [ ] 6.4 Strict-mode behaviors tested both on and off (backpressure budget configurable)
+- [ ] 6.5 OTel — N/A (transport layer; consumers attach spans)
+- [ ] 6.6 Lifecycle dedup — N/A (no FSM)
+- [ ] 6.7 No retroactive tick
+
+## 7. Archive
+
+- [ ] 7.1 Fold spec delta into `openspec/specs/api-worker-rpc/spec.md`
+- [ ] 7.2 Move `openspec/changes/api-worker-rpc/` → `openspec/archive/<yyyy-mm-dd>-api-worker-rpc/`
+- [ ] 7.3 Tick Stage-3 row in umbrella
+- [ ] 7.4 Refresh `MANIFEST.md`