# `Parlora.Status`
[🔗](https://github.com/hfiguera/parlora/blob/v0.1.0/lib/parlora/status.ex#L1)

Public map returned by `Parlora.status/1`; this module defines types only.

Optional fields are absent until observed, not inferred. Monotonic timestamps
are signed microseconds on this VM and cannot be compared across VM restarts.
`:settled` interpretation does not mean jobs finished. A submitted or uncertain
job may still be running. Delivery acceptance is not playback confirmation.
A submitted job reserves capacity while its adapter command may still be
pending. `admission` tracks that callback: pending, dispatched (`:started`), or
replied (`:settled`). These labels do not establish that backend work started;
`started_at_us` and `:request_started` report that separate observation.

Status omits transcript history, full task inputs and backend results. Retained
clarification data can contain question text and application-defined input.
Treat it as application data, not automatically safe public telemetry.

# `delegation`

```elixir
@type delegation() :: %{
  :status => :pending | :claimed | :cancelled,
  :received_at_us => integer(),
  optional(:task_id) => String.t(),
  optional(:task_revision) => pos_integer(),
  optional(:context_wait) => Parlora.ContextSnapshot.context_wait(),
  optional(:clarification) => Parlora.ContextSnapshot.policy_clarification()
}
```

# `delivery`

```elixir
@type delivery() ::
  :awaiting_interpretation
  | :awaiting_provider
  | :accepted
  | :unconfirmed
  | :rejected
  | :unknown
  | :stale
  | :not_applicable
```

# `interpretation`

```elixir
@type interpretation() :: :running | :settled | :unresolved
```

# `job`

```elixir
@type job() :: %{
  :status => job_state(),
  optional(:admission) => :pending | :started | :settled,
  :task_id => String.t(),
  :task_revision => pos_integer(),
  :delegation_id => String.t() | nil,
  :deadline_at_us => integer() | nil,
  :current? => boolean(),
  optional(:started_at_us) => integer(),
  optional(:completed_at_us) => integer(),
  optional(:delivery) => delivery(),
  optional(:result_command_id) => String.t() | nil,
  optional(:delivery_updated_at_us) => integer(),
  optional(:context_wait) => Parlora.ContextSnapshot.context_wait(),
  optional(:clarification) => Parlora.ContextSnapshot.clarification()
}
```

# `job_state`

```elixir
@type job_state() ::
  :queued | :submitted | :uncertain | Parlora.BackendResult.status()
```

# `lifecycle`

```elixir
@type lifecycle() :: :starting | :ready | :closing
```

# `playback`

```elixir
@type playback() :: %{
  :stage => playback_stage(),
  :observed_at_us => integer(),
  optional(:evidence) => Parlora.Channel.Capabilities.evidence(),
  optional(:stream_id) => String.t(),
  optional(:sequence) => non_neg_integer(),
  optional(:epoch) => non_neg_integer(),
  optional(:first_sample) => non_neg_integer(),
  optional(:end_sample) => non_neg_integer()
}
```

# `playback_stage`

```elixir
@type playback_stage() ::
  :queued
  | :handed_off
  | :cleared
  | :estimated_playback
  | :device_reported_playback
  | :unknown
```

# `t`

```elixir
@type t() :: %{
  session_id: String.t(),
  status: lifecycle(),
  provider_activity: :unknown | :in_progress | :idle,
  provider_speech: :unknown | :speaking | :idle,
  context_acknowledgment?: boolean(),
  observed_at_us: integer(),
  interpretation: interpretation(),
  delegations: %{optional(String.t()) => delegation()},
  jobs: %{optional(String.t()) => job()},
  health: Parlora.SessionHealth.t(),
  playback: %{optional(playback_stage()) => playback()},
  output_recovery:
    %{
      token: pos_integer(),
      cause: atom(),
      stage: :reconnecting | :awaiting_user,
      started_at_us: integer()
    }
    | nil
}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*