init commit

python_app/docs/shm_protocol_and_readers.md

@@ -0,0 +1,28 @@
+# 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.