expect-pty 0.5.3 → 0.6.1

data/lib/expect/logging.rb

@@ -5,196 +5,197 @@ require_relative "redactor"
 # 管理日志目标、监听器及同步输出；资源所有权仍由会话的 SessionResources 统一保存。
 # 接收日志、诊断和协议转发是三条独立通道；脱敏只改变前两条，不改变匹配或转发字节。
 class Expect
-  # 读取当前日志目标，可能为库打开的文件、借用的 IO、回调或 nil。
-  attr_reader :log_output, :diagnostic_output
-
-  # 诊断目标仅借用；nil 沿用 stderr，Logger 使用 info/debug，回调接收冻结的事件 Hash。
-  # 先校验再冲刷旧流；校验或冲刷失败时保留旧目标，避免把暂存尾部交给错误的接收方。
-  def diagnostic_output=(target)
-    unless target.nil? || (target.respond_to?(:info) && target.respond_to?(:debug)) ||
-           target.respond_to?(:write) || target.respond_to?(:call)
-      raise ArgumentError, "diagnostic output must support info/debug, write or call, or be nil"
+  # @api private
+  module Logging
+    # 读取当前日志目标，可能为库打开的文件、借用的 IO、回调或 nil。
+    attr_reader :log_output, :diagnostic_output
+
+    # 诊断目标仅借用；nil 沿用 stderr，Logger 使用 info/debug，回调接收冻结的事件 Hash。
+    # 先校验再冲刷旧流；校验或冲刷失败时保留旧目标，避免把暂存尾部交给错误的接收方。
+    def diagnostic_output=(target)
+      unless target.nil? || (target.respond_to?(:info) && target.respond_to?(:debug)) ||
+             target.respond_to?(:write) || target.respond_to?(:call)
+        raise ArgumentError, "diagnostic output must support info/debug, write or call, or be nil"
+      end
+      return if @diagnostic_output.equal?(target)
+
+      flush_diagnostics
+      @diagnostic_output = target
     end
-    return if @diagnostic_output.equal?(target)
 
-    flush_diagnostics
-    @diagnostic_output = target
-  end
+    # 秘密仅作用于本会话的日志和诊断，不改写匹配、stdout 显示或 listeners 的协议字节。
+    # 先校验全部值再发布；注册是追加操作，应在首次通信前完成，不能追溯已交付的日志。
+    def redact(*secrets)
+      unless secrets.any? && secrets.all? { |secret| secret.is_a?(String) && !secret.empty? }
+        raise ArgumentError, "secrets must be nonempty Strings"
+      end
 
-  # 秘密仅作用于本会话的日志和诊断，不改写匹配、stdout 显示或 listeners 的协议字节。
-  # 先校验全部值再发布；注册是追加操作，应在首次通信前完成，不能追溯已交付的日志。
-  def redact(*secrets)
-    unless secrets.any? && secrets.all? { |secret| secret.is_a?(String) && !secret.empty? }
-      raise ArgumentError, "secrets must be nonempty Strings"
+      @secrets = ((@secrets || []) + secrets.map { |secret| secret.b.freeze }).uniq.freeze
+      @log_redactor.patterns = @secrets if @log_redactor
+      @diagnostic_redactors.each_value { |redactor| redactor.patterns = @secrets }
+      connection
     end
 
-    @secrets = ((@secrets || []) + secrets.map { |secret| secret.b.freeze }).uniq.freeze
-    @log_redactor.patterns = @secrets if @log_redactor
-    @diagnostic_redactors&.each_value { |redactor| redactor.patterns = @secrets }
-    self
-  end
+    # 替换借用的日志目标或停止日志；先校验新目标，失败时保留旧目标。
+    def log_output=(target)
+      unless target.nil? || target.respond_to?(:write) || target.respond_to?(:call)
+        raise ArgumentError, "log output must support write or call, or be nil"
+      end
 
-  # 替换借用的日志目标或停止日志；先校验新目标，失败时保留旧目标。
-  def log_output=(target)
-    unless target.nil? || target.respond_to?(:write) || target.respond_to?(:call)
-      raise ArgumentError, "log output must support write or call, or be nil"
+      replace_log(target)
     end
 
-    replace_log(target)
-  end
-
-  # 打开追加/覆盖日志文件，或注册接收字节的日志块；同一次只能指定一种目标。
-  def log_to(target = nil, mode: "a", &block)
-    raise ArgumentError, "provide a log target or a block, not both" if block && target
+    # 打开追加/覆盖日志文件，或注册接收字节的日志块；同一次只能指定一种目标。
+    def log_to(target = nil, mode: "a", &block)
+      raise ArgumentError, "provide a log target or a block, not both" if block && target
 
-    target = block if block
-    if target.respond_to?(:to_path) || target.is_a?(String)
-      raise ArgumentError, "log mode must be a or w" unless %w[a w].include?(mode)
+      target = block if block
+      if target.respond_to?(:to_path) || target.is_a?(String)
+        raise ArgumentError, "log mode must be a or w" unless %w[a w].include?(mode)
 
-      # 先交付旧过滤尾部，再允许新路径截断；同一文件不能在截断后被旧句柄写回。
-      flush_log
-      # 库打开的文件由 SessionResources 持有，替换日志或关闭会话时释放；外部 IO 只借用。
-      replace_log(File.open(target, "#{mode}b", 0o600), owned: true)
-    else
-      raise ArgumentError, "provide a log target or a block" unless target
+        # 先交付旧过滤尾部，再允许新路径截断；同一文件不能在截断后被旧句柄写回。
+        flush_log
+        # 库打开的文件由 SessionResources 持有，替换日志或关闭会话时释放；外部 IO 只借用。
+        replace_log(File.open(target, "#{mode}b", 0o600), owned: true)
+      else
+        raise ArgumentError, "provide a log target or a block" unless target
 
-      self.log_output = target
+        self.log_output = target
+      end
     end
-  end
 
-  # 向当前日志目标补写内容，支持 IO 和回调，不发送给子进程或监听器。
-  # 启用脱敏后可能暂存末尾字节，因此一次调用不保证触发一次日志写入或回调。
-  def write_log(*objects)
-    target = log_output
-    return unless target
-
-    data = objects.map { |object| object.to_s.b }.join
-    if @secrets
-      @log_redactor ||= Redactor.new(@secrets)
-      data = @log_redactor.append(data)
-      return if data.empty?
+    # 向当前日志目标补写内容，支持 IO 和回调，不发送给子进程或监听器。
+    # 启用脱敏后可能暂存末尾字节，因此一次调用不保证触发一次日志写入或回调。
+    def write_log(*objects)
+      target = log_output
+      return unless target
+
+      data = objects.map { |object| object.to_s.b }.join
+      if @secrets
+        @log_redactor ||= Redactor.new(@secrets)
+        data = @log_redactor.append(data)
+        return if data.empty?
+      end
+      target.respond_to?(:call) ? target.call(data) : emit(target, data)
     end
-    target.respond_to?(:call) ? target.call(data) : emit(target, data)
-  end
 
-  # 返回监听器列表副本，避免外部原地修改转发关系。
-  def listeners = @listeners.dup
+    # 返回监听器列表副本，避免外部原地修改转发关系。
+    def listeners = @listeners.dup
 
-  # 校验所有监听器均可写后一次性替换列表，外部数组后续修改不会影响会话。
-  def listeners=(outputs)
-    outputs = Array(outputs)
-    raise ArgumentError, "listeners must support write" unless outputs.all? { |output| output.respond_to?(:write) }
+    # 校验所有监听器均可写后一次性替换列表，外部数组后续修改不会影响会话。
+    def listeners=(outputs)
+      outputs = Array(outputs)
+      raise ArgumentError, "listeners must support write" unless outputs.all? { |output| output.respond_to?(:write) }
 
-    @listeners = outputs.dup
-  end
+      @listeners = outputs.dup
+    end
 
-  private
+    # 按各自开关将接收字节转发到 stdout 和监听器，不重复写日志。
+    def propagate(data)
+      emit($stdout, data) if log_stdout?
+      @listeners.each { |listener| emit(listener, data) } if log_listeners?
+    end
 
-  # 按各自开关将接收字节转发到 stdout 和监听器，不重复写日志。
-  def propagate(data)
-    emit($stdout, data) if log_stdout?
-    @listeners.each { |listener| emit(listener, data) } if log_listeners?
-  end
+    private
 
-  # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
-  # 这里遵循同步写入协议，不受 Matcher 的 IO 等待期限中断；慢目标转接应使用 Relay。
-  # 短写只推进已确认的字节数；目标抛错时不猜测它是否已经产生副作用。
-  def emit(target, data)
-    offset = 0
-    while offset < data.bytesize
-      count = target.write(data.byteslice(offset..))
-      unless count.is_a?(Integer) && count.positive? && count <= data.bytesize - offset
-        raise IOError, "write must return the number of accepted bytes"
-      end
+    # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
+    # 这里遵循同步写入协议，不受 Matcher 的 IO 等待期限中断；慢目标转接应使用 Relay。
+    # 短写只推进已确认的字节数；目标抛错时不猜测它是否已经产生副作用。
+    def emit(target, data)
+      offset = 0
+      while offset < data.bytesize
+        count = target.write(data.byteslice(offset..))
+        unless count.is_a?(Integer) && count.positive? && count <= data.bytesize - offset
+          raise IOError, "write must return the number of accepted bytes"
+        end
 
-      offset += count
+        offset += count
+      end
+      target.flush if target.respond_to?(:flush)
     end
-    target.flush if target.respond_to?(:flush)
-  end
 
-  # 字节诊断在 inspect 转义之前过滤；缓冲快照可能只含秘密中间片段，启用脱敏时不展开。
-  def trace_data(event, data, level:)
-    if @secrets
-      return trace("buffer [FILTERED]", level: level, event: event) if event == :buffer
+    # 字节诊断在 inspect 转义之前过滤；缓冲快照可能只含秘密中间片段，启用脱敏时不展开。
+    def trace_data(event, data, level:)
+      if @secrets
+        return trace("buffer [FILTERED]", level:, event:) if event == :buffer
 
-      @diagnostic_redactors ||= {}
-      redactor = (@diagnostic_redactors[event] ||= Redactor.new(@secrets))
-      data = redactor.append(data)
-      return if data.empty?
+        redactor = (@diagnostic_redactors[event] ||= Redactor.new(@secrets))
+        data = redactor.append(data)
+        return if data.empty?
+      end
+      trace("#{event} #{data.inspect}", level:, event:)
     end
-    trace("#{event} #{data.inspect}", level: level, event: event)
-  end
 
-  # 诊断与接收字节日志分开；回调元数据不含会话对象，避免格式化时意外展开原始缓冲。
-  def trace(message, level: 1, event: :matched)
-    return unless debug_level >= level
-
-    severity = level == 1 ? :info : :debug
-    target = diagnostic_output
-    if target.respond_to?(:info) && target.respond_to?(:debug)
-      target.public_send(severity, "#{inspect}: #{message}")
-    elsif target.respond_to?(:call)
-      target.call({ event: event, level: severity, pid: pid, fd: fileno, message: message.freeze }.freeze)
-    elsif target
-      emit(target, "#{inspect}: #{message}\n")
-    else
-      warn("#{inspect}: #{message}")
+    # 诊断与接收字节日志分开；回调元数据不含会话对象，避免格式化时意外展开原始缓冲。
+    def trace(message, level: 1, event: :matched)
+      return unless debug_level >= level
+
+      severity = level == 1 ? :info : :debug
+      target = diagnostic_output
+      if target.respond_to?(:info) && target.respond_to?(:debug)
+        target.public_send(severity, "#{inspect}: #{message}")
+      elsif target.respond_to?(:call)
+        target.call({ event:, level: severity, pid:, fd: fileno, message: message.freeze }.freeze)
+      elsif target
+        emit(target, "#{inspect}: #{message}\n")
+      else
+        warn("#{inspect}: #{message}")
+      end
     end
-  end
 
-  # 结束当前日志片段并交付过滤器尾部；重复调用不会重放已释放字节，写入异常原样传播。
-  def flush_log
-    loop do
-      return unless @log_redactor && log_output
+    # 结束当前日志片段并交付过滤器尾部；重复调用不会重放已释放字节，写入异常原样传播。
+    def flush_log
+      loop do
+        return unless @log_redactor && log_output
 
-      data = @log_redactor.finish
-      return if data.empty?
+        data = @log_redactor.finish
+        return if data.empty?
 
-      log_output.respond_to?(:call) ? log_output.call(data) : emit(log_output, data)
-      # 回调可能轮换目标并追加新尾部；先结束它，再允许外层截断文件或关闭日志。
+        log_output.respond_to?(:call) ? log_output.call(data) : emit(log_output, data)
+        # 回调可能轮换目标并追加新尾部；先结束它，再允许外层截断文件或关闭日志。
+      end
     end
-  end
-
-  # EOF 只结束接收诊断；目标替换或显式关闭结束全部方向，发送与接收不能拼成一个秘密。
-  # GC 终结器不进入本方法，避免在回收阶段调用用户回调或持有会话对象。
-  def flush_diagnostics(event = nil)
-    return unless @diagnostic_redactors
-
-    loop do
-      delivered = false
-      # 回调可能首次创建另一个方向，也可能写入本轮已经处理的方向。
-      @diagnostic_redactors.to_a.each do |name, redactor|
-        next if event && name != event
-
-        data = redactor.finish
-        next if data.empty?
 
-        delivered = true
-        trace("#{name} #{data.inspect}", level: 2, event: name)
+    # EOF 只结束接收诊断；目标替换或显式关闭结束全部方向，发送与接收不能拼成一个秘密。
+    # GC 终结器不进入本方法，避免在回收阶段调用用户回调或持有会话对象。
+    def flush_diagnostics(event = nil)
+      return unless @diagnostic_redactors
+
+      loop do
+        delivered = false
+        # 回调可能首次创建另一个方向，也可能写入本轮已经处理的方向。
+        @diagnostic_redactors.to_a.each do |name, redactor|
+          next if event && name != event
+
+          data = redactor.finish
+          next if data.empty?
+
+          delivered = true
+          trace("#{name} #{data.inspect}", level: 2, event: name)
+        end
+        # 目标尚未交接，新产生的尾部仍归旧诊断流；排空后才结束这次冲刷。
+        break unless delivered
       end
-      # 目标尚未交接，新产生的尾部仍归旧诊断流；排空后才结束这次冲刷。
-      break unless delivered
     end
-  end
 
-  # 交接日志目标和所有权，只关闭库拥有的旧文件；失败时释放新打开的文件。
-  def replace_log(target, owned: false)
-    # 重复赋值同一目标时保留原所有权，防止将库打开的文件误变成借用资源。
-    return target if log_output.equal?(target)
-
-    flush_log
-    # 尾部回调可以重入并替换目标；交接时重新读取目标和所有权，不能关闭旧的回调对象。
-    return target if log_output.equal?(target)
-
-    previous = @resources.owned_log
-    previous.close if previous && !previous.closed?
-    # 终结器只持有所属文件；借用回调可能捕获会话，不能让它经资源对象成为 GC 根。
-    @resources.owned_log = owned ? target : nil
-    @log_output = target
-    @log_redactor = nil
-    target
-  rescue Exception # rubocop:disable Lint/RescueException -- 替换失败时仍释放刚打开的文件。
-    target.close if owned && target && !target.closed?
-    raise
+    # 交接日志目标和所有权，只关闭库拥有的旧文件；失败时释放新打开的文件。
+    def replace_log(target, owned: false)
+      # 重复赋值同一目标时保留原所有权，防止将库打开的文件误变成借用资源。
+      return target if log_output.equal?(target)
+
+      Cleanup.on_failure(-> { target.close if owned && target && !target.closed? }) do
+        flush_log
+        # 尾部回调可以重入并替换目标；交接时重新读取目标和所有权，不能关闭旧的回调对象。
+        next target if log_output.equal?(target)
+
+        previous = @resources.owned_log
+        previous.close if previous && !previous.closed?
+        # 终结器只持有所属文件；借用回调可能捕获会话，不能让它经资源对象成为 GC 根。
+        @resources.owned_log = owned ? target : nil
+        @log_output = target
+        @log_redactor = nil
+        target
+      end
+    end
   end
 end

data/lib/expect/matcher.rb

@@ -3,16 +3,18 @@
 class Expect
   # 驱动一次单会话或多会话匹配，管理模式优先级、EOF 和共享期限，不接管 IO 所有权。
   # 调度只在扫描、回调和 IO 操作之间检查期限，不强行中断用户代码或单次正则计算。
+  # @api private
   class Matcher
     # 固定本次参与的会话及初始期限；已处理 EOF 的会话仅从本次等待中移除。
     def initialize(patterns, timeout, deadline: nil)
-      @patterns = patterns
-      @sessions = patterns.sessions
+      @patterns = patterns.finalize!
+      @sessions = patterns.sessions.map { |connection| Session.for(connection) }
+      @groups = patterns.groups.map { |connections, entries| [connections.map { |c| Session.for(c) }, entries] }
       @timeout = Expect.duration(timeout)
       # 相对期限可因接收或 continue 重算，总期限始终固定；两者共用单调时钟。
       @hard_deadline = deadline
       @deadline = next_deadline
-      @handled_eof = []
+      @handled_eof = {}.compare_by_identity
       @stalled_matches = {}
       @polled = false
       @expired_eof_continuation = false
@@ -22,15 +24,15 @@ class Expect
     def run
       @relay_buffers = {}
       @sessions.each do |session|
-        buffer = session.__send__(:interaction_buffer)
+        buffer = session.interaction_buffer
         if buffer
           # 转义回调中的显式匹配临时接管读取，先消费转接已经预读的尾部。
           @relay_buffers[session] = buffer
-          session.__send__(:interaction_buffer=, nil)
-          session.__send__(:restore_relay_buffer, buffer)
+          session.interaction_buffer = nil
+          session.restore_relay_buffer(buffer)
           buffer.clear
         end
-        session.__send__(:reset_result)
+        session.reset_result
       end
       loop do
         # 先消费已缓冲的匹配，再处理 EOF，最后读取；避免进程退出时丢失最后一个匹配。
@@ -49,7 +51,7 @@ class Expect
       # 嵌套 expect 即使异常退出，也要把未消费尾部还给原 Relay 的同一个缓冲对象。
       @relay_buffers.each do |session, buffer|
         buffer.replace(session.clear_buffer)
-        session.__send__(:interaction_buffer=, buffer)
+        session.interaction_buffer = buffer
       end
     end
 
@@ -59,13 +61,13 @@ class Expect
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 声明优先级与单轮快照须在同一次扫描保持一致。
     def find_match
       # 单组且来源不重复时无需缓存；重复来源才为本轮扫描建立快照表。
-      groups = @patterns.groups
+      groups = @groups
       if groups.size > 1 || (groups.first && groups.first.first.size > @sessions.size)
         snapshots = {}.compare_by_identity
       end
       groups.each do |sessions, patterns|
         sessions.each do |session|
-          next if @handled_eof.include?(session)
+          next if @handled_eof.key?(session)
 
           buffer = snapshots ? (snapshots[session] ||= session.buffer) : session.buffer
           stalled = @stalled_matches[session]
@@ -99,23 +101,22 @@ class Expect
       @literal_misses ||= {}.compare_by_identity
       misses = (@literal_misses[session] ||= {}.compare_by_identity)
       previous = misses[pattern]
-      generation = session.__send__(:buffer_generation)
-      # 缓冲代次未变意味着只有尾部追加；模式对象的 value 被替换时也不能沿用旧扫描位置。
-      offset = if previous && previous[0] == generation && previous[2].equal?(pattern.value)
+      generation = session.buffer_generation
+      # 模式已冻结；缓冲代次未变意味着只有尾部追加。
+      offset = if previous && previous[0] == generation
                  return nil if previous[1] == buffer.bytesize
 
                  [previous[1] - pattern.value.bytesize + 1, 0].max
                else
                  0
                end
-      position = pattern.locate(buffer, offset: offset)
+      position = pattern.locate(buffer, offset:)
       if position
         misses.delete(pattern)
       else
         entry = (misses[pattern] ||= [])
         entry[0] = generation
         entry[1] = buffer.bytesize
-        entry[2] = pattern.value
       end
       position
     end
@@ -123,8 +124,8 @@ class Expect
     # 先记录并消费匹配，再执行回调；回调可选择结束、重置期限或保留期限继续。
     def handle_match(session, pattern, position)
       previous_buffer = session.buffer
-      result = session.__send__(:record_match, pattern, position)
-      action = pattern.call(session)
+      result = session.record_match(pattern, position)
+      action = pattern.call(session.connection)
       return result unless continuing?(action)
 
       # 回调未改变缓冲时暂停当前模式，等待缓冲变化后再匹配，避免原地空转。
@@ -141,18 +142,18 @@ class Expect
 
     # 找出尚未派发 EOF 事件的会话，保证每个源只处理一次结束事件。
     def unhandled_eof
-      @sessions.find { |session| session.eof? && !@handled_eof.include?(session) }
+      @sessions.find { |session| session.eof? && !@handled_eof.key?(session) }
     end
 
     # 将剩余字节交给 EOF 回调；需要继续时等待其他源，全部结束则立即返回。
     def handle_eof(session)
-      result = session.__send__(:record_eof)
-      @handled_eof << session
-      actions = @patterns.eof_patterns_for(session).map { |pattern| pattern.call(session) }
+      result = session.record_eof
+      @handled_eof[session] = true
+      actions = @patterns.eof_patterns_for(session.connection).map { |pattern| pattern.call(session.connection) }
       return result unless actions.any? { |action| continuing?(action) }
 
       @deadline = next_deadline if actions.include?(CONTINUE)
-      return result if @sessions.all? { |candidate| @handled_eof.include?(candidate) }
+      return result if @handled_eof.size == @sessions.size
 
       # 期限已过时不再扫描文本，但先派发已知 EOF；最后一个源结束不能被误报为超时。
       @expired_eof_continuation = !actions.include?(CONTINUE) && expired?
@@ -192,11 +193,11 @@ class Expect
         session = by_io ? by_io.fetch(io) : sessions.find { |candidate| candidate.to_io.equal?(io) }
         begin
           # 转接回调消费匹配内容，余下字节交回 Relay，不能在这里提前转发两次。
-          data = session.__send__(:read_available, propagate: !@relay_buffers.key?(session))
+          data = session.read_available(propagate: !@relay_buffers.key?(session))
         rescue Errno::EINTR
           next
         rescue IOError, SystemCallError => error
-          return session.__send__(:record_error, error)
+          return session.record_error(error)
         end
         @stalled_matches.delete(session) if data
         @deadline = next_deadline if data && session.reset_timeout_on_read?
@@ -205,7 +206,7 @@ class Expect
     end
 
     # 返回本次仍需监听的会话，供读取选择和超时回调使用。
-    def active_sessions = @sessions.reject { |session| @handled_eof.include?(session) }
+    def active_sessions = @sessions.reject { |session| @handled_eof.key?(session) }
 
     # 只有约定的继续符号会驱动下一轮，普通回调返回值不会改变等待流程。
     def continuing?(action) = [CONTINUE, CONTINUE_WITHOUT_RESET].include?(action)
@@ -229,16 +230,16 @@ class Expect
     # 绝对总期限不受接收数据和 continue 重置；已知 EOF 仍按原顺序派发。
     def hard_expired? = @hard_deadline && Expect.monotonic >= @hard_deadline
 
-    # select 失败时无法归属单个源，为本次会话记录同一原始异常并返回首个结果。
+    # select 失败时无法归属单个源，只更新仍监听的会话；已派发 EOF 的结果保持不变。
     def record_error(error)
-      @sessions.map { |session| session.__send__(:record_error, error) }.first
+      active_sessions.map { |session| session.record_error(error) }.first
     end
 
     # 为活跃会话记录超时，回调接收全部活跃源；只有重置计时的继续符号能重新等待。
     # 已到总期限仍通知超时回调，但不接受继续请求，且不消费尚未匹配的字节。
     def handle_timeout
-      results = active_sessions.map { |session| session.__send__(:record_error, :timeout) }
-      action = @patterns.timeout_pattern&.call(active_sessions)
+      results = active_sessions.map { |session| session.record_error(:timeout) }
+      action = @patterns.timeout_pattern&.call(active_sessions.map(&:connection))
       return results.first unless action == CONTINUE && !hard_expired?
 
       @deadline = next_deadline

data/lib/expect/pattern.rb

@@ -2,7 +2,12 @@
 
 class Expect
   # 一个已编号的文本模式或事件及其回调；匹配结果统一使用字节偏移，便于精确消费 IO 缓冲。
-  Pattern = Struct.new(:number, :value, :callback, keyword_init: true) do
+  # @api private
+  Pattern = Data.define(:number, :value, :callback) do
+    def initialize(value:, number: nil, callback: nil)
+      super(value: value.is_a?(String) ? value.b.freeze : value, number:, callback:)
+    end
+
     # 将匹配会话或超时会话数组交给回调；额外上下文由调用方闭包保存。
     def call(subject)
       callback&.call(subject)
@@ -28,7 +33,7 @@ class Expect
                end
         unless text.valid_encoding?
           # 不完整的尾字符可能改变锚点或前瞻结果，必须等字符收齐后再匹配。
-          validate_incomplete_suffix!(text, final: final)
+          validate_incomplete_suffix!(text, final:)
           return nil
         end
         found = value.match(text)
@@ -58,4 +63,5 @@ class Expect
       raise EncodingError, "received invalid #{text.encoding} data; use a binary regexp (/.../n) for binary streams"
     end
   end
+  private_constant :Pattern
 end

data/lib/expect/pattern_list.rb

@@ -4,6 +4,8 @@ class Expect
   # 将 Ruby 模式和块回调整理为有序会话组；注册阶段不读取 IO、不执行匹配回调。
   # 分组结构直接决定 Matcher 的“声明组 → 会话 → 模式”优先级，不能按匹配位置重排。
   class PatternList
+    # 供匹配器读取的已编译分组和超时规则。
+    # @api private
     attr_reader :groups, :timeout_pattern
 
     # 建立默认来源，并将位置参数中的文本、正则、:eof、:timeout 转成统一模式。
@@ -26,7 +28,7 @@ class Expect
     def on(value, from: @default_sessions, &block)
       raise ArgumentError, "pattern must be a String or Regexp" unless value.is_a?(String) || value.is_a?(Regexp)
 
-      add(value.is_a?(String) ? value.b.freeze : value, from, block)
+      add(value, from, block)
     end
 
     # 为指定来源注册 EOF 回调；实例 DSL 默认使用当前会话。
@@ -37,6 +39,8 @@ class Expect
     # 注册一次等待的唯一超时回调，重复定义直接报错，避免悄悄覆盖业务处理。
     # 超时是整次等待的事件，回调收到全部活跃会话，不归属于某一个来源组。
     def timeout(&block)
+      raise FrozenError, "patterns are finalized" if frozen?
+
       raise ArgumentError, "timeout callback already registered" if @timeout_pattern
 
       @timeout_pattern = build(:timeout, block)
@@ -45,22 +49,42 @@ class Expect
 
     # 汇总并去重读取源，同一会话出现在多个模式组时仍只读取一次。
     # 这里只去重会话对象；不同会话包装同一 IO 时的读取归属由 Matcher 决定。
-    def sessions = groups.flat_map(&:first).uniq
+    # @api private
+    def sessions
+      groups.flat_map(&:first).each_with_object({}.compare_by_identity) do |session, unique|
+        unique[session] = true
+      end.keys
+    end
 
     # 收集指定会话的所有 EOF 处理器，保留原注册顺序。
+    # @api private
     def eof_patterns_for(session)
       groups.flat_map do |sessions, patterns|
-        sessions.include?(session) ? patterns.select(&:eof?) : []
+        sessions.any? { |candidate| candidate.equal?(session) } ? patterns.select(&:eof?) : []
       end
     end
 
     # 启动引擎前确保存在读取源；类级等待必须通过 from: 明确来源。
+    # @api private
     def validate!
       raise ArgumentError, "at least one session is required" if groups.empty?
 
       self
     end
 
+    # 固定本次等待的规则；只冻结声明容器，不冻结借用的会话与回调。
+    # @api private
+    def finalize!
+      validate!
+      groups.each do |sessions, patterns|
+        sessions.freeze
+        patterns.freeze
+      end
+      groups.each(&:freeze).freeze
+      @default_sessions.freeze
+      freeze
+    end
+
     private
 
     # 校验并复制来源列表，将模式加入相邻的相同来源组或新建组。
@@ -69,7 +93,7 @@ class Expect
       validate_sessions!(sessions)
       pattern = build(value, callback)
       # 仅合并相邻的相同来源，保持声明顺序；跨组复用会话由引擎去重读取。
-      if groups.last&.first == sessions
+      if same_sessions?(groups.last&.first, sessions)
         groups.last.last << pattern
       else
         groups << [sessions, [pattern]]
@@ -77,10 +101,16 @@ class Expect
       self
     end
 
+    # 会话的业务相等性不能合并不同读取源；来源对象及排列都必须相同。
+    def same_sessions?(previous, sessions)
+      previous && previous.size == sessions.size &&
+        previous.each_with_index.all? { |session, index| session.equal?(sessions[index]) }
+    end
+
     # 按注册顺序分配从 1 开始的序号，文本模式与事件共用编号。
     def build(value, callback)
       @number += 1
-      Pattern.new(number: @number, value: value, callback: callback)
+      Pattern.new(number: @number, value:, callback:)
     end
 
     # 拒绝空来源和非 Expect 对象，在任何 IO 读取之前暴露调用错误。