docs: document the listener thread; narrow the no-threads guarantee

[benaliabderrahmane]

Description

"No background threads" was asserted across DESIGN.md and README.md and is no
longer unconditional, so each of those assertions now says what it actually
guarantees: no background thread for an executor that waits, and one per-context
listener thread for an application that registers a listener callback. The
### No background threads, and why heading keeps its name; the section under it
now states the exception instead of an absolute. The property that matters to a
reader choosing this RMW — that a SingleThreadedExecutor or
MultiThreadedExecutor process starts nothing — is unchanged, and saying so
precisely beats leaving a claim a reader can disprove with ps.

DESIGN.md gains "The listener thread: delivery without a wait", written in
the same shape as the doorbell section it borrows its ordering proof from: why
EventsExecutor deadlocks against wait-only delivery, the lazy start, the two
hazards that come with a watched endpoint still sitting in a wait set, the
listener_mutex lifetime rule and the restrictions it implies, and what the
thread deliberately is not — it wakes on socket readiness, never on a clock, so
it does not make deadline or liveliness enforceable.

Both hazards are documented, where an earlier draft of this section asserted the
first one away. Reordering comes first: drain_endpoint recvs outside
queue_mutex and pushes inside it, so the listener and an rmw_wait/rmw_take
draining the same socket can interleave as recv A / recv B / push B / push A, and
a per-endpoint drain_mutex held for the whole drain serialises them. Calling
that "fine, since both use non-blocking recv into the same mutex-protected
queue" was wrong — the queue mutex prevents corruption, not reordering — so this
is a correction, not a rewording. The lost wakeup comes second, and keeps the
delivery_fd ordering pair and its "there is no order in which it is missed"
proof, now with a subsection on why that fd belongs to the wait set rather
than the context: reading an eventfd drains its whole counter, so a single shared
fd is a single credit, and both ways it went missing are written down — a wait set
that gained no work of its own still consumed it and discarded it, and a wait
already blocked when the listener started had armed nothing at all. The ordering
rule that comes with a per-wait-set fd is written down too: rmw_destroy_wait_set
deregisters under listener_mutex strictly before it closes the fd, or the
listener writes eight bytes into a recycled fd number.

The lifetime rule is stated as context-wide, not endpoint-local, because there
is one listener_mutex per context: a callback must not destroy, register a
callback on, or clear the callback of any endpoint in the context, and must
not create or destroy a wait set either, since that mutex also guards the
delivery-fd list. That same context-wide mutex is held across the drain and taken
again by listener_unwatch, which is why an unwatch blocks on whatever drain is
in flight rather than specifically on a drain of the endpoint being unwatched. The
second new lock adds a second restriction — a callback must not rmw_take its own
endpoint, because it fires inside drain_endpoint while that endpoint's
drain_mutex is held.

The unsupported-features list separates two things that were conflated under
"event callbacks": QoS status events, refused for every rmw_event_type_t
with the reasoning for why refusing beats reporting success for an event that
never arrives, and the listener callbacks, which are supported and are what an
EventsExecutor actually needs. The same split lands in README.md's limitations
paragraph, which also gains a Callbacks row in the architecture table. The
file table gains drain.cpp and listener.cpp, and rmw_event.cpp is no longer
described as "event stubs".

Two statements elsewhere in DESIGN.md still asserted the old world and are
corrected here as well. The resource profile was wrong on three rows, not just the
thread count: a listener adds an epoll instance and a wake eventfd per context,
and every wait set now owns a delivery eventfd, so the descriptor undercount is
its own fix. And the wait set's In-process concurrency section still opened
"All socket I/O happens inside rmw_wait()", which the listener thread makes
false; it now says where I/O actually runs, names both new locks, and is explicit
that two callers draining the same endpoint do serialise on its drain_mutex —
that is what keeps a publisher's samples in order — while different entities still
do not contend.

test/README.md gains a section for test_rmw_listener_callbacks.cpp in the
existing per-file table format, and its "what is NOT tested" table now covers QoS
status events and notes that the listener is not a timer.

CHANGELOG.md gains an Unreleased entry in the existing Added/Changed/Fixed
structure. It covers this stack only: #64's event-API changes are not an ancestor
of this branch and carry their own entry there, so merging this does not ship a
changelog for absent code.

Is this user-facing behavior change?

How was this tested?

Documentation only; no source change. Suite re-run on jazzy to confirm
nothing moved: 176 tests, 0 failures.

Did you use Generative AI?

Additional Information

Two pre-existing inaccuracies in test/README.md are left alone rather than
fixed here, to keep this PR to the listener change: it still says "All tests run
in a single process" although test_rmw_cross_process.cpp exists, and it has no
section for test_rmw_event.cpp (added in #61). Happy to fix either in a
separate docs PR.

The PR template's own note says "CI builds and tests run on jazzy, kilted and
rolling" — lyrical was added to the matrix in #17, so that line is now stale too.