[2026-09-17] eagle: personal/projects/zont-config-compiler.md personal/tech/roundtrip-key-verification.md

2026-09-17 23:05:58 +06:00
parent de4c219648
commit 665a2147b5
2 changed files with 108 additions and 18 deletions
@@ -100,3 +100,38 @@ diff <(iconv -f <вх> -t utf-8 <оригинал> | tr -d '\r' | sort) \
 1. Новый ключ, где эмитится, какие точки входа поправлены.
 2. Команду подмены и наблюдённый результат («1 строка изменилась, маркер на месте»).
 3. Питфолл «две точки входа» — чтобы следующая сессия сразу проверяла обе.
+
+---
+
+## 🔴 Круг зелёный ≠ приёмка (2026-09-17, ZONT круг 39)
+
+Жёсткий урок той же сессии. Round-trip **байтово чистый** не означает, что правка верна.
+
+**Случай:** правка декодера + энкодера прошла круг 9/9, но владелец проекта посмотрел на артефакт
+и увидел **выдуманный ключ** и **обёртку-список на один элемент**. С точки зрения байтов всё
+правильно; с точки зрения человека — сломано.
+
+```
+круг зелёный  +  артефакт читается плохо   =   правка не принята
+```
+
+**Правило:** перед правкой формы назвать **целевую форму словами владельца** и только потом
+трогать код. Если форма не названа — **не угадывать**: спросить одним вопросом.
+
+**Правило трёх:** третья подряд правка «вслепую» (форма не названа, гипотеза за гипотезой) —
+стоп. Не править код. Назвать **допущение, которое может быть неверным**, и задать ОДИН вопрос.
+
+**Симптом «сломано, хотя круг зелёный»:** объект, у которого есть id **в строке конфига**, при
+развороте тела в YAML **теряет этот id** → энкодеру не из чего собрать строку, и объекты уезжают
+в `raw`-секции (в ZONT: орфаны с `46` выросли с 4 до 69). Проверять **не только** число объектов
+и строк, но и **состав служебных секций** до/после.
+
+**Проверка, которую стоит добавить в любой конвертер:**
+
+```bash
+# число объектов в raw-фоллбэк-секциях ДО и ПОСЛЕ правки должно совпадать
+grep -c '^\- id:' out.yml.before   # <секция-фоллбэк>
+grep -c '^\- id:' out.yml.after
+```
+
+Рост этой секции = форма не разобрана, а не «данных нет».