# `SuperPi.Conversation.Locator`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/conversation/locator.ex#L1)

Finds, or starts, the one machine of a conversation. The machine is unique in the whole
cluster: its name is registered in `Horde.Registry`, so a request that lands on any node reaches
the same process (a pid on another node works with `Machine.submit/3` and the rest of the API).

## Supervision

`config :super_pi, machine_supervision:`

- `:horde` (default). `Horde.DynamicSupervisor` places the machine on a node and restarts it on
  another node when its node stops. The machine starts in `:recovering`, finds the task that was
  running, and resumes it.
- `:local`. The machine runs under the supervisor of the calling node and stays there. If the
  node stops, the name is released and the next request starts the machine on whichever node
  receives it (no automatic resume). Use it when a conversation must stay with the node that
  holds its `local` or `scratch` workspace.

`restart: :transient` (default) restarts a machine that stops abnormally. `restart: :temporary`
never restarts it; use that for short-lived helpers such as subagent children.

A netsplit can briefly allow two machines for one conversation. Horde removes one when the
nodes reconnect. Task rows carry the owner node, so the survivor does not reset a live task.

# `all`

All conversation ids that have a machine, with their pids (the whole cluster).

# `await_gone`

Waits until the conversation has no registered machine. Returns `:ok` or `:timeout`.

# `ensure_started`

```elixir
@spec ensure_started(term(), keyword(), keyword()) :: {:ok, pid()} | {:error, term()}
```

Returns `{:ok, pid}` for the conversation's machine, starting it if there is none.
`machine_opts` are the options of `Machine.start_link/1` (`:extensions`, test hooks).
Options: `:restart` (default `:transient`), `:supervision` (default from config).

# `ensure_started!`

The pid of the conversation's machine, started with `extensions` when none runs. With
`set_extensions: true` a running machine gets `extensions` too: the gateway resolves the harness
on every request. The RPC server keeps a running machine's extensions.

# `key`

# `registry`

# `whereis`

```elixir
@spec whereis(term()) :: pid() | nil
```

The machine pid for the conversation, on any node, or `nil`.

---

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