`@suaveplan/api-events-worker-proxy` — worker-side proxy to main-process `@suaveplan/events` bus

Package: @suaveplan/api-events-worker-proxy Status: PROPOSED Type: new-package Stage: 3 (Worker isolation infrastructure)

Why

Per design doc §5.2a, every capability ships a proxy surface for worker-tier plugins. The events capability is special: there is no abstract api-events contract package — the host injects the existing @suaveplan/events bus directly into PluginContext.events. So this proxy is a worker-side surface over the existing @suaveplan/events EventBusLike interface, NOT a new contract layer. Worker-side ctx.events.emit(...) / ctx.events.on(...) calls marshal across MessagePort to the main-process bus.

Per §5.2b sandboxed gating: only manifested publishes topics are emittable; only manifested subscribes topics deliverable. That gating is enforced MAIN-SIDE; this proxy is the transport.

What changes

Net-new package.

ADDED exports:

./client — createEventsProxyClient(port): WorkerProxyOf<EventBusLike>.
./subscriber — on(topic, handler) / off / once; handlers run worker-side; backpressure carried by api-worker-rpc so a slow worker-side subscriber cannot exhaust main-side memory.
./publisher — emit(topic, payload) marshals payload; main-side does the topic-allow check + actual bus publish; emit-not-allowed returns EVENTS_PROXY_TOPIC_NOT_ALLOWED (rebuilt SuaveplanError).
./error-codes — EVENTS_PROXY_* codes (EVENTS_PROXY_TOPIC_NOT_ALLOWED, EVENTS_PROXY_HANDLER_THROW, EVENTS_PROXY_PORT_CLOSED, EVENTS_PROXY_BACKPRESSURE_DROP).
./testing — paired MessageChannel + stub bus.

Out of scope

Topic allowlisting policy — enforced main-side per §5.2b.
Cross-host fan-out — @suaveplan/events's job (and api-ws-broker-redis for WS specifically).
Bounded-queue capability — events.bounded-queue capability flag is honored main-side; the proxy only marshals.

Source mapping

Genesis-original. Design doc sections: §5.2a (worker-RPC variants), §5.2b (sandboxed gating), §6 (capability scoping).

Requirement	Design doc section
Proxy surface over existing `@suaveplan/events` bus (no new contract)	§5.2a
Topic allow-check on main side; proxy rejects with reconstructed error	§5.2b
Handler throws reconstructed via `api-worker-rpc`	§5.2a

Verification approach

src/publisher/publisher.test.ts — emit allowed topic round-trips; disallowed topic throws.
src/subscriber/subscriber.test.ts — handler invocation; off cancels; backpressure throttles main → worker.
tests/conformance/run-events-bus-conformance.test.ts — runEventsBusConformance from @suaveplan/events/testing passes against the proxy as surface. Required before Stage 4 can complete.

Migration impact

None — additive only.

2.9 KiB Raw Blame History

@suaveplan/api-events-worker-proxy — worker-side proxy to main-process @suaveplan/events bus

Why