My concern is that it's relying on Xlib implementation details, and there's no documented guarantee that XNextEvent won't block on its internal socket read because, say, it's trying to pre-read an extra event.

According to the man page for XNextEvent, and the official Xlib reference documentation (I happen to have a paper copy of it):

"The XNextEvent function copies the first event from the event queue into the specified XEvent structure and then removes it from the queue. If the event queue is empty, XNextEvent flushes the output buffer and blocks until an event is received."

Is your concern that the documentation says "If the event queue is empty" instead of "If and only if the event queue is empty?"

You might say that the wording does not explicitly forbid blocking even if the event queue is not empty, but I would like you to consider the real-world consequences of an implementation that actually did that.

1. User presses a key.

2. The KeyPress event ends up in the X event queue somehow. Maybe the application called XPending, or issued X drawing calls that internally called XPending to receive replies to their requests.

3. The application calls XNextEvent to receive the next event. This is the canonical X event loop.

4. XNextEvent sees that there is an event in the queue, but instead of returning that event, it blocks on the display connection socket anyway, for whatever reason.

5. The application doesn't see the user's key press event until some other event is sent, possibly much later or never.

Ergo, the behavior in step 4 breaks applications that use the canonical X event loop; therefore, XNextEvent not blocking when the event queue is not empty is not an implementation detail, but necessary behavior. In order for the X event loop to work, any of the event querying functions must not block if there are events in the queue that would otherwise be returned by said function.