Initialize

roadmap/epics/05-persistence.md

@@ -0,0 +1,44 @@
+# 05. WAL, Job ID И Восстановление
+
+Статус: не начат. Зависимости: 01, 02; интеграция 03, 04.
+
+## Цель
+
+Изолировать журналы владельцев и обеспечить восстановление без пересечения ID, появления двух копий tube или незаметной потери совместимости данных.
+
+## Задачи
+
+1. Определить layout общего data root, метаданных топологии и отдельных каталогов owner slots. Каждый WAL имеет одного writer и собственную блокировку.
+2. Проверять топологию и layout до любых изменяющих операций с журналами; создавать начальные метаданные атомарно с необходимой durability, если сервер запускается с пустыми данными.
+3. Задать формат decimal uint64 job ID и маршрутизацию к владельцу без глобального mutable каталога каждого job на критическом пути, если выбранная схема это позволяет.
+4. Решить восстановление генератора ID при частичном restart: чтения максимального ID среди живых jobs недостаточно, если большие ID уже удалены. Учитывать старые сообщения/сессии и generation fencing; документировать срок гарантий уникальности.
+5. Определить переполнение и исчерпание диапазона ID: контролируемый отказ вместо wraparound и коллизий.
+6. Сохранить порядок FIFO внутри tube при изменении ID. Если вводится отдельный sequence, определить момент выдачи и запись/восстановление; не изменять порядок поступления относительно текущей версии без решения.
+7. Запускать replay каждого owner отдельно. До готовности replay его partition space недоступен; frontend не перенаправляет операции к соседям.
+8. Восстанавливать jobs в соответствии с текущей семантикой WAL, не считать клиентские резервации пережившими restart. Старые frontend-сессии не продолжают работу поверх восстановленных jobs.
+9. Проверить compaction, segment rotation, file references, disk-full/short write/fsync errors и взаимодействие с подтверждением команд.
+10. Реализовать выбранную в 01 политику старого WAL: отдельный offline import с сохранением оригинала либо явный отказ нового режима. Если отдельный legacy сохраняется, он читает прежний формат.
+
+## Ограничения
+
+- Нельзя совместно писать независимыми owners в существующий binlog-каталог, даже если убрать `waldirlock`.
+- Tube descriptor не становится персистентным объектом: имя восстанавливается из живых jobs. Пустые клиентские tubes не обязаны переживать restart.
+- Частичный перезапуск без WAL теряет данные только соответствующего owner по заявленному контракту; это нельзя выдавать за восстановление или HA.
+- С `-b` границы потери данных определяются реальной записью и настройками fsync. Не требовать отсутствия любых потерь при `-F` и не ослаблять `-f 0` под видом ускорения.
+- При изменении `Jobrec` следовать процедуре `Walver` в `dat.h`, включая чтение старых версий. Многопроцессность сама по себе не требует изменения `Jobrec`.
+- Онлайн-миграция и изменение карты не входят в эпик. Увеличение числа slots с переназначением partitions требует отдельной offline-процедуры, не простого изменения config.
+
+## Приёмка
+
+- Два owners одновременно записывают задания, используют разные WAL и не пересекающиеся ID.
+- После удаления всех jobs и частичного restart генерация ID не создаёт опасных коллизий по утверждённому контракту; тест включает запоздалые сообщения старого поколения.
+- Неизменная топология восстанавливает jobs в правильных tubes и owners; несовместимая карта не меняет существующие файлы при отказе запуска.
+- Полный/частичный restart проверен с ready, delayed, buried и ранее reserved jobs; внешние сессии не сохраняют ложное владение восстановленными jobs.
+- Ошибка одного WAL не повреждает файлы другого. Реакция логического сервера соответствует 01/06.
+- Проверены crash windows до/после записи и подтверждения, compaction, rotation, недостаток места и повреждённый журнал.
+- Старые данные остаются пригодны для legacy либо импортируются явным инструментом согласно выбранной политике; исходник не уничтожается автоматически.
+- Документированы ID layout, topology metadata, срок гарантий ID, WAL compatibility и ограничения durability.
+
+## Точки Кода
+
+`job.c:make_job_with_id/next_id/job_pri_less`, `dat.h:Jobrec/Walver/Wal/File`, `walg.c`, `file.c`, `serv.c:srv_acquire_wal`, `prot.c:prot_replay`, WAL-тесты в `testserv.c`.