Response Type Decision Matrix

ResponseType.CONTENT

Use when: Endpoint returns narrative content fragments from the journal.

Return type: list[BaseFragment] (FragmentStream alias)

Examples:

  • get_journal_entries() - returns last N fragments

  • get_story_update() - returns blocks + choices + media

Characteristics:

  • Read-only (MethodType.READ)

  • Returns story discourse (what player sees)

  • Ordered, sequential output

ResponseType.INFO

Use when: Endpoint queries metadata without side effects.

Return type: Subclass of InfoModel (ProjectedState, UserInfo, WorldInfo, SystemInfo)

Examples:

  • get_story_info() - projected current-state sections

  • get_user_info() - account details, achievements

  • list_worlds() - available world templates

Characteristics:

  • Read-only (MethodType.READ)

  • Returns structured metadata (not narrative)

  • Idempotent queries

ResponseType.RUNTIME

Use when: Endpoint returns a runtime/status envelope rather than plain metadata or raw fragment lists. This includes state mutations, control operations and control/status envelopes that need acknowledgment metadata.

Return type: RuntimeInfo

Examples:

  • resolve_choice() - player took action

  • create_story() - new ledger created

  • drop_story() - ledger deleted

  • get_story_update() - runtime envelope wrapped in RuntimeInfo

Characteristics:

  • Common for write operations, but not limited to them

  • Returns acknowledgment + cursor position

  • May succeed (status=”ok”) or fail (status=”error”)

RuntimeInfo fields:

  • status: “ok” | “error”

  • code: Optional error code (e.g., “CHOICE_NOT_FOUND”)

  • message: Human-readable description

  • cursor_id, step: Current position (if applicable)

  • details: Free-form metadata (controller-specific data)

ResponseType.MEDIA

Use when: Endpoint returns binary/media content.

Return type: MediaFragment (at native layer)

Examples:

  • get_world_media() - retrieve world-scoped media payloads

  • future asset/media fetch endpoints with native media payloads

Characteristics:

  • Read-only (MethodType.READ)

  • Returns media objects with RITs (not HTTP URLs yet)

  • Service layer dereferences RIT → backend-specific format

  • Transport layer converts to URL/base64/file path

Status: Active. Current service surfaces already include world-media responses, and gateway/transport layers may further adapt those payloads.

Decision Flowchart

Does endpoint return narrative fragments?
  YES → CONTENT
  NO ↓

Does endpoint mutate state?
  YES → RUNTIME
  NO ↓

Does endpoint return media/assets?
  YES → MEDIA
  NO ↓

Endpoint returns metadata
  → INFO