first commit

docs/api-stack/api/api-ws-bun/src/registry/connection-registry.md

@@ -0,0 +1,56 @@
+# `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.