ctx_runner 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4961379c70c9dd72c7ac0afad79008648adaaa0caff7baef893a1ad7f4d8d26e
4
- data.tar.gz: 54a11d9c82858210d79756cd16745b1dd49ee28bb1aa3b1d9b1354a8d069c646
3
+ metadata.gz: 309468f8b97d51e31739cf478abc3af96885ba53453366837c1b7dba56518a9f
4
+ data.tar.gz: 80edf1ff1d91b7de2f5cd3618346e55d1761f4c5a3940ecd2bb4eaa5af8287f6
5
5
  SHA512:
6
- metadata.gz: e3111872018d2149b79f4541da771290fb70e21d1593593ed03fb9e899f463d0272238b100fd204aba8f250d8a260d11353bc73136c83d07f826d2ce72d34005
7
- data.tar.gz: 64895489cdc3616f7946dd01795d9c44fd236fcac82053a3b6269b8a73fdff1ddf70e658cdadd307d17b5ac3a3bbcbbf0cca74e289062c1320e20f7b932a5e37
6
+ metadata.gz: 72f558b4857909003298d7593574a2c913face19002e9afd980a832fc69572e3a88fa603358b9ac434a019267dc022ae93a9cc89b8736fbe68fbd964757bf048
7
+ data.tar.gz: 762d6e943fc55eeba9f4989098bb23804233590d3f743445782506330146d02f689b1be8b0cb0ada2ba235b5c632a4d9051a24e174f1e6c6b89dfba146a4a223
data/CHANGELOG.md CHANGED
@@ -2,6 +2,10 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.5.0 (2026-10-30)
6
+
7
+ - Adopt immutable `Target` identity values and typed observation sources; share `records(name)` and configuration session behavior. Schema 4 uses `target`, validates aggregate status and full identity, and rejects empty applicability proof. Reject duplicate/unrequested batch work and mismatched returned snapshots. Align fingerprint depth with Document.
8
+
5
9
  ## 0.4.0 (2026-10-29)
6
10
 
7
11
  - Add composed Snapshot and public Target contracts, independent collection status, and typed UTC times. Empty requests remain not_requested.
data/README.md CHANGED
@@ -70,3 +70,7 @@ ruby script/verify_package.rb pkg/ctx_runner-0.1.0.gem
70
70
  首个版本为 0.1.0。发布流程复用 CI 制品,验证 GitHub Release 与 RubyGems 下载字节。
71
71
 
72
72
  模块契约、破坏性迁移与版本矩阵见 [契约迁移](docs/contracts-2026-10-29.md)。
73
+
74
+ ## Domain contract migration (2026-10-30)
75
+
76
+ Adopt immutable `Target` identity values and typed observation sources; share `records(name)` and configuration session behavior. Schema 4 uses `target`, validates aggregate status and full identity, and rejects empty applicability proof. Reject duplicate/unrequested batch work and mismatched returned snapshots. Align fingerprint depth with Document. See the [schema 4 migration and module contracts](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-30.md). Regenerate old collection reports and change plans; changing only their version number is not supported.
@@ -1,5 +1,7 @@
1
1
  # 九模块契约与迁移
2
2
 
3
+ > Historical schema 3 review. Current contracts and migration: [2026-10-30](contracts-2026-10-30.md).
4
+
3
5
  此次改动以实际调用链和既有故障测试为依据。保持九个 gem,不新增公共工具 gem;厂商语法、AP 租约、Fabric 范围及健康规则仍由对应领域维护。
4
6
 
5
7
  ## 质量审查结论
@@ -0,0 +1,58 @@
1
+ # 领域契约与 schema 4 迁移
2
+
3
+ 本轮一次性切换公共接口,不保留旧字段别名。旧报告、变更计划必须重新采集或生成;仅把 schema_version 改为 4 无法补足身份、来源和聚合证据。
4
+
5
+ ## 模块职责
6
+
7
+ | 模块 | 拥有的领域责任 | 不承担的责任 |
8
+ | --- | --- | --- |
9
+ | expect-pty | PTY、IO、进程、匹配与终端恢复 | 设备健康、业务策略 |
10
+ | net-connector | 会话、登录、操作租约、资产与库存、邻居发现 | 公共观察结论和领域配置验收 |
11
+ | ctx_parser | 纯值、解析完整性、命令声明、语法注册 | 连接与报告交付 |
12
+ | ctx_driver | 单命令回执、来源摘要、借用会话读写 | 重连、健康判断、厂商配置策略 |
13
+ | ctx_runner | Target、Observation、Snapshot、采集交付、配置会话、受控执行 | 厂商语法、资产持久化 |
14
+ | ctx_checker | 运行事实、维度身份、健康与覆盖规则 | 配置下发 |
15
+ | vxlan | NX-OS、Fabric、配置依赖、可验证变更 | PTY 和公共交付状态机 |
16
+ | wireless-rb | AP/Radio/客户端、模板、AP 转接、无线变更 | 公共报告持久性与终端确认 |
17
+ | ctx_cli | 配置发现、用户输入输出、宿主入口编排 | 领域身份、采集完整性、网络会话 |
18
+
19
+ ## 公共 Ruby 协议
20
+
21
+ - `Target.coerce(hash)` 接受明确的公开字段,内部使用 Symbol 键;`host` 必填,其他字段为 `platform/name/model/software_version/id`。对象深度不可变,支持 `with`、相等性、Hash 键和模式匹配。`same_identity?` 只比较 host/platform/id;显示名变化不改变身份。平台由领域 Registry 归一化,采集前拒绝目标与连接平台冲突。
22
+ - `Snapshot#target` 返回 Target;`to_h` 投影为普通数据。三个领域都提供 `observations`、`observation(name)`、`records(name)`、`collection_status`、`same_target?`。
23
+ - `Observation#evidence` 返回 `CtxDriver::Source` 数组。Source 的核心字段为 command、sha256、bytes、reference、observed_at、status、context;摘要和非负字节数必须同时存在。空 Hash 或仅有时间的来源无效,`not_applicable` 至少需要一份带摘要的来源。
24
+ - Source 属性 observed_at 是 UTC Time,`to_h` 将它输出为 ISO8601;领域附加属性放在 context。来源的摘要取自原始输出,不是解析后的正文。时间读取失败不得丢弃已经取得的摘要。
25
+ - Checker Observation 继承公共不可变值语义,但每次 `new`/`with` 都重新执行领域字段、身份和状态校验。
26
+ - `ConfigurationSession` 借用会话,接受领域注入的准备命令、配置查询和解析器。准备、写入和读取都验证单命令回执;失败不自动重放、不关闭借用会话。领域保留操作租约和前后配置验收。
27
+ - 变更对象提供 `to_h`、`commands`、`rollback`、`eligible?`、`satisfied?`;工厂提供 `build`、`candidate`。无线配置索引只构建一次,重复模板名仍是歧义,不能选第一条执行。
28
+
29
+ ## 序列化与字段切换
30
+
31
+ | 旧接口 | 新接口 |
32
+ | --- | --- |
33
+ | 报告/计划/执行的 device | target |
34
+ | Hash 形式 snapshot.target | Target 值对象,序列化后仍是映射 |
35
+ | 任意 Hash 来源附加字段 | Source.context |
36
+ | neighbor_name / neighbor_interface / chassis_id | remote_name / remote_interface / remote_chassis_id |
37
+ | CDP interface | local_interface |
38
+ | BGP peer / peer_ip | peer_address |
39
+ | VXLAN BGP address_family: L2VPN EVPN | afi_safi: l2vpn_evpn |
40
+ | prefixes_received | received_prefixes |
41
+ | BGP 字符串状态 | Symbol 状态,管理关闭为 :shutdown |
42
+ | AP 原始状态文本 | :online / :offline / :unknown |
43
+ | channel_width / utilization | channel_width_mhz / utilization_percent |
44
+ | 无线报告平台 h3c_wireless | h3c |
45
+
46
+ 厂商 CLI 原文和命令名称不改写。Netdisco 的 vendor、连接器凭据命名空间仍保留 h3c_wireless;无线 CLI 在领域平台边界进行映射。Netdisco 资产 Device 仍是资产对象。
47
+
48
+ schema 4 集合报告的顶层 status 必须与快照实际聚合结果一致;target 与 snapshot.target 的 host/platform/id 必须一致。无快照只能报告 failed。计划的目标平台必须匹配计划平台。Batch 在执行前拒绝重复和未请求目标,返回快照身份不符时不发布其事实。
49
+
50
+ 纯数据和 JSON 使用 128 层深度预算;Fingerprint 不再受 JSON 默认 100 层限制。对象循环、键归一化碰撞和非有限数字仍被拒绝。
51
+
52
+ ## 升级与验证
53
+
54
+ 候选版本:ctx_cli/ctx_driver/ctx_runner 0.5.0,ctx_checker 0.6.0,net-connector 0.21.0,vxlan 0.8.0,wireless-rb 0.9.0。ctx_parser 继续 0.4.0,expect-pty 继续 0.9.6;没有为了统一命名而改动其稳定执行内核。
55
+
56
+ 按 ctx_cli → ctx_driver → ctx_runner → 消费模块更新依赖;net-connector 0.21 依赖 ctx_cli 0.5。Parser 继续使用 0.4 系列。锁文件必须同步,避免把源码联调误当成已安装依赖兼容。
57
+
58
+ 使用 RVM Ruby 4.0.6 执行各仓库 `bundle exec rake`。`script/verify_stack.rb WORKSPACE OUTPUT` 构建九个候选,在临时 GEM_HOME 验证依赖、普通入口、领域 Batch/schema 往返、本地 PTY 和最小 Bundler 消费方。无线 `benchmark/review.rb` 测完整审查序列化,`benchmark/configuration_index.rb` 测候选索引;合成性能不代表实机吞吐或型号认证。
@@ -22,7 +22,7 @@ end
22
22
 
23
23
  Dir.mktmpdir do |root|
24
24
  report = CtxRunner::Report.new(File.join(root, "execution"))
25
- plan = { "device" => { "host" => "192.0.2.1" }, "expected_config_sha256" => CtxRunner::Fingerprint.call("mode" => "disabled") }
25
+ plan = { "target" => { "host" => "192.0.2.1" }, "expected_config_sha256" => CtxRunner::Fingerprint.call("mode" => "disabled") }
26
26
  execution = CtxRunner::Execution.new(plan: plan, change: ExampleChange.new, journal: report, plan_sha256: "a" * 64)
27
27
  result = execution.run { |operation| operation.call(ExampleSession.new) }
28
28
  raise "Unverified configuration" unless result["status"] == "configuration_verified"
data/examples/report.rb CHANGED
@@ -8,7 +8,7 @@ Dir.mktmpdir do |root|
8
8
  report = CtxRunner::Report.new(File.join(root, "reports"))
9
9
  report.publish("evidence.json", JSON.generate(source: "synthetic", records: []))
10
10
  device = { "host" => "192.0.2.1", "name" => "example" }
11
- summary = report.finish([ { device: device, status: :complete, report_saved: true } ], requested: [ device ]) do |value|
11
+ summary = report.finish([ { target: device, status: :complete, report_saved: true } ], requested: [ device ]) do |value|
12
12
  "Evidence: #{value.fetch('status')}; health was not evaluated.\n"
13
13
  end
14
14
  raise "Report incomplete" unless summary.fetch("status") == "complete"
@@ -3,6 +3,7 @@
3
3
  require "ctx_parser/immutable"
4
4
  require "ctx_driver/failure"
5
5
  require_relative "document"
6
+ require_relative "target"
6
7
 
7
8
  module CtxRunner
8
9
  # 批量采集的交付账本;调度器负责并发与回收,领域块只返回设备快照。
@@ -73,26 +74,42 @@ module CtxRunner
73
74
  end
74
75
 
75
76
  def initialize(report:, progress:, requested:)
76
- @requested = CtxParser::Immutable.copy(requested)
77
+ raise ArgumentError, "Requested targets must be a list" unless requested.is_a?(Array)
78
+ targets = requested.map { |value| Target.coerce(value) }
79
+ @identities = targets.to_h { |target| [ target.identity_key, true ] }.freeze
80
+ raise ArgumentError, "Duplicate requested target" unless targets.size == @identities.size
81
+ @requested = Document.call(targets)
82
+ @claimed = {}
77
83
  @report, @progress = report, progress
78
84
  @results, @lock = [], Mutex.new
79
85
  end
80
86
 
81
87
  # 先登记设备事实,再保存报告;报告失败仍可在最终摘要中定位未交付结果。
82
88
  def collect(device)
83
- raise ArgumentError, "Batch is closed" if @closed
84
- device = CtxParser::Immutable.copy(device)
89
+ identity = Target.coerce(device)
90
+ device = Document.call(identity)
91
+ @lock.synchronize do
92
+ raise ArgumentError, "Batch is closed" if @closed
93
+ unless @identities.key?(identity.identity_key) && !@claimed.key?(identity.identity_key)
94
+ raise ArgumentError, "Target must be requested exactly once"
95
+ end
96
+ @claimed[identity.identity_key] = true
97
+ end
85
98
  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
86
99
  @progress.start(device)
87
100
  snapshot = nil
88
101
  begin
89
102
  snapshot = yield
103
+ unless snapshot.respond_to?(:target) && identity.same_identity?(snapshot.target)
104
+ snapshot = nil
105
+ raise ArgumentError, "Snapshot identity differs from the requested target"
106
+ end
90
107
  dimensions = snapshot.observations.transform_values do |value|
91
108
  { status: value.status, records: value.records.size, issues: value.issues.map { |issue| issue[:code] }.uniq }
92
109
  end
93
- result = { device: device, status: snapshot.collection_status, dimensions: dimensions }
110
+ result = { target: device, status: snapshot.collection_status, dimensions: dimensions }
94
111
  rescue StandardError => error
95
- result = { device: device, status: :failed, error: CtxDriver::Failure.code(error, :collection_failed), dimensions: {} }
112
+ result = { target: device, status: :failed, error: CtxDriver::Failure.code(error, :collection_failed), dimensions: {} }
96
113
  end
97
114
  result[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
98
115
  result[:report_saved] = false
@@ -105,7 +122,7 @@ module CtxRunner
105
122
  end
106
123
 
107
124
  def results
108
- @lock.synchronize { CtxParser::Immutable.copy(@results).sort_by { |result| result[:device].fetch("host") }.freeze }
125
+ @lock.synchronize { CtxParser::Immutable.copy(@results).sort_by { |result| result[:target].fetch("host") }.freeze }
109
126
  end
110
127
 
111
128
  # 调度器回收后调用;输出诊断只补写报告,绝不重新执行设备操作。
@@ -0,0 +1,43 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ctx_driver"
4
+ require "ctx_driver/receipt"
5
+ require "ctx_parser/commands"
6
+ require_relative "document"
7
+
8
+ module CtxRunner
9
+ # 借用领域已取得租约的会话;查询策略和配置解析器由领域显式注入。
10
+ class ConfigurationSession
11
+ def initialize(session:, preparation_commands:, configuration_command:, parser:, clock: -> { Time.now.utc })
12
+ unless preparation_commands.is_a?(Array) && parser.respond_to?(:parse) && session.respond_to?(:write_command)
13
+ raise ArgumentError, "Configuration session requires a writer and parser"
14
+ end
15
+ @preparation = preparation_commands.map { |command| CtxParser::Commands.command_text(command) }.freeze
16
+ @command = CtxParser::Commands.command_text(configuration_command)
17
+ @session, @parser = session, parser
18
+ @reader = CtxDriver::Reader.new(session: session, clock: clock)
19
+ end
20
+
21
+ def read_configuration
22
+ @preparation.each { |command| write(command) }
23
+ capture = @reader.read(@command)
24
+ raise IOError, "Configuration readback failed" unless capture.success?
25
+ observation = @parser.parse(capture.body, complete: true)
26
+ unless observation.complete? && observation.records.one?
27
+ raise ArgumentError, "Configuration evidence is incomplete"
28
+ end
29
+ Document.call(observation.records.first)
30
+ end
31
+
32
+ def write(command)
33
+ command = CtxParser::Commands.command_text(command).strip
34
+ receipt = @session.write_command(command)
35
+ raise IOError, "Device command is unconfirmed" unless CtxDriver::Receipt.validate(receipt, command: command)
36
+ true
37
+ end
38
+
39
+ def inspect = "#<#{self.class.name}>"
40
+ alias to_s inspect
41
+ def pretty_print(printer) = printer.text(inspect)
42
+ end
43
+ end
@@ -9,7 +9,7 @@ require_relative "snapshot"
9
9
  module CtxRunner
10
10
  # 离线证据的公共外壳;记录字段和领域语义交给消费模块校验。
11
11
  module Evidence
12
- VERSION = 3
12
+ VERSION = 4
13
13
  KINDS = %w[collection batch change_plan change execution review recommendations fabric_review].freeze
14
14
 
15
15
  def self.wrap(value, kind:)
@@ -33,8 +33,9 @@ module CtxRunner
33
33
  selected = document["changes"].fetch(item)
34
34
  validate_version!(selected, kind: "change")
35
35
  raise ArgumentError, "Change platform differs from its plan" unless selected["platform"] == platform
36
- identity = Target.snapshot(selected.fetch("device"))
37
- host = identity.fetch(:host)
36
+ identity = Target.coerce(selected.fetch("target"))
37
+ raise ArgumentError, "Change target platform differs from its plan" unless identity.platform == platform
38
+ host = identity.host
38
39
  unless !host.include?("/") && IPAddr.new(host).to_s == host &&
39
40
  selected["expected_config_sha256"].is_a?(String) && selected["expected_config_sha256"].match?(/\A[0-9a-f]{64}\z/)
40
41
  raise ArgumentError, "Invalid change target or configuration fingerprint"
@@ -44,15 +45,18 @@ module CtxRunner
44
45
 
45
46
  def self.validate(document, names:)
46
47
  validate_version!(document, kind: "collection")
47
- unless document.is_a?(Hash) && document["device"].is_a?(Hash) &&
48
- %w[name host].all? { |key| document["device"][key].is_a?(String) && !document["device"][key].empty? }
48
+ unless document.is_a?(Hash) && document["target"].is_a?(Hash) &&
49
+ %w[name host].all? { |key| document["target"][key].is_a?(String) && !document["target"][key].empty? }
49
50
  raise ArgumentError, "Device identity is missing"
50
51
  end
51
- host = document["device"]["host"]
52
- Target.snapshot(document["device"])
52
+ host = document["target"]["host"]
53
+ Target.coerce(document["target"])
53
54
  raise ArgumentError, "Target address must be a canonical host address" unless !host.include?("/") && IPAddr.new(host).to_s == host
54
55
  snapshot = document.fetch("snapshot")
55
- return if snapshot.nil?
56
+ if snapshot.nil?
57
+ raise ArgumentError, "Missing snapshots cannot claim successful collection" unless document["status"] == "failed"
58
+ return
59
+ end
56
60
  unless snapshot.is_a?(Hash) && snapshot["observations"].is_a?(Hash) &&
57
61
  %w[complete partial failed not_requested].include?(snapshot["collection_status"])
58
62
  raise ArgumentError, "Invalid snapshot structure"
@@ -60,9 +64,9 @@ module CtxRunner
60
64
  if !snapshot["target"].is_a?(Hash) || snapshot["target"]["host"] != host
61
65
  raise ArgumentError, "Device identity does not match the collection target"
62
66
  end
63
- identity = Target.snapshot(snapshot["target"])
67
+ identity = Target.coerce(snapshot["target"])
64
68
  %w[platform id].each do |field|
65
- if document["device"].key?(field) && snapshot["target"].key?(field) && document["device"][field] != snapshot["target"][field]
69
+ if document["target"][field] != snapshot["target"][field]
66
70
  raise ArgumentError, "Device identity does not match the collection target"
67
71
  end
68
72
  end
@@ -73,7 +77,7 @@ module CtxRunner
73
77
  end
74
78
  records = array(observation.fetch("records"))
75
79
  value = Observation.new(name: dimension.to_sym, status: observation["status"].to_sym, records: records,
76
- issues: array(observation.fetch("issues", [])), evidence: array(observation.fetch("evidence", [])).map { |entry| entry.transform_keys(&:to_sym) },
80
+ issues: array(observation.fetch("issues", [])), evidence: array(observation.fetch("evidence", [])),
77
81
  covered_scopes: array(observation.fetch("covered_scopes", [])),
78
82
  started_at: observation["started_at"] && CtxParser::Values.timestamp(observation["started_at"]),
79
83
  completed_at: observation["completed_at"] && CtxParser::Values.timestamp(observation["completed_at"]))
@@ -82,7 +86,7 @@ module CtxRunner
82
86
  end
83
87
  value = Snapshot.new(target: identity, observations: observations, names: names,
84
88
  observed_at: CtxParser::Values.timestamp(snapshot.fetch("observed_at")), issues: array(snapshot.fetch("issues", [])))
85
- unless value.collection_status.to_s == snapshot["collection_status"]
89
+ unless value.collection_status.to_s == snapshot["collection_status"] && document["status"] == snapshot["collection_status"]
86
90
  raise ArgumentError, "Collection status differs from its evidence"
87
91
  end
88
92
  end
@@ -13,7 +13,7 @@ module CtxRunner
13
13
  # 领域动作负责有限命令及前后置条件;日志接收独立的不可变检查点。
14
14
  def initialize(plan:, change:, journal:, plan_sha256:, item: nil)
15
15
  @plan = CtxParser::Immutable.copy(plan)
16
- unless @plan.is_a?(Hash) && @plan["device"].is_a?(Hash) &&
16
+ unless @plan.is_a?(Hash) && @plan["target"].is_a?(Hash) &&
17
17
  [ @plan["expected_config_sha256"], plan_sha256 ].all? { |value| value.is_a?(String) && /\A[0-9a-f]{64}\z/.match?(value) }
18
18
  raise ArgumentError, "Execution requires a verified plan and fingerprints"
19
19
  end
@@ -26,7 +26,7 @@ module CtxRunner
26
26
  end
27
27
  @commands.each { |command| CtxParser::Commands.command_text(command) }
28
28
  @change, @journal = change, journal
29
- @state = { "schema_version" => Evidence::VERSION, "kind" => "execution", "status" => "confirmed", "device" => @plan["device"], "plan_sha256" => plan_sha256.dup.freeze,
29
+ @state = { "schema_version" => Evidence::VERSION, "kind" => "execution", "status" => "confirmed", "target" => @plan["target"], "plan_sha256" => plan_sha256.dup.freeze,
30
30
  "expected_config_sha256" => @plan["expected_config_sha256"], "commands" => @commands, "steps" => [] }
31
31
  @state["plan_item"] = CtxParser::Immutable.copy(item) if item
32
32
  @started = @used = @journal_failed = false
@@ -7,7 +7,7 @@ require "ctx_parser/immutable"
7
7
  module CtxRunner
8
8
  # 配置映射顺序不影响身份;列表顺序和全部字段仍参与旧版摘要协议。
9
9
  module Fingerprint
10
- def self.call(value) = Digest::SHA256.hexdigest(JSON.generate(canonical(value)))
10
+ def self.call(value) = Digest::SHA256.hexdigest(JSON.generate(canonical(value), max_nesting: false))
11
11
 
12
12
  # 先拒绝非纯数据与循环,再将键归一化;重名键不能静默覆盖来源事实。
13
13
  def self.canonical(value)
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "ctx_parser/immutable"
4
+ require "ctx_driver/source"
4
5
  require "ctx_parser/values"
5
6
  require "time"
6
7
 
@@ -12,7 +13,7 @@ module CtxRunner
12
13
  def self.validate(name:, status:, records:, issues:, evidence:, statuses: STATUSES)
13
14
  raise ArgumentError, "Observation name must be a symbol" unless name.is_a?(Symbol)
14
15
  raise ArgumentError, "Invalid observation status" unless statuses.include?(status)
15
- unless [ records, issues, evidence ].all? { |entries| entries.is_a?(Array) && entries.all? { |entry| entry.is_a?(Hash) } }
16
+ unless [ records, issues ].all? { |entries| entries.is_a?(Array) && entries.all? { |entry| entry.is_a?(Hash) } }
16
17
  raise ArgumentError, "Observation entries must be arrays of hashes"
17
18
  end
18
19
  if %i[failed unsupported not_requested not_applicable].include?(status) && records.any?
@@ -29,16 +30,20 @@ module CtxRunner
29
30
  (covered_scopes.empty? || %i[complete partial].include?(status))
30
31
  raise ArgumentError, "Covered scopes require available observations and unique hashes"
31
32
  end
32
- if status == :not_applicable && evidence.empty?
33
+ raise ArgumentError, "Evidence must be a list of sources" unless evidence.is_a?(Array)
34
+ evidence = evidence.map { |entry| CtxDriver::Source.coerce(entry) }.freeze
35
+ if status == :not_applicable && !evidence.any?(&:verified?)
33
36
  raise ArgumentError, "Not applicable observations require evidence"
34
37
  end
35
- @observed_at = evidence.filter_map { |entry| CtxParser::Values.timestamp(entry[:observed_at]) if entry.key?(:observed_at) }.max
38
+ @observed_at = evidence.filter_map(&:observed_at).max
36
39
  super(name: name, status: status, records: CtxParser::Immutable.copy(records),
37
- issues: CtxParser::Immutable.copy(issues), evidence: CtxParser::Immutable.copy(evidence),
40
+ issues: CtxParser::Immutable.copy(issues), evidence: evidence,
38
41
  started_at: started_at&.getutc&.freeze, completed_at: completed_at&.getutc&.freeze,
39
42
  covered_scopes: CtxParser::Immutable.copy(covered_scopes))
40
43
  end
41
44
 
45
+ def to_h = super.merge(evidence: evidence.map(&:to_h))
46
+
42
47
  def complete? = status == :complete
43
48
  def partial? = status == :partial
44
49
  def available? = complete? || partial?
@@ -55,9 +55,9 @@ module CtxRunner
55
55
  summary = checkpoint = nil
56
56
  # 转换和编码也属于发布;失败或取消不能让上一轮完成结论继续生效。
57
57
  checkpoint_body = publish_checkpoint("summary.json") do
58
- # 按地址索引一次,避免大批次逐个扫描所有已完成结果。
59
- completed_hosts = results.to_h { |result| [ result.fetch(:device).fetch("host"), true ] }
60
- pending = requested.reject { |device| completed_hosts.key?(device.fetch("host")) }
58
+ # 按完整目标身份索引一次,不让同地址的其他平台或资产替代待采集目标。
59
+ completed_targets = results.to_h { |result| [ Target.coerce(result.fetch(:target)).identity_key, true ] }
60
+ pending = requested.reject { |target| completed_targets.key?(Target.coerce(target).identity_key) }
61
61
  complete = !report_error && !execution_error && !output_error && pending.empty? && results.any? && results.all? { |r| r[:status] == :complete && r[:report_saved] != false }
62
62
  summary = { status: interrupted ? :interrupted : (complete ? :complete : :incomplete),
63
63
  total: [ requested.size, results.size ].max, completed: results.size, pending: pending, counts: results.map { |r| r[:status] }.tally, devices: results,
@@ -23,7 +23,7 @@ module CtxRunner
23
23
  unless issues.is_a?(Array) && issues.all? { |issue| issue.is_a?(Hash) }
24
24
  raise ArgumentError, "Snapshot issues must be hashes"
25
25
  end
26
- @target = Target.snapshot(target)
26
+ @target = Target.coerce(target)
27
27
  @names = names.dup.freeze
28
28
  @observations = observations.to_h { |name, value| [ name, value ] }.freeze
29
29
  @observed_at = observed_at.getutc.freeze
@@ -38,10 +38,11 @@ module CtxRunner
38
38
  end
39
39
 
40
40
  def complete? = collection_status == :complete
41
- def same_target?(other) = other.respond_to?(:target) && %i[host platform id].all? { |key| target[key] == other.target[key] }
41
+ def same_target?(other) = other.respond_to?(:target) && target.same_identity?(other.target)
42
+ def records(name) = observation(name).records
42
43
 
43
44
  def to_h
44
- { target: target, observations: observations.transform_values(&:to_h), observed_at: observed_at,
45
+ { target: target.to_h, observations: observations.transform_values(&:to_h), observed_at: observed_at,
45
46
  issues: issues, collection_status: collection_status }
46
47
  end
47
48
 
@@ -4,22 +4,37 @@ require "ctx_parser/immutable"
4
4
 
5
5
  module CtxRunner
6
6
  # 设备身份与连接设置分离;边界只接受公开字段,Ruby 内部统一符号键。
7
- module Target
7
+ class Target < Data.define(:host, :platform, :name, :model, :software_version, :id)
8
8
  FIELDS = %i[host platform name model software_version id].freeze
9
9
 
10
- def self.snapshot(value)
10
+ def self.coerce(value)
11
+ return value if value.is_a?(self)
11
12
  raise ArgumentError, "Target must be a mapping of public identity fields" unless value.is_a?(Hash)
12
13
  result = value.each_with_object({}) do |(key, entry), target|
13
14
  unless (key.is_a?(String) || key.is_a?(Symbol)) && FIELDS.include?(key.to_sym) && !target.key?(key.to_sym)
14
15
  raise ArgumentError, "Target contains unknown or duplicate identity fields"
15
16
  end
16
- unless entry.nil? || entry.is_a?(String) && !entry.strip.empty? && !/[\x00-\x1f\x7f]/.match?(entry) || key.to_sym == :id && entry.is_a?(Integer) && entry >= 0
17
- raise ArgumentError, "Invalid target identity value"
18
- end
19
17
  target[key.to_sym] = entry
20
18
  end
21
19
  raise ArgumentError, "Target requires a host" unless result[:host].is_a?(String)
22
- CtxParser::Immutable.copy(result)
20
+ new(**result)
21
+ end
22
+
23
+ def initialize(host:, platform: nil, name: nil, model: nil, software_version: nil, id: nil)
24
+ attributes = { host: host, platform: platform, name: name, model: model, software_version: software_version, id: id }
25
+ unless host.is_a?(String) && attributes.all? do |key, value|
26
+ value.nil? || value.is_a?(String) && !value.strip.empty? && !/[\x00-\x1f\x7f]/.match?(value) || key == :id && value.is_a?(Integer) && value >= 0
27
+ end
28
+ raise ArgumentError, "Invalid target identity value"
29
+ end
30
+ super(**CtxParser::Immutable.copy(attributes))
23
31
  end
32
+
33
+ def identity_key = [ host, platform, id ].freeze
34
+ def same_identity?(other) = other.is_a?(Target) && identity_key == other.identity_key
35
+ def to_h = super.compact
36
+ def inspect = "#<#{self.class.name}>"
37
+ alias to_s inspect
38
+ def pretty_print(printer) = printer.text(inspect)
24
39
  end
25
40
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module CtxRunner
4
- VERSION = "0.4.0"
4
+ VERSION = "0.5.0"
5
5
  end
data/lib/ctx_runner.rb CHANGED
@@ -12,3 +12,4 @@ require_relative "ctx_runner/fingerprint"
12
12
  require_relative "ctx_runner/document"
13
13
  require_relative "ctx_runner/evidence"
14
14
  require_relative "ctx_runner/execution"
15
+ require_relative "ctx_runner/configuration_session"
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ctx_runner
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.0
4
+ version: 0.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Gatework contributors
@@ -35,20 +35,20 @@ dependencies:
35
35
  requirements:
36
36
  - - ">="
37
37
  - !ruby/object:Gem::Version
38
- version: 0.4.0
38
+ version: 0.5.0
39
39
  - - "<"
40
40
  - !ruby/object:Gem::Version
41
- version: '0.5'
41
+ version: '0.6'
42
42
  type: :runtime
43
43
  prerelease: false
44
44
  version_requirements: !ruby/object:Gem::Requirement
45
45
  requirements:
46
46
  - - ">="
47
47
  - !ruby/object:Gem::Version
48
- version: 0.4.0
48
+ version: 0.5.0
49
49
  - - "<"
50
50
  - !ruby/object:Gem::Version
51
- version: '0.5'
51
+ version: '0.6'
52
52
  - !ruby/object:Gem::Dependency
53
53
  name: digest
54
54
  requirement: !ruby/object:Gem::Requirement
@@ -143,6 +143,7 @@ files:
143
143
  - LICENSE
144
144
  - README.md
145
145
  - docs/contracts-2026-10-29.md
146
+ - docs/contracts-2026-10-30.md
146
147
  - docs/module-boundaries.md
147
148
  - docs/superpowers/plans/2026-10-21-runner.md
148
149
  - docs/superpowers/plans/2026-10-23-report-documents.md
@@ -155,6 +156,7 @@ files:
155
156
  - lib/ctx_runner.rb
156
157
  - lib/ctx_runner/batch.rb
157
158
  - lib/ctx_runner/collection.rb
159
+ - lib/ctx_runner/configuration_session.rb
158
160
  - lib/ctx_runner/document.rb
159
161
  - lib/ctx_runner/evidence.rb
160
162
  - lib/ctx_runner/execution.rb