first commit

docs/api-stack/api/api-ws-bun/src/subscription/subscription-bus.md

@@ -0,0 +1,58 @@
+# `subscription`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Builds the per-engine subscription bus instance and binds it to the engine's connection registry. The bus implementation itself is `InMemorySubscriptionBus` from the contract package — there is no Bun-specific subscription algorithm — but constructing the bus requires the registry's `raw` accessor so the contract's bookkeeping (`registry.recordSubscription`) stays in lockstep with bus state.
+
+Concentrating that wiring in a single factory means the engine module reads `createBunSubscriptionBus(registry)` instead of poking the registry's internal accessor inline.
+
+## Features
+
+- One-line construction with the correct registry plumb-through.
+- Generic over the payload type so plugins narrow `Payload` at engine instantiation time.
+- Cross-tenant broadcast denial inherited from the contract bus (the `ws.broadcast-cross-tenant` capability check).
+
+## Usage: Basic
+
+```ts
+import {
+    BunConnectionRegistry,
+    createBunSubscriptionBus,
+} from "@suaveplan/api-ws-bun";
+
+const registry = new BunConnectionRegistry();
+const bus = createBunSubscriptionBus<{ ok: true }>(registry);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    BunConnectionRegistry,
+    createBunSubscriptionBus,
+} from "@suaveplan/api-ws-bun";
+
+const registry = new BunConnectionRegistry();
+const bus = createBunSubscriptionBus(registry);
+registry.add(conn);
+bus.subscribe(conn, "orders", { tenant: conn.tenantId });
+const delivered = bus.broadcast(
+    { tenant: conn.tenantId, capabilities: new Set() },
+    "orders",
+    { tenant: conn.tenantId, payload: { ok: true } }
+);
+```
+
+## API Reference
+
+- `createBunSubscriptionBus<Payload>(registry): SubscriptionBus<Payload>` — builds an `InMemorySubscriptionBus` bound to the registry.
+
+## Implementation Notes
+
+The factory does not currently inject any custom subscribers — every broadcast flows through `bus.send(connection, ...)` which the contract implements as `connection.send(envelope)`. If a future engine needs per-broadcast OTel instrumentation, the right place to hook it is inside the engine's `Connection.send` adapter, not by forking the bus.
+
+The return type is the abstract `SubscriptionBus` interface (not `InMemorySubscriptionBus`) so consumers cannot rely on bus internals. The engine relies only on the contract surface, and that's what the public type advertises.