[2026-09-26] eagle: personal/projects/balda/balda-kraken-mm-deploy.md personal/projects/balda/balda-mattermost-connector.md personal/projects/balda/balda-mm-delegation-plan.md personal/tech/balda-go-fx-pitfalls.md personal/tech/hermes-secret-redaction-bypass.md

personal/tech/balda-go-fx-pitfalls.md

@@ -1,9 +1,11 @@
 # Balda — Go/fx pitfalls и метод правок (зеркало скилла)
 
-> Создано 2026-09-26. Обновлено 2026-09-26 (ночь) — добавлены lint/arch-lint и закрытие Фазы 2.
+> Создано 2026-09-26. Обновлено 2026-09-26 (ночь, позже) — добавлен **Дефект 4**
+> (advertisement ↔ actor-хендлер), найденный при первом реальном запуске на Kraken.
 > Зеркало секции скилла `devops/docker-balda-service`, добавленной 2026-09-26.
-> Источник: работа над Mattermost-адаптером Балды (Фаза 2).
+> Источник: работа над Mattermost-адаптером Балды (Фаза 2) + деплой на Kraken (Фаза 3).
 > Проектные доки: [[personal/projects/balda/balda-mattermost-connector]],
+> [[personal/projects/balda/balda-kraken-mm-deploy]],
 > [[personal/projects/balda/balda-mm-delegation-plan]].
 
 ---
@@ -109,6 +111,72 @@ fx.Provide(
 
 ---
 
+## 🔴🔴 Дефект 4: объявленная команда без actor-хендлера (роняет ВЕСЬ fx-граф)
+
+Найден **только реальным запуском на Kraken** (Фаза 3). До этого Фаза 2 считалась закрытой:
+`go build` = 0, `go vet` = 0, `golangci-lint` = 0 issues, `go-arch-lint` = OK, тесты зелёные.
+**Ни один из этих гейтов его не видит.**
+
+**Симптом** — crash-loop контейнера (`Restarting (1)`), в логах одна строка на тысячи
+`"message":"provided"`:
+
+```
+Error: starting Balda app: could not build arguments for function
+".../execution".init.func1: failed to build *execution.ActorHost: ...
+failed to build *command.Router: received non-nil error from function
+"reflect".makeFuncStub: advertised commands have no actor handler: goal
+```
+
+**Причина:** в `mattermostfx/module.go` в `commandcmd.Advertisement{Names: [...]}` была
+объявлена команда `goal`, которой **не существует** как actor-хендлер. `goal` — это
+**payload kind** (`goalkeepercmd.PayloadKindGoal`, `actorcmd.KindGoal`,
+`actors/job_actor.go:100`), а снаружи цикл GoalKeeper называется `goalkeeper`.
+
+**Механизм:** `actors/command/router.go:49 ValidateAdvertised()` вызывается из
+`commandfx/module.go:306`. Он валидирует **весь** список `Names` одного advertisement и при
+первом отсутствующем имени возвращает ошибку → fx не может построить `*command.Router` →
+падает `*execution.ActorHost` → падает приложение. Одна опечатка в списке = полный отказ старта,
+а не «недоступна одна команда».
+
+**Правильно — сверять `Names` с реальными `Name()`:**
+
+```bash
+cd ~/Developer/balda
+grep -rn 'func (h \*Handler) Name() string' internal/apps/balda/actors/command/
+```
+
+Эталонный фактический список (2026-09-26, `balda@de273d8f`):
+
+```
+locator · reset · usage · auto · cancel · close · start · user · topic · skill
+goalkeeper · help · plugin
+```
+
+`mattermostfx/module.go` после фикса:
+```go
+Names: []string{
+    "locator", "reset", "usage", "auto", "cancel",
+    "goalkeeper", "topic", "close", "start",
+    "user", "skill",
+},
+```
+`channel/mattermost/inbound.go` — тот же список в inbound allow-list, синхронно.
+
+⚠️ `Zulip`-адаптер изначально был **прав** — там `"goalkeeper"` без `"goal"`. Регрессию внёс
+MM-адаптер при копировании «на глаз».
+⚠️ **`docs/commands.md` — НЕ источник истины** для имён команд. Там таблица доступности по
+транспортам; реестр хендлеров — только `actors/command/*/handler.go`.
+⚠️ Фикс — дельта-апплаером: `tools/deltas-goal-command-fix.json` (2 дельты, обе APPLIED).
+
+📌 **Общий вывод (расширяет §«go build = exit 0 ≠ рабочий транспорт» выше):** недостаточно
+проверять DI-граф тестом `validateBaldaApplication`. Тест должен прогоняться **с реальным
+списком `Names` из модуля**. Но и это не поймало бы опечатку, если тест использует тот же
+неверный advertisement — поэтому единственная надёжная проверка нового транспорта =
+**живой запуск бинаря**. Для нового транспорта добавлять в чек-лист шаг:
+`docker run` (или локальный `balda start`) с включённым транспортом **до** объявления готовности.
+
+---
+
 ## ⚠️ Env-override работает только по ключам, уже присутствующим в YAML
 
 `appconfig/loader.go:367` — `SetEnvPrefix("BALDA")` + `SetEnvKeyReplacer(".", "_")` +
@@ -129,6 +197,10 @@ fx.Provide(
    `TestLoadConfigDocument_AppliesZulipEnvOverrides`)
 9. если добавлял маршрут в `BuiltinRoutes()` — обновить `TestBuiltinRoutes`
 10. доки: `docs/reference/configuration.md` (ключи), `docs/commands.md` (колонка транспорта)
+11. 🔴 **сверить `Advertisement.Names` с реальными `Name()`** в
+    `actors/command/*/handler.go` — опечатка роняет весь fx-граф (см. §«Дефект 4» выше)
+12. 🔴 **живой запуск** `balda start` (или `docker run`) с включённым транспортом —
+    единственная проверка, которая ловит дефект 4
 
 **Финальные quality gates (все обязательны, из `AGENTS.md`):**
 ```bash