debate_read

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

Purpose

Reads the topic-wide transcript with a compound (ts, msg_id) cursor plus kind/priority filters. This is the broadcast view every participant shares; genuinely private delivery is only via debate_signal_check.

Arguments

Required: topic_id, role.

Optional: kind_filter_csv, limit, priority_filter_csv, since_latest_compaction, since_msg_id, since_ts.

topic_id: existing debate topic.
role.
kind_filter_csv.
limit. Note: Bounded page size; over-range pages report truncation with follow-on cursors.
priority_filter_csv.
since_latest_compaction. Note: When true, resume after the latest COMPACTION snapshot instead of replaying from the start.
since_msg_id. Note: Takes precedence over since_ts; both take precedence over the stored role cursor.
since_ts.

Result

Object with messages, topic_state, last_msg_id_returned, last_ts_returned, count, truncated, next_msg_id_cursor, next_ts_cursor, limit, and bootstrap_compaction_msg_id (null when no snapshot exists).

Boundaries

Gated by project scope AND active participation; the sentinel project denies everyone including star and conductor, whose only path is debate_reconcile_project. Missing, foreign, and non-participant topics answer an identical unknown_topic shape. Blind-claim hiding applies inside for non-privileged viewers.

Lifecycle / side effects

Pure read: preserves nothing and advances no cursor. Bounded resume depends on snapshots written by debate_compact.

Errors

Malformed ids fail shape validation. Unknown topics answer unknown_topic regardless of caller. Unknown cursor ids are rejected without revealing transcript content.

Example

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

Result shape:

{
  "bootstrap_compaction_msg_id": null,
  "count": 0,
  "messages": [],
  "topic_state": "ACTIVE",
  "truncated": false
}

Filters and cursors narrow the window; the transcript itself is never altered by reading.