ctx_runner 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ff3a46f0ebe797a901ddcadbae2203d4074e45fa27642ae105c4756a1425a865
+  data.tar.gz: e06e7ce433130362c644f9d8c2efabcf317e688ba779a6efb647775a05a81a21
+SHA512:
+  metadata.gz: 86a015cecb44ae07990cca0e129fb269bae3d6f8b11ff7d12ec2011b472e94829a15e9b16503a4b1afdead0ca0313380e3069097134015d261dde35a1afa305b
+  data.tar.gz: dd14c83315b9d4f919d6326c1fb82b2dfc39e4fac7189fae844f547b1cfaba4678f5070203cad2cc7a2db799e298129294ab37aedd6be619dac5b723e947a8d3

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (2026-10-22)
+
+- Centralize batch completion, cancellation priority and presentation failures; close result registration before finalization and preserve immutable summaries.
+
+- Preserve successful sibling views when another query projection fails.
+
+- Centralize collection lifecycle, shared query execution and immutable observation contracts.
+- Share batch accounting and durable evidence publication across domain consumers.
+- Execute confirmed typed changes with immutable journal checkpoints, readback verification and no replay.
+- Preserve JSON configuration fingerprints while rejecting normalized key collisions.
+- Add offline examples, fault-contract tests, Ruby 4.0.6 engineering gates and isolated package verification.

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Song Huang
+Copyright (c) 2026 Gatework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# ctx_runner
+
+网络证据采集、批次交付与受控变更的公共业务库。沿用 ctx_parser 的普通 Ruby 对象、显式参数、不可变快照及独立 gem 工程范式。
+
+## 职责
+
+| 对象 | 负责的业务 |
+| --- | --- |
+| `Collection` | 一次连接器交付、阶段诊断、禁止重复执行 |
+| `Query` | 单命令读取解析、共享视图、失败与来源绑定 |
+| `Observation` | 事实外壳、可用性、时间类型、深度快照及安全展示 |
+| `Batch` | 单设备结果登记、报告交付、输出失败补写 |
+| `Report` | 私有批次目录、文件发布、检查点、完成判定及恢复 |
+| `Fingerprint` | 稳定配置身份，拒绝归一化键冲突 |
+| `Execution` | 已确认增量的前提核验、执行记账、效果不确定状态及回读验收 |
+
+ctx_parser 负责解析事实，ctx_driver 负责借用会话并交付命令 Capture，ctx_runner 负责组织业务过程。厂商语法、健康判定、AP 转接租约和变更规则留在领域模块。连接器拥有连接及关闭，Runner 不隐式连接、重连、提权或重放。
+
+## 使用
+
+Ruby >= 4.0.6。安装后 `require "ctx_runner"`，或按能力加载 `ctx_runner/report` 等文件。加载库不建立网络连接或创建目录。
+
+```ruby
+run = CtxRunner::Collection.new
+run.open(connector) do |session|
+  reader = CtxDriver::Reader.new(session: session)
+  query = CtxRunner::Query.new(reader: reader, parser: profile)
+  query.read("show example", names: [:example], unavailable: failure_projection) do |name, result, capture|
+    CtxRunner::Observation.new(name: name, **result.to_h,
+      evidence: capture.evidence, started_at: capture.started_at,
+      completed_at: capture.completed_at)
+  end
+end
+# run.failure 是安全的 code/stage/error_type，不包含设备正文或异常消息。
+```
+
+领域 Profile 实现 `parse_many(names, body, complete:, command:)`；不可用投影接收 `(name, capture, failure)`。一次 Query 对应一条命令，多个视图共享同一份 Capture。
+
+`Collection.new(strict: true)` 对连接器零次/重复回调抛出 ArgumentError，兼容严格宿主契约；默认记录 session_not_opened/session_reentered。连接关闭错误不会覆盖已完成的领域事实。借用会话直接使用 Reader/Query，无需再进入 Collection。
+
+`Batch.new(report:, progress:, requested:)` 接收报告和进度协作者。`collect(device) { snapshot }` 返回不含原始配置的设备摘要；`run(present:) { ... }` 包住调度和领域后处理；块必须在返回或抛错前回收全部任务。Runner 统一取消、执行失败、报告及输出失败，返回不可变 Completion（status、summary、安全 failure、finalization_error、recovery_failed）。取消优先于收尾失败，展示失败只补写报告、不重采或重复展示。进入收尾即关闭结果登记，run 不可重放。CLI 将 complete/incomplete/failed/interrupted 映射到 0/1/2/130。`finish` 是内部交付步骤；调度和网络资源仍由宿主拥有。
+
+`Report.new(root)` 创建排他的私有批次，目录 0700、文件 0600。`finish(results, requested:) { |summary| text }` 先保存未完成检查点，再发布领域文本，最后发布最终 JSON。`Report::Error#committed?` 区分是否已替换；失败不能被当作可靠发布。`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)。
+
+## 开发与验证
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake build
+ruby script/verify_package.rb pkg/ctx_runner-0.1.0.gem
+```
+
+默认 rake 运行 RSpec、RuboCop 和离线示例。CI 沿用 ctx_parser 的 Ruby 4.0.6 / Linux、macOS 矩阵和固定 action 提交。源码联调在消费仓库显式设置 `CTX_RUNNER_PATH=../ctx_runner`；普通验证使用已安装依赖。首次发版前须先构建安装 runner 候选包再验证消费包。
+
+首个版本为 0.1.0。发布流程复用 CI 制品，验证 GitHub Release 与 RubyGems 下载字节。

data/docs/superpowers/plans/2026-10-21-runner.md

@@ -0,0 +1,83 @@
+# ctx_runner Implementation Plan
+
+> **For agentic workers:** Use executing-plans to implement this plan task-by-task. Preserve unrelated work and do not commit or publish without authorization.
+
+**Goal:** 集中公共采集、证据交付和受控变更业务，迁移真实消费方，沿用 ctx_parser 工程范式。
+
+**Architecture:** CtxRunner 组合 CtxDriver 和 CtxParser；领域提供查询/事实投影与变更策略。连接器继续拥有会话和操作租约；Runner 不加载网络或数据库。
+
+**Tech Stack:** Ruby >= 4.0.6、RSpec、RuboCop Omakase、Rake、独立 gem。
+
+**Spec:** ../../../../module-architecture-review-2026-10-21.md 及用户已确认的 ctx_runner 分层方案。
+
+## Global Constraints
+
+- 名称采用明确业务名词：Report、Collection、Batch、Execution、Fingerprint；不引入通用回调框架。
+- 中文实现注释，英文 RSpec/Changelog；显式 require；不可变值使用 CtxParser::Immutable。
+- 厂商解析器名称与布局保持；领域策略不迁入公共库。
+- 保留失败证据、取消、来源字节摘要、禁止重放、私有报告和持久化确认契约。
+- 当前授权为实现与本地验证，不包含提交、推送、发布。
+
+## Review Focus
+
+- 文件 rename 后 fsync 或取消失败不得留下可信的成功摘要。
+- 注入回调修改输入不能改变已确认计划或已校验请求。
+- 无会话/重复会话不能虚报完成或重放命令。
+- 无线 AP 操作租约不能被统一连接包装破坏。
+- 已安装依赖和候选源码/包分别验证，不能依赖相邻源码路径才能工作。
+
+## Tasks
+
+### Task 1: Evidence reports and gem foundation
+
+Files: lib/ctx_runner/report.rb, spec/report_spec.rb, examples/report.rb, gemspec, Rakefile, AGENTS.md; VXLAN/Wireless cli/report.rb.
+
+Interfaces: Report.new(root, error_class:) owns a private batch; publish(relative, body), prepare_directory(path), serializable(value), finish(results, requested:, ...) { |summary| text }, recovery_failed?, restore_checkpoint(body, relative:).
+
+- [x] Write behavior specs for private evidence, incomplete checkpoint, post-rename failure and cancellation; run RED.
+- [x] Implement report publication and completion protocol; run GREEN.
+- [x] Replace domain publication/state machine with composition; retain rendering and error class names.
+- [x] Run runner and both consumer report/review/CLI specs, lint and offline example.
+
+### Task 2: Typed change execution
+
+Files: lib/ctx_runner/fingerprint.rb, execution.rb, specs/examples; both change_plan.rb and cli/apply.rb.
+
+Interfaces: Fingerprint.canonical(value)/call(value); Execution owns intent and command acknowledgements; domain change supplies commands, eligible?, satisfied?.
+
+- [x] Pin cancellation, stale preconditions, mutation, log failure before/after send, duplicate session and readback failure before migration.
+- [x] Implement and migrate both apply paths, retaining CLI confirmation and domain plan selection.
+- [x] Verify both apply suites and fingerprint compatibility for existing legal JSON inputs.
+
+### Task 3: Collection and evidence contracts
+
+Files: lib/ctx_runner/collection.rb, query.rb, observation.rb, specs/examples; three collectors and domain adapters.
+
+- [x] Pin unique session, independent failure, shared query, stopped session, close error and borrowed ownership.
+- [x] Implement lifecycle and read/parse/evidence coordination; migrate all three collectors with domain strategies retained.
+- [x] Preserve Checker applicability/discovery/scopes, VXLAN configuration ordering, Wireless AP scope and leases.
+- [x] Unify observation envelope validation while retaining domain schemas and public representations.
+
+### Task 4: Batch delivery
+
+Files: lib/ctx_runner/batch.rb, specs/examples; both cli/collect.rb.
+
+- [x] Pin result retention, output failures, cancellation and repeated invocation.
+- [x] Centralize collection accounting and report delivery; migrate both CLIs without changing options/inventory policies.
+- [x] Verify actual CLI entrypoints, full consumer suites and offline examples.
+
+### Task 5: Engineering gates and final audit
+
+- [x] Complete README, architecture, CHANGELOG, AGENTS, CI and isolated package verification matching ctx_parser conventions.
+- [x] Full runner/default Rake plus affected consumer default tasks; current-source integration and isolated candidate installation.
+- [x] Fresh review, resolve material findings, audit requirements and remaining duplicated business state machines.
+
+## Progress / rulings
+
+- Initial: ctx_runner absent; seven module source state rechecked. Net-connector unrelated untracked documents preserved.
+- Ruling: user explicitly requested implementation after reviewing architecture; proceed without another design approval round.
+- Ruling: retain domain publication error types through explicit error-class injection; shared Report owns protocol, consumer Report owns presentation.
+
+- Final: seven named capabilities implemented; ctx_checker, vxlan and wireless consume the shared workflows. Domain parsers, policy and connection ownership remain with their existing owners.
+- Evidence: see `../../verification-2026-10-22.md` for contract coverage, source/installed/package gates and validation limits.
+- Review: mutable summary, retained callbacks, cancellation after replacement, initial checkpoint cancellation and rejected-path cleanup findings resolved with regression coverage.

data/docs/verification-2026-10-22.md

@@ -0,0 +1,35 @@
+# ctx_runner 本地验收（2026-10-22）
+
+## 目标与实现
+
+将重复公共业务流程收敛到独立 gem，沿用 ctx_parser 工程规范。命名使用 Collection、Query、Observation、Batch、Report、Fingerprint、Execution；普通对象组合、显式 require、两空格缩进、中文实现注释、英文 RSpec，复用 CtxParser::Immutable。未引入通用工作流 DSL。
+
+| 范围 | 实现及验收依据 |
+| --- | --- |
+| 私有证据与完成协议 | Report；report_spec 覆盖目录权限、未完成检查点、不可变摘要、取消及拒绝路径；消费方 report/review specs 验证发布失败和恢复 |
+| 受控变更 | Execution/Fingerprint；执行 specs 验证先记账后发送、重复调用、回调失效、发送后日志失败与中断；两方 apply specs 验证漂移、确认、回读失败和领域增量 |
+| 采集与来源 | Collection/Query/Observation；唯一会话、关闭失败、共享命令、错误投影与独立快照；三个 collector suites 保留借用会话、覆盖范围和无线 AP 租约 |
+| 批量交付 | Batch；保存失败仍保留结果、设备异常隔离、输出失败补写而不重放；消费 CLI suites 验证取消和调度器收尾 |
+| 领域边界 | ctx_checker 保留 schema/评估；VXLAN 保留配置顺序和未配置判定；Wireless 保留 AP 作用域与转接；厂商解析器名称不变 |
+| 工程 | Rake 默认 RSpec/RuboCop/离线 examples；gemspec 明确包清单；固定 action SHA 的 Linux/macOS CI；隔离安装脚本；README、CHANGELOG、AGENTS |
+
+## 验证记录
+
+Ruby 4.0.6，Bundler 4.0.20。所有命令在各自仓库通过 zsh -ic 执行。
+
+| 仓库 | RSpec | RuboCop | 离线示例与构建 |
+| --- | ---: | ---: | --- |
+| ctx_runner | 30 / 0 failures | 23 files / 0 offenses | 通过 |
+| ctx_checker | 700 / 0 failures | 192 files / 0 offenses | 通过 |
+| vxlan | 453 / 0 failures | 106 files / 0 offenses | 通过 |
+| wireless | 316 / 0 failures | 91 files / 0 offenses | 通过 |
+
+消费模块分别运行了 `CTX_RUNNER_PATH=../ctx_runner bundle exec rake` 源码联调，以及安装最新 Runner 候选后、不设置该变量的 `bundle install --local`、`bundle exec rake` 和 `bundle exec rake build`。普通入口的完整测试合计 1499 examples，0 failures。源码联调之后 Report 的路径恢复保护又补充了回归；最终普通安装测试使用包含该修复的候选。
+
+Runner 的 `ruby script/verify_package.rb pkg/ctx_runner-0.1.0.gem` 在空 GEM_HOME 安装并运行包内示例。消费模块隔离验证显式传入 Runner 0.1.0、net-connector 0.16.1、expect-pty 0.9.5 候选，精确激活后运行包内示例与 CLI 验证。VXLAN/Wireless 参数顺序为目标、connector、expect、runner；Checker 为目标后跟依赖包（runner、expect、connector）。
+
+独立复核的 Report/Execution/Collection 回归 20 examples、0 failures；已解决摘要所有权、失效回调、替换后取消、初始检查点取消和拒绝路径清理问题。
+
+## 证据边界
+
+本地合成数据及隔离安装证明库契约和普通入口可运行，不表示真实设备认证、远程 CI 已执行或版本已发布。本次不提交、不推送、不发布，也不改变仓库可见性。ctx_parser、ctx_driver、expect-ruby 无变更，net-connector-trunk 原有两份未跟踪设计文档保留。

data/examples/execution.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "ctx_runner"
+require "tmpdir"
+
+# 合成领域动作，只演示前提、执行记账与回读验收；没有设备连接。
+class ExampleChange
+  def commands = [ "set mode enabled" ].freeze
+  def eligible?(config) = config["mode"] == "disabled"
+  def satisfied?(config, before:) = before["mode"] == "disabled" && config["mode"] == "enabled"
+end
+
+class ExampleSession
+  def initialize = @mode = "disabled"
+  def read_configuration = { "mode" => @mode }
+  def write(command)
+    raise "Unexpected command" unless command == "set mode enabled"
+    @mode = "enabled"
+    true
+  end
+end
+
+Dir.mktmpdir do |root|
+  report = CtxRunner::Report.new(File.join(root, "execution"))
+  plan = { "device" => { "host" => "192.0.2.1" }, "expected_config_sha256" => CtxRunner::Fingerprint.call("mode" => "disabled") }
+  execution = CtxRunner::Execution.new(plan: plan, change: ExampleChange.new, journal: report, plan_sha256: "a" * 64)
+  result = execution.run { |operation| operation.call(ExampleSession.new) }
+  raise "Unverified configuration" unless result["status"] == "configuration_verified"
+  raise "Lost command evidence" unless result["steps"].one?
+end

data/examples/report.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "ctx_runner"
+require "tmpdir"
+
+# 离线证据发布；临时目录由示例拥有，不接触设备或宿主配置。
+Dir.mktmpdir do |root|
+  report = CtxRunner::Report.new(File.join(root, "reports"))
+  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"
+  end
+  raise "Report incomplete" unless summary[:status] == :complete
+  raise "Missing evidence" unless File.file?(File.join(report.directory, "evidence.json"))
+end

data/lib/ctx_runner/batch.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "ctx_parser/immutable"
+require "ctx_driver/failure"
+
+module CtxRunner
+  # 批量采集的交付账本；调度器负责并发与回收，领域块只返回设备快照。
+  class Batch
+    Completion = Data.define(:status, :summary, :failure, :finalization_error, :recovery_failed) do
+      def initialize(**attributes)
+        super(**CtxParser::Immutable.copy(attributes))
+      end
+
+      def inspect = "#<#{self.class.name} status=#{status}>"
+      alias to_s inspect
+      def pretty_print(printer) = printer.text(inspect)
+    end
+
+    # 块拥有调度及回收；返回后统一交付，取消优先于收尾失败。
+    def run(present: nil)
+      raise ArgumentError, "Batch cannot be replayed" if @running
+      raise ArgumentError, "Batch requires an operation" unless block_given?
+      @running = entered = true
+      options = { interrupted: false, report_error: nil, execution_error: nil }
+      failure = nil
+      begin
+        yield
+      rescue Interrupt
+        options[:interrupted] = true
+      rescue StandardError, LoadError => error
+        failure = classify(error)
+        options[failure[:kind] == :report ? :report_error : :execution_error] = failure[:detail]
+      end
+      @closed = true
+      settling = true
+      summary, finalization_error = settle(options)
+      if summary && present
+        presenting = true
+        begin
+          present.call(summary)
+        rescue Interrupt
+          options[:interrupted] = true
+          summary, finalization_error = settle(options)
+        rescue StandardError, LoadError => error
+          failure ||= classify(error)
+          options[:report_error] = diagnostic(error)
+          summary, finalization_error = settle(options)
+        end
+      end
+      presenting = false
+      status = if options[:interrupted]
+        :interrupted
+      elsif failure || finalization_error
+        :failed
+      else
+        summary[: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?)
+      completed = true
+      completion
+    ensure
+      @closed = true if entered
+      # throw/非局部 return 也要收尾，但绝不覆盖原退出或再次展示。
+      if entered && !completed && (!settling || presenting)
+        begin
+          finish(interrupted: true)
+        rescue StandardError, LoadError, Interrupt
+          nil
+        end
+      end
+    end
+
+    def initialize(report:, progress:, requested:)
+      @requested = CtxParser::Immutable.copy(requested)
+      @report, @progress = report, progress
+      @results, @lock = [], Mutex.new
+    end
+
+    # 先登记设备事实，再保存报告；报告失败仍可在最终摘要中定位未交付结果。
+    def collect(device)
+      raise ArgumentError, "Batch is closed" if @closed
+      device = CtxParser::Immutable.copy(device)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @progress.start(device)
+      snapshot = nil
+      begin
+        snapshot = yield
+        dimensions = snapshot.dimensions.transform_values do |value|
+          { status: value.status, records: value.records.size, issues: value.issues.map { |issue| issue[:code] }.uniq }
+        end
+        result = { device: device, status: snapshot.dimensions.fetch(:collection).status, dimensions: dimensions }
+      rescue StandardError => error
+        result = { device: device, status: :failed, error: CtxDriver::Failure.code(error, :collection_failed), dimensions: {} }
+      end
+      result[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+      result[:report_saved] = false
+      @lock.synchronize { @results << result }
+      @report.write(CtxParser::Immutable.copy(result), snapshot: snapshot)
+      @lock.synchronize { result[:report_saved] = true }
+      saved = CtxParser::Immutable.copy(result)
+      @progress.result(saved)
+      saved
+    end
+
+    def results
+      @lock.synchronize { CtxParser::Immutable.copy(@results).sort_by { |result| result[:device].fetch("host") }.freeze }
+    end
+
+    # 调度器回收后调用；输出诊断只补写报告，绝不重新执行设备操作。
+    def finish(interrupted: false, report_error: nil, execution_error: nil)
+      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]
+        summary = @report.finish(snapshot, **options, output_error: @progress.output_error)
+      end
+      summary
+    end
+
+    def inspect = "#<#{self.class.name}>"
+
+    private
+
+    def settle(options)
+      [ CtxParser::Immutable.copy(finish(**options)), nil ]
+    rescue Interrupt
+      options[:interrupted] = true
+      begin
+        [ CtxParser::Immutable.copy(finish(**options)), nil ]
+      rescue StandardError, LoadError, Interrupt => error
+        [ nil, diagnostic(error) ]
+      end
+    rescue StandardError, LoadError => error
+      [ nil, diagnostic(error) ]
+    end
+
+    def classify(error)
+      kind = error.is_a?(SystemCallError) || error.is_a?(IOError) ? :report : :execution
+      { kind: kind, error_type: error.class.name, detail: kind == :report ? diagnostic(error) : error.class.name }.freeze
+    end
+
+    def diagnostic(error)
+      type = @report.class.const_get(:Error) if @report.class.const_defined?(:Error)
+      type && error.instance_of?(type) ? error.message : error.class.name
+    end
+  end
+end

data/lib/ctx_runner/collection.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "ctx_driver/failure"
+
+module CtxRunner
+  # 约束一次连接器交付，不接管连接或操作租约；已取得的事实由领域块保留。
+  class Collection
+    attr_reader :failure, :stage
+
+    def initialize(strict: false)
+      raise ArgumentError, "Strict session contract must be boolean" unless [ true, false ].include?(strict)
+      @strict, @used = strict, false
+      @stage = :connect
+    end
+
+    # 准备阶段由领域计划显式声明，关闭阶段仅在采集块正常完成后进入。
+    def stage=(value)
+      raise ArgumentError, "Invalid collection stage" unless %i[connect prepare collect close].include?(value)
+      @stage = value
+    end
+
+    def open(connector)
+      raise ArgumentError, "Collection cannot be replayed" if @used
+      raise ArgumentError, "Collection requires an operation" unless block_given?
+      @used = true
+      acquire(connector) { |session| yield session }
+      self
+    end
+
+    def inspect = "#<#{self.class.name} stage=#{stage}>"
+
+    private
+
+    def acquire(connector)
+      yielded = false
+      active = true
+      connector.open do |session|
+        raise IOError, "Session provider scope has ended" unless active
+        if yielded
+          contract_failure(:session_reentered)
+          next
+        end
+        yielded = true
+        @stage = :collect
+        yield session
+        @stage = :close
+      end
+      contract_failure(:session_not_opened) unless yielded
+    rescue StandardError => error
+      raise unless CtxDriver::Failure.connection_error?(error, connector)
+      details = CtxDriver::Failure.details(error, fallback: :connection_failed, stage: stage)
+      @failure = (stage == :close ? details.merge(code: :session_close_failed) : details).freeze
+    ensure
+      active = false
+    end
+
+    def contract_failure(code)
+      raise ArgumentError, "Connector must provide one session" if @strict
+      @failure ||= { code: code, stage: stage }.freeze
+    end
+  end
+end

data/lib/ctx_runner/execution.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "ctx_parser/immutable"
+require "ctx_driver/failure"
+require_relative "fingerprint"
+
+module CtxRunner
+  # 只执行已确认的单项领域变更；日志、设备效果与配置验收分别记账。
+  class Execution
+    # 领域动作负责有限命令及前后置条件；日志接收独立的不可变检查点。
+    def initialize(plan:, change:, journal:, plan_sha256:, item: nil)
+      @plan = CtxParser::Immutable.copy(plan)
+      unless @plan.is_a?(Hash) && @plan["device"].is_a?(Hash) &&
+          [ @plan["expected_config_sha256"], plan_sha256 ].all? { |value| value.is_a?(String) && /\A[0-9a-f]{64}\z/.match?(value) }
+        raise ArgumentError, "Execution requires a verified plan and fingerprints"
+      end
+      unless %i[commands eligible? satisfied?].all? { |method| change.respond_to?(method) } && journal.respond_to?(:write_execution)
+        raise ArgumentError, "Execution requires a typed change and journal"
+      end
+      @commands = CtxParser::Immutable.copy(change.commands)
+      unless @commands.is_a?(Array) && @commands.any? && @commands.all? { |command| command.is_a?(String) && !command.strip.empty? && !/[\x00-\x1f\x7f]/.match?(command) }
+        raise ArgumentError, "Change commands must be individual lines"
+      end
+      @change, @journal = change, journal
+      @state = { "status" => "confirmed", "device" => @plan["device"], "plan_sha256" => plan_sha256.dup.freeze,
+        "expected_config_sha256" => @plan["expected_config_sha256"], "commands" => @commands, "steps" => [] }
+      @state["plan_item"] = CtxParser::Immutable.copy(item) if item
+      @started = @used = @journal_failed = false
+    end
+
+    # 由连接器提供唯一会话并清理；关闭失败同样不能发布配置已验证状态。
+    def run
+      raise ArgumentError, "Execution cannot be replayed" if @used
+      raise ArgumentError, "Execution requires a session provider" unless block_given?
+      @used = true
+      perform { |operation| yield operation }
+    end
+
+    def started? = @started
+    def journal_failed? = @journal_failed
+    def state = CtxParser::Immutable.copy(@state)
+    def inspect = "#<#{self.class.name} status=#{@state.fetch('status')}>"
+
+    private
+
+    # 保存意图先于连接；回调次数和完成状态不依赖连接器返回值。
+    def perform
+      opened = verified = finished = recorded = false
+      active = true
+      save
+      yield lambda { |session|
+        raise IOError, "Session provider scope has ended" unless active
+        raise IOError, "Session callback repeated" if opened
+        opened = true
+        before = CtxParser::Immutable.copy(session.read_configuration)
+        unless Fingerprint.call(before) == @plan["expected_config_sha256"] && @change.eligible?(before)
+          raise ArgumentError, "Configuration changed or preconditions failed"
+        end
+        @commands.each_with_index { |command, index| execute(session, command, index) }
+        after = CtxParser::Immutable.copy(session.read_configuration)
+        raise IOError, "Configuration verification failed" unless @change.satisfied?(after, before: before)
+        @state["observed_config_sha256"] = Fingerprint.call(after)
+        verified = true
+      }
+      raise IOError, "Session did not verify the configuration" unless verified
+      @state["status"] = "configuration_verified"
+      save
+      finished = true
+      state
+    rescue StandardError, Interrupt => error
+      recorded = true
+      type = error.is_a?(Interrupt) ? "interrupted" : CtxDriver::Failure.details(error, fallback: :execution_failed, stage: :execute).fetch(:error_type)
+      record_failure(type)
+      raise
+    ensure
+      active = false
+      # 非局部退出与线程取消也不能留下可重放的成功意图。
+      record_failure("aborted") unless finished || recorded
+    end
+
+    # 发送前记录未决命令；已执行事实在发送后的日志失败时继续保留。
+    def execute(session, command, index)
+      @state["status"] = "executing"
+      @state["pending_command"] = index
+      save
+      @started = true
+      raise IOError, "Command was not acknowledged" unless session.write(command) == true
+      @state["steps"] << { "index" => index, "status" => "acknowledged" }
+      @state.delete("pending_command")
+      save
+    end
+
+    def save = @journal.write_execution(state)
+
+    # 次级日志故障不覆盖主异常，也不允许继续发送命令。
+    def record_failure(code)
+      @state["status"] = started? ? "uncertain" : "failed"
+      @state["error"] = code
+      save
+    rescue StandardError, Interrupt
+      @journal_failed = true
+    end
+  end
+end

data/lib/ctx_runner/fingerprint.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "ctx_parser/immutable"
+
+module CtxRunner
+  # 配置映射顺序不影响身份；列表顺序和全部字段仍参与旧版摘要协议。
+  module Fingerprint
+    def self.call(value) = Digest::SHA256.hexdigest(JSON.generate(canonical(value)))
+
+    # 先拒绝非纯数据与循环，再将键归一化；重名键不能静默覆盖来源事实。
+    def self.canonical(value)
+      normalize(CtxParser::Immutable.copy(value), 0)
+    end
+
+    def self.normalize(value, depth)
+      raise ArgumentError, "Configuration nesting exceeds the fingerprint budget" if depth > 128
+
+      case value
+      when Hash
+        normalized = {}
+        value.each do |key, entry|
+          raise ArgumentError, "Configuration keys must be strings or symbols" unless key.is_a?(String) || key.is_a?(Symbol)
+          name = key.to_s
+          raise ArgumentError, "Configuration keys collide after normalization" if normalized.key?(name)
+          normalized[name] = normalize(entry, depth + 1)
+        end
+        normalized.sort.to_h
+      when Array then value.map { |entry| normalize(entry, depth + 1) }
+      else value
+      end
+    end
+    private_class_method :normalize
+  end
+end

data/lib/ctx_runner/observation.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "ctx_parser/immutable"
+
+module CtxRunner
+  # 不可变的事实外壳；领域可继承外壳或复用校验，记录身份和业务字段仍由领域负责。
+  class Observation < Data.define(:name, :status, :records, :issues, :evidence, :started_at, :completed_at)
+    STATUSES = %i[complete partial failed unsupported not_requested].freeze
+
+    def self.validate(name:, status:, records:, issues:, evidence:, statuses: STATUSES)
+      raise ArgumentError, "Observation name must be a symbol" unless name.is_a?(Symbol)
+      raise ArgumentError, "Invalid observation status" unless statuses.include?(status)
+      unless [ records, issues, evidence ].all? { |entries| entries.is_a?(Array) && entries.all? { |entry| entry.is_a?(Hash) } }
+        raise ArgumentError, "Observation entries must be arrays of hashes"
+      end
+      if %i[failed unsupported not_requested not_applicable].include?(status) && records.any?
+        raise ArgumentError, "Unavailable observations cannot contain records"
+      end
+    end
+
+    def initialize(name:, status:, records: [], issues: [], evidence: [], started_at: nil, completed_at: nil)
+      self.class.validate(name: name, status: status, records: records, issues: issues, evidence: evidence)
+      unless [ started_at, completed_at ].all? { |time| time.nil? || time.is_a?(Time) }
+        raise ArgumentError, "Observation timestamps must be Time values or nil"
+      end
+      super(name: name, status: status, records: CtxParser::Immutable.copy(records),
+        issues: CtxParser::Immutable.copy(issues), evidence: CtxParser::Immutable.copy(evidence),
+        started_at: started_at&.dup&.freeze, completed_at: completed_at&.dup&.freeze)
+    end
+
+    def complete? = status == :complete
+    def partial? = status == :partial
+    def available? = complete? || partial?
+    def inspect = "#<#{self.class.name} name=#{name} status=#{status} records=#{records.size}>"
+    alias to_s inspect
+    def pretty_print(printer) = printer.text(inspect)
+  end
+end

data/lib/ctx_runner/query.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ctx_parser/immutable"
+require "ctx_driver/failure"
+
+module CtxRunner
+  # 一条查询只读取解析一次；共享视图交付相同来源，失败不影响其他查询。
+  class Query
+    def initialize(reader:, parser:)
+      @reader, @parser = reader, parser
+    end
+
+    # 不可用投影负责领域诊断结构；成功投影负责将事实与来源绑定。
+    def read(command, names:, unavailable:)
+      unless names.is_a?(Array) && names.any? && names.uniq == names && names.all? { |name| name.is_a?(Symbol) }
+        raise ArgumentError, "Query views must be unique symbols"
+      end
+      names = CtxParser::Immutable.copy(names)
+      command = CtxParser::Immutable.copy(command)
+      capture = @reader.read(command)
+      failure = capture.failure
+      if capture.success?
+        begin
+          parsed = @parser.parse_many(names, capture.body, complete: true, command: command)
+        rescue StandardError => error
+          failure = CtxDriver::Failure.details(error, fallback: :command_processing_failed, stage: :parse)
+        else
+          return names.to_h do |name|
+            value = begin
+              yield(name, parsed.fetch(name), capture)
+            rescue StandardError => error
+              details = CtxDriver::Failure.details(error, fallback: :command_processing_failed, stage: :parse)
+              unavailable.call(name, capture, details)
+            end
+            [ name, value ]
+          end
+        end
+      end
+      names.to_h { |name| [ name, unavailable.call(name, capture, failure) ] }
+    end
+
+    def inspect = "#<#{self.class.name}>"
+  end
+end

data/lib/ctx_runner/report.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "tempfile"
+require "fileutils"
+require "ctx_parser/immutable"
+
+module CtxRunner
+  # 持有私有证据批次，统一检查点、发布和失败恢复；领域只提供展示内容。
+  class Report
+    attr_reader :directory
+
+    # 仅交付发布阶段，不保留底层异常正文或敏感报告内容。
+    class Error < IOError
+      attr_reader :relative, :phase
+
+      # 保留安全的发布阶段与提交状态，不携带底层异常正文。
+      def initialize(relative:, phase:, committed:)
+        @relative, @phase, @committed = relative.dup.freeze, phase, committed
+        super("报告写入失败：#{relative}；阶段 #{phase}；#{committed ? '已替换，收尾未确认' : '尚未替换'}")
+      end
+
+      # 区分原子替换已完成与目录同步尚未确认。
+      def committed? = @committed
+    end
+
+    # 批次目录排他创建，重复时间戳不会覆盖上一批次。
+    def initialize(root, error_class: Error)
+      raise ArgumentError, "Report error must inherit from Report::Error" unless error_class.is_a?(Class) && error_class <= Error
+      @error_class = error_class
+      root = File.expand_path(root)
+      prepare_directory(root)
+      stat = File.lstat(root)
+      unless stat.directory? && (stat.mode & 0o077).zero?
+        raise ArgumentError, "报告根目录须为真实私有目录，权限0700；请设置独立目录并检查 chmod 0700"
+      end
+      stem = Time.now.utc.strftime("%Y-%m-%d_%H-%M-%S")
+      sequence = 0
+      begin
+        @directory = File.join(root, sequence.zero? ? stem : "#{stem}_#{sequence}").freeze
+        Dir.mkdir(directory, 0o700)
+      rescue Errno::EEXIST
+        sequence += 1
+        retry
+      end
+      sync_directory(root)
+    end
+
+    # 摘要不嵌入配置事实，只汇总状态与诊断，供终端和自动化共用。
+    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("summary.json", checkpoint)
+      publish("summary.txt", yield(summary))
+      finalize("summary.json", summary, checkpoint: checkpoint)
+    end
+
+    # 新一轮发布必须先撤销旧完成结论；非局部退出也不能绕过这条边界。
+    def checkpoint(relative, value)
+      relative = checked_relative(relative)
+      validated = true
+      published = false
+      publish(relative, JSON.pretty_generate(serializable(value)) + "\n")
+      published = true
+    ensure
+      invalidate_completed_summary(relative: relative) if validated && !published
+    end
+
+    # 领域报告正文完成后提交最终状态；取消和提交后失败共用恢复协议。
+    def finalize(relative, summary, checkpoint:)
+      relative = checked_relative(relative)
+      summary = CtxParser::Immutable.copy(serializable(summary))
+      checkpoint = CtxParser::Immutable.copy(serializable(checkpoint))
+      checkpoint_body = JSON.pretty_generate(checkpoint) + "\n"
+      finalized = false
+      begin
+        publish(relative, JSON.pretty_generate(serializable(summary)) + "\n")
+        finalized = true
+      rescue Error => error
+        # 未替换时原检查点仍安全，不做可能破坏它的多余恢复写入。
+        restore_checkpoint(checkpoint_body, relative: relative) if error.committed?
+        finalized = true
+        raise
+      rescue Interrupt
+        restore_checkpoint(JSON.pretty_generate(serializable(checkpoint.merge(status: :interrupted))) + "\n", relative: relative)
+        finalized = true
+        raise
+      ensure
+        # throw、线程终止等不经过 rescue；仍撤销尚未确认持久性的最终状态。
+        restore_checkpoint(checkpoint_body, relative: relative) unless finalized
+      end
+      summary
+    end
+
+    # 每次发送配置前后发布检查点；失败由执行器停止后续写入。
+    def write_execution(state)
+      publish("execution.json", JSON.pretty_generate(state) + "\n")
+    end
+
+    # 恢复写入或删除受阻时，调用方须把退出码及此状态作为未确认诊断。
+    def recovery_failed? = @recovery_failed == true
+
+    # 新建目录的名字属于父目录；文件 fsync 不能替代这条持久化链。
+    def prepare_directory(path)
+      missing, parent = [], path
+      until File.directory?(parent)
+        missing << parent
+        parent = File.dirname(parent)
+      end
+      FileUtils.mkdir_p(path, mode: 0o700)
+      missing.reverse_each do |created|
+        parent = File.dirname(created)
+        sync_directory(File.symlink?(parent) ? File.realpath(parent) : parent)
+      end
+    end
+
+    # 批次创建与文件发布共享目录同步边界，失败直接交还宿主停止执行。
+    def sync_directory(path)
+      File.open(path, File::RDONLY | File::NOFOLLOW) { |parent| parent.fsync }
+    end
+
+    # 新一次收尾失败时，旧成功摘要不再代表当前状态；安全检查点继续保留。
+    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)))
+        discard_summary(relative: relative) if saved["status"] == "complete"
+      end
+    rescue Errno::ENOENT
+      nil
+    rescue SystemCallError, JSON::ParserError, Interrupt
+      @recovery_failed = true
+    end
+
+    # 屏蔽恢复中的次级取消，始终把最先观察到的发布失败或取消交还调用方。
+    def restore_checkpoint(body, relative: "summary.json")
+      relative = checked_relative(relative)
+      Thread.handle_interrupt(Exception => :never) do
+        begin
+          publish(relative, body)
+        rescue Error, Interrupt => error
+          @recovery_failed = true
+          discard_summary(relative: relative) unless error.is_a?(Error) && error.committed?
+        end
+      end
+    rescue Interrupt
+      @recovery_failed = true
+    end
+
+    # 存储拒绝恢复时尽力移除不可信摘要，不删除已获得的设备事实。
+    def discard_summary(relative: "summary.json")
+      relative = checked_relative(relative)
+      File.unlink(File.join(directory, relative))
+    rescue Errno::ENOENT
+      nil
+    rescue SystemCallError
+      @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)
+      target = File.join(directory, relative)
+      phase, committed = :temporary_file, false
+      Tempfile.create([ ".ctx-runner-", ".tmp" ], File.dirname(target)) do |file|
+        file.chmod(0o600)
+        phase = :write
+        file.write(body)
+        phase = :file_sync
+        file.flush
+        file.fsync
+        phase = :rename
+        File.rename(file.path, target)
+        committed = true
+        phase = :directory_sync
+        sync_directory(File.dirname(target))
+        phase = :cleanup
+      end
+    rescue SystemCallError, IOError, NotImplementedError
+      raise @error_class.new(relative: relative, phase: phase, committed: committed), cause: nil
+    end
+    private
+
+    # 发布、恢复与删除使用同一条路径契约；拒绝路径时不能执行收尾副作用。
+    def checked_relative(relative)
+      unless relative.is_a?(String) && !relative.empty? && !relative.start_with?("/") &&
+          relative.split("/", -1).none? { |part| [ "", ".", ".." ].include?(part) } && !relative.include?("\0")
+        raise ArgumentError, "Report path must remain inside the batch"
+      end
+      relative.dup.freeze
+    end
+  end
+end

data/lib/ctx_runner/version.rb

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

data/lib/ctx_runner.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "ctx_runner/version"
+require_relative "ctx_runner/observation"
+require_relative "ctx_runner/collection"
+require_relative "ctx_runner/query"
+require_relative "ctx_runner/batch"
+require_relative "ctx_runner/report"
+require_relative "ctx_runner/fingerprint"
+require_relative "ctx_runner/execution"

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: ctx_runner
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gatework contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ctx_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.6
+  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
+- !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.5
+  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.5
+- !ruby/object:Gem::Dependency
+  name: digest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: time
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tempfile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fileutils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Shared collection, evidence publication and controlled change workflows
+  with explicit ownership and failure evidence.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/superpowers/plans/2026-10-21-runner.md
+- docs/verification-2026-10-22.md
+- examples/execution.rb
+- examples/report.rb
+- lib/ctx_runner.rb
+- lib/ctx_runner/batch.rb
+- lib/ctx_runner/collection.rb
+- lib/ctx_runner/execution.rb
+- lib/ctx_runner/fingerprint.rb
+- lib/ctx_runner/observation.rb
+- lib/ctx_runner/query.rb
+- lib/ctx_runner/report.rb
+- lib/ctx_runner/version.rb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.6
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Run evidence collection and controlled network changes.
+test_files: []