docs: condense implementation comments

server/src/conn_session.cpp

@@ -186,15 +186,8 @@ void ConnSession::close() {
     state_.store(State::Disconnecting, std::memory_order_release);
     uint32_t uid = user_id_.load();
     if (uid) {
-        // Broadcast LEFT BEFORE erasing the user, so remaining clients (and the audio
-        // engine's remove_stream path on each peer) learn about the departure. This
-        // covers ungraceful disconnects (TCP drop, crash, network loss) that previously
-        // silently erased the user from the registry without notifying anyone — which
-        // left stale users in peer client lists and kept Opus PLC hissing forever on
-        // peers whose remove_stream was never triggered. Mirrors kick_user's first half
-        // (session_registry.cpp kick_user). broadcast_left releases its shared_lock
-        // before remove_user acquires the unique_lock, so no deadlock; and send_envelope
-        // on this session is a no-op now that closed_ is true.
+        // Broadcast before erasing so peers can remove the user's streams. broadcast_left
+        // releases its shared lock before remove_user acquires the unique lock.
         registry_->broadcast_left(uid, "");
         registry_->remove_user(uid);
     }

server/src/main.cpp

@@ -36,7 +36,7 @@ int main(int argc, char** argv) {
     // launcher redirects stdout to a pipe, as the C# interop smoke test's Process does to
     // read the bound port) — go unbuffered so the startup banner (incl. "TCP :<port>") is
     // visible immediately instead of sitting in the CRT's buffer until it fills or the
-    // process exits. Same fix as tools/vccli/src/main.cpp.
+    // process exits.
     std::setvbuf(stdout, nullptr, _IONBF, 0);
 
     voicecat::server::Config cfg;

server/src/server.cpp

@@ -169,12 +169,8 @@ int Server::run() {
     });
 
     // ── Keepalive reaper (docs/protocol.md §7) ─────────────────────────────────
-    // Sweeps every reaper_sweep_ms and drops any session whose last_seen is older than
-    // reaper_timeout_ms. Each close() broadcasts UserEvent::LEFT via the Tier 1 fix, so
-    // peers learn about the timeout exactly like a normal disconnect — their audio engines
-    // call remove_stream and stop PLC. This catches half-open connections (NAT timeout,
-    // wifi loss without RST, laptop sleep) that never produce a TCP EOF and would otherwise
-    // leave ghost users forever. Disabled when reaper_timeout_ms <= 0.
+    // Drops half-open sessions and broadcasts LEFT so peers remove their streams.
+    // Disabled when reaper_timeout_ms <= 0.
     asio::steady_timer reaper_timer(io);
     std::function<void()> arm_reaper;
     if (cfg_.reaper_timeout_ms > 0) {

server/src/session_registry.h

@@ -1,10 +1,4 @@
-/*
- * server/session_registry.h — In-memory session, channel, and user registry.
- *
- * Tracks all authenticated sessions, the channel tree, user<→>channel assignments,
- * UDP endpoint bindings, and SSRC<→>session mappings.
- * Protected by a shared_mutex (many readers, few writers). All methods are thread-safe.
- */
+/* Thread-safe in-memory session, channel, user, and media registry. */
 #ifndef VOICECAT_SERVER_SESSION_REGISTRY_H
 #define VOICECAT_SERVER_SESSION_REGISTRY_H
 
@@ -49,19 +43,14 @@ class SessionRegistry {
    public:
     explicit SessionRegistry(std::shared_ptr<Database> db);
 
-    // Load channels from the database, seeding defaults on first run.
     void load_channels();
 
-    // Register a session (before auth). Returns the assigned session_id.
     uint64_t register_session(std::weak_ptr<ConnSession> session);
 
-    // Remove a session (called on disconnect).
     void unregister_session(uint64_t session_id);
 
-    // Add a user once authenticated. Returns the assigned user_id.
     uint32_t add_user(uint64_t session_id, const voicecat::v1::User& user);
 
-    // Remove a user (called on disconnect after auth).
     void remove_user(uint32_t user_id);
 
     // Broadcast a UserEvent::LEFT for a user to all other sessions. Called by
@@ -70,29 +59,21 @@ class SessionRegistry {
     // kick_user(). Takes the shared lock internally; safe to call from ConnSession::close.
     void broadcast_left(uint32_t user_id, const std::string& reason);
 
-    // Move a user to a channel. Returns false if channel doesn't exist.
     bool set_user_channel(uint32_t user_id, uint32_t channel_id);
 
-    // Set the user's voice-plane subscription flag on their proto (broadcast-ready).
     void set_user_voice_subscribed(uint32_t user_id, bool subscribed);
 
-    // Snapshot for ServerStateSnapshot message.
     std::vector<voicecat::v1::Channel> channel_snapshot() const;
     std::vector<voicecat::v1::User>    user_snapshot() const;
     std::optional<voicecat::v1::User>  user_snapshot_user(uint32_t user_id) const;
     std::optional<std::string>         user_nickname(uint32_t user_id) const;
 
-    // Resolve target sessions for a text message relay.
     std::vector<std::shared_ptr<ConnSession>> resolve_text_targets(
         uint64_t sender_session_id, voicecat::v1::TextScope scope, uint32_t target_id) const;
 
-    // Broadcast an envelope to all sessions except the excluded one.
     void broadcast(const voicecat::v1::Envelope& env, uint64_t exclude_session_id = 0) const;
 
-    // Return all sessions whose last_seen is older than max_age_ms (steady_clock ms), i.e.
-    // have not had any inbound TCP or UDP activity in that span. The reaper (server.cpp)
-    // calls close() on each — which broadcasts UserEvent::LEFT via the Tier 1 fix. Locks
-    // only to collect the list; close() runs outside the lock (mirrors kick_user's pattern).
+    // The caller closes returned sessions outside the registry lock because close re-enters it.
     std::vector<std::shared_ptr<ConnSession>> find_stale_sessions(int64_t max_age_ms) const;
 
    private:
@@ -100,65 +81,42 @@ class SessionRegistry {
                             uint64_t exclude_session_id = 0) const;
 
    public:
-    // ── Permissions ────────────────────────────────────────────────────────────
-
     void set_session_permissions(uint64_t session_id,
                                  const voicecat::v1::Permissions& perms);
     std::optional<voicecat::v1::Permissions> get_session_permissions(
         uint64_t session_id) const;
 
-    // ── Moderation ─────────────────────────────────────────────────────────────
-
-    // Find a live session by its user_id. Returns nullptr if offline.
     std::shared_ptr<ConnSession> find_session_by_user_id(uint32_t user_id) const;
 
-    // Forcibly disconnect a user with a reason. Broadcasts UserEvent::LEFT.
-    // Returns true if the user was online.
     bool kick_user(uint32_t user_id, const std::string& reason);
 
-    // Kick a user and insert a persistent ban. Returns true if the user was online.
     bool ban_user(uint32_t user_id, const std::string& reason, int64_t expires_at);
 
-    // Set server-mute/deafen flags on a user and broadcast the update.
     bool set_server_mute(uint32_t user_id, bool muted, bool deafened);
 
-    // Move a user to a channel (permission-checked by caller).
     bool move_user(uint32_t user_id, uint32_t channel_id);
 
-    // ── Channel CRUD ───────────────────────────────────────────────────────────
-
-    // Create a channel. Returns the new channel id, or 0 on error.
     uint32_t create_channel(const voicecat::v1::Channel& ch, const std::string& password,
                             std::string& error);
 
-    // Update a channel. Returns false on error.
     bool update_channel(const voicecat::v1::Channel& ch, const std::string& password,
                         std::string& error);
 
-    // Delete a channel. Remaining users are moved to Lobby (id=1). Returns false on error.
+    // Deleting a channel moves its users to Lobby.
     bool delete_channel(uint32_t channel_id, std::string& error);
 
-    // Return a channel proto by id, or nullopt.
     std::optional<voicecat::v1::Channel> get_channel(uint32_t channel_id) const;
 
-    // Check a channel password.
     bool check_channel_password(uint32_t channel_id, const std::string& password) const;
 
-    // ── UDP / media ────────────────────────────────────────────────────────────
-
-    // Register a session's UDP token (called at auth success).
     void register_udp_token(const std::array<uint8_t, 16>& token, uint64_t session_id);
 
-    // Locate a session by its UDP binding token (called by MediaRelay on UDP_BINDING).
     std::shared_ptr<ConnSession> find_by_udp_token(const std::array<uint8_t, 16>& token) const;
 
-    // Associate a UDP endpoint with a session (called by MediaRelay after token verification).
     void register_udp_endpoint(asio::ip::udp::endpoint ep, uint64_t session_id);
 
-    // Locate the session that owns a UDP sender endpoint (called per incoming voice packet).
     std::shared_ptr<ConnSession> find_by_udp_endpoint(const asio::ip::udp::endpoint& ep) const;
 
-    // Assign an SSRC for a new stream. Returns the assigned SSRC.
     uint32_t assign_ssrc(uint64_t session_id);
 
     // Add/replace a stream entry on a user (called when StreamAnnounce succeeds).
@@ -170,17 +128,12 @@ class SessionRegistry {
     // User proto for broadcasting, or nullopt if user not found.
     std::optional<voicecat::v1::User> clear_user_stream(uint32_t user_id, uint32_t stream_id);
 
-    // Get all sessions in a channel except the one excluded (for SFU relay).
     std::vector<std::shared_ptr<ConnSession>> find_channel_sessions(
         uint32_t channel_id, uint64_t exclude_session_id = 0) const;
 
-    // Return the channel_id of a user (0 if not found).
     uint32_t user_channel(uint32_t user_id) const;
 
-    // Return a channel's authoritative AudioConfig (per-channel Opus tuning), or nullopt
-    // if the channel doesn't exist. There is no per-id Channel getter today otherwise —
-    // channel_snapshot() copies every channel, which callers needing just one config should
-    // avoid.
+    // Returns the authoritative per-channel Opus configuration.
     std::optional<voicecat::v1::AudioConfig> channel_audio_config(uint32_t channel_id) const;
 
    private: