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

Acknowledges the caller's outstanding snapshot notification.

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

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

@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}.

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

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

@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}.

@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.

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

Returns bounded collector health and snapshot freshness information.

@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.

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

Stops snapshot notifications for the calling process.