# `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.