suaveplan/openspec/archive/2026-05-25-api-ws/proposal.md

@suaveplan/api-ws — abstract WebSocket Connection, Registry, Bus, Broker contract

Package: @suaveplan/api-ws Status: PROPOSED Type: new-package Stage: 1 (Contracts) — see umbrella openspec/changes/api-plugin-foundation/

Why

Persistent connections are first-class in the API foundation (design §11). Plugins declare WebSocket endpoints in their manifest; the host runs the engine, manages connection lifecycle, fans out subscriptions. Concrete engines (api-ws-bun) and multi-host brokers (api-ws-broker-redis, api-ws-broker-in-memory) plug behind a stable contract. This package owns that contract: Connection, ConnectionRegistry, SubscriptionBus, WsBroker, plus the cross-tenant gate that requires ws.broadcast-cross-tenant capability.

Per design §11.2: "conn.subscribe(topic, { tenant?, filter? }) registers the connection with the host's subscription bus." Per §11.3: brokers make bus.broadcast visible across host replicas without migrating connections. Both shapes live here.

What changes

Net-new package. Contract types + Zod schemas for the wire envelope + the cross-tenant capability gate + the conformance harness.

• ADDED: ./connection — abstract WsConnection: principal, tenantId, subscribe(topic, opts), unsubscribe(topic), send(message), close(code, reason), ack(id), id, lastEventId, state (open | closing | closed).
• ADDED: ./connection-registry — abstract ConnectionRegistry: add(conn), remove(conn), lookupByTenant(tenant), lookupByTopic(topic, tenant?), countByTenant(tenant). Backed by a multi-index.
• ADDED: ./subscription-bus — abstract SubscriptionBus: subscribe(conn, topic, { tenant?, filter? }), unsubscribe(conn, topic), broadcast(topic, { tenant, payload, filter? }), asyncIterator(topic, opts).
• ADDED: ./broker — abstract WsBroker for multi-host fan-out: publish(topic, envelope), subscribe(topic, handler), dispose(). Connections are NOT migrated across hosts — the broker only makes broadcasts visible.
• ADDED: ./envelope — Zod schema for the wire WsEnvelope ({ id, type, topic?, payload? }); type-narrowing helpers.
• ADDED: ./backpressure — BackpressurePolicy: bounded send queue (maxQueuedMessages, default 256); eviction emits BACKPRESSURE_EVICTED close.
• ADDED: ./heartbeat — HeartbeatPolicy: heartbeatMs (default 30000), two missed pongs → close ABNORMAL.
• ADDED: ./reconnect-token — ReconnectToken HMAC envelope ({ tenant, principalId, lastEventId, exp }); 5-min TTL constant.
• ADDED: ./capability-id — adds "ws" AND "ws.broadcast-cross-tenant" to the CapabilityId union via type-level augmentation.
• ADDED: ./error-codes — frozen WS_CODES: HANDSHAKE_FAILED, PRINCIPAL_EXPIRED, BACKPRESSURE_EVICTED, HEARTBEAT_FAILED, CONNECTION_CAP_EXCEEDED, CROSS_TENANT_BROADCAST_DENIED, RECONNECT_TOKEN_INVALID, BROKER_UNAVAILABLE.
• ADDED: ./testing — runWsEngineConformance(factory) reusable harness.

CapabilityId additions

This package contributes "ws" and "ws.broadcast-cross-tenant" to the CapabilityId union. The cross-tenant id is a separate capability so the manifest declares it explicitly and the host audit-logs every use (design §11.2 "audit-logged on every use").

Out of scope

• Concrete engines (api-ws-bun) — Stage 7.
• Concrete brokers (api-ws-broker-redis, api-ws-broker-in-memory) — Stages 5 and 7.
• The graphql-ws protocol wiring (subscriptions over WebSocket) — that lives in api-graphql engine adapters, which read this package's SubscriptionBus.

Source mapping

Genesis-original. Source of design intent: docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md.

Requirement	Design doc section
WsConnection shape + handshake flow	§11.1
SubscriptionBus.broadcast + filter predicate	§11.2
Multi-host fan-out via broker	§11.3
Backpressure (maxQueuedMessages: 256)	§11.4
Heartbeat (heartbeatMs: 30000, two missed pongs)	§11.4
Per-tenant caps (maxConnectionsPerTenant)	§11.4
Reconnect tokens (HMAC, 5-min TTL)	§11.5
Cross-tenant gate (ws.broadcast-cross-tenant)	§11.2

Requirements with no source line

Requirement	Justification
runWsEngineConformance harness	Stage-5 deliverable (§13.4).

Verification approach

• src/connection/connection.spec-conformance.test.ts — expectTypeOf<WsConnection>() declares every documented method.
• src/connection-registry/connection-registry.test.ts — add/remove/lookup; multi-index correctness; count-by-tenant.
• src/subscription-bus/subscription-bus.test.ts — subscribe/unsubscribe; broadcast fans out to matching (topic, tenant); filter predicate applied per-connection.
• src/subscription-bus/cross-tenant.test.ts — broadcast WITHOUT ws.broadcast-cross-tenant is rejected with WS.CROSS_TENANT_BROADCAST_DENIED when tenant arg is omitted or differs from emitter's tenant.
• src/broker/broker.spec-conformance.test.ts — WsBroker interface declared.
• src/envelope/envelope.test.ts — Zod accept/reject suite over the wire envelope.
• src/backpressure/backpressure.test.ts — queue saturation triggers BACKPRESSURE_EVICTED.
• src/heartbeat/heartbeat.test.ts — two missed pongs → close ABNORMAL.
• src/reconnect-token/reconnect-token.test.ts — HMAC verify, TTL boundary.
• src/capability-id/capability-id.spec-conformance.test.ts — both ids in CapabilityId.
• tests/dep-graph.test.ts — deps: @suaveplan/api-types, @suaveplan/error, @suaveplan/types, zod. No transport deps.

Migration impact

None — additive only.

Impact

Affected dependents

• (none) — [x] no action needed (reason: net-new; engines + brokers land Stage 5/7)