ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/subscription.rb

@@ -0,0 +1,852 @@
+# frozen_string_literal: true
+
+require_relative 'subscription/notification_dispatcher'
+
+module MCPClient
+  # A long-lived notification subscription opened with `subscriptions/listen`
+  # (MCP 2026-07-28 basic/patterns/subscriptions).
+  #
+  # The subscription is identified by the JSON-RPC id of its listen request;
+  # every notification delivered on it carries that id in
+  # `_meta["io.modelcontextprotocol/subscriptionId"]`. It starts :pending,
+  # becomes :active when the server acknowledges it (with the subset of
+  # notification types it agreed to honour), and ends :closed — gracefully
+  # when the server answers the listen request, otherwise on a transport
+  # drop, a server `notifications/cancelled`, an error, or {#close}.
+  class Subscription
+    # The published SubscriptionFilter's fields and their value types (MCP
+    # 2026-07-28 schema, SubscriptionFilter). Nothing beyond these four is a
+    # core filter field: an extension that defines one of its own — the tasks
+    # extension's `taskIds`, say — registers it with {.register_filter_field}.
+    FILTER_FIELDS = {
+      'toolsListChanged' => :boolean,
+      'promptsListChanged' => :boolean,
+      'resourcesListChanged' => :boolean,
+      'resourceSubscriptions' => :string_array
+    }.freeze
+
+    # snake_case spellings accepted for the published filter fields
+    FILTER_ALIASES = {
+      'tools_list_changed' => 'toolsListChanged',
+      'prompts_list_changed' => 'promptsListChanged',
+      'resources_list_changed' => 'resourcesListChanged',
+      'resource_subscriptions' => 'resourceSubscriptions'
+    }.freeze
+
+    # The value types a filter field may have
+    FILTER_VALUE_TYPES = %i[boolean string_array].freeze
+
+    class << self
+      # Register a filter field an extension defines beyond the published
+      # SubscriptionFilter, so {.normalize_filter} accepts it (and its
+      # snake_case spelling) with the value type the extension gives it. A
+      # published field cannot be redefined; registering the same extension
+      # field twice with the same type is a no-op.
+      # @param name [String] the camelCase wire name of the field
+      # @param type [Symbol] :boolean or :string_array
+      # @param alias_name [String, nil] a snake_case spelling to accept for it
+      # @return [void]
+      # @raise [ArgumentError] on a published field, an unknown type, or a
+      #   name already registered with another type
+      def register_filter_field(name, type, alias_name: nil)
+        name = name.to_s
+        raise ArgumentError, "#{name} is a published SubscriptionFilter field" if FILTER_FIELDS.key?(name)
+        raise ArgumentError, 'a filter field is boolean or string_array' unless FILTER_VALUE_TYPES.include?(type)
+
+        extension_filter_fields_mutex.synchronize do
+          fields = @extension_filter_fields || { fields: {}, aliases: {} }
+          registered = fields[:fields][name]
+          raise ArgumentError, "#{name} is already registered as #{registered}" if registered && registered != type
+
+          fields[:fields][name] = type
+          fields[:aliases][alias_name.to_s] = name if alias_name
+          @extension_filter_fields = fields
+        end
+        nil
+      end
+
+      # @return [Hash{String => Symbol}] every accepted filter field — the
+      #   published four and the registered extension fields — with its type
+      def filter_fields
+        FILTER_FIELDS.merge(extension_filter_fields[:fields]).freeze
+      end
+
+      # @return [Hash{String => String}] every accepted snake_case spelling
+      def filter_aliases
+        FILTER_ALIASES.merge(extension_filter_fields[:aliases]).freeze
+      end
+
+      private
+
+      # @return [Hash] the registered extension fields and aliases
+      def extension_filter_fields
+        extension_filter_fields_mutex.synchronize { @extension_filter_fields || { fields: {}, aliases: {} } }
+      end
+
+      # @return [Mutex] guards the registry across extensions loading concurrently
+      def extension_filter_fields_mutex
+        @extension_filter_fields_mutex ||= Mutex.new
+      end
+    end
+
+    STATES = %i[pending active reconnecting closed].freeze
+
+    # Ceiling on the notifications waiting for this subscription's listeners.
+    # The queue is filled by the peer and drained by the host, so a chatty
+    # server and a listener that does real work (re-reading the resource that
+    # changed, say) would otherwise grow it without bound.
+    #
+    # A full queue discards by identity rather than by arrival order, so
+    # overflow costs a listener a repeated notice of the same resource or task
+    # and never its only notice of one of them; see
+    # {MCPClient::Subscription::NotificationDispatcher} for the policy.
+    # Blocking the transport reader instead would reinstate the deadlock the
+    # dispatcher exists to prevent — the reader would wait for a listener that
+    # is waiting for a response only that reader can deliver.
+    MAX_PENDING_NOTIFICATIONS = 1024
+
+    # Ceiling on the bytes the queued notifications retain, because a count is
+    # not a memory bound: the method name and params of every queued
+    # notification are held until its listener has run, one Streamable HTTP
+    # listen event may approach
+    # {MCPClient::HttpTransportBase::ListenStream::LISTEN_MAX_BUFFER_BYTES} and
+    # a stdio line has no inbound limit at all — so a peer facing a slow
+    # listener could put tens of gigabytes behind a nominally bounded queue.
+    #
+    # This changes when overflow starts, not what it discards: whichever
+    # ceiling the arriving notification would breach, the entry that goes is
+    # still chosen by identity, and only ever an entry whose removal relieves
+    # the breach. A notification larger than the whole budget is not charged
+    # against it and is held in a slot of its own, of which there is only ever
+    # one — so the retained total is the budget plus at worst one peer-sized
+    # payload rather than {MAX_PENDING_NOTIFICATIONS} of them, and no signal
+    # is lost to its size or displaced by one.
+    MAX_PENDING_NOTIFICATION_BYTES = 8 * 1024 * 1024
+
+    # The states {#wait_until_settled} waits for: the server has answered the
+    # listen request one way or the other.
+    SETTLED_STATES = %i[active closed].freeze
+
+    # @return [Integer, String, nil] the JSON-RPC id of the listen request (nil before it is sent)
+    attr_reader :id
+    # @return [Hash] the requested SubscriptionFilter (camelCase keys)
+    attr_reader :requested
+    # @return [Hash, nil] the filter the server agreed to honour, once acknowledged
+    attr_reader :acknowledged
+    # @return [MCPClient::ServerBase] the transport that owns the subscription
+    attr_reader :server
+    # @return [Symbol] :pending, :active, :reconnecting or :closed
+    attr_reader :state
+    # @return [MCPClient::Errors::MCPError, nil] why the subscription failed, if it did
+    attr_reader :error
+    # @return [String, nil] the reason a server-side teardown gave, if any
+    attr_reader :close_reason
+    # @return [Numeric, false, nil] the acknowledgment deadline the host asked
+    #   for; every listen request re-issued for this subscription is bounded by
+    #   it, not only the first
+    attr_reader :ack_timeout
+
+    # Normalize and validate a SubscriptionFilter given with String or Symbol,
+    # camelCase or snake_case keys.
+    #
+    # The result is detached from the caller and frozen. The filter is not
+    # serialized once and forgotten: Streamable HTTP builds the listen request
+    # on the stream's own thread, after `listen` has returned, and every
+    # reconnect builds it again — so an array the caller kept a reference to
+    # would let a later `<<` or a mutated String change the request that goes
+    # out, or change what a re-opened stream asks for.
+    # @param filter [Hash] the notification filter
+    # @return [Hash] camelCase String keys, frozen
+    # @raise [ArgumentError] on an unknown key or a mistyped value
+    def self.normalize_filter(filter)
+      raise ArgumentError, 'notifications must be a Hash (SubscriptionFilter)' unless filter.is_a?(Hash)
+
+      fields = filter_fields
+      aliases = filter_aliases
+      filter.to_h do |key, value|
+        name = key.to_s
+        name = aliases.fetch(name, name)
+        type = fields[name]
+        raise ArgumentError, "Unknown subscription filter field #{key.inspect}" unless type
+
+        case type
+        when :boolean
+          raise ArgumentError, "#{name} must be true or false" unless [true, false].include?(value)
+        when :string_array
+          raise ArgumentError, "#{name} must be an array of strings" unless value.is_a?(Array) && value.all?(String)
+
+          value = value.map { |item| item.dup.freeze }.freeze
+        end
+        [name, value]
+      end.freeze
+    end
+
+    # @param server [MCPClient::ServerBase] owning transport
+    # @param requested [Hash] normalized filter
+    # @param ack_timeout [Numeric, false, nil] the acknowledgment deadline the
+    #   host asked for, kept for the requests re-issued later (see
+    #   {MCPClient::SubscriptionSupport#rearm_acknowledgment_deadline}). Set
+    #   here rather than assigned afterwards: a transport may re-open the
+    #   stream before `listen` has returned the handle.
+    # @yield [method, params] optional listener for notifications on this subscription
+    def initialize(server:, requested:, ack_timeout: nil, &listener)
+      @server = server
+      @requested = requested
+      @ack_timeout = ack_timeout
+      @listeners = []
+      @listeners << listener if listener
+      @state = :pending
+      @mutex = Mutex.new
+      @settled = ConditionVariable.new
+      @id = nil
+      @acknowledged = nil
+      @error = nil
+      @close_reason = nil
+      @closed_gracefully = false
+      @closed_by_client = false
+      @dispatcher = nil
+      # Whether the server has answered the listen request this subscription
+      # is on — or the last one it was on, while no replacement has gone out.
+      # Written where those two things happen ({#acknowledge} and the two
+      # methods that take a new listen id), never inferred from how far a
+      # transport has got through a reconnect.
+      @answered = false
+      # Whether a transport is handing this subscription to a new session:
+      # see {#reestablishing?}.
+      @reestablishing = false
+      # The listen ids the transport has written for this subscription, and
+      # not yet cancelled, each paired with the pipe it was written to: see
+      # {#record_outstanding_listen}.
+      @outstanding_listens = []
+      # Of those, the ones whose write has not finished yet. They are not
+      # cancellable: see {#take_outstanding_listens}.
+      @unwritten_listens = []
+      # The transport generation this subscription's listen went out on: see
+      # {#with_open_id}.
+      @open_generation = nil
+    end
+
+    # @return [Integer] notifications queued for this subscription's listeners
+    def pending_notifications
+      dispatcher = @mutex.synchronize { @dispatcher }
+      dispatcher ? dispatcher.pending : 0
+    end
+
+    # Bytes retained by the notifications queued for this subscription's
+    # listeners, measured as the JSON the peer sent for them — their method
+    # names as well as their params (see {MAX_PENDING_NOTIFICATION_BYTES}).
+    # @return [Integer]
+    def pending_notification_bytes
+      dispatcher = @mutex.synchronize { @dispatcher }
+      dispatcher ? dispatcher.pending_bytes : 0
+    end
+
+    # Notifications dropped because the listeners could not keep up with the
+    # server (see {MAX_PENDING_NOTIFICATIONS} and
+    # {MAX_PENDING_NOTIFICATION_BYTES}).
+    # @return [Integer]
+    def dropped_notifications
+      dispatcher = @mutex.synchronize { @dispatcher }
+      dispatcher ? dispatcher.dropped : 0
+    end
+
+    # Add a listener for notifications delivered on this subscription.
+    # @yield [method, params]
+    # @return [self]
+    def on_notification(&block)
+      @mutex.synchronize { @listeners << block }
+      self
+    end
+
+    # @return [Boolean] whether the server acknowledged it and it is still open
+    def active?
+      @mutex.synchronize { @state == :active }
+    end
+
+    # @return [Boolean]
+    def closed?
+      @mutex.synchronize { @state == :closed }
+    end
+
+    # @return [Boolean] whether it is waiting for a transport to re-establish
+    #   it — the stream dropped, or the stdio process it was on exited, and
+    #   the transport that noticed has queued it for the next session
+    def reconnecting?
+      @mutex.synchronize { @state == :reconnecting }
+    end
+
+    # @return [Boolean] whether the server ended it with a response to the listen request
+    def closed_gracefully?
+      @mutex.synchronize { @closed_gracefully }
+    end
+
+    # @return [Boolean] whether {#close} ended it
+    def closed_by_client?
+      @mutex.synchronize { @closed_by_client }
+    end
+
+    # Requested notification types the server did not agree to honour.
+    #
+    # Support is read from the value the server acknowledged, not from the
+    # mere presence of the field: an acknowledgment that names
+    # `resourceSubscriptions` with none of the URIs it was sent has accepted
+    # no resource subscription at all, and a flag acknowledged as `false` will
+    # not be honoured either. A list the server granted in part counts as
+    # supported; see {#unacknowledged_resource_uris} for the URIs it left out.
+    # @return [Array<String>] empty until acknowledged
+    def unsupported
+      ack = @mutex.synchronize { @acknowledged }
+      return [] unless ack
+
+      @requested.keys.reject { |field| granted?(@requested[field], ack[field]) }
+    end
+
+    # Requested resource URIs the server did not agree to watch.
+    # @return [Array<String>] empty until acknowledged
+    def unacknowledged_resource_uris
+      ack = @mutex.synchronize { @acknowledged }
+      return [] unless ack
+
+      wanted = Array(@requested['resourceSubscriptions'])
+      granted = ack['resourceSubscriptions'].is_a?(Array) ? ack['resourceSubscriptions'] : []
+      wanted - granted
+    end
+
+    # Whether this stream is, right now, an active acknowledged watch of a
+    # resource: the server granted that URI and the stream it granted it on is
+    # the one still running.
+    #
+    # Being open is not enough, which is what a `subscribe_resource` looking
+    # for a stream to reuse has to know: a stream between listen attempts is
+    # serving nothing, and the request that replaces it is a new one the
+    # server holds no state for — it may be rejected, or acknowledged more
+    # narrowly.
+    # @param uri [String] the resource URI
+    # @return [Boolean]
+    def watching_resource?(uri)
+      @mutex.synchronize { @state == :active && acknowledges_resource?(uri) }
+    end
+
+    # Block until the server has answered the listen request this subscription
+    # is waiting on, and report what it said about this URI.
+    #
+    # This is the question the subscriber that *opened* the stream asks: it is
+    # waiting for the answer to its own listen request, and it gets it. A
+    # connection that merely drops does not unask that question and does not
+    # unanswer it — the server did grant the filter, and making the caller
+    # wait out its whole acknowledgment timeout for an answer it had already
+    # been given would be the transport's problem told as the subscriber's. A
+    # replacement request that has actually gone out is another matter: the
+    # server holds no subscription state across one and has to grant the
+    # filter again, so the answer to it is waited for rather than assumed —
+    # which is why {#with_open_id} and {#assign_id} unanswer it explicitly,
+    # instead of that turning on whether the reconnect has got as far as
+    # taking an id.
+    #
+    # Waiting is also the right answer for a request in flight with nothing
+    # granted yet, which used to read as success: a subscription with no
+    # acknowledgment has no unacknowledged URIs either.
+    # @param uri [String] the resource URI
+    # @param timeout [Numeric] seconds to wait for an answer
+    # @return [Symbol] :watching, :not_watching (answered without the URI),
+    #   :closed, or :timeout
+    def await_resource_watch(uri, timeout)
+      await_watch(uri, timeout) { @answered }
+    end
+
+    # Block until this subscription is a running watch of the URI, and report
+    # whether it is.
+    #
+    # This is the other question, and the one a `subscribe_resource` looking
+    # for a stream to *reuse* asks: not "what did the server say" but "is the
+    # server watching this, now". Only a running stream answers it. An
+    # acknowledgment left on record by a stream that has dropped is not a
+    # grant — no server-side subscription exists between listen attempts, the
+    # request that replaces it is a new one the server may reject or
+    # acknowledge more narrowly, and reading the old record as the current
+    # grant reported a watch for the whole of an HTTP backoff or a stdio
+    # handshake. So a stream between attempts is waited for instead.
+    # @param uri [String] the resource URI
+    # @param timeout [Numeric] seconds to wait for the stream to be granted
+    # @return [Symbol] :watching, :not_watching (granted without the URI),
+    #   :closed, or :timeout
+    def await_live_resource_watch(uri, timeout)
+      await_watch(uri, timeout) { @state == :active }
+    end
+
+    # Block until the server has settled the subscription: acknowledged it,
+    # or ended it with a response, an error or a cancellation.
+    # @param timeout [Numeric] seconds to wait
+    # @return [Symbol, nil] :active or :closed, nil while it is still pending
+    def wait_until_settled(timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @mutex.synchronize do
+        loop do
+          answer = settled_state
+          return answer if answer
+
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return nil if remaining <= 0
+
+          @settled.wait(@mutex, remaining)
+        end
+      end
+    end
+
+    # Cancel the subscription: the transport closes the stream (HTTP) or
+    # sends notifications/cancelled (stdio).
+    # @return [MCPClient::Subscription, nil] self if it was open, nil if already closed
+    def close
+      return nil if closed?
+
+      @server.cancel_subscription(self)
+      self
+    end
+
+    # --- transport-facing state transitions -------------------------------
+
+    # Put the subscription on a listen id, without the registration and the
+    # write {#with_open_id} holds its lock across. No transport opens or
+    # re-opens a stream this way — {#with_open_id} is the step every one of
+    # them takes — so a guarantee about opening or reconnecting is one this
+    # method cannot stand in for.
+    # @param id [Integer, String] the listen request id
+    # @return [void]
+    # @api private
+    def assign_id(id)
+      @mutex.synchronize do
+        @id = id
+        @acknowledged = nil
+        # A request the server has not seen is a question it has not answered.
+        @answered = false
+        # A subscription the host closed stays closed, whatever a racing
+        # reconnect does.
+        @state = :pending unless @state == :closed
+      end
+    end
+
+    # Take a fresh listen id and register/send the request under this
+    # subscription's own lock, so a concurrent {#close} either wins outright
+    # (nothing is sent) or waits and then cancels the id that was sent. A
+    # closed subscription is never re-opened.
+    # @param id [Integer, String] the new listen request id
+    # @yield runs while the id cannot change underneath it
+    # @return [Boolean] false when the host had already closed it
+    # @api private
+    def with_open_id(id, generation = nil)
+      @mutex.synchronize do
+        return false if @state == :closed
+
+        @id = id
+        @acknowledged = nil
+        # The request that went out is a new one: whatever the server said
+        # about the last, it has not answered this.
+        @answered = false
+        @state = :pending
+        # Stamped in the same step as the registration, so every registered
+        # subscription names the process its listen went out on: a teardown
+        # parks the ones belonging to the process it claimed and leaves the
+        # replacement's alone (see {MCPClient::ServerStdio#park_open_subscriptions}).
+        # A transport with no such notion (the HTTP ones, whose streams are
+        # per-connection) passes none and is never asked.
+        @open_generation = generation
+        yield
+        true
+      end
+    end
+
+    # The transport generation the listen this subscription is on went out
+    # under, or nil on a transport that does not number its processes.
+    # @return [Integer, nil]
+    # @api private
+    def open_generation
+      @mutex.synchronize { @open_generation }
+    end
+
+    # Record a listen request the transport has written for this subscription
+    # on the session it is on.
+    #
+    # A cancellation has to name a request the server may be serving, and
+    # that is not always the id the subscription happens to be on: a second
+    # listen written for it on one session (a hand-over that queued it twice,
+    # say) leaves the server holding the first stream, and
+    # `notifications/cancelled` for the newest id alone would never close it —
+    # the stream stays open until the server's own timeout, with the client
+    # unable to name it again.
+    #
+    # An attempt whose write raised is recorded too: the client cannot know
+    # how much of it the peer saw, and cancelling a request the server never
+    # received is ignored, while failing to cancel one it did receive is not.
+    # Recorded *before* the write for that reason, and marked written by
+    # {#mark_listen_written} whichever way the write ends.
+    #
+    # The pipe it is written to is recorded with it, because forgetting the
+    # ids of a process that is gone ({#discard_outstanding_listens}) cannot
+    # reach an attempt that has not recorded its id yet. One paused here while
+    # its process was torn down recorded afterwards, with nothing left to
+    # forget it, and the `close` that followed named it on the process that
+    # replaced it — a request that one had never been sent, while
+    # "the cancelled request MUST have been previously issued"
+    # (basic/patterns/cancellation). Recording the pipe makes the id
+    # cancellable on that pipe alone, whenever it is recorded.
+    # @param id [Integer, String] the listen request id
+    # @param io [IO, nil] the pipe the request is being written to; nil leaves
+    #   the id cancellable wherever the caller is cancelling
+    # @return [void]
+    # @api private
+    def record_outstanding_listen(id, io = nil)
+      @mutex.synchronize do
+        @outstanding_listens << [id, io] unless @outstanding_listens.any? { |(known, _)| known == id }
+        @unwritten_listens << id unless @unwritten_listens.include?(id)
+      end
+    end
+
+    # The write of a listen request has finished — sent, or raised having sent
+    # who knows how much. Either way the id may now be cancelled.
+    #
+    # An id the session that carried it has since discarded
+    # ({#discard_outstanding_listens}) stays discarded: nothing written to a
+    # process that is gone is outstanding, and a late write that lands on its
+    # closed pipe must not put the id back.
+    # @param id [Integer, String] the listen request id
+    # @return [void]
+    # @api private
+    def mark_listen_written(id)
+      @mutex.synchronize { @unwritten_listens.delete(id) }
+    end
+
+    # The listen ids the server may still be serving for this subscription,
+    # leaving none behind: the caller is cancelling them.
+    #
+    # An id whose write has not finished is not among them, however impatient
+    # the caller: "the cancelled request MUST have been previously issued"
+    # (basic/patterns/cancellation), and cancelling an id the pipe has not
+    # carried yet put `cancelled(n)` on the wire ahead of `listen(n)`. The
+    # transport that is writing it cancels it itself once the write is done
+    # and it finds the subscription closed — the one moment at which the
+    # cancellation can name a request the server has actually been sent.
+    #
+    # Nor is an id written to a *different* pipe among them: the process on
+    # this one was never sent that request (see {#record_outstanding_listen}).
+    # Those are left recorded rather than dropped, since the caller that pins
+    # a pipe is not always the one that will cancel on the pipe they went to.
+    # @param io [IO, nil] cancel only what was written to this pipe; nil takes
+    #   every written id, and an id recorded against no pipe is taken by any
+    #   caller
+    # @return [Array] the recorded ids that have been written, oldest first
+    # @api private
+    def take_outstanding_listens(io = nil)
+      @mutex.synchronize do
+        taken, kept = @outstanding_listens.partition do |(id, recorded_io)|
+          !@unwritten_listens.include?(id) && cancellable_on?(recorded_io, io)
+        end
+        @outstanding_listens = kept
+        taken.map(&:first)
+      end
+    end
+
+    # Forget the recorded listen ids without cancelling them: the session they
+    # were written to is gone, so nothing is outstanding and none of them must
+    # be cancelled on the session that replaces it.
+    # @return [void]
+    # @api private
+    def discard_outstanding_listens
+      @mutex.synchronize do
+        @outstanding_listens = []
+        @unwritten_listens = []
+      end
+    end
+
+    # Whether this subscription is still the stream a given listen id opened.
+    # A transport that fails an attempt asks before undoing it: a restart
+    # racing a blocked write may already have re-opened the subscription under
+    # a newer id, and that stream is not the older attempt's to tear down.
+    # @param id [Integer, String] a listen request id
+    # @return [Boolean]
+    # @api private
+    def open_as?(id)
+      @mutex.synchronize { @id == id }
+    end
+
+    # Undo the listen attempt that failed — or find that it is no longer this
+    # attempt's to undo — in one step.
+    #
+    # {#open_as?} used to answer the first half of that question on its own,
+    # and a restart could re-open the subscription under a newer id *and*
+    # have it acknowledged between the answer and the transition it guarded:
+    # the older attempt then finished the very stream the fresh process was
+    # serving, with nothing left to cancel it. Asking and acting under one
+    # hold of the lock is what makes the answer good for the transition it
+    # decides.
+    #
+    # The three answers are the three things a failed attempt can be:
+    # superseded by a newer attempt, which owns the subscription now; a
+    # hand-over to a new session that could not be written
+    # ({#reestablishing?}), which goes back to waiting for the next one; or
+    # the caller's own request, which ends with the error.
+    # A hand-over is deferred only when it is the *process* that could not be
+    # written to: that process is on its way out, and the next one drains the
+    # queue. An attempt that failed before it took an id at all (the request
+    # could not be built) says nothing about the process, which stays up and
+    # healthy — nothing would ever drain the queue on it, and the previous
+    # acknowledgment would keep the watchdog from expiring it: the
+    # subscription stayed :reconnecting for ever with the host never told. So
+    # that failure is the subscription's own, and it ends with it.
+    # @param id [Integer, String, nil] the listen id the attempt sent under;
+    #   nil for an attempt that failed before it took one (the request could
+    #   not be built), which no newer attempt can have superseded
+    # @param error [MCPClient::Errors::MCPError] why it failed
+    # @return [Symbol] :superseded, :deferred (it is :reconnecting again) or
+    #   :failed (ended with the error — or already closed)
+    # @api private
+    def fail_attempt(id, error)
+      @mutex.synchronize do
+        return :superseded if id && @id != id
+        return :failed if @state == :closed
+
+        if @reestablishing && id
+          @state = :reconnecting
+          return :deferred
+        end
+
+        close_locked(error: error)
+        :failed
+      end
+    end
+
+    # End the request a deadline was set on, if the subscription is still on
+    # that request and the server has still not answered it — in one step.
+    #
+    # The watchdog that waits out the deadline cannot decide this for itself:
+    # by the time its wait returns, a restart may have replaced the request
+    # with a newer one (a new id, with a deadline of its own, which the older
+    # request's timer must not spend), and an acknowledgment may have landed
+    # in the instant between the wait and the verdict, which is the server's
+    # answer and is kept.
+    # Anyone waiting for the subscription to settle is woken only once the
+    # block — the cancellation the transport sends for the expired request —
+    # has run: a host that sees the handle settle on a timeout sees a server
+    # that has already been told, rather than one the watchdog is still
+    # writing to. The block runs outside the lock, since telling the server
+    # takes the ids recorded on this subscription.
+    # @param id [Integer, String] the listen id the deadline was set on
+    # @param error [MCPClient::Errors::RequestTimeoutError] the deadline missed
+    # @yield after the subscription has been ended, before the waiters wake
+    # @return [Symbol, nil] :expired when the subscription was ended here;
+    #   nil when the request was no longer this one's to expire
+    # @api private
+    def expire_unanswered(id, error)
+      @mutex.synchronize do
+        return nil if @id != id || @answered || SETTLED_STATES.include?(@state)
+        # A deadline bounds the request that is out, not the subscription: a
+        # transport waiting to send the next listen (an HTTP reconnect inside
+        # its backoff, a stdio restart still spawning) has nothing in flight
+        # for this deadline to expire, and ending the handle here would also
+        # mark it closed by the client — unreconnectable, so the re-send that
+        # basic/patterns/subscriptions requires after a reconnect never
+        # happens. The next attempt arms a deadline of its own with its id.
+        return nil if @state == :reconnecting
+
+        close_locked(by_client: true, error: error, announce: false)
+      end
+      begin
+        yield if block_given?
+      ensure
+        @mutex.synchronize { @settled.broadcast }
+      end
+      :expired
+    end
+
+    # Record what the server agreed to honour.
+    #
+    # The filter is copied and frozen through and through, arrays and strings
+    # included. The hash it arrives in is the peer's, parsed from the
+    # acknowledgment notification, and that same hash is handed to the host's
+    # `on_notification` callback and to this subscription's own listeners — so
+    # host code that edits it in place would otherwise be rewriting this
+    # subscription's record of what the server granted. Adding a URI the
+    # acknowledgment left out is enough to make a waiting `subscribe_resource`
+    # report a watch that does not exist.
+    # @param filter [Hash, nil] the acknowledged SubscriptionFilter
+    # @return [void]
+    # @api private
+    def acknowledge(filter)
+      detached = Subscription.deep_frozen_copy(filter.is_a?(Hash) ? filter : {})
+      @mutex.synchronize do
+        return if @state == :closed
+
+        @acknowledged = detached
+        @state = :active
+        @answered = true
+        # A stream the server has granted is no longer one being handed over.
+        @reestablishing = false
+        @settled.broadcast
+      end
+    end
+
+    # A detached, deeply frozen copy of a parsed JSON value.
+    # @param value [Object]
+    # @return [Object] frozen, sharing nothing mutable with the original
+    def self.deep_frozen_copy(value)
+      case value
+      when Hash then value.to_h { |key, item| [deep_frozen_copy(key), deep_frozen_copy(item)] }.freeze
+      when Array then value.map { |item| deep_frozen_copy(item) }.freeze
+      when String then value.dup.freeze
+      else value
+      end
+    end
+
+    # @api private
+    def deliver(method, params)
+      @mutex.synchronize do
+        return if @state == :closed || @listeners.empty?
+
+        # Queued while still open, so a closure that follows cannot swallow a
+        # notification that had already arrived, and the stop that ends the
+        # dispatcher can never overtake this one. Enqueuing never waits for
+        # the listeners: the transport reader must stay free to deliver the
+        # responses a listener's own requests are waiting for.
+        (@dispatcher ||= NotificationDispatcher.new(self)).deliver(@listeners.dup, method, params)
+      end
+    end
+
+    # @api private
+    def mark_reconnecting
+      @mutex.synchronize do
+        next if @state == :closed
+
+        @state = :reconnecting
+        @reestablishing = true
+      end
+    end
+
+    # Whether a transport is handing this subscription to a new session: it
+    # was {#mark_reconnecting}ed and no server has acknowledged it since.
+    #
+    # Unlike {#reconnecting?} this survives the :pending that taking the new
+    # listen id moves it to, which is the whole point: a transport whose
+    # re-send fails on the write has to tell a stream it is handing over —
+    # which MUST be re-sent, and belongs to the next session — from one it is
+    # opening for a caller, which is the caller's to hear about. The state
+    # alone cannot: by the time the write raises, the re-send has already
+    # moved it off :reconnecting.
+    # @return [Boolean]
+    # @api private
+    def reestablishing?
+      @mutex.synchronize { @reestablishing && @state != :closed }
+    end
+
+    # @api private
+    def finish(gracefully: false, by_client: false, error: nil, reason: nil)
+      @mutex.synchronize { close_locked(gracefully: gracefully, by_client: by_client, error: error, reason: reason) }
+    end
+
+    # @return [Boolean] whether the subscription should be re-established after a reconnect
+    # @api private
+    def reconnectable?
+      @mutex.synchronize { @state != :closed && !@closed_by_client }
+    end
+
+    def inspect
+      "#<MCPClient::Subscription id=#{@id.inspect} state=#{@state} requested=#{@requested.keys.join(',')}>"
+    end
+
+    private
+
+    # The closing transition, for the callers that decide it under the lock
+    # they already hold. A closed subscription stays as it was closed.
+    # @param announce [Boolean] whether to wake the waiters now; a caller
+    #   that passes false owes them a broadcast of its own
+    # @return [void]
+    def close_locked(gracefully: false, by_client: false, error: nil, reason: nil, announce: true)
+      return if @state == :closed
+
+      @state = :closed
+      @closed_gracefully = gracefully
+      @closed_by_client = by_client
+      @error = error
+      @close_reason = reason
+      @settled.broadcast if announce
+      # Deliveries already queued still run; the dispatcher ends after them.
+      @dispatcher&.stop
+    end
+
+    # Wait for the condition the caller is asking about to hold, then read the
+    # acknowledgment on record for this URI. The block is evaluated with the
+    # lock held and decides *when* the record may be read; what it then says
+    # about the URI is the same question either way.
+    # @param uri [String] the resource URI
+    # @param timeout [Numeric] seconds to wait
+    # @yieldreturn [Boolean] whether the record may be read yet
+    # @return [Symbol] :watching, :not_watching, :closed or :timeout
+    def await_watch(uri, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @mutex.synchronize do
+        loop do
+          return :closed if @state == :closed
+          return acknowledges_resource?(uri) ? :watching : :not_watching if yield
+
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return :timeout if remaining <= 0
+
+          @settled.wait(@mutex, remaining)
+        end
+      end
+    end
+
+    # Whether the value the server acknowledged for a requested field grants
+    # anything: a flag has to come back true, and a list of URIs or task ids
+    # has to name at least one of those asked for. Anything else is the server
+    # declining the field while echoing its name. A field this client did not
+    # really ask for (a `false` flag, an empty list) is trivially granted —
+    # there was nothing there for the server to decline.
+    # @param wanted [Object] the value this client asked for
+    # @param granted [Object] the value the server acknowledged
+    # @return [Boolean]
+    def granted?(wanted, granted)
+      if wanted.is_a?(Array)
+        return true if wanted.empty?
+
+        return granted.is_a?(Array) && wanted.intersect?(granted)
+      end
+
+      wanted == false || granted == true
+    end
+
+    # Whether the acknowledgment that stands names this URI. Called with the
+    # lock held.
+    # @param uri [String] the resource URI
+    # @return [Boolean]
+    def acknowledges_resource?(uri)
+      granted = @acknowledged.is_a?(Hash) ? @acknowledged['resourceSubscriptions'] : nil
+      granted.is_a?(Array) && granted.include?(uri)
+    end
+
+    # Whether a recorded listen id may be cancelled by a caller writing to a
+    # given pipe. An id recorded against no pipe belongs to a transport that
+    # does not pin one, and a caller that names none is cancelling wherever
+    # the ids went. Called with the lock held.
+    # @param recorded [IO, nil] the pipe the request was written to
+    # @param io [IO, nil] the pipe the caller is cancelling on
+    # @return [Boolean]
+    def cancellable_on?(recorded, io)
+      recorded.nil? || io.nil? || recorded.equal?(io)
+    end
+
+    # The answer {#wait_until_settled} reports. A drop does not unask the
+    # question the waiter asked: the server acknowledged the listen request,
+    # and putting the stream back to :reconnecting until it is acknowledged
+    # again does not unanswer it. A replacement request that has gone out
+    # does — that one is unanswered until the server answers it, which is a
+    # different thing from a connection that merely dropped and is recorded
+    # as such rather than left to whichever the reconnect reached first.
+    # Called with the lock held.
+    # @return [Symbol, nil] :closed, :active, or nil while it is still pending
+    def settled_state
+      return @state if SETTLED_STATES.include?(@state)
+      return :active if @answered
+
+      nil
+    end
+  end
+end