debate_signal_check

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

Purpose

Returns the recipient-scoped inbox: messages addressed to the caller's role or session past the compound cursor. This is the sole private-delivery path; debate_read shows the topic-wide transcript instead.

Arguments

Required: session_id, role, topic_id.

Optional: limit, since_msg_id, since_ts.

session_id. Note: Caller session; UUID sessions without a worker claim resolve through the parent binding claim.
role. Note: Must be declared in the topic; delivery matches role OR session.
topic_id: existing debate topic.
limit. Note: Defaults to 200, capped at 1000.
since_msg_id. Note: Explicit cursor, takes precedence over since_ts and any persisted cursor.
since_ts.

Result

Object with pending, count, truncated, next_cursor ({ts, msg_id} or null), max_priority, topic_state, and limit. Empty inboxes return zero counts with null cursors rather than errors.

Boundaries

Only messages addressed to the given role or session are ever returned. Cursor precedence is explicit ids, then timestamps, then persisted signal plus watermark self-heal, then the start of the topic. Unknown roles and missing topics answer with uniform vocabulary.

Lifecycle / side effects

Read-shaped but not side-effect free: checking persists cursor, delivery-progress, and one-shot DECISION claim state atomically, so later advances observe current data.

Errors

Malformed session, role, or topic ids fail shape validation. Undeclared roles, missing worker claims for UUID sessions, and unknown topics are rejected without disclosing foreign traffic.

Example

{
  "limit": 200,
  "role": "CONDUCTOR",
  "session_id": "<uuid>",
  "topic_id": "<uuid>"
}

Result shape:

{
  "count": 0,
  "limit": 200,
  "max_priority": null,
  "next_cursor": null,
  "pending": [],
  "topic_state": "ACTIVE",
  "truncated": false
}