debate_add_role

Category: debate
Access: write
Audience: administrative (ordinary users do not normally call this directly)

Purpose

Appends a NEW role to a live topic and installs its active binding in one atomic unit. The mid-debate way to grow the roster, including numbered EXECUTOR_n workers.

Arguments

Required: topic_id, role, session_id.

Optional: bound_by_msg_id, bound_by_role, conductor_override_msg_id, reason, replace_active, runtime.

topic_id: existing debate topic.
role.
session_id. Note: The session owning the new role; must be owned by the caller.
bound_by_msg_id.
bound_by_role.
conductor_override_msg_id. Note: Validated when supplied; ordinary roster growth does not need it.
reason. Note: Defaults to a flexible-roster marker when omitted.
replace_active. Note: Covers the same-owner replay path; idempotent replays report added_role false.
runtime.

Result

Object with topic_id, role, session_id, runtime, state, generation, added_role, retired_sessions, and retired_worker_claims.

Boundaries

Restricted to conductor or star callers, plus ownership of the named session by the caller: knowing a foreign session id never enrolls it. Shape validation runs before ownership so precedence is unchanged for privileged callers.

Lifecycle / side effects

Roster append plus binding install succeed or fail together with an audit/history event. Same-owner replays are idempotent; a role owned elsewhere falls through to the ordinary binding path.

Errors

Unknown topics, malformed ids, unowned sessions, and callers without conductor or star scope are rejected uniformly.

Example

{
  "reason": "Spawn packaging worker",
  "role": "EXECUTOR_1",
  "session_id": "<uuid>",
  "topic_id": "<uuid>"
}

Result shape:

{
  "added_role": true,
  "generation": 1,
  "role": "EXECUTOR_1",
  "session_id": "<uuid>",
  "state": "active",
  "topic_id": "<uuid>"
}