debate_worker_claim

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

Purpose

Idempotently allocates or reuses the derived worker for one trigger (topic, role, parent, trigger). The worker-side take primitive for exactly-once execution.

Arguments

Required: topic_id, role, parent_session_id, trigger_msg_id.

Optional: details_json.

topic_id: existing debate topic.
role.
parent_session_id. Note: Owning parent session of the trigger.
trigger_msg_id. Note: The message being claimed.
details_json. Note: Optional object; malformed JSON is rejected with an envelope error.

Result

Claim object: topic_id, role, parent_session_id, trigger_msg_id, worker_session_id, state, parent cursor pair, claimed_at, heartbeat_at, completed_at, ack_msg_id, details, plus duplicate and no_action markers. Active claims heartbeat; retired claims requeue at most twice before reporting exhausted.

Boundaries

Only caller-visible triggers resolve; foreign triggers answer without disclosure. Triggers on the implementation vehicle fail closed here and belong to the conductor-approved vehicle out of band. Worker session ids are UUIDs; the counter is history only.

Lifecycle / side effects

Allocate, heartbeat, bounded requeue, and completion persist atomically with an audit/history event. Terminal replies complete the claim through the post and advance paths.

Errors

Unknown triggers, inactive parents, malformed JSON, and exhausted requeues are reported without leaking foreign claim state.

Example

{
  "parent_session_id": "<uuid>",
  "role": "EXECUTOR_1",
  "topic_id": "<uuid>",
  "trigger_msg_id": "<uuid>"
}

Result shape:

{
  "duplicate": false,
  "no_action": false,
  "role": "EXECUTOR_1",
  "state": "active",
  "topic_id": "<uuid>",
  "trigger_msg_id": "<uuid>",
  "worker_session_id": "<uuid>"
}