# `adapter-introspection`

## Purpose

`adapter-introspection` is a small support module that holds the
`BrowserTimelineAdapter` operations that would otherwise push the
adapter class file over its 300-line budget: FX plugin hosting and the
project-level bus registry declarations. Each function is a thin
delegator — the adapter still owns the lifecycle invariants
(`assertReady`, `requireTrack`) and delegates the work here.

The module is consumed directly by `browser-adapter.ts` rather than
re-exported from the package barrel. Consumers do not call into it
themselves — they go through the adapter's public methods.

## Features

- `hostFxOnTrack(rec, plugin, context, worklets, graph)` adds the
  plugin to the track's `PluginChain`, materialises the render node
  via `createFxNode`, and registers the node under
  `<trackId>:fx:<pluginId>`.
- `declareBusPublish` / `declareBusSubscribe` thin wrappers around
  `BusOrchestrator`.
- `busRegistry`, `processOrder` read accessors.
- Owns the `audio_engine_browser_nodes_created_total` counter
  increment under `kind=fx`.

## Usage: Basic Example

```ts
import { hostFxOnTrack } from "@suaveplan/audio-engine-browser/adapter/adapter-introspection";

await hostFxOnTrack(rec, plugin, context, worklets, graph);
```

## Usage: Advanced Example

```ts
import {
    busRegistry,
    declareBusPublish,
    declareBusSubscribe,
    processOrder,
} from "@suaveplan/audio-engine-browser/adapter/adapter-introspection";

declareBusPublish(orch, "kick", "kick-bus", 2);
declareBusSubscribe(orch, "bass", "kick-bus");

const order = processOrder(orch, ["kick", "bass"]);
const registry = busRegistry(orch);
```

## API Reference

### `hostFxOnTrack(rec, plugin, context, worklets, graph) → Promise<void>`

Adds the plugin to the chain, calls `createFxNode` to pick the render
path, and registers the resulting node in `graph`.

### `declareBusPublish(orch, trackId, bus, channels) → void`

Delegates to `BusOrchestrator.declarePublish`.

### `declareBusSubscribe(orch, trackId, bus) → void`

Delegates to `BusOrchestrator.declareSubscribe`.

### `busRegistry(orch) → BusRegistry`

Returns the orchestrator's underlying `BusRegistry`.

### `processOrder(orch, trackIds) → ReadonlyArray<string>`

Returns the topological order of `trackIds`.

## Implementation Notes

- The OTel counter is module-scoped so each `BrowserTimelineAdapter`
  instance records into the same series; consumers wanting per-adapter
  cardinality should add their own attribute on the calling side.
- `hostFxOnTrack` does not catch errors from `createFxNode` — those
  propagate so the adapter raises the right
  `AUDIO_ENGINE_BROWSER.WORKLET_LOAD_FAILED` code with the original
  cause attached.
- These helpers are intentionally not exported from the package barrel
  because they take internal types (`TrackRecord`, `BusOrchestrator`)
  whose shape should not be part of the public surface.