Build specification

APIs and Commands#

Read surface#

• GET /v1/bellwether/level
• GET /v1/bellwether/island
• GET /v1/scenes/{id}?cursor=
• GET /v1/scenes/{id}/available-actions
• GET /v1/actors/{id}/public-state
• GET /v1/projects/{id}/state
• GET /v1/quests/{id}/state
• GET /v1/portals/{id}/preview (authorization before content)
• GET /v1/events?cursor=

Action surface#

POST /v1/actions; GET /v1/actions/{id}; POST /v1/actions/{id}/confirm|defer|cancel. Bellwether definitions include pitch respond, Orientation accept/disagree, Project create/join, Contribution submit/accept, Ally create/configure, Portal move, funding signal/decide, and mystery interpret.

Envelope#

Every Action includes definition/version, idempotency key, principal, Source, Organization, optional Project/Scene/instance, expected aggregate versions, parameters, proofs, and sim. Responses distinguish awaiting context, awaiting confirmation, committed, waiting external, completed, denied, state changed, and idempotency conflict.

Real-time#

SSE/WebSocket sends authorized event envelopes, aggregate-version notices, presence summaries, and Action state. Clients resync by cursor and never treat a dropped connection as cancellation or completion.