# `Giocci.Inspect`

Read-only inspection of this client and Giocci relays and engines.

Inspection does not register clients, save modules, or execute application
functions. The client application and its Zenoh session must be running, but
remote queries do not require a prior `Giocci.register_client/1` call.
Module queries use this configured client name; it is not access control.

Results are snapshots and registration lists do not guarantee reachability.
Remote operations accept `timeout: milliseconds` (default: `5_000`).
A responsive relay with no matching records returns `{:ok, []}`; a
communication failure does not. Remote queries require a compatible
relay or engine. Module queries describe saved relay BEAMs, not engine
distribution or execution. Multiple responses to the same inspection key
are reported as an error rather than selecting one responder.

`relay_info/2` and `engine_info/2` return `:name`, `:giocci_version`,
`:elixir_version`, `:otp_release`, `:system_architecture`, `:uptime_ms`
(since the target application started), and `:schedulers_online` (BEAM
schedulers, not allocated vCPUs). Engine information and ping query the
engine directly, without a relay name. Relay information and ping work
without registered engines. Ping measures Giocci Query/Reply round-trip
time using the client's monotonic clock; it includes waiting and response
processing, not ICMP timing.

# `connection_info`

Returns this client's name and key prefix, its Zenoh ID, and the router and
peer IDs known to its own session. It does not query a relay or describe
the entire network; zero connected routers can be normal in a peer setup.

Returns `{:ok, %{client_name: name, key_prefix: prefix, zenoh_id: id,
router_ids: routers, peer_ids: peers}}` or `{:error, reason}`.

# `engine_info`

Queries an engine's runtime information by engine name.

# `list_engines`

Returns the sorted, distinct engine names recorded at the specified relay.
Returns `{:ok, []}` if none are registered. Use `ping_engine/2` to check
whether an engine responds.

# `list_functions`

Returns the saved BEAM's public callable functions as sorted
`{name, arity}` tuples with string names (for example, `{"hello", 0}`).
The module can be specified as an atom or a name returned by
`list_modules/2`. Default-argument arities and public callbacks are
included; private functions, macros, `module_info/0,1`,
`__info__/1`, and `__struct__/0,1` are excluded. Other `__`-prefixed
public functions are not excluded just because of their names.

The relay analyzes the stored BEAM without loading or running the module.
Returns `{:error, "module_not_found"}` for a missing saved module or
`{:error, "invalid_beam"}` if its BEAM cannot be analyzed.

# `list_modules`

Returns the sorted, distinct module names as strings (for example,
`"Elixir.MyModule"`) saved at a relay under this configured client name,
or `{:ok, []}` if none are saved.

The list is based on the relay's stored BEAMs, not the client's loaded
code. Names can be passed directly to `list_functions/3` or
`module_info/3`. Other connections using the same client name share
the stored namespace.

# `list_relays`

Compares relays this client has successfully registered with each relay's
current record for this client's name. The result is sorted by relay name.

Returns `{:ok, []}` if there is no local history, `{:ok, confirmed_relays}`
if all candidates agree, `{:warn, confirmed_relays, issues}` if some
agree, or `{:error, issues}` if none can be confirmed. Each issue has
`%{relay: name, reason: reason}`; a relay that responds without this
client's registration reports `"client_not_registered"`, while a relay
without a response reports its timeout or connection error.

`:timeout` applies separately to each candidate relay (default: 5_000 ms).

# `module_info`

Returns `%{module: name, beam_sha256: hash, beam_size_bytes: size,
saved_at: date_time}` for this client's BEAM saved at the relay.
`:module` is a string even when the module argument is an atom; the
argument can also be a name returned by `list_modules/2`.

`beam_sha256` is the lowercase hexadecimal SHA-256 of the entire BEAM,
`beam_size_bytes` is its size in bytes, and `saved_at` is a UTC
`DateTime` from the relay's clock. It records the last successful relay
save, including identical re-saves; inspection and distribution to a
later-registered engine do not update it. Engine distribution failures
do not undo a successful relay save. Functions are available separately
via `list_functions/3`.

Returns `{:error, "module_not_found"}` if the module is not saved under
this client name, or `{:error, "invalid_beam"}` for an invalid saved BEAM.

# `ping_engine`

Queries an engine by name and returns `{:ok, %{rtt_ms: milliseconds}}`
when it responds.

# `ping_relay`

Queries a relay directly and returns `{:ok, %{rtt_ms: milliseconds}}`
when it responds.

# `relay_info`

Queries the specified relay's runtime information.

---

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