## ADDED Requirements

### Requirement: Stream modes

The system SHALL support multiple stream modes when invoking a compiled graph:

- `"values"` — emits the full state after each superstep
- `"updates"` — emits only the state changes after each superstep
- `"messages"` — emits individual message chunks for chat-oriented graphs
- `"debug"` — emits debug events with full superstep information
- `"custom"` — supports user-defined events via a emit function

#### Scenario: Values mode emits full state

- **WHEN** a graph is streamed with `streamMode: ["values"]`
- **THEN** each chunk SHALL contain the complete state object after each superstep

#### Scenario: Updates mode emits diffs

- **WHEN** a graph is streamed with `streamMode: ["updates"]`
- **THEN** each chunk SHALL contain only the state keys that changed

### Requirement: Stream event protocol

The system SHALL emit structured events during graph execution, including:
- `on_chain_start` — node execution begins
- `on_chain_end` — node execution completes
- `on_chain_stream` — intermediate output from a node
- `on_custom_event` — user-defined events
- Checkpoint metadata paired with each event (id, parent_id, step, source)

#### Scenario: Events include checkpoint metadata

- **WHEN** a stream event is received
- **THEN** it SHALL include a `checkpoint` envelope with `id`, `step`, and `source`

#### Scenario: Custom events propagate from nodes

- **WHEN** a node emits a custom event via an emit function
- **THEN** that event SHALL appear in the stream with type `on_custom_event`

### Requirement: Async iteration over streams

The system SHALL support `for await...of` iteration over graph streams.

#### Scenario: Stream is async iterable

- **WHEN** `for await (const chunk of graph.stream(...))` is used
- **THEN** each chunk SHALL be available as it is produced