core.choir

keeper-sidesoulstack.orchestrationorchestration

Edit a Voice's membership in an incarnation's Choir, keeper-side.

core.choir adds and removes a Voice (a host by SID) from an incarnation's Choir part in the Keeper registry (Postgres); both states require on: keeper and never touch the host. Idempotent by construction: a repeated present of an already-Voice and absent of a missing one return changed=false, not an error. The incarnation's existence is checked before the mutation.

Requirements

Rootnot required
Sidekeeper-side
Collectionsoulstack.orchestration
Categoryorchestration

core.choir.present — The host (by SID) becomes a Voice of the incarnation's specified Choir (AddVoice).

Changes when

The Voice was added.

Stays unchanged when

The Voice already exists (ErrVoiceExists), which is not an error.

Parameters

Param	Type	Required / default	Description
`incarnation`	`string`	required	Name of the incarnation whose Choir is managed.
`choir`	`string`	required	Name of the Choir part within the incarnation.
`sid`	`string` format: sid	required	SID (FQDN) of the Soul whose Voice is added to the Choir.
`role`	`string`	optional	Role label of the voice in the choir (free-form).
`position`	`int`	optional	Position of the Voice in the part (>= 0).

Example — Add a new replica to the replicas choir

- 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

Field	Type	Description
`incarnation`	`string`	echoes params
`choir`	`string`	echoes params
`sid`	`string`	echoes params
`state`	`present`
`added`	`bool`	true if the Voice was added; false if it already existed

core.choir.absent — The host (by SID) is removed from the incarnation's Choir (RemoveVoice).

Changes when

The Voice was removed.

Stays unchanged when

The Voice does not exist (ErrVoiceNotFound), which is not an error.

Parameters

Param	Type	Required / default	Description
`incarnation`	`string`	required	Name of the incarnation whose Choir is managed.
`choir`	`string`	required	Name of the Choir part within the incarnation.
`sid`	`string` format: sid	required	SID (FQDN) of the Soul whose Voice is removed from the Choir.

Example — Remove the host from the replicas choir when retiring the role

- 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

Field	Type	Description
`incarnation`	`string`	echoes params
`choir`	`string`	echoes params
`sid`	`string`	echoes params
`state`	`absent`
`removed`	`bool`	true if the Voice was removed; false if it was not there

Notes

Keeper-side: all side effects are in the Keeper registry (Postgres incarnation_choir_voices), not in the file system or the Soul's processes. It spawns no subprocesses and delivers nothing to the Soul.
present is the default when state is empty (symmetric to core.file.present); an unknown state (not present/absent) makes the step fail.
The module edits a Voice's membership; it does not create the Choir or the incarnation itself.
Relation to soulprint: after present/absent the membership is projected into expressions as soulprint.self.choirs and soulprint.hosts[].choirs (a mirror of covens, sourced from the incarnation_choir_voices registry).
Roster growth within a single run is not implemented: a new Voice is visible only to subsequent runs.

Security & defaults

A keeper-side operation (on: keeper): root/capability semantics do not apply, and there is no capabilities manifest. Access to running a scenario with this step is governed by the operator's RBAC at the run level.
The membership invariant (ADR-044) is reused, not duplicated: a Voice can be added only for a SID that is already a member of the incarnation — this is guaranteed by the choir CRUD (AddVoice → ErrNotMembers), not the module itself; a violation → a failed event.
Input validation against injecting garbage into the registry: choir is checked by ValidChoirName, sid by ValidSID (FQDN); anything invalid makes the step fail and never reaches the registry.
The incarnation's existence is checked before the mutation: absent on a mistyped incarnation name does not pass silently — it fails the step.

core.choir

Requirements

States

Notes

Security & defaults

See also