expect-pty 0.9.6 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24f49a4a4e864cdcfb8bd248b9ca01d7de830098f0767a0a1b5829c2569fe386
-  data.tar.gz: 057d8e7efa345d73790a47e35390d92f643ec211746b064105cc1fb2c4da628f
+  metadata.gz: eabbf4b5d408191298426e8bc078219eacd371b58fd0cb06bdfda6ca26d43f22
+  data.tar.gz: 6735e5a170c9b82f8043909001004bcb705f6be5971bfdd0c96db495f2cef29c
 SHA512:
-  metadata.gz: e7c9b71e0c1f74b891f9773cf438ef09ef1e9496faa0414af7048b4090efe86f141f84aa72eca9f5a4e0f1b21f69889f3084a1922158b6addfc80346d91bb423
-  data.tar.gz: 220a9fda4d96aca8c632cceb408f4c1bcc705c79ab92cc177520c5ce72c534888c96282e5613110d84f07e6594eed5923b13bbfdc356def25c54a046ce3a1b96
+  metadata.gz: 16e185ae81ce6355aa215c2e91c42ad625c6082317f19f45f51e9f300bfe937318f75f3de81183cd405f9fafaf4ecd99709a54502efd089d10d7d24011c194eb
+  data.tar.gz: ab419a9535eed4647d6b4c095caf6a0af84cd5522e5213fe2b186c4dd5ca67428300b40025843d56705a7a9e32b5c3d2a1f8ec29a803c1c3d794405850c3f178

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.10.0 - 2026-10-30
+
+- 最低 Ruby 升级至 4.0.6；Result 明确区分 matched、timeout、eof、error，编号统一为 match_number，error 只保存原始异常。构造和 with 拒绝矛盾状态，旧 number 字段移除。
+- 保留既有模块结构，将日志与转接状态初始化归回所属模块，协议输出归 Interaction 管理；等待与转接发送诊断使用显式内部协作入口。
+- 转义规则变更后首次使用时统一编译，读取期间复用正则包装与冻结文本规则快照；保持优先级、UTF-8、零宽校验、跨次 interact 历史和短写恢复契约。
+- API 检查同时拒绝已移除接口的残留 RBS 声明；同步迁移示例、签名和安装验证。
+
 ## 0.9.6 - 2026-10-23
 
 - 移除 io-console、json、logger 和 stringio 的额外版本下限，沿用 Ruby 3.4+ 的运行时要求。

data/README.md

@@ -6,7 +6,7 @@
 
 A Ruby library for automating interactive programs through POSIX pseudo-terminals. Start a child process, wait for text or regular expressions, send input, and manage timeouts, callbacks, and cleanup with Ruby objects and blocks.
 
-RubyGems package: **expect-pty**. Requires Ruby 3.4+ on Linux or macOS.
+RubyGems package: **expect-pty**. Requires Ruby 4.0.6+ on Linux or macOS.
 
 ## Install
 

data/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 一个通过 POSIX 伪终端自动操作交互式程序的 Ruby 库。启动子进程、等待文本或正则匹配、发送输入，并用 Ruby 对象和代码块管理超时、回调与资源清理。
 
-RubyGems 包名：**expect-pty**。要求 Ruby 3.4+，支持 Linux 和 macOS。
+RubyGems 包名：**expect-pty**。要求 Ruby 4.0.6+，支持 Linux 和 macOS。
 
 ## 安装
 

data/docs/API.md

@@ -1,6 +1,6 @@
 # Ruby API
 
-支持 Ruby 3.4+ 和 Linux/macOS。加载入口为 `require "expect/pty"`，独立流过滤器可加载 `expect/redactor`。
+支持 Ruby 4.0.6+ 和 Linux/macOS。加载入口为 `require "expect/pty"`，独立流过滤器可加载 `expect/redactor`。
 `Expect` 是模块；`Expect::Session` 是公开的真实会话。工厂、回调、链式方法与 `Result#session` 使用同一个 Session。
 
 ## 创建与关闭
@@ -37,7 +37,7 @@ nil。
 `Expect::Result`。
 `Expect.expect` 使用相同操作关键字，另加 `from:` 指定默认来源；其 timeout 默认 nil。模式为 String、Regexp、`:eof` 或
 `:timeout`，
-位置模式与声明块不能混用。`number` 为从 1 开始的文本模式序号或 nil，事件声明也占序号；使用 `matched?` 判断成功。
+位置模式与声明块不能混用。`match_number` 为从 1 开始的文本模式序号或 nil，事件声明也占序号；使用 `matched?` 判断成功。
 
 ```ruby
 result = session.expect(timeout: 3) do |patterns|
@@ -47,7 +47,7 @@ result = session.expect(timeout: 3) do |patterns|
   end
   patterns.on(/hello (\w+)/)
 end
-result => { number:, captures: }
+result => { status: :matched, match_number:, captures: }
 ```
 
 无参数声明块在 PatternList 上运行，直接调用 `on`、`eof`、`timeout`；有参数块保留调用者 self。
@@ -69,11 +69,15 @@ nil 保留全缓冲扫描；指定时，字符串和正则只搜索最新的尾
 
 Result 的 `inspect` 与 `to_s` 仅显示匹配序号和错误状态，不打印原始文本、异常消息或来源对象。
 需要原始结果时显式读取字段；`redact` 不改变这些字段。
-Result 字段为 `number`、`error`、`match`、`before`、`after`、`session`、`captures`。对象、文本及捕获数组均不可变，未参与捕获为
-nil。
-错误为 nil、`:timeout`、`:eof` 或原始 IO 异常；来源会话与异常不复制、不冻结。使用 `matched?`、`timeout?`、`eof?` 查询，
-使用 `to_h`、位置/键模式解构或 `with` 构造新结果；没有字段 writer 或 `to_a`。
-会话的 `last_result`、`before`、`after`、`match`、`match_number`、`captures`、`error` 读取最近结果。
+Result 字段按顺序为 `status`、`match_number`、`error`、`match`、`before`、`after`、`session`、`captures`。
+状态为 `:matched`、`:timeout`、`:eof` 或 `:error`；`error` 只保存原始异常或 nil，等待超时和 EOF 均不是异常。
+使用 `matched?`、`timeout?`、`eof?`、`error?` 查询。仅匹配状态具有正整数编号和字符串 match（包括零宽匹配的空串）；
+其余状态没有编号、match、after 或捕获，只有 `:error` 状态携带异常。参数、编码与回调异常仍按原规则直接抛出。
+
+对象、文本及捕获数组均不可变，未参与的捕获为 nil；来源会话与异常不复制、不冻结。
+使用 `to_h`、位置/键模式解构或 `with` 构造新结果；构造必须指定 status，new、[]、with 都拒绝矛盾状态与非字符串文本。
+没有字段 writer、旧 number 或 to_a。会话的 `last_result`、`before`、`after`、`match`、`match_number`、`captures`、`error`
+读取最近结果；最近等待状态使用 `last_result.status`，与输入 EOF、IO 关闭、进程状态分别查询。
 
 匹配、捕获按原始字节保存；文本显示时先 `dup` 再 `force_encoding`。固定 UTF-8 正则等待尾部字符收齐，非法编码抛出
 EncodingError。
@@ -95,7 +99,7 @@ end.freeze
 commands.each do |command|
   session.puts(command)
   result = rules.expect(session, "device>", timeout: 30, deadline: Expect.monotonic + 60)
-  raise "command incomplete: #{result.error}" unless result.matched?
+  raise "command incomplete: #{result.status}" unless result.matched?
 end
 ```
 

data/docs/COMPATIBILITY.md

@@ -36,7 +36,8 @@ Austin Schutz、Roland Giersig、Dave Jacoby，采用与 Perl 相同的许可。
 UTF-8、EOF/超时回调、绝对期限与接收重置、多会话、缓冲上限、慢速写入和背压、借用 writer 的接收记录、标准 Logger 诊断、outputs
 转发图、人工接管、跨读取转义及终端恢复。
 
-`expect` / `last_result` 返回不可变七字段 `Data`，匹配序号通过 `number` 读取。使用 `to_h` 或模式解构；
+`expect` / `last_result` 返回不可变八字段 `Data`，匹配序号通过 `match_number` 读取，等待结果通过 `status` 查询。
+`error` 只保存原始异常或 nil；EOF 与超时各有独立状态。使用 `to_h` 或模式解构；
 字段及文本快照不可修改，不提供 `to_a`。日志按实际读取时记录，转接与匹配切换不重复写日志；显式启用 `redact` 时过滤已注册秘密。
 
 ## 软关闭与硬关闭

data/docs/MIGRATION.md

@@ -1,5 +1,21 @@
 # 迁移说明
 
+## 0.9.x → 0.10.0：Ruby 4 与明确的等待结果
+
+- 最低运行环境为 Ruby 4.0.6，保留 Linux/macOS 支持；本地开发使用 RVM。
+- `result.number` 改为 `result.match_number`，与 Session 的快照访问器一致，不提供旧字段别名。
+- `result.error == :timeout` / `:eof` 改用 `result.timeout?` / `result.eof?`，或判断 `result.status`。
+  `error` 现在只保存原始异常或 nil；`session.error` 同样遵守此约定，最近等待状态为 `session.last_result.status`。
+- Result 的位置参数与解构在开头加入 status，第二项为 match_number；优先使用键模式。
+  手工构造匹配结果用 `Result.new(status: :matched, match_number: 1, match: "ready")`，
+  EOF 用 `Result.new(status: :eof, before: "tail")`，IO 错误用 `Result.new(status: :error, error: exception)`。
+- `new`、`[]`、`with` 校验状态一致性：修改匹配结果为超时还须清除编号、match、after、captures。
+  输入 EOF、IO 关闭、子进程退出继续独立表达，关闭和命令发送策略不变。
+- net-connector 使用配套 0.22.x；它在 PTY 适配层转换结果，上层设备事件和零基索引协议保持不变。
+
+内部保留既有类与混入模块。转义注册表改为冻结快照；内部恢复须使用 sequences=，避免绕过缓存更新。
+历史按实际扫描规则失效，临时 interact 注册与恢复仍支持同规则跨次接管。
+
 ## 0.8.x → 0.9.0：启动与时间参数
 
 - 始终使用 `require "expect/pty"`，Gemfile 指定 `require: "expect/pty"`。本库删除 `lib/expect.rb` 后，

data/lib/expect/interaction.rb

@@ -8,7 +8,7 @@ require_relative "literal_scan"
 # 为会话补充人工接管和多路 IO 转接；核心会话定义位于 session.rb。
 module Expect
   # 为公开 Session 混入转义注册与人工接管接口；协作方法各自标记为内部协议。
-  # 宿主提供真实读写 IO、缓冲及 outputs；本模块保存转义、显示历史和待写游标。
+  # 宿主提供真实读写 IO 和缓冲；本模块保存输出目标、转义、显示历史和待写游标。
   # Relay 暂借输入缓冲并调度游标，Matcher 可在转义回调中临时接管，退出时归还未消费尾部。
   module Interaction
     # 正则没有“潜在部分匹配”接口，只保留有限历史；已转发的历史字节不能撤回。
@@ -54,7 +54,7 @@ module Expect
             end
       raise ArgumentError, "escape sequence must not be empty" if key == ""
 
-      @sequences[key] = block || STOP
+      self.sequences = @sequences.merge(key => block || STOP).freeze
       self
     end
 
@@ -79,15 +79,34 @@ module Expect
     # 超时或异常后仍有未交付的数据；重新 interconnect 同一源会话可继续发送。
     def pending_output? = @pending_writes.any? { |output| !output.done? }
 
+    # 返回协议转发目标的副本，外部修改不能原地改变转发图。
+    def outputs = @outputs.dup
+
+    # 先校验整个数组再替换，失败时保留原输出图；目标始终由调用方拥有。
+    def outputs=(targets)
+      unless targets.is_a?(Array) && targets.all? { |target| target.respond_to?(:write) }
+        raise ArgumentError, "outputs must be an Array of writers"
+      end
+
+      @outputs = targets.dup
+    end
+
+    # 普通接收同步交付原始字节；日志脱敏不影响协议输出。
+    # @api private
+    def propagate(data)
+      @outputs.each { |output| emit(output, data) }
+    end
+
     # 将待处理输入排入唯一的转接发送队列；返回 :ready、:queued、:stopped 或 :timeout。
     # 字面序列暂存潜在前缀，正则序列结合历史匹配；final 为真时不再等待后续字节。
     # @api private
     def self.queue_input(session, buffer, final: false, deadline: nil, literal_scan: nil)
       loop do
-        sequences = session.sequences.except(:eof)
+        sequences = session.text_sequences
         history = session.relay_history
         found, regexp_scanned, utf8_regexp = scan_sequences(
-          buffer, sequences, history, final:, literal_scan:, generation: session.buffer_generation
+          buffer, sequences, history, final:, literal_scan:, generation: session.buffer_generation,
+                                      compiled: session.sequence_patterns
         )
         return :timeout if expired?(deadline)
 
@@ -141,17 +160,19 @@ module Expect
     end
 
     # 单轮正则共用一个组合文本；回调返回后下一轮重新取得规则和历史。
-    def self.scan_sequences(buffer, sequences, history, final:, literal_scan: nil, generation: nil)
+    def self.scan_sequences(buffer, sequences, history, final:, literal_scan: nil, generation: nil, compiled: {})
       text = nil
       utf8_regexp = false
       earliest = nil
+      earliest_offset = Float::INFINITY
       # 只保存最早候选，同位置不替换先注册者；仍扫描全部正则以校验零宽规则并收集编码状态。
       sequences.each do |key, handler|
         if key.is_a?(Regexp)
           # 仅在本轮扫描复用组合文本；回调可能更换规则或消费缓冲，下一轮必须重新构造。
           text ||= history + buffer
           utf8_regexp ||= key.fixed_encoding? && key.encoding == Encoding::UTF_8
-          position = Pattern.new(value: key).locate(text, final:, captures: false)
+          pattern = compiled.fetch(key) { Pattern.new(value: key) }
+          position = pattern.locate(text, final:, captures: false)
           next unless position
 
           offset, length, = position
@@ -165,7 +186,10 @@ module Expect
 
           length = key.bytesize
         end
-        earliest = [offset, length, handler] if !earliest || offset < earliest.first
+        if offset < earliest_offset
+          earliest = [offset, length, handler]
+          earliest_offset = offset
+        end
       end
       [earliest, !text.nil?, utf8_regexp]
     end
@@ -173,11 +197,10 @@ module Expect
     # 普通转发和超时排出的字面前缀都属于正则历史，跨次转接时必须接续同一字节流。
     # @api private
     def self.remember_output(session, data)
-      regexps = session.sequences.keys.grep(Regexp)
-      return if regexps.empty?
+      return if session.sequence_patterns.empty?
 
-      utf8 = regexps.any? { |regexp| regexp.fixed_encoding? && regexp.encoding == Encoding::UTF_8 }
-      trim_history(session.relay_history, data, limit: session.buffer_limit || REGEXP_ESCAPE_HISTORY_LIMIT, utf8:)
+      trim_history(session.relay_history, data, limit: session.buffer_limit || REGEXP_ESCAPE_HISTORY_LIMIT,
+                                                utf8: session.utf8_sequences?)
     end
 
     # 只暂存可能拼成完整字面转义的最长后缀。
@@ -221,14 +244,54 @@ module Expect
       end
     end
 
-    # 仅供转接内部保存和恢复注册表，避免公开可变 Hash 绕过 on_sequence 的校验。
+    # 冻结的注册快照只能通过 on_sequence 或内部恢复入口替换，不能绕过编译及历史失效。
     # @api private
     attr_reader :sequences
 
     # @api private
     def sequences=(sequences)
-      @sequences = sequences
-      @literal_prefix_tables&.delete_if { |sequence, _table| !sequences.key?(sequence) }
+      # Hash 的值相等忽略插入顺序；转义优先级必须同时比较声明顺序。
+      return if @sequences == sequences && @sequences.keys == sequences.keys
+
+      @sequences = sequences.frozen? ? sequences : sequences.dup.freeze
+      @literal_prefix_tables.delete_if { |sequence, _table| !sequences.key?(sequence) }
+    end
+
+    # 连续声明只发布注册快照；首次扫描统一编译，后续读取不重复创建集合及正则包装。
+    # @api private
+    def text_sequences
+      return @text_sequences if @compiled_sequences.equal?(@sequences)
+
+      registered = @sequences
+      text = registered.except(:eof).freeze
+      patterns = text.each_key.with_object({}) do |key, patterns|
+        patterns[key] = @sequence_patterns[key] || Pattern.new(value: key) if key.is_a?(Regexp)
+      end.freeze
+      utf8 = patterns.each_key.any? do |regexp|
+        regexp.fixed_encoding? && regexp.encoding == Encoding::UTF_8
+      end
+      # 编译结果一起发布；失败时旧缓存仍完整，下次扫描可以重新编译，不读取陈旧规则。
+      Thread.handle_interrupt(Object => :never) do
+        @text_sequences = text
+        @sequence_patterns = patterns
+        @utf8_sequences = utf8
+        @compiled_sequences = registered
+      end
+      text
+    end
+
+    # 冻结的正则包装快照；已存在的正则跨规则变更复用。
+    # @api private
+    def sequence_patterns
+      text_sequences
+      @sequence_patterns
+    end
+
+    # 正则历史的编码边界由当前已注册规则决定。
+    # @api private
+    def utf8_sequences?
+      text_sequences
+      @utf8_sequences
     end
     # 冻结字面规则对应的 KMP 前缀表，跨转接复用，避免每个读块重新编译长规则。
     # @api private
@@ -252,8 +315,9 @@ module Expect
     # 同规则保留跨次转接的连续历史；换规则或消费、改写输入后，不能拼接旧的前缀。
     # @api private
     def relay_history
-      sequences = @sequences.except(:eof)
-      @relay_history = "".b unless @relay_history_sequences == sequences
+      # interact 的临时注册和恢复不消费输入；只比较实际扫描时的规则，保留同规则跨次接管的历史。
+      sequences = text_sequences
+      @relay_history.clear unless @relay_history_sequences == sequences
       @relay_history_sequences = sequences
       @relay_history
     end
@@ -267,6 +331,22 @@ module Expect
 
     private
 
+    # 转接状态集中在所属模块初始化；缓冲和进程状态仍由 Session 管理。
+    def initialize_interaction
+      @outputs = []
+      @sequences = {}.freeze
+      @text_sequences = @sequence_patterns = @sequences
+      @compiled_sequences = @sequences
+      @utf8_sequences = false
+      @literal_prefix_tables = {}
+      @pending_writes = []
+      @interact_inputs = {}.compare_by_identity
+      @interact_output = nil
+      @interaction_buffer = @relay_owner = @relay_callback = nil
+      @relay_history = "".b
+      @relay_history_sequences = @text_sequences
+    end
+
     # 同一输入 IO 重用一个借用会话，以保留上次接管预读的尾部并避免不断积累包装器。
     def interact_source(input)
       return input if input.is_a?(Session)

data/lib/expect/logging.rb

@@ -3,12 +3,11 @@
 require "logger"
 require_relative "redactor"
 
-# 借用标准 Logger、接收记录 writer 和协议输出 writer，不接管它们的生命周期。
+# 借用标准 Logger 和接收记录 writer，不接管它们的生命周期。
 # 脱敏只作用于诊断与接收记录，协议输出和匹配缓冲始终保留原始字节。
 module Expect
-  # 会话诊断、接收记录和协议转发的独立输出接口。
-  # 宿主 Session 初始化目标与过滤器状态，并提供 pid、fileno 作为诊断元数据。
-  # 三种输出各有边界：Logger 接收事件，transcript 接收脱敏字节，outputs 接收原协议字节。
+  # 会话诊断与接收记录接口；Session 构造时调用本模块初始化过滤器，并提供 pid、fileno 元数据。
+  # Logger 接收事件，transcript 接收脱敏字节；Interaction 的协议输出只复用同步 writer 交付。
   module Logging
     # 调用方提供的诊断 Logger 与接收记录 writer，均由调用方管理生命周期。
     attr_reader :logger, :transcript
@@ -68,26 +67,21 @@ module Expect
       nil
     end
 
-    # 返回副本，避免外部原地修改转发关系；stdout 与其他 writer 使用相同协议。
-    def outputs = @outputs.dup
-
-    # 先校验整个数组再替换，失败时保留原输出图。
-    def outputs=(targets)
-      unless targets.is_a?(Array) && targets.all? { |target| target.respond_to?(:write) }
-        raise ArgumentError, "outputs must be an Array of writers"
-      end
-
-      @outputs = targets.dup
-    end
-
-    # 原样转发协议字节，接收记录在读取时单独写入。
+    # 转接确认交付后记录发送字节；调用者已登记游标，诊断失败不能回退发送进度。
     # @api private
-    def propagate(data)
-      @outputs.each { |output| emit(output, data) }
+    def record_sent(data)
+      trace_data(:sending, data)
     end
 
     private
 
+    # 每个日志方向独立保留脱敏状态；协议缓冲及转发图属于 Session 与 Interaction。
+    def initialize_logging
+      @secrets = @transcript_redactor = nil
+      @diagnostic_redactors = {}
+      @logger = @transcript = nil
+    end
+
     # 关闭时两种记录都要尝试完成；后续 writer 的常规异常不能覆盖先发生的诊断异常。
     # 不关闭借用目标，新的 Interrupt/SystemExit 仍由 Cleanup 原样传播。
     def finish_logging

data/lib/expect/matcher.rb

@@ -255,7 +255,7 @@ module Expect
     # 为活跃会话记录超时，回调接收全部活跃源；只有重置计时的继续符号能重新等待。
     # 已到总期限仍通知超时回调，但不接受继续请求，且不消费尚未匹配的字节。
     def handle_timeout
-      results = active_sessions.map { |session| session.record_error(:timeout) }
+      results = active_sessions.map(&:record_timeout)
       action = @patterns.timeout_pattern&.call(active_sessions)
       return results.first unless CONTINUE.equal?(action) && !hard_expired?
 

data/lib/expect/pattern.rb

@@ -3,10 +3,10 @@
 module Expect
   # 一个已编号的文本模式或事件及其回调；匹配结果统一使用字节偏移，便于精确消费 IO 缓冲。
   # @api private
-  Pattern = Data.define(:number, :value, :callback) do
+  Pattern = Data.define(:match_number, :value, :callback) do
     # 复制字符串模式；Regexp 和 callable 只引用，不取得外部对象的生命周期。
-    def initialize(value:, number: nil, callback: nil)
-      super(value: value.is_a?(String) ? value.b.freeze : value, number:, callback:)
+    def initialize(value:, match_number: nil, callback: nil)
+      super(value: value.is_a?(String) ? value.b.freeze : value, match_number:, callback:)
     end
 
     # 将匹配会话或超时会话数组交给回调；额外上下文由调用方闭包保存。

data/lib/expect/pattern_list.rb

@@ -14,7 +14,7 @@ module Expect
       validate_sessions!(@default_sessions) unless @default_sessions.empty?
       # 保留空模式的默认会话组，使 expect(timeout:) 也能只收集输出而不匹配文本。
       @groups = @default_sessions.empty? ? [] : [[@default_sessions, []]]
-      @number = 0
+      @match_number = 0
       patterns.each do |value|
         case value
         when :eof then eof
@@ -140,8 +140,8 @@ module Expect
 
     # 按注册顺序分配从 1 开始的序号，文本模式与事件共用编号。
     def build(value, callback)
-      @number += 1
-      Pattern.new(number: @number, value:, callback:)
+      @match_number += 1
+      Pattern.new(match_number: @match_number, value:, callback:)
     end
 
     # 拒绝空来源和非 Session 对象，在任何 IO 读取之前暴露调用错误。

data/lib/expect/pty.rb

@@ -188,6 +188,8 @@ module Expect
     end
 
     # 声明完成后固定模式；有参数块保留调用方 self，无参数块使用模式 DSL。
+    # Session 与 Responder 共用的内部入口，不通过反射绕过方法边界。
+    # @api private
     def run_expect(sessions, patterns, timeout, deadline:, consume:, reset_timeout_on_read:,
                    match_by_position: false, search_window: nil, &block)
       unless search_window.nil? || (search_window.is_a?(Integer) && search_window.positive?)
@@ -205,5 +207,7 @@ module Expect
       Matcher.new(pattern_list, timeout, deadline:, consume:, reset_timeout_on_read:, match_by_position:,
                                          search_window:).run
     end
+
+    public :run_expect
   end
 end

data/lib/expect/relay/writer.rb

@@ -89,7 +89,7 @@ module Expect
 
       # 诊断可嵌套写入；外层只报告本游标的进度，原超时及其内层进度保留在 cause。
       def trace_delivery(data)
-        target.__send__(:trace_data, :sending, data)
+        target.record_sent(data)
       rescue WriteTimeout
         raise WriteTimeout.new("relay interrupted by a diagnostic timeout", bytes_written: @offset)
       end

data/lib/expect/responder.rb

@@ -38,9 +38,9 @@ module Expect
       raise ArgumentError, "provide patterns or a pattern block, not both" if block && !patterns.empty?
 
       rules = @rules.dup.freeze
-      Expect.__send__(
-        :run_expect, [session], [], timeout, deadline:, consume: true,
-                                             reset_timeout_on_read: false, match_by_position: true, search_window:
+      Expect.run_expect(
+        [session], [], timeout, deadline:, consume: true,
+                                reset_timeout_on_read: false, match_by_position: true, search_window:
       ) do |list|
         patterns.each do |pattern|
           case pattern

data/lib/expect/result.rb

@@ -21,38 +21,60 @@ module Expect
   #   按成员声明顺序返回字段数组。
   # @!method deconstruct_keys(keys)
   #   按指定键解构结果，nil 表示全部字段。
-  Result = Data.define(:number, :error, :match, :before, :after, :session, :captures) do
+  Result = Data.define(:status, :match_number, :error, :match, :before, :after, :session, :captures) do
     # 构造独立不可变快照，复制字符串和捕获数组。
     # @param captures [Array<String, nil>] 按声明顺序保存捕获组，未参与的组保留 nil。
-    def initialize(number: nil, error: nil, match: nil, before: nil, after: nil, session: nil, captures: [])
-      super(number:, error:, session:, match: match&.dup&.freeze,
-            before: before&.dup&.freeze, after: after&.dup&.freeze,
-            captures: captures.map { |value| value&.dup&.freeze }.freeze)
+    def initialize(status:, match_number: nil, error: nil, match: nil, before: nil, after: nil,
+                   session: nil, captures: [])
+      raise ArgumentError, "captures must be an Array" unless captures.is_a?(Array)
+
+      validate_outcome!(status, match_number, error, match, after, captures)
+      super(status:, match_number:, error:, session:, match: copy_text(match), before: copy_text(before),
+            after: copy_text(after), captures: captures.map { |value| copy_text(value) }.freeze)
     end
 
     # 诊断只显示匹配序号和错误状态，不检查原始文本、异常或来源对象。
     # @return [String] 不包含协议内容的结果摘要。
-    def inspect
-      state = if error.nil? then "none"
-              elsif error.equal?(:eof) then "eof"
-              elsif error.equal?(:timeout) then "timeout"
-              else "exception"
-              end
-      index = number.is_a?(Integer) ? number.to_s : "nil"
-      "#<#{self.class} number=#{index} error=#{state}>"
-    end
+    def inspect = "#<#{self.class} status=#{status} match_number=#{match_number.inspect}>"
 
     # Data 的默认 to_s 独立于 inspect；字符串插值同样只使用安全摘要。
     # @return [String] 与 inspect 相同的结果摘要。
     def to_s = inspect
 
     # 是否命中文本；EOF 和超时没有模式序号。
-    def matched? = !number.nil?
+    def matched? = status == :matched
 
     # 是否因等待期限到达而返回。
-    def timeout? = error == :timeout
+    def timeout? = status == :timeout
 
     # 是否读取源已经结束，子进程状态由会话单独查询。
-    def eof? = error == :eof
+    def eof? = status == :eof
+
+    # 是否因原始 IO 异常结束；等待事件不属于异常。
+    def error? = status == :error
+
+    private
+
+    # 正文和捕获使用同一快照边界；不转换任意对象，也不冻结调用方的字符串。
+    def copy_text(value)
+      return nil if value.nil?
+
+      raise ArgumentError, "result text must be a String or nil" unless value.is_a?(String)
+
+      value.dup.freeze
+    end
+
+    # 状态是唯一判据；new、[] 和 with 都经过同一边界，不能产生相互矛盾的结果。
+    def validate_outcome!(status, match_number, error, match, after, captures)
+      valid = case status
+              when :matched
+                match_number.is_a?(Integer) && match_number.positive? && match.is_a?(String) && error.nil?
+              when :eof, :timeout, :error
+                match_number.nil? && match.nil? && after.nil? && captures.empty? &&
+                (status == :error ? error.is_a?(Exception) : error.nil?)
+              else false
+              end
+      raise ArgumentError, "inconsistent result status and fields" unless valid
+    end
   end
 end

data/lib/expect/session.rb

@@ -50,8 +50,8 @@ module Expect
     # 等待自身输入，返回 Result；匹配消费和接收重置策略只对本轮有效。
     def expect(*patterns, timeout: self.timeout, deadline: nil, consume: true, reset_timeout_on_read: false,
                search_window: nil, &)
-      Expect.__send__(:run_expect, [self], patterns, timeout,
-                      deadline:, consume:, reset_timeout_on_read:, search_window:, &)
+      Expect.run_expect([self], patterns, timeout,
+                        deadline:, consume:, reset_timeout_on_read:, search_window:, &)
     end
 
     # 在新控制终端中执行命令并同步确认 exec 结果；同一会话只能启动一次。
@@ -119,12 +119,12 @@ module Expect
     def match = @last_result&.match
 
     # 最近命中的模式序号；EOF、超时或尚无结果时为 nil。
-    def match_number = @last_result&.number
+    def match_number = @last_result&.match_number
 
     # 最近捕获值的不可变数组；未参与的捕获为 nil。
     def captures = @last_result&.captures || []
 
-    # 最近的 EOF、超时事件或原始 IO 异常。
+    # 最近结果的原始 IO 异常；等待状态通过 last_result.status 查询。
     def error = @last_result&.error
 
     # 返回缓冲副本，防止调用方原地修改绕过裁剪规则。
@@ -309,7 +309,8 @@ module Expect
     # @api private
     def record_match(pattern, position, consume: true)
       offset, length, captures = position
-      @last_result = Result.new(number: pattern.number, before: @buffer.byteslice(0, offset),
+      @last_result = Result.new(status: :matched, match_number: pattern.match_number,
+                                before: @buffer.byteslice(0, offset),
                                 match: @buffer.byteslice(offset, length), after: @buffer.byteslice((offset + length)..),
                                 session: self, captures:)
       if consume
@@ -320,22 +321,28 @@ module Expect
       end
       # 诊断回调可能嵌套等待；恢复本次结果后再交给正式模式回调，不能返回内层等待的结果。
       result = @last_result
-      trace { "matched pattern #{pattern.number}" }
+      trace { "matched pattern #{pattern.match_number}" }
       @last_result = result
     end
 
-    # 记录超时、EOF 或原始 IO 异常，保留当前缓冲快照并清除旧匹配及捕获组。
+    # 记录原始 IO 异常，保留当前缓冲快照并清除旧匹配及捕获组。
     # @api private
     def record_error(error)
       # Result 自行复制冻结文本，无须先通过公开 buffer 再复制一遍。
-      @last_result = Result.new(error:, before: @buffer, session: self, captures: [])
+      @last_result = Result.new(status: :error, error:, before: @buffer, session: self)
+    end
+
+    # 超时是本次等待的正常终止事件，未消费输入继续留在缓冲中。
+    # @api private
+    def record_timeout
+      @last_result = Result.new(status: :timeout, before: @buffer, session: self)
     end
 
     # 输入结束时将剩余缓冲放入 before 并清空，尝试回收但不终止仍活跃的子进程。
     # @api private
     def record_eof
       process_status
-      record_error(:eof)
+      @last_result = Result.new(status: :eof, before: @buffer, session: self)
       clear_buffer
       @last_result
     end
@@ -403,18 +410,8 @@ module Expect
       @buffer_generation = 0
       @received_bytes = 0
       @buffer_discarded_bytes = 0
-      @outputs = []
-      @sequences = {}
-      @literal_prefix_tables = {}
-      @pending_writes = []
-      @interact_inputs = {}.compare_by_identity
-      @interact_output = nil
-      @interaction_buffer = @relay_owner = @relay_callback = nil
-      @relay_history = "".b
-      @relay_history_sequences = {}
-      @secrets = @transcript_redactor = nil
-      @diagnostic_redactors = {}
-      @logger = @transcript = nil
+      initialize_interaction
+      initialize_logging
       @last_result = @command = nil
       @closed = @eof = @receiving = false
       self.timeout = timeout

data/lib/expect/version.rb

@@ -2,5 +2,5 @@
 
 module Expect
   # Gem 与库共用的版本号；独立文件使 gemspec 无需加载完整会话实现。
-  VERSION = "0.9.6"
+  VERSION = "0.10.0"
 end

data/sig/expect.rbs

@@ -2,8 +2,9 @@
 module Expect
   type duration = Numeric
   type pattern = String | Regexp | :eof | :timeout
-  type result_error = :eof | :timeout | Exception | nil
-  type result_fields = { number: Integer?, error: result_error, match: String?, before: String?, after: String?, session: Session?, captures: Array[String?] }
+  type result_status = :matched | :timeout | :eof | :error
+  type result_error = Exception | nil
+  type result_fields = { status: result_status, match_number: Integer?, error: result_error, match: String?, before: String?, after: String?, session: Session?, captures: Array[String?] }
   type diagnostic_event = { event: Symbol, pid: Integer?, fd: Integer?, message: String }
 
   interface _Writer
@@ -189,7 +190,8 @@ module Expect
 
   class Result < Data
     def self.new: (
-        ?number: Integer?,
+        status: result_status,
+        ?match_number: Integer?,
         ?error: result_error,
         ?match: String?,
         ?before: String?,
@@ -197,10 +199,11 @@ module Expect
         ?session: Session?,
         ?captures: Array[String?]
       ) -> Result
-      | (?Integer?, ?result_error, ?String?, ?String?, ?String?, ?Session?, ?Array[String?]) -> Result
+      | (result_status, ?Integer?, ?result_error, ?String?, ?String?, ?String?, ?Session?, ?Array[String?]) -> Result
 
     def self.[]: (
-        ?number: Integer?,
+        status: result_status,
+        ?match_number: Integer?,
         ?error: result_error,
         ?match: String?,
         ?before: String?,
@@ -208,7 +211,7 @@ module Expect
         ?session: Session?,
         ?captures: Array[String?]
       ) -> Result
-      | (?Integer?, ?result_error, ?String?, ?String?, ?String?, ?Session?, ?Array[String?]) -> Result
+      | (result_status, ?Integer?, ?result_error, ?String?, ?String?, ?String?, ?Session?, ?Array[String?]) -> Result
 
     def self.members: () -> Array[Symbol]
 
@@ -216,7 +219,8 @@ module Expect
 
     def members: () -> Array[Symbol]
 
-    attr_reader number: Integer?
+    attr_reader status: result_status
+    attr_reader match_number: Integer?
     attr_reader error: result_error
     attr_reader match: String?
     attr_reader before: String?
@@ -225,7 +229,8 @@ module Expect
     attr_reader captures: Array[String?]
 
     def initialize: (
-        ?number: Integer?,
+        status: result_status,
+        ?match_number: Integer?,
         ?error: result_error,
         ?match: String?,
         ?before: String?,
@@ -236,6 +241,8 @@ module Expect
 
     def matched?: () -> bool
 
+    def error?: () -> bool
+
     def timeout?: () -> bool
 
     def eof?: () -> bool
@@ -244,10 +251,11 @@ module Expect
 
     def to_s: () -> String
 
-    def deconstruct: () -> [Integer?, result_error, String?, String?, String?, Session?, Array[String?]]
+    def deconstruct: () -> [result_status, Integer?, result_error, String?, String?, String?, Session?, Array[String?]]
 
     def with: (
-        ?number: Integer?,
+        ?status: result_status,
+        ?match_number: Integer?,
         ?error: result_error,
         ?match: String?,
         ?before: String?,

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: expect-pty
 version: !ruby/object:Gem::Version
-  version: 0.9.6
+  version: 0.10.0
 platform: ruby
 authors:
 - expect-pty contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: io-console
@@ -114,7 +114,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: 4.0.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="