debate_init

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

Purpose

Bootstraps a new debate topic: idempotent on (topic_id, roles), declares the roster, seeds active bindings, and optionally configures debate/v1 micro-state. Call it once per topic before any posts.

Arguments

Required: title, created_by_role.

Optional: blind_roles_csv, max_rounds, metadata_json, phase_timeout_seconds, project, protocol_version, resolve_by, roles_json, topic_id.

title: non-empty.
created_by_role: role posting the init.
blind_roles_csv: exactly two declared semantic roles when using debate/v1.
max_rounds. Note: 1..10; executor roles must be numbered EXECUTOR_1, EXECUTOR_2, ...
metadata_json: JSON object.
phase_timeout_seconds.
project: topic-owned immutable project; defaults from a singleton-grant creator, untagged for star, required otherwise. Note: Topic-owned immutable project. Explicit value wins when writable; otherwise derived from a singleton-grant creator, untagged for star/conductor, and required for multi-grant creators.
protocol_version: empty for legacy behavior, or debate/v1. Note: Empty selects legacy behaviour; debate/v1 enables blind roles, phases, and rounds.
resolve_by: optional ISO 8601 UTC deadline.
roles_json: JSON array of unique {role, session_id} dicts. Note: JSON array of {role, session_id} entries. Entries naming an existing session must be owned by the caller and visible in caller scope; omitted session ids are minted by the service as caller-owned identity.
topic_id: optional previously returned UUID; omitted on CREATE.

Result

Object with topic_id, title, state (INIT), created_at, created_by_role, resolve_by, archived_at (null), roles, metadata, seeded_bindings, plus protocol_state when the topic runs under debate/v1.

Boundaries

Creation stays inside the selected profile boundary and the resolved topic project. Named sessions are never taken over by knowledge of an identifier: each supplied session must exist, be owned by the caller, and sit in caller scope (star never substitutes for ownership). A repeat call with identical shape returns the existing topic; differing shape is rejected.

Lifecycle / side effects

Creates the topic and its seeded bindings atomically with an audit/history event. Priority lane plus reason is required at creation. Topics live INIT to ACTIVE to RESOLVED to ARCHIVED; later movement uses debate_state or debate_close_topic.

Errors

Missing title or created_by_role is rejected. Malformed topic ids, role shapes, blind sets, round bounds, timeout floors, and out-of-scope projects are rejected by validation. Unknown arguments are rejected. Nothing is partially created on failure.

Example

{
  "created_by_role": "CONDUCTOR",
  "project": "shared-ops",
  "roles_json": "[{\"role\":\"CONDUCTOR\",\"session_id\":\"<uuid>\"}]",
  "title": "Musl-first packaging"
}

Result shape:

{
  "seeded_bindings": [],
  "state": "INIT",
  "title": "Musl-first packaging",
  "topic_id": "<uuid>"
}

topic_id is assigned by the server when omitted; placeholders stand for returned values.