# SHM protocol and readers

## 1. Ring format
Python reader ожидает ring header:
- magic: `RDRRING2`
- version: `1`
- fields capacity/slot_size/write_seq/read_seq.

Ring files находятся в `/dev/shm/<ring_name_without_slash>`.

## 2. Reader components
- `orchestration/shm/binary_cursor.py`: primitive cursor API.
- `orchestration/shm/decoder.py`: decode trace/result payloads.
- `orchestration/shm/ring_reader.py`: mmap-based ring consumption.
- `orchestration/shm_reader.py`: фасад для импортов.

## 3. Consumption semantics
- `pop_payload()` возвращает `None`, если новых payload нет.
- При sequence mismatch reader выполняет fast-forward read pointer.
- `drop_all()` принудительно дропает unread payloads.

## 4. Error cases
- missing ring file -> `FileNotFoundError`
- magic/version mismatch -> `RuntimeError`
- bad payload magic/kind -> `ValueError`

## 5. Integration
`AppWindowPipelineMixin` использует по одному reader на raw/preprocessed/results ring.