## `eigenkit.reservoir.driver`

The reservoir driver: run a frozen circuit over input sequences, carrying quantum state across timesteps per a policy, and return the statevector trajectory.

The reservoir (circuit + fixed `weights`) is never trained here — this is the forward pass that produces the features a classical readout learns on. Two dispatch paths, chosen by the policy:

- **Stateless / parallel** (policy exposes `expand_inputs`): all `$B \cdot T$` timesteps are independent, so they evolve in a single batched `statevector` sweep. No Python timestep loop.
- **Sequential** (policy implements `initial` / `inject` / `advance`): the quantum state is carried step to step, so timesteps run in order. The `B` sequences still evolve in parallel within each step via per-sample injection.

### `run_reservoir(circuit, policy, sequences, weights)`

Evolve `circuit` over `sequences` under `policy`, with frozen `weights`.

The result is the trajectory of statevectors, a complex array of shape `(B, T, 2**n)`.

`sequences` has shape `(B, T, F)`: `B` independent series, `T` timesteps and `F` features per step. `weights` is the fixed 1-D parameter vector of the reservoir, shared by the whole batch. Features are extracted separately from the returned trajectory (see the feature extractors), so the same run can produce expectation, probability or amplitude features without evolving the circuit again.

Parameters:

| Name        | Type      | Description                                         | Default    |
| ----------- | --------- | --------------------------------------------------- | ---------- |
| `circuit`   | `Circuit` | The reservoir circuit, run with frozen weights.     | *required* |
| `policy`    | `Policy`  | How the state passes from one timestep to the next. | *required* |
| `sequences` | `ndarray` | The inputs, of shape (B, T, F).                     | *required* |
| `weights`   | `ndarray` | The frozen weights of the reservoir.                | *required* |

Returns:

| Type      | Description                                              |
| --------- | -------------------------------------------------------- |
| `ndarray` | The trajectory of statevectors, of shape (B, T, 2\*\*n). |