-spec advertise_capabilities() -> ok.

(Re-)publish this service's capabilities onto the mesh. Typically called once at boot; call again when the capability set changes.

-spec boot(module()) -> {ok, pid()} | {error, term()}.

Wire a service module into hecate_om and start it.

Typical call from the hosting service's _app:start/2:

start(_, _) -> hecate_om:boot(my_service).

-spec call_capability(binary(), binary(), term(), pos_integer()) -> {ok, term()} | {error, term()}.

Call a capability by name over the direct-dial data path: resolve a provider from the DHT, dial its serving station directly, and issue the CALL there (failing over to the next provider on error). The CALL uses CapName as the procedure, realm-scoped.

-spec health() -> hecate_om_service:health().

Snapshot of this service's health. Used by /health handler.

-spec keypair() -> {ok, macula_identity:key_pair()} | {error, term()}.

This service's stable signing keypair, or {error, no_keypair} when running on an ephemeral identity. Needed by every direct-dial PROVIDER desk (macula_response:advertise_direct/6,7, macula_streamer:advertise_direct/6,7, ...), which sign their own DHT advertisement record with it.

-spec mesh_handles() -> {ok, term(), binary()} | {error, mesh_unavailable}.

The {Pool, Realm} pair every PubSub/RPC-consumer/Content call needs together. Replaces the hand-rolled case {macula_client(), realm()} of {{ok,P},{ok,R}} -> ... pairing four independent hecate-services repos each wrote for themselves (hecate_mesh.erl, tom_ocean_mesh.erl, tom_wire_macula.erl, tom_crier.erl) because hecate_om gave them nothing to build on. Degrades to {error, mesh_unavailable} rather than crashing when either half is missing (mesh unreachable, or no client attached yet).

-spec realm() -> {ok, binary()} | {error, term()}.

This service's realm tag (32-byte binary). Previously reachable only by calling hecate_om_identity:realm/0 directly, past the public facade -- every service wanting to publish/subscribe/advertise on the mesh needs this alongside macula_client/0, so it belongs here.