# `BeamConsole`
[🔗](https://github.com/cristianodabc/beam-console/blob/v0.5.4/lib/beam_console.ex#L1)

Read-only access to sampled BEAM runtime topology.

The public API returns bounded normalized data. It never accepts PID strings,
atom names, or encoded Erlang terms from clients.

# `acknowledge`

```elixir
@spec acknowledge(non_neg_integer(), GenServer.server()) :: :ok
```

Acknowledges the caller's outstanding snapshot notification.

# `changes_since`

```elixir
@spec changes_since(non_neg_integer(), GenServer.server()) ::
  BeamConsole.Collector.changes_result()
```

Returns the directly following bounded diff or a full snapshot resync instruction.

# `detail`

```elixir
@spec detail(BeamConsole.Snapshot.t() | nil, String.t()) ::
  {:ok, BeamConsole.ProcessDetail.t()} | {:error, :unknown | :unavailable}
```

Loads allowlisted details for an opaque process entity ID.

Unknown IDs return `{:error, :unknown}`. A process that has exited or is not
local to the inspected snapshot returns `{:error, :unavailable}`.

# `latest_snapshot`

```elixir
@spec latest_snapshot(GenServer.server()) :: BeamConsole.Snapshot.t() | nil
```

Returns the latest completed snapshot, or `nil` before the first scan.

# `refresh`

```elixir
@spec refresh(GenServer.server()) :: :ok | {:error, :rate_limited}
```

Requests a new bounded runtime scan.

Concurrent requests are coalesced so the collector never overlaps scans.
Rapid operator requests return `{:error, :rate_limited}`.

# `search`

```elixir
@spec search(BeamConsole.Snapshot.t() | nil, String.t(), non_neg_integer()) :: [
  BeamConsole.ProcessInfo.t()
]
```

Searches process labels and safe metadata in a snapshot.

Matching is case-insensitive and the result count is bounded by `limit`. A
missing snapshot returns an empty list.

# `status`

```elixir
@spec status(GenServer.server()) :: BeamConsole.Collector.Status.t()
```

Returns bounded collector health and snapshot freshness information.

# `subscribe`

```elixir
@spec subscribe(GenServer.server()) :: {:ok, BeamConsole.Snapshot.t() | nil}
```

Subscribes the calling process to sampled snapshot notifications.

The return value contains the latest snapshot when one has already completed.
Subscribers receive `{:beam_console_snapshot, sequence}` version-invalidating
messages and are removed automatically when they terminate. A subscriber must
acknowledge each delivered sequence after reading the latest bounded state.

# `unsubscribe`

```elixir
@spec unsubscribe(GenServer.server()) :: :ok
```

Stops snapshot notifications for the calling process.

---

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