Address review feedback: PartialSubFlags.coerce helper and docs

- `PartialSubFlags.coerce(requestsPartial, supportsSendingPartial)`:
  single source of truth for the spec coercion rule
  `supportsSendingPartial := requestsPartial || supportsSendingPartial`.
  Used from `GossipRouter.setTopicPartialFlags` for the outbound side.
  AbstractRouter keeps the inline expression for the receive side to
  avoid a reverse layering dependency (pubsub -> gossip); a comment
  notes the rule is applied on both sides.

- `PartialSubscriptionState.setPeerFlags`: document that passing
  `PartialSubFlags.NONE` (or any equivalent all-false flags) is
  treated as a removal. Makes the set-sometimes-deletes invariant
  explicit for readers.

- `AbstractRouter.handleMessageSubscriptions`: add Kdoc now that the
  method is `protected open`. Documents the "call super" contract
  for overrides (GossipRouter relies on this to keep peersTopics and
  partialSubscriptionState in sync) and the flag-normalisation
  precondition.

Author: lucassaldanha

libp2p/src/main/kotlin/io/libp2p/pubsub/AbstractRouter.kt

@@ -186,6 +186,7 @@ abstract class AbstractRouter(
             val subscriptions = msg.subscriptionsList.map {
                 // Per partial-messages spec: flags MUST be ignored on subscribe=false, and the
                 // receiving side coerces supportsSendingPartial := requestsPartial || supportsSendingPartial.
+                // The coercion rule is also applied on the outbound side by GossipRouter.
                 PubsubSubscription(
                     topic = it.topicid,
                     subscribe = it.subscribe,
@@ -321,6 +322,19 @@ abstract class AbstractRouter(
         }
     }
 
+    /**
+     * Applies a single filtered inbound subscription to the router's state.
+     *
+     * Called once per `SubOpts` on the pubsub event loop, after
+     * [SubscriptionFilter.filterIncomingSubscriptions] has run. Subclasses may
+     * override to react to subscription state changes (for example, to track
+     * per-topic capability flags). Overrides MUST call `super` so that
+     * [peersTopics] stays in sync.
+     *
+     * [msg] carries the protocol-level flags already normalised by the caller:
+     * for `subscribe=false` frames, extension flags are zeroed before reaching
+     * this method.
+     */
     protected open fun handleMessageSubscriptions(peer: PeerHandler, msg: PubsubSubscription) {
         if (msg.subscribe) {
             peersTopics.add(peer, msg.topic)

libp2p/src/main/kotlin/io/libp2p/pubsub/gossip/GossipRouter.kt

@@ -153,13 +153,11 @@ open class GossipRouter(
      */
     fun setTopicPartialFlags(topic: Topic, requestsPartial: Boolean, supportsSendingPartial: Boolean) {
         runOnEventThread {
-            if (!requestsPartial && !supportsSendingPartial) {
+            val coerced = PartialSubFlags.coerce(requestsPartial, supportsSendingPartial)
+            if (coerced == PartialSubFlags.NONE) {
                 localTopicPartialFlags -= topic
             } else {
-                localTopicPartialFlags[topic] = PartialSubFlags(
-                    requestsPartial = requestsPartial,
-                    supportsSendingPartial = requestsPartial || supportsSendingPartial
-                )
+                localTopicPartialFlags[topic] = coerced
             }
         }
     }

libp2p/src/main/kotlin/io/libp2p/pubsub/gossip/PartialSubscriptionState.kt

@@ -9,6 +9,21 @@ data class PartialSubFlags(
 ) {
     companion object {
         val NONE = PartialSubFlags(requestsPartial = false, supportsSendingPartial = false)
+
+        /**
+         * Applies the partial-messages spec coercion
+         * `supportsSendingPartial := requestsPartial || supportsSendingPartial`.
+         *
+         * Per the spec, this rule MUST be applied by both the sender (when
+         * advertising flags outbound) and the receiver (when parsing inbound
+         * `SubOpts`). Callers are expected to have already zeroed the flags
+         * for `subscribe=false` frames before calling this helper.
+         */
+        fun coerce(requestsPartial: Boolean, supportsSendingPartial: Boolean): PartialSubFlags =
+            PartialSubFlags(
+                requestsPartial = requestsPartial,
+                supportsSendingPartial = supportsSendingPartial || requestsPartial
+            )
     }
 }
 
@@ -25,6 +40,14 @@ class PartialSubscriptionState {
 
     private val byTopic: MutableMap<Topic, MutableMap<PeerId, PartialSubFlags>> = mutableMapOf()
 
+    /**
+     * Stores [flags] for `(topic, peer)`.
+     *
+     * Passing [PartialSubFlags.NONE] (or any equivalent `PartialSubFlags(false, false)`)
+     * is treated as a removal: the peer's entry is dropped and, if it was the
+     * last peer for the topic, the topic entry is GC'd. This keeps the snapshot
+     * invariant "present ⇔ non-default flags".
+     */
     fun setPeerFlags(topic: Topic, peer: PeerId, flags: PartialSubFlags) {
         if (flags == PartialSubFlags.NONE) {
             removePeerFlags(topic, peer)