ctx_runner 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb856e1dde339c23607f185f8ac5ac0ab9bca29d94dc115661b145d1f2dfef5a
-  data.tar.gz: a255c77dafecab0b028974ebf2173efa5c412771621454a7e5c7cf2f6f0ee1cf
+  metadata.gz: e38041886eddd4c62f64ac92bb2af4e5f82f62accfe84d276cf169463b1bfd5e
+  data.tar.gz: 57174343df0368bf45997665c436781585d23a165a496de58b2ae2f7a7c0c612
 SHA512:
-  metadata.gz: b2bfdd9ed85c4c2f48dfcaa568575a39f38cd6d7ebb952f198ed0d251b62b8749fe519de9886162bdaffa907733b4d12259bcf85d6b79a1aec7fa10868b1d8d7
-  data.tar.gz: 1e0fd95eddbe30863f53c3ac854d0c4a6452b17ad5b42e91c60b9dd4789ff162d7625ffb8a96c9b92e09bb1aae1d5b812600206c922fcf683f146796f9920c46
+  metadata.gz: 79b6a398ac323338de8656129163d6863761ee568221e55f57e465b2e14fb161a3c6bc7eebf6dc1895ba8a80aea113d041b68e576e7611e85ce6ccce66f4ccb6
+  data.tar.gz: 83f2e533cc140782d46985cd1084d6a729a68d632718edc4ab86b4bce672a47bf2242627b24b03363a9267a76de182d3bee6654ea08362fac4eebd6fbdeb3d21

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.2.0 (2026-10-23)
+
+- Breaking: report presenters, completion callbacks and progress callbacks now receive immutable string-keyed documents; remove Report#serializable and migrate consumers.
+- Validate summary and execution documents before publication, remove stale completion after conversion failures, and confirm recovery checkpoint durability.
+- Preserve collected evidence and the original exit when final progress abandons a batch without replaying progress.
+- Use English evidence validation and report publication diagnostics.
+
 ## 0.1.1 (2026-10-23)
 
 - Add shared offline evidence validation with mandatory target identity.

data/README.md

@@ -11,6 +11,7 @@
 | `Observation` | 事实外壳、可用性、时间类型、深度快照及安全展示 |
 | `Batch` | 单设备结果登记、报告交付、输出失败补写 |
 | `Report` | 私有批次目录、文件发布、检查点、完成判定及恢复 |
+| `Document` | 有界、无歧义、深冻结的 JSON 值；统一报告和进度交付表示 |
 | `Fingerprint` | 稳定配置身份，拒绝归一化键冲突 |
 | `Execution` | 已确认增量的前提核验、执行记账、效果不确定状态及回读验收 |
 
@@ -42,6 +43,12 @@ end
 
 `Report.new(root)` 创建排他的私有批次，目录 0700、文件 0600。`finish(results, requested:) { |summary| text }` 先保存未完成检查点，再发布领域文本，最后发布最终 JSON。`Report::Error#committed?` 区分是否已替换；失败不能被当作可靠发布。`recovery_failed?` 提示恢复也未确认。
 
+`finish` 的展示块、返回摘要与最终 JSON 使用相同的字符串键/状态文档，例如 `summary.fetch("status") == "complete"`；展示回调不能改变这份深冻结快照。`Batch::Completion#status` 仍是符号，`#summary` 是该文档。`progress.result` 与 `progress.finish` 同样接收字符串键文档；`Batch#collect` 的返回值及领域 `report.write` 输入保持 Ruby 设备结果结构。这些交付边界没有符号键兼容分支，旧的 `Report#serializable` 已移除。
+
+最终进度输出发生取消或非局部退出时，Batch 仅补写中断报告，保留已经采集和保存的事实及原退出值，不再调用进度展示或重采设备。普通进度异常记录为输出错误；恢复中的存储异常不会替换最先观察到的退出。
+
+`Document.call(value)` 复制键和值，支持普通 Hash/Array、Time 的 ISO-8601 字符串和 Data 记录，拒绝正规化后的同名键、循环、不透明对象、非有限数以及超过 128 层的嵌套。`checkpoint(relative, value)`、`finalize(relative, value, checkpoint:)` 和 `write_execution(state)` 使用同一转换规则。检查点必须包含非空且不为 `complete` 的状态；最终提交失败只能恢复未完成事实。转换、编码或取消失败也会撤销旧完成结论；撤销文件后的目录同步失败会设置 `recovery_failed?`，原失败仍交还调用者。
+
 `Execution` 只接受宿主已经校验、向用户展示且明确确认的计划。领域 change 实现 `commands`、`eligible?(before)`、`satisfied?(after, before:)`；journal 实现 `write_execution(state)`。每次回调获得快照。发送前保存 pending，发送后保留 acknowledged；失败后的 uncertain 禁止自动重放。`run { |operation| connector.open(&operation) }` 在连接器正常退出后才发布 configuration_verified；这不表示业务健康已验收。
 
 完整可运行离线例子见 [examples](examples)。

data/examples/report.rb

@@ -9,8 +9,8 @@ Dir.mktmpdir do |root|
   report.publish("evidence.json", JSON.generate(source: "synthetic", records: []))
   device = { "host" => "192.0.2.1", "name" => "example" }
   summary = report.finish([ { device: device, status: :complete, report_saved: true } ], requested: [ device ]) do |value|
-    "Evidence: #{value.fetch(:status)}; health was not evaluated.\n"
+    "Evidence: #{value.fetch('status')}; health was not evaluated.\n"
   end
-  raise "Report incomplete" unless summary[:status] == :complete
+  raise "Report incomplete" unless summary.fetch("status") == "complete"
   raise "Missing evidence" unless File.file?(File.join(report.directory, "evidence.json"))
 end

data/lib/ctx_runner/batch.rb

@@ -2,6 +2,7 @@
 
 require "ctx_parser/immutable"
 require "ctx_driver/failure"
+require_relative "document"
 
 module CtxRunner
   # 批量采集的交付账本；调度器负责并发与回收，领域块只返回设备快照。
@@ -53,7 +54,7 @@ module CtxRunner
       elsif failure || finalization_error
         :failed
       else
-        summary[:status] == :complete ? :complete : :incomplete
+        summary.fetch("status") == "complete" ? :complete : :incomplete
       end
       completion = Completion.new(status: status, summary: summary, failure: failure, finalization_error: finalization_error,
         recovery_failed: @report.respond_to?(:recovery_failed?) && @report.recovery_failed?)
@@ -99,7 +100,7 @@ module CtxRunner
       @report.write(CtxParser::Immutable.copy(result), snapshot: snapshot)
       @lock.synchronize { result[:report_saved] = true }
       saved = CtxParser::Immutable.copy(result)
-      @progress.result(saved)
+      @progress.result(Document.call(saved))
       saved
     end
 
@@ -112,8 +113,8 @@ module CtxRunner
       snapshot = results
       options = { interrupted: interrupted, requested: @requested, report_error: report_error, execution_error: execution_error }
       summary = @report.finish(snapshot, **options, output_error: @progress.output_error)
-      @progress.finish(summary)
-      if @progress.output_error && !summary[:output_error]
+      finish_progress(summary, snapshot, options)
+      if @progress.output_error && !summary["output_error"]
         summary = @report.finish(snapshot, **options, output_error: @progress.output_error)
       end
       summary
@@ -123,12 +124,32 @@ module CtxRunner
 
     private
 
+    # 终端收尾退出时只补写报告；保留已完成事实及原退出，不重放进度或采集。
+    def finish_progress(summary, snapshot, options)
+      recovery = { interrupted: true, output_error: summary["output_error"] }
+      @progress.finish(summary)
+      completed = true
+    rescue StandardError, LoadError => error
+      recovery = { output_error: { error_type: error.class.name } }
+      raise
+    ensure
+      unless completed
+        begin
+          @report.finish(snapshot, **options, **recovery)
+        rescue StandardError, LoadError, Interrupt
+          nil
+        end
+      end
+    end
+
     def settle(options)
       [ CtxParser::Immutable.copy(finish(**options)), nil ]
     rescue Interrupt
       options[:interrupted] = true
       begin
-        [ CtxParser::Immutable.copy(finish(**options)), nil ]
+        # 取消后的终端不可再次调用；仅确认中断报告的交付状态。
+        summary = @report.finish(results, **options, requested: @requested, output_error: @progress.output_error)
+        [ CtxParser::Immutable.copy(summary), nil ]
       rescue StandardError, LoadError, Interrupt => error
         [ nil, diagnostic(error) ]
       end

data/lib/ctx_runner/document.rb

@@ -5,12 +5,14 @@ require "time"
 module CtxRunner
   # 显式证据边界：生成独立 JSON 值，不通过文本往返转换业务事实。
   module Document
+    MAX_DEPTH = 128
+
     def self.call(value)
       convert(value, {}.compare_by_identity, 0)
     end
 
     def self.convert(value, active, depth)
-      raise ArgumentError, "Document nesting exceeds the evidence budget" if depth > 128
+      raise ArgumentError, "Document nesting exceeds the evidence budget" if depth > MAX_DEPTH
       case value
       when Hash, Array, Data
         raise ArgumentError, "Document must not contain cyclic data" if active[value]
@@ -21,10 +23,12 @@ module CtxRunner
           when Array then value.map { |item| convert(item, active, depth + 1) }.freeze
           when Hash
             value.each_with_object({}) do |(key, item), result|
-              unless [ String, Symbol, Integer, Float, Rational, Complex, NilClass, TrueClass, FalseClass ].any? { |type| key.is_a?(type) }
-                raise ArgumentError, "Document keys must be plain values"
+              # 符号名已由 Ruby 持有并冻结；其他键复制后才冻结，不占用调用方对象。
+              name = case key
+              when Symbol then key.name
+              when String, Integer, Float, Rational, Complex, NilClass, TrueClass, FalseClass then String.new(key.to_s)
+              else raise ArgumentError, "Document keys must be plain values"
               end
-              name = String.new(key.to_s)
               raise ArgumentError, "Document keys collide after normalization" if result.key?(name)
               result[name.freeze] = convert(item, active, depth + 1)
             end.freeze
@@ -34,7 +38,8 @@ module CtxRunner
         end
       when Time then value.iso8601(6).freeze
       when String then value.dup.freeze
-      when Symbol, Rational, Complex then value.to_s.freeze
+      when Symbol then value.name
+      when Rational, Complex then value.to_s.freeze
       when Float
         raise ArgumentError, "Document numbers must be finite" unless value.finite?
         value

data/lib/ctx_runner/evidence.rb

@@ -8,19 +8,19 @@ module CtxRunner
     def self.validate(document)
       unless document.is_a?(Hash) && document["device"].is_a?(Hash) &&
           %w[name host].all? { |key| document["device"][key].is_a?(String) && !document["device"][key].empty? }
-        raise ArgumentError, "无设备身份"
+        raise ArgumentError, "Device identity is missing"
       end
       host = document["device"]["host"]
-      raise ArgumentError, "目标地址须为规范主机地址" unless !host.include?("/") && IPAddr.new(host).to_s == host
+      raise ArgumentError, "Target address must be a canonical host address" unless !host.include?("/") && IPAddr.new(host).to_s == host
       snapshot = document.fetch("snapshot")
       return if snapshot.nil?
-      raise ArgumentError, "快照结构错误" unless snapshot.is_a?(Hash) && snapshot["dimensions"].is_a?(Hash)
+      raise ArgumentError, "Invalid snapshot structure" unless snapshot.is_a?(Hash) && snapshot["dimensions"].is_a?(Hash)
       if !snapshot["target"].is_a?(Hash) || snapshot["target"]["host"] != host
-        raise ArgumentError, "设备身份与采集目标不一致"
+        raise ArgumentError, "Device identity does not match the collection target"
       end
       snapshot["dimensions"].each do |dimension, observation|
         unless observation.is_a?(Hash) && %w[complete partial failed unsupported not_requested].include?(observation["status"])
-          raise ArgumentError, "观测结构错误"
+          raise ArgumentError, "Invalid observation structure"
         end
         records = array(observation.fetch("records"))
         array(observation.fetch("issues", []))
@@ -29,12 +29,12 @@ module CtxRunner
     end
 
     def self.array(value)
-      raise ArgumentError, "列表结构错误" unless value.is_a?(Array) && value.all? { |entry| entry.is_a?(Hash) }
+      raise ArgumentError, "Expected a list of records" unless value.is_a?(Array) && value.all? { |entry| entry.is_a?(Hash) }
       value
     end
 
     def self.map(value)
-      raise ArgumentError, "映射结构错误" unless value.is_a?(Hash) && value.values.all? { |entry| entry.is_a?(Hash) }
+      raise ArgumentError, "Expected a mapping of records" unless value.is_a?(Hash) && value.values.all? { |entry| entry.is_a?(Hash) }
       value
     end
   end

data/lib/ctx_runner/report.rb

@@ -4,7 +4,7 @@ require "json"
 require "time"
 require "tempfile"
 require "fileutils"
-require "ctx_parser/immutable"
+require_relative "document"
 
 module CtxRunner
   # 持有私有证据批次，统一检查点、发布和失败恢复；领域只提供展示内容。
@@ -18,7 +18,7 @@ module CtxRunner
       # 保留安全的发布阶段与提交状态，不携带底层异常正文。
       def initialize(relative:, phase:, committed:)
         @relative, @phase, @committed = relative.dup.freeze, phase, committed
-        super("报告写入失败：#{relative}；阶段 #{phase}；#{committed ? '已替换，收尾未确认' : '尚未替换'}")
+        super("Report publication failed: #{relative}; phase #{phase}; #{committed ? 'replaced; finalization unconfirmed' : 'not replaced'}")
       end
 
       # 区分原子替换已完成与目录同步尚未确认。
@@ -33,7 +33,7 @@ module CtxRunner
       prepare_directory(root)
       stat = File.lstat(root)
       unless stat.directory? && (stat.mode & 0o077).zero?
-        raise ArgumentError, "报告根目录须为真实私有目录，权限0700；请设置独立目录并检查 chmod 0700"
+        raise ArgumentError, "Report root must be a real private directory with mode 0700; use a dedicated directory and check chmod 0700"
       end
       stem = Time.now.utc.strftime("%Y-%m-%d_%H-%M-%S")
       sequence = 0
@@ -51,46 +51,55 @@ module CtxRunner
     def finish(results, interrupted: false, requested: [], report_error: nil, execution_error: nil, output_error: nil, review: nil)
       raise ArgumentError, "Report requires a presentation block" unless block_given?
       @recovery_failed = false
-      # 按地址索引一次，避免大批次逐个扫描所有已完成结果。
-      completed_hosts = results.to_h { |result| [ result.fetch(:device).fetch("host"), true ] }
-      pending = requested.reject { |device| completed_hosts.key?(device.fetch("host")) }
-      complete = !report_error && !execution_error && !output_error && pending.empty? && results.any? && results.all? { |r| r[:status] == :complete && r[:report_saved] != false }
-      summary = { status: interrupted ? :interrupted : (complete ? :complete : :incomplete),
-        total: [ requested.size, results.size ].max, completed: results.size, pending: pending, counts: results.map { |r| r[:status] }.tally, devices: results,
-        directory: directory, evidence_only: true }
-      summary[:review] = review if review
-      summary[:report_error] = report_error if report_error
-      summary[:execution_error] = execution_error if execution_error
-      summary[:output_error] = output_error if output_error
-      summary = CtxParser::Immutable.copy(serializable(summary))
-      # 先保存未完成检查点；文本发布或最终提交失败都不能留下成功摘要。
-      checkpoint = summary.merge(status: interrupted ? :interrupted : :incomplete,
-        report_error: report_error || :report_finalization_unconfirmed)
-      checkpoint_body = JSON.pretty_generate(checkpoint) + "\n"
-      publish_checkpoint("summary.json", checkpoint_body)
+      summary = checkpoint = nil
+      # 转换和编码也属于发布；失败或取消不能让上一轮完成结论继续生效。
+      checkpoint_body = publish_checkpoint("summary.json") do
+        # 按地址索引一次，避免大批次逐个扫描所有已完成结果。
+        completed_hosts = results.to_h { |result| [ result.fetch(:device).fetch("host"), true ] }
+        pending = requested.reject { |device| completed_hosts.key?(device.fetch("host")) }
+        complete = !report_error && !execution_error && !output_error && pending.empty? && results.any? && results.all? { |r| r[:status] == :complete && r[:report_saved] != false }
+        summary = { status: interrupted ? :interrupted : (complete ? :complete : :incomplete),
+          total: [ requested.size, results.size ].max, completed: results.size, pending: pending, counts: results.map { |r| r[:status] }.tally, devices: results,
+          directory: directory, evidence_only: true }
+        summary[:review] = review if review
+        summary[:report_error] = report_error if report_error
+        summary[:execution_error] = execution_error if execution_error
+        summary[:output_error] = output_error if output_error
+        summary = Document.call(summary)
+        # 检查点共享已固定的证据；不重复转换，也不重新读取调用方对象。
+        checkpoint = summary.merge("status" => interrupted ? "interrupted" : "incomplete",
+          "report_error" => summary["report_error"] || "report_finalization_unconfirmed").freeze
+        document_body(checkpoint)
+      end
       publish("summary.txt", yield(summary))
       commit_summary("summary.json", summary, checkpoint: checkpoint, checkpoint_body: checkpoint_body)
     end
 
     # 新一轮发布必须先撤销旧完成结论；非局部退出也不能绕过这条边界。
     def checkpoint(relative, value)
-      publish_checkpoint(relative, JSON.pretty_generate(serializable(value)) + "\n")
+      publish_checkpoint(relative) { document_body(checkpoint_document(value)) }
     end
 
     # 领域报告正文完成后提交最终状态；取消和提交后失败共用恢复协议。
     def finalize(relative, summary, checkpoint:)
       relative = checked_relative(relative)
-      summary = CtxParser::Immutable.copy(serializable(summary))
-      checkpoint = CtxParser::Immutable.copy(serializable(checkpoint))
-      commit_summary(relative, summary, checkpoint: checkpoint, checkpoint_body: JSON.pretty_generate(checkpoint) + "\n")
+      validated = true
+      summary = Document.call(summary)
+      checkpoint = checkpoint_document(checkpoint)
+      commit_summary(relative, summary, checkpoint: checkpoint, checkpoint_body: document_body(checkpoint))
+      finalized = true
+      summary
+    ensure
+      invalidate_completed_summary(relative: relative) if validated && !finalized
     end
 
-    def publish_checkpoint(relative, body)
+    def publish_checkpoint(relative)
       relative = checked_relative(relative)
       validated = true
-      published = false
+      body = yield
       publish(relative, body)
       published = true
+      body
     ensure
       invalidate_completed_summary(relative: relative) if validated && !published
     end
@@ -99,7 +108,7 @@ module CtxRunner
     def commit_summary(relative, summary, checkpoint:, checkpoint_body:)
       finalized = false
       begin
-        publish(relative, JSON.pretty_generate(summary) + "\n")
+        publish(relative, document_body(summary))
         finalized = true
       rescue Error => error
         # 未替换时原检查点仍安全，不做可能破坏它的多余恢复写入。
@@ -107,7 +116,7 @@ module CtxRunner
         finalized = true
         raise
       rescue Interrupt
-        restore_checkpoint(JSON.pretty_generate(checkpoint.merge(status: :interrupted)) + "\n", relative: relative)
+        restore_checkpoint(document_body(checkpoint.merge("status" => "interrupted")), relative: relative)
         finalized = true
         raise
       ensure
@@ -120,7 +129,7 @@ module CtxRunner
 
     # 每次发送配置前后发布检查点；失败由执行器停止后续写入。
     def write_execution(state)
-      publish("execution.json", JSON.pretty_generate(state) + "\n")
+      publish("execution.json", document_body(Document.call(state)))
     end
 
     # 恢复写入或删除受阻时，调用方须把退出码及此状态作为未确认诊断。
@@ -149,7 +158,7 @@ module CtxRunner
     def invalidate_completed_summary(relative: "summary.json")
       relative = checked_relative(relative)
       Thread.handle_interrupt(Exception => :never) do
-        saved = JSON.parse(File.read(File.join(directory, relative)))
+        saved = JSON.parse(File.read(File.join(directory, relative)), max_nesting: Document::MAX_DEPTH + 1)
         discard_summary(relative: relative) if saved["status"] == "complete"
       end
     rescue Errno::ENOENT
@@ -176,24 +185,15 @@ module CtxRunner
     # 存储拒绝恢复时尽力移除不可信摘要，不删除已获得的设备事实。
     def discard_summary(relative: "summary.json")
       relative = checked_relative(relative)
-      File.unlink(File.join(directory, relative))
+      target = File.join(directory, relative)
+      File.unlink(target)
+      sync_directory(File.dirname(target))
     rescue Errno::ENOENT
       nil
-    rescue SystemCallError
+    rescue SystemCallError, IOError, NotImplementedError
       @recovery_failed = true
     end
 
-    # Time 使用 ISO-8601，递归转换 Data 只发生在显式持久化边界。
-    def serializable(value)
-      case value
-      when Time then value.iso8601(6)
-      when Data then serializable(value.to_h)
-      when Hash then value.transform_values { |item| serializable(item) }
-      when Array then value.map { |item| serializable(item) }
-      else value
-      end
-    end
-
     # 临时文件与目标在同一目录，写入失败不发布半份报告。
     def publish(relative, body)
       relative = checked_relative(relative)
@@ -218,6 +218,18 @@ module CtxRunner
     end
     private
 
+    # 恢复只能保留未完成事实，不能把完成摘要当作安全检查点。
+    def checkpoint_document(value)
+      document = Document.call(value)
+      unless document.is_a?(Hash) && document["status"].is_a?(String) && !document["status"].empty? && document["status"] != "complete"
+        raise ArgumentError, "Checkpoint requires a non-complete status"
+      end
+      document
+    end
+
+    # 深度由 Document 校验；编码阶段不再施加 JSON 默认的更低嵌套限制。
+    def document_body(document) = JSON.pretty_generate(document, max_nesting: false) + "\n"
+
     # 发布、恢复与删除使用同一条路径契约；拒绝路径时不能执行收尾副作用。
     def checked_relative(relative)
       unless relative.is_a?(String) && !relative.empty? && !relative.start_with?("/") &&

data/lib/ctx_runner/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CtxRunner
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_runner
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Gatework contributors
@@ -13,42 +13,30 @@ dependencies:
   name: ctx_parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.6
+        version: 0.2.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.6
+        version: 0.2.7
 - !ruby/object:Gem::Dependency
   name: ctx_driver
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.6
+        version: 0.2.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.6
+        version: 0.2.7
 - !ruby/object:Gem::Dependency
   name: digest
   requirement: !ruby/object:Gem::Requirement