debate_bind_role

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

Purpose

Installs, retires, or diagnoses one role/session binding. Enforces single active ownership per role; retiring an active owner needs conductor sanction.

Arguments

Required: topic_id, role, session_id.

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

topic_id: existing debate topic.
role.
session_id. Note: The session being bound; must be owned by the caller.
bound_by_msg_id.
bound_by_role.
conductor_override_msg_id. Note: Conductor or star callers only; cites the sanctioning CONDUCTOR decision and is validated twice, read-only first and authoritatively inside the unit.
reason.
replace_active. Note: Atomic swap onto a new session; without it a duplicate active owner is rejected.
runtime.
state. Note: Defaults to active when omitted; an explicit empty value fails validation.

Result

Object with topic_id, role, session_id, runtime, state, generation, plus retired_sessions and retired_worker_claims counts for the swap path.

Boundaries

Binding a session to a role the caller does not hold is treated as takeover and denied as not-found unless a valid conductor override is supplied. Topic existence is checked before ownership so missing topics never become an existence oracle. Without an override, star and conductor callers meet the same ownership rule as everyone else.

Lifecycle / side effects

Binding changes persist atomically with an audit/history event; replacing an active owner retires its worker claims. Retired bindings stay visible as history and never grant further authority.

Errors

Unknown topics, malformed ids, unowned sessions, duplicate actives, and invalid or missing overrides are rejected with uniform vocabulary.

Example

{
  "reason": "Resume after restart",
  "role": "CONDUCTOR",
  "session_id": "<uuid>",
  "state": "active",
  "topic_id": "<uuid>"
}

Result shape:

{
  "generation": 2,
  "role": "CONDUCTOR",
  "session_id": "<uuid>",
  "state": "active",
  "topic_id": "<uuid>"
}