debate_advance_watermark

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

Purpose

Advances the (topic, role) watermark cursor to a specific message: looks up its timestamp, posts the canonical WATERMARK marker, and reconciles the active primary signal cursor in one atomic unit.

Arguments

Required: topic_id, role, processed_up_to_msg_id.

topic_id: existing debate topic.
role. Note: Role-addressed only (no session argument): the caller must own the active binding for (topic, role).
processed_up_to_msg_id. Note: Must name a message already preserved in the topic.

Result

Same post shape: msg_id, ts, topic_state, and vehicle, for the INFO/WATERMARK marker.

Boundaries

Ownership without exception: star and conductor callers naming a role they hold no binding for are denied as not-found. All shape checks run before ownership.

Lifecycle / side effects

Marker plus cursor progress persist atomically with an audit/history event. The marker carries no recipients, so on its own it reconciles no addressed inbox.

Errors

Unknown message ids for the topic, malformed ids, and unowned roles are rejected; failures preserve nothing.

Example

{
  "processed_up_to_msg_id": "<uuid>",
  "role": "CONDUCTOR",
  "topic_id": "<uuid>"
}

Result shape:

{
  "msg_id": "<uuid>",
  "topic_state": "ACTIVE",
  "ts": "<iso-8601>",
  "vehicle": "analysis"
}