# Response Type Decision Matrix

## ResponseType.CONTENT

**Use when:** Internal code needs a plain narrative fragment stream without
runtime cursor metadata.

**Return type:** `list[BaseFragment]` (FragmentStream alias)

**Examples:**
- lower-level journal reads that return last N fragments
- test helpers or adapters that intentionally do not need a runtime envelope

**Characteristics:**
- Read-only (MethodType.READ)
- Returns story discourse without session status
- Ordered, sequential output

**Status:** Internal/narrow. Public story-session service methods return
`RuntimeEnvelope` rather than raw fragment lists.

---

## ResponseType.RUNTIME_ENVELOPE

**Use when:** Endpoint returns ordered story fragments plus cursor/session
metadata.

**Return type:** `RuntimeEnvelope`

**Examples:**
- `create_story()` - creates a ledger and returns the initial envelope
- `resolve_choice()` - advances the story and returns new fragments
- `get_story_update()` - returns ordered runtime fragments for the active story

**Characteristics:**
- Carries `cursor_id`, `step`, redirect metadata, and service metadata
- Carries `fragments: list[BaseFragment]`
- The client renders fragments directly through a registry/shell model
- Unknown fragment types are valid extension points and must survive transport

See `FRAGMENT_STREAM_CONTRACT.md` for the detailed client-facing contract.

---

## 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 narrative fragments. This is for acknowledgment/control operations
that do not return a story fragment batch.

**Return type:** `RuntimeInfo`

**Examples:**
- `drop_story()` - ledger deleted
- future maintenance or control operations that need status/details only

**Characteristics:**
- Common for write operations, but not limited to them
- Returns acknowledgment and optional 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 → RUNTIME_ENVELOPE for public story sessions
        CONTENT only for lower-level raw-fragment helpers
  NO ↓

Does endpoint mutate state?
  YES → RUNTIME_ENVELOPE if it advances story and returns fragments
        RUNTIME if it is acknowledgment/status only
  NO ↓

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

Endpoint returns metadata
  → INFO
```