# `stream-session`

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

## Purpose

`StreamSession` is the public face of the stream-tier session core. It
wraps the FSM, the transport adapter, the interruption classifier, and
the per-peer `StreamSourcePlugin` registry into one orchestration
object. Consumers in chunks B/C (transports, hooks, components) talk to
this class — they never reach into the FSM or the classifier directly.

The class is intentionally a thin shell. Every lifecycle method
(`connect`, `join`, `leave`, `disconnect`) is a `dispatchSessionEvent`
followed by the matching transport call followed by another
`dispatchSessionEvent`. Transport faults flow through
`reportInterruption`, which classifies the cause, emits the
`'interruption'` event, drives the FSM to `disconnected`, and updates
telemetry. Auto-reconnect (chunk D) subscribes to `'interruption'` and
decides whether to retry — the session itself never retries, keeping
the retry policy at the right layer for testability.

## Features

- Eight `'state-changed'` emissions covering the canonical happy path.
- `'peer-stream-added'` / `'peer-stream-removed'` emissions for every
  peer the transport reports.
- Deterministic `'interruption'` emission via the
  `InterruptionClassifier`.
- Injectable transport via constructor — no globals, no singletons.
- Telemetry: peer-connect / peer-disconnect counters, active-session
  gauge, RTT histogram (the latter wired by chunk B).
- `dispose()` for clean teardown including peer chain removal.
- Typed `EventBus` surface so consumers in chunk C can write
  `useEventListener(session.bus, "peer-stream-added", …)` without any
  `as` casts.

## Usage: Basic

```ts
import { createStreamSession } from "@suaveplan/react-audio-stream/session";

const session = createStreamSession({ transport });
await session.connect("room-1");
await session.join();
// ...stream activity...
await session.leave();
await session.disconnect();
```

## Usage: Advanced

```ts
import {
  createStreamSession,
  type StreamTransportAdapter,
} from "@suaveplan/react-audio-stream/session";

const session = createStreamSession({ transport });
session.bus.on("state-changed", ({ from, to }) => {
  metrics.set("ras_state", to);
});
session.bus.on("peer-stream-added", ({ participantId, stream }) => {
  console.log("attaching peer", participantId);
  engine.attachSource(`peer:${participantId}`, stream);
});
session.bus.on("interruption", (verdict) => {
  if (verdict.class === "network") {
    scheduleReconnect();
  }
});

try {
  await session.connect("room-1");
  await session.join();
} catch (err) {
  // The session has already emitted 'interruption' and driven the FSM
  // to 'disconnected'. The error is re-thrown so the caller can decide.
  console.error(err);
}
```

## API Reference

- `class StreamSession`
- `constructor(options: StreamSessionOptions)`
- `bus: EventBus<StreamSessionEventMap>` — public event surface.
- `state`, `roomId`, `peers()` — read-only inspection.
- `connect(roomId)`, `join()`, `leave()`, `disconnect()` — lifecycle
  methods that drive the FSM and the transport in lock-step.
- `reportInterruption(cause)` — classify + emit + transition to
  `disconnected`. Used by chunk-B transports.
- `dispose()` — unsubscribe transport listeners + tear down peers.
- `createStreamSession(options)` — factory wrapper.
- Type re-exports: `StreamSessionEventMap`, `StreamSessionOptions`,
  `StreamTransportAdapter`, `PeerStreamEvent`, `InterruptionCause`.

## Implementation Notes

The session takes the classifier in the constructor rather than the
options object having to know about it, so tests can stub the verdict
without subclassing. Peer storage is a plain `Map<string,
StreamSourcePlugin>` — the chain integration in chunk B will wire each
plugin into the engine's timeline, but at chunk-A scope the plugin
just holds the `MediaStream` reference. `tearDownAllPeers` runs
on every transition to `disconnected` (both explicit and via FAIL) so
the engine sees consistent peer-stream-removed events regardless of
how the session ended. `extractReason` keeps the failure path
allocation-free for the common `Error` case while still surfacing a
useful string when the transport throws a non-Error. The `active` flag
guards the OTel gauge against double-decrement when both an explicit
disconnect and an interruption land back-to-back.