debate_rotate_binding

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

Purpose

Atomically swaps a role owner from an old session to a new one with an explicit cursor mode, so exhausted sessions hand off without losing or replaying the inbox.

Arguments

Required: topic_id, role, old_session_id, new_session_id, cursor_mode.

Optional: bound_by_msg_id, bound_by_role, reason, runtime.

topic_id: existing debate topic.
role.
old_session_id. Note: Must currently hold the role actively and be owned by the caller.
new_session_id. Note: The incoming owner; must also be owned by the caller.
cursor_mode. Note: head starts at the tip, copy carries the newest primary-or-completed-worker cursor, replay restarts from the beginning.
bound_by_msg_id.
bound_by_role.
reason.
runtime. Note: Carried onto the new binding when supplied.

Result

Binding object plus old_session_id, new_session_id, cursor_mode, cursor_source (primary or completed_worker, null when none), and warning (copy_source_cursor_missing when copy found nothing to carry).

Boundaries

Both sides must be caller-owned; any other combination denies with one shared not-found shape so neither side is revealed. The predecessor binding must be active. No override parameter exists on this path: both-owned is the fail-closed rule.

Lifecycle / side effects

Swap plus cursor carry persist atomically with an audit/history event. Copy mode supersedes the incoming cursor when no source exists; replay mode marks prior cursors superseded.

Errors

Missing cursor modes, malformed sessions, inactive predecessors, and unowned sides are rejected; failures move nothing.

Example

{
  "cursor_mode": "copy",
  "new_session_id": "<uuid>",
  "old_session_id": "<uuid>",
  "role": "CONDUCTOR",
  "topic_id": "<uuid>"
}

Result shape:

{
  "cursor_mode": "copy",
  "cursor_source": "primary",
  "new_session_id": "<uuid>",
  "old_session_id": "<uuid>",
  "role": "CONDUCTOR",
  "topic_id": "<uuid>",
  "warning": null
}