# `registry`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Wraps the api-ws contract's `InMemoryConnectionRegistry` to give the Bun engine a typed registry surface that the conformance harness can drive. The wrapper does not add data structures of its own — every method delegates to the inner registry — but it does expose the bus-integration helpers `recordSubscription` and `dropSubscription` so the Bun-specific subscription bus can keep its topic index hot.

The registry indexes connections by both connection id and tenant id, which is what powers the `lookupByTenant` fast path used by the broadcast fan-out.

## Features

- Drop-in `ConnectionRegistry` implementation; passes the conformance suite directly.
- `recordSubscription` / `dropSubscription` exposed for the bus.
- `raw` accessor exposes the underlying `InMemoryConnectionRegistry` for the conformance harness factory.
- Tenant-bucket maps so `countByTenant` is O(1), powering the per-tenant cap enforcer.

## Usage: Basic

```ts
import { BunConnectionRegistry } from "@suaveplan/api-ws-bun";

const registry = new BunConnectionRegistry();
registry.add(conn);
console.log(registry.countByTenant(conn.tenantId));
registry.remove(conn);
```

## Usage: Advanced

```ts
import { BunConnectionRegistry } from "@suaveplan/api-ws-bun";
import { InMemorySubscriptionBus } from "@suaveplan/api-ws";

const registry = new BunConnectionRegistry();
const bus = new InMemorySubscriptionBus(registry.raw);
registry.add(conn);
bus.subscribe(conn, "orders");
// `registry.lookupByTopic("orders", conn.tenantId)` now returns [conn].
```

## API Reference

- `new BunConnectionRegistry()` — constructor; no options.
- `add(conn): void` / `remove(conn): void` — lifecycle bookkeeping.
- `lookupByTenant(tenant) / lookupByTopic(topic, tenant?) / countByTenant(tenant)` — read-only lookups.
- `recordSubscription(conn, topic, tenant)` / `dropSubscription(conn, topic, tenant)` — bus integration.
- `raw: InMemoryConnectionRegistry` — escape hatch.

## Implementation Notes

The wrapper class is deliberately thin: the engine wants to treat the registry as a Bun-engine concept (`BunConnectionRegistry`) for ergonomics, but at the implementation level the contract's `InMemoryConnectionRegistry` is the canonical data structure that the conformance harness exercises. Duplicating bookkeeping inside the wrapper would create two sources of truth.

The `raw` accessor exists for the conformance harness factory — `runWsEngineConformance` expects a `ConnectionRegistry` instance, but the in-memory subscription bus needs the concrete `InMemoryConnectionRegistry` so it can call `recordSubscription`. Exposing `raw` lets the factory hand the same underlying registry to both.