init commit

python_app/docs/storage_formats.md

@@ -0,0 +1,41 @@
+# Storage formats
+
+## 1. Calibration/reference sets
+Хранятся в `python_app/data/{calibration|reference}/{radar_key}`:
+- `<set_name>.npz`
+- `<set_name>.json`
+
+`radar_key` формируется из sweep и power параметров (`radar_key_from_config`).
+
+## 2. Binary collection serialization
+`storage/npz/serialize.py`:
+- `RAW_MAGIC = 0x31574152`
+- `PREPROC_MAGIC = 0x31525050`
+- `RESULT_MAGIC = 0x314C5352`
+
+Поддерживается сериализация:
+- trace collections (`serialize_trace_collection`)
+- result collections (`serialize_result_collection`)
+
+## 3. Runtime numpy snapshot (`numpy-directory-v1`)
+Структура:
+- `manifest.json`
+- `raw/<collection_dir>/...`
+- `preprocessed/<collection_dir>/...`
+- `results/<collection_dir>/block_*/...`
+
+Коллекция: `0003_id22_ns11999302655222`.
+
+## 4. History selection
+Перед записью snapshot вызывается `select_aligned_histories()`:
+- primary mode: `aligned_by_collection_and_occurrence`
+- fallback: `independent_tail`
+
+Это предотвращает рассинхронизацию raw/preprocessed/results при сохранении.
+
+## 5. Обратное чтение
+Для валидации snapshot используется `scripts/check_snapshot_numpy.py`:
+- проверка shape/finite,
+- сравнение коллекций,
+- построение графиков сравнения,
+- plot всех switch states для одной коллекции.