core.choir

keeper-sidesoulstack.orchestrationorchestration

Правка членства Voice-а в Choir-е инкарнации на стороне Keeper.

core.choir добавляет и убирает Voice (хост по SID) из Choir-партии инкарнации в реестре Keeper-а (Postgres); оба состояния требуют on: keeper и хост не трогают. Идемпотентно по конструкции: повторный present уже-Voice-а и absent отсутствующего дают changed=false, не ошибку. До мутации проверяется существование инкарнации.

Требования

Rootне требуется
Сторонаkeeper-side
Коллекцияsoulstack.orchestration
Категорияorchestration

core.choir.present — Хост (по SID) становится Voice-ом указанного Choir-а инкарнации (AddVoice).

Меняется, когда

Voice добавлен.

Не меняется, когда

Voice уже есть (ErrVoiceExists), это не ошибка.

Параметры

Параметр	Тип	Обяз. / дефолт	Описание
`incarnation`	`string`	required	Имя инкарнации, чьим Choir управляем.
`choir`	`string`	required	Имя Choir-партии внутри инкарнации.
`sid`	`string` format: sid	required	SID (FQDN) Soul, чей Voice добавляется в Choir.
`role`	`string`	optional	Роль-метка голоса в хоре (свободная).
`position`	`int`	optional	Позиция Voice в партии (>= 0).

Пример — Добавить новую реплику в Choir replicas

- name: Add the new replica to the replicas choir
  on: keeper
  module: core.choir.present
  params:
    incarnation: "${ incarnation.name }"
    choir:       replicas
    sid:         "${ vars.new_sid }"
    role:        replica

Output

Поле	Тип	Описание
`incarnation`	`string`	эхо params
`choir`	`string`	эхо params
`sid`	`string`	эхо params
`state`	`present`
`added`	`bool`	true, если Voice добавлен; false, если уже существовал

core.choir.absent — Хост (по SID) убирается из Choir-а инкарнации (RemoveVoice).

Меняется, когда

Voice снят.

Не меняется, когда

Voice-а нет (ErrVoiceNotFound), это не ошибка.

Параметры

Параметр	Тип	Обяз. / дефолт	Описание
`incarnation`	`string`	required	Имя инкарнации, чьим Choir управляем.
`choir`	`string`	required	Имя Choir-партии внутри инкарнации.
`sid`	`string` format: sid	required	SID (FQDN) Soul, чей Voice убирается из Choir.

Пример — Снять хост с Choir replicas при выводе из роли

- name: Remove the host from the replicas choir
  on: keeper
  module: core.choir.absent
  params:
    incarnation: "${ incarnation.name }"
    choir:       replicas
    sid:         "${ input.target_sid }"

Output

Поле	Тип	Описание
`incarnation`	`string`	эхо params
`choir`	`string`	эхо params
`sid`	`string`	эхо params
`state`	`absent`
`removed`	`bool`	true, если Voice был снят; false, если его не было

Заметки

Keeper-side: все side-effect-ы — в реестре Keeper-а (Postgres incarnation_choir_voices), не в файловой системе или процессах Soul-а. Подпроцессов не выполняет, на Soul ничего не доставляет.
present — default при пустом state (симметрично core.file.present); неизвестный state (не present/absent) — шаг падает.
Модуль правит членство Voice-а, а не создаёт сам Choir или инкарнацию.
Связь с soulprint: после present/absent членство проецируется в выражения как soulprint.self.choirs и soulprint.hosts[].choirs (зеркало covens, источник — реестр incarnation_choir_voices).
Roster-growth в пределах одного прогона не реализован: новый Voice виден только последующим прогонам.

Безопасность и умолчания

Keeper-side операция (on: keeper): root/capability-семантика неприменима, манифеста capabilities нет. Доступ к запуску сценария с этим шагом регулируется RBAC оператора на уровне прогона.
Инвариант членства (ADR-044) переиспользуется, не дублируется: Voice можно добавить только для SID, уже являющегося членом инкарнации — это гарантирует choir-CRUD (AddVoice → ErrNotMembers), не сам модуль; нарушение → failed-событие.
Валидация входа против инъекции мусора в реестр: choir проверяется ValidChoirName, sid — ValidSID (FQDN); невалидное — шаг падает и в реестр не попадает.
Существование инкарнации проверяется до мутации: absent на опечатке имени инкарнации не проходит тихо, а валит шаг.

core.choir

Требования

Состояния

Заметки

Безопасность и умолчания

См. также