swactor/crates/dashboard/ACTOR_PANEL_SPEC.md

# Actor Panel — v1 Spec (DRAFT)

Status: **DRAFT, v1 scope.** Converged scope for the first menu item of the
swactor dashboard: live observation of actors, their messages, mailbox, and
throughput. North star is `tokio-console`, scoped down to ship fast and iterate.

---

## 1. Goal

An **actor-first** roster plus a per-actor **dossier**, focused on identity,
lifecycle, mailbox, and message throughput. Streaming-feel, single-runtime in
focus with a runtime selector. Replaces the worker page's worker-centric framing
with actors as the primary axis; workers become a column and a filter.

One sentence: *a live console over the actor population and what each actor is
doing with its messages.*

## 2. Non-goals (deferred backlog)

Explicitly out of v1, queued for later iterations:

- Tree lens (spawn/supervision hierarchy) — needs `parent`.
- Flow/message graph (who talks to whom).
- All relationship facets: parent, children, senders/receivers, monitors.
- Per-actor **arrival** rate (saturation is derived from mailbox growth instead).
- Death-event capture with `StopReason` + `ExitValue` (dead actors get a stale
  badge from the last retained snapshot only).
- Rich lifecycle transition timeline (v1 shows current state + age).
- SSE streaming transport (v1 polls, matching the existing pages).
- Actor state inspection (`GetActorState` — security-gated, tier-3).
- Per-actor busy/poll handler timing.

## 3. Roster (primary view)

Sortable, filterable live table. Default sort: **mailbox depth descending**
(hot actors bubble up). Matches the existing worker page's poll cadence (750 ms)
and runtime selector.

| Column        | Source                                  | Notes |
|---------------|-----------------------------------------|-------|
| `name · addr` | `LogicalName` + `ActorAddress` (short)  | short hex identity + human label |
| `type`        | `actor_type_name`                       | **new** — the actor's Rust type |
| `state`       | derived from lifecycle flags (see §6)   | **up from poisoned-only**; colored badge |
| `mailbox`     | `mailbox_depth` + growth color          | trend color: steady / rising / runaway |
| `msg/s`       | derived from `messages_processed` delta | processed rate |
| `processed`   | `messages_processed`                    | lifetime total |
| `last msg`    | `last_msg_type`                         | last handled message type |
| `worker`      | `worker_id`                             | placement; also a filter |
| `age`         | from `spawn_time`                       | **new** — alive duration |

Filters: by **state** (e.g. "show all poisoned"), by **type**, by **worker**, by
**name/address** substring.

## 4. Dossier (row click)

Focus panel with three facets, all about the actor itself — no relationships.

### 4.1 Lifecycle & identity
Full address, `actor_type`, the `message_type` it accepts, spawn age, current
state. If the actor is dead, show the last-known state as stale (no
`StopReason`/`ExitValue` in v1 — deferred).

### 4.2 Mailbox dynamics
Depth-over-time chart + growth rate. Saturation signal. Backed by a **per-actor
history ring buffer** the view maintains (bounded `VecDeque`, same pattern as
the existing `HistorySample` in `worker_view.rs`). No core change — the view
folds each incoming snapshot into the buffer.

### 4.3 Message diet  *(signature feature)*
`message_type_counts` rendered as a sorted bar list (top-N) with counts, plus the
last message. Data already exists. This is the column `tokio-console` cannot have
(tasks are opaque); swactor actors are message-typed, so "what does this actor
do" is answered by what it eats. Lean into it visually.

## 5. Summary strip

Throughput at the runtime level, above the roster. Same card shape as the worker
view, actor-centric:

`actors` · `total msg/s` · `total mailbox` · `poisoned` · `uptime`

## 6. Lifecycle state derivation

A single display state derived from the four flags, in priority order:

```
poisoned               → "poisoned"   (red)
else stopping          → "stopping"   (orange)
else suspended         → "suspended"  (yellow)
else !started          → "new"        (blue)
else                   → "running"    (green)
```

swactor's flags *are* the states — cleaner than `tokio-console`'s running/idle.

## 7. Data model — the one core prerequisite

The live feed is `runtime.actors`, emitted by `DatastreamStatsHook`
(`crates/datastream/src/endpoint.rs`) from `ActorSnapshot` (`src/stats.rs:123`),
built in `ActorPool::mailbox_depths_into` (`src/worker.rs:995`). `ActorSlot`
(`src/worker.rs:558`) already holds every field v1 needs; the change is purely
additive in the snapshot, keeping the read-only push contract.

### Enrich `ActorSnapshot` with

| Field           | Type                  | Source on `ActorSlot` / actor        |
|-----------------|-----------------------|--------------------------------------|
| `started`       | `bool`                | `slot.started`                       |
| `suspended`     | `bool`                | `slot.suspended`                     |
| `stopping`      | `bool`                | `slot.stopping`                      |
| `actor_type`    | `&'static str`        | `slot.actor.metadata().actor_type_name` |
| `message_type`  | `&'static str`        | `slot.actor.metadata().message_type_name` |
| `spawn_time`    | `Option<u64>`         | `slot.env` → `SpawnTimestamp` (ms since runtime creation) |

`poisoned` already present. Propagate through `RuntimeActorSnapshotRecord`
(`endpoint.rs`) so the JSON wire payload carries the new keys.

**`parent` is excluded** — only needed for the tree lens (deferred).

### `name` continues via the existing merge

`name` is a `swactor-std` registry concern, not core. It already flows through the
`runtime.stats` → `actor_details` (`ActorInfo.name`) path and is merged by the
existing worker view. v1 reuses that merge; no new core plumbing for names.

## 8. View-side state (dashboard)

New view module, mirroring `SwactorWorkerView`'s structure but actor-centric.

### Per-actor view state

```rust
struct ActorState {
    address: String,
    name: Option<String>,
    actor_type: Option<String>,
    message_type: Option<String>,
    // lifecycle
    started: bool,
    suspended: bool,
    stopping: bool,
    poisoned: bool,
    spawn_time: Option<u64>,
    // throughput
    mailbox_depth: u32,
    mailbox_growth: f64,                  // depth/s, derived from history
    messages_processed: u64,
    msg_per_sec: f64,                     // derived via assign_u64_rate
    last_msg_type: Option<String>,
    message_type_counts: Vec<(String, u64)>,
    worker_id: Option<u32>,
    history: VecDeque<HistorySample>,     // per-actor mailbox chart buffer
    last_update: Option<Instant>,
}
```

`apply_json` reuses the tolerant multi-alias field helpers already in
`worker_view.rs` (`u32_field`, `string_field`, `assign_u64_rate`,
`parse_message_type_counts`) so the new keys land gracefully across versions.

### Snapshot JSON contract

Same envelope as the worker view:

```jsonc
{
  "runtimes": [
    {
      "stream": { "key": "...", "node": "...", "life": 0 },
      "live": true,
      "last_seen_ms_ago": 42,
      "summary": { "actors": 0, "msg_per_sec": 0.0, "mailbox_depth": 0, "poisoned": 0, "uptime_ms": 0 },
      "actors": [ { /* ActorState fields */ } ]
    }
  ]
}
```

Keyed by `stream_key = "{node}#{life}"` (one entry per runtime stream), matching
the worker view so the runtime selector is shared.

## 9. Transport & feel (kept cheap for v1)

- **Poll-first**, 750 ms, matching `worker_page.rs`. SSE is an iteration upgrade.
- **State-badge color** carries the alarm; no flash/animation machinery.
- **Dead actors**: last snapshot retained with a stale badge (`now - last_seen >
  LIVE_TTL`), no death-event capture.
- `LIVE_TTL` ~8 s (match the worker view).

## 10. File map

| File | Change |
|------|--------|
| `src/stats.rs` | add fields to `ActorSnapshot` (§7) |
| `src/worker.rs` (`mailbox_depths_into`) | populate new fields from `ActorSlot` |
| `crates/datastream/src/endpoint.rs` (`RuntimeActorSnapshotRecord`) | serialize new fields |
| `crates/dashboard/src/swactor/actor_view.rs` | **new** — `ActorPanelView: DashboardView` |
| `crates/dashboard/src/swactor/actor_page.rs` | **new** — `ACTOR_HTML` const |
| `crates/dashboard/src/swactor/mod.rs` | `pub fn actor_view()`, register |
| `crates/dashboard/src/server.rs` / `root_page.rs` | list **first** in the menu |

## 11. Open decisions

1. **Menu first**: render the index dynamically from `ViewRegistry::descriptors()`
   (today the static root HTML ignores it) vs. hardcode the actor link ahead of
   workers. Recommend dynamic — scales as views grow.
2. **Type cardinality display**: with many instances per type, do we also offer a
   type-aggregated rollup (OrleansDashboard-style) in v1, or instance-only?
   Recommend instance-only for v1; rollup is a fast follow.