ctx_runner 0.2.2 → 0.4.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 +4 -4
- data/CHANGELOG.md +10 -0
- data/README.md +3 -1
- data/docs/contracts-2026-10-29.md +84 -0
- data/docs/module-boundaries.md +12 -10
- data/docs/verification-2026-10-29.md +76 -0
- data/lib/ctx_runner/batch.rb +2 -2
- data/lib/ctx_runner/collection.rb +3 -4
- data/lib/ctx_runner/document.rb +5 -3
- data/lib/ctx_runner/evidence.rb +64 -5
- data/lib/ctx_runner/execution.rb +5 -2
- data/lib/ctx_runner/observation.rb +17 -4
- data/lib/ctx_runner/query.rb +2 -1
- data/lib/ctx_runner/report.rb +2 -1
- data/lib/ctx_runner/snapshot.rb +66 -0
- data/lib/ctx_runner/target.rb +25 -0
- data/lib/ctx_runner/version.rb +1 -1
- data/lib/ctx_runner.rb +1 -0
- metadata +21 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 4961379c70c9dd72c7ac0afad79008648adaaa0caff7baef893a1ad7f4d8d26e
|
|
4
|
+
data.tar.gz: 54a11d9c82858210d79756cd16745b1dd49ee28bb1aa3b1d9b1354a8d069c646
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: e3111872018d2149b79f4541da771290fb70e21d1593593ed03fb9e899f463d0272238b100fd204aba8f250d8a260d11353bc73136c83d07f826d2ce72d34005
|
|
7
|
+
data.tar.gz: 64895489cdc3616f7946dd01795d9c44fd236fcac82053a3b6269b8a73fdff1ddf70e658cdadd307d17b5ac3a3bbcbbf0cca74e289062c1320e20f7b932a5e37
|
data/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.4.0 (2026-10-29)
|
|
6
|
+
|
|
7
|
+
- Add composed Snapshot and public Target contracts, independent collection status, and typed UTC times. Empty requests remain not_requested.
|
|
8
|
+
- Share observation scopes and acquisition times, requiring evidence for not_applicable. Preserve unfinished callback failures when cleanup also fails.
|
|
9
|
+
- Version collection, batch, change plan, review and execution documents with schema 3 and explicit kinds; reject older reports and plans.
|
|
10
|
+
|
|
11
|
+
## 0.3.0 (2026-10-29)
|
|
12
|
+
|
|
13
|
+
- Remove `Collection.new(strict:)`: provider contract failures consistently return structured diagnostics without replay and preserve the first failure. Batch consumers now expose `snapshot.observations`.
|
|
14
|
+
|
|
5
15
|
## 0.2.2 (2026-10-25)
|
|
6
16
|
|
|
7
17
|
- Share a single session delivery scope between collection and controlled execution; reject swallowed delivery violations, unfinished operations and cross-thread callbacks without replaying device actions.
|
data/README.md
CHANGED
|
@@ -38,7 +38,7 @@ end
|
|
|
38
38
|
|
|
39
39
|
领域 Profile 实现 `parse_many(names, body, complete:, command:)`;不可用投影接收 `(name, capture, failure)`。一次 Query 对应一条命令,多个视图共享同一份 Capture。
|
|
40
40
|
|
|
41
|
-
`Collection.new
|
|
41
|
+
`Collection.new` 统一记录 session_not_opened/session_reentered,保留首次失败且不重放;strict: 参数已移除。批次快照统一提供 observations Ruby 成员,文档统一使用 observations,采集结论独立为 collection_status,不再生成 :collection 伪观测。交付块未正常完成但异常被连接器吞掉时记录 session_incomplete;跨线程交付记录 session_out_of_scope,并拒绝执行领域块。连接关闭错误不会覆盖已完成的领域事实或先前交付故障。借用会话直接使用 Reader/Query,无需再进入 Collection。
|
|
42
42
|
|
|
43
43
|
Collection 与 Execution 共用 `SessionScope`。会话必须由创建流程的线程同步交付;并行调度应在每个设备任务内部创建流程。重复交付的异常即使被提供方吞掉,流程仍不能报告完成;所有者退出后保留的回调立即失效。作用域不持有或关闭会话,连接清理仍由连接器负责。跨模块职责、业务原子边界与领域拆分见 [模块设计](docs/module-boundaries.md)。
|
|
44
44
|
|
|
@@ -68,3 +68,5 @@ ruby script/verify_package.rb pkg/ctx_runner-0.1.0.gem
|
|
|
68
68
|
默认 rake 运行 RSpec、RuboCop 和离线示例。CI 沿用 ctx_parser 的 Ruby 4.0.6 / Linux、macOS 矩阵和固定 action 提交。源码联调在消费仓库显式设置 `CTX_RUNNER_PATH=../ctx_runner`;普通验证使用已安装依赖。首次发版前须先构建安装 runner 候选包再验证消费包。
|
|
69
69
|
|
|
70
70
|
首个版本为 0.1.0。发布流程复用 CI 制品,验证 GitHub Release 与 RubyGems 下载字节。
|
|
71
|
+
|
|
72
|
+
模块契约、破坏性迁移与版本矩阵见 [契约迁移](docs/contracts-2026-10-29.md)。
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# 九模块契约与迁移
|
|
2
|
+
|
|
3
|
+
此次改动以实际调用链和既有故障测试为依据。保持九个 gem,不新增公共工具 gem;厂商语法、AP 租约、Fabric 范围及健康规则仍由对应领域维护。
|
|
4
|
+
|
|
5
|
+
## 质量审查结论
|
|
6
|
+
|
|
7
|
+
| 模块 | 主要结论 | 本次处理 |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| expect-pty(仓库 expect-ruby) | IO/PID 所有权、超时、脱敏和回收已有独立边界 | 保留实现,验证 PTY、资源关闭和独立安装 |
|
|
10
|
+
| net-connector | 已有独占会话与 Credentials;消费端 apply 重复凭据逻辑;归档投递可能漏检同一时钟粒度内的源文件覆写 | 复用 Credentials,限定依赖区间;投递后在原描述符上再次核对大小与摘要 |
|
|
11
|
+
| ctx_parser | ScopedResult 在消费端另行定义值语义;命令校验散落多处 | Result 正式包含 covered_scopes;统一 command_text 和严格时刻解析 |
|
|
12
|
+
| ctx_driver | 借用会话、单命令回执边界清晰 | 使用公共命令校验,保留失同步后停止和不重连契约 |
|
|
13
|
+
| ctx_runner | 三个领域的快照聚合与 Batch 不一致;关闭失败可能遮盖被吞掉的回调失败 | 公共 Snapshot/Target,独立 collection_status,保留最初失败 |
|
|
14
|
+
| ctx_cli | 两套 apply 重复校验和、确认、错误处理和执行编排 | 注入领域 adapter 与执行器的 Apply;无 Runner/连接器依赖 |
|
|
15
|
+
| ctx_checker | 严格领域校验有价值,但公共值与时间接口分叉 | 组合公共 Observation/Snapshot,保留身份、字段和覆盖校验 |
|
|
16
|
+
| VXLAN | OSPF 字段与 Checker 同义不同名;快照接收任意身份字段 | 统一公共字段和快照;保留 Fabric/ACL/ChangePlan |
|
|
17
|
+
| Wireless | 未知维度与已知不支持维度混淆;计划缺少统一选择和校验和 | 未知维度报错,已知不支持保留 unsupported;并发收集后稳定汇总具名计划 |
|
|
18
|
+
|
|
19
|
+
完整采集、语法覆盖、领域健康、设备变更效果和报告持久性是不同事实。此次统一接口不把它们合并成单一 success。
|
|
20
|
+
|
|
21
|
+
## 对象契约
|
|
22
|
+
|
|
23
|
+
- `CtxParser::Result` 是深度不可变的 Data 值:`status, records, issues, covered_scopes`。默认 scopes 为 `[]`,参与 `==`、`eql?`、`hash`、`with`、模式匹配和 `to_h`;不再使用 ScopedResult。
|
|
24
|
+
- `CtxParser::Commands.command_text(value)` 接受非空、无控制字符的单行 String,返回独立冻结文本。Profile、Driver、Query 和 Execution 共用该边界。
|
|
25
|
+
- `CtxParser::Values.timestamp(value)` 接受含明确时区的 ISO8601 文本,拒绝日期、时分秒和时区越界,返回 UTC Time。
|
|
26
|
+
- `Observation` 的公共字段为 `name, status, records, issues, evidence, started_at, completed_at, covered_scopes`。采集时间为 Time 或 nil;`observed_at` 从来源 evidence 的时刻得出,不能用报告时间替代。
|
|
27
|
+
- Checker 组合公共 Observation,再约束领域字段、记录身份和 scope;VXLAN/Wireless 保留公开 Observation 类型。不会冻结调用方对象。
|
|
28
|
+
- `Snapshot` 提供 `target, observations, observed_at, issues, collection_status, observation(name), complete?, same_target?, to_h`。领域通过组合声明允许的维度;未知维度或键值名称不一致立即报错。
|
|
29
|
+
- `target` 只允许 `host, platform, name, model, software_version, id`;String/Symbol 键归一为 Symbol,拒绝重复、未知字段和控制字符。host 必须有值;id 可为文本或非负整数。密码、连接选项及任意属性不可进入身份。
|
|
30
|
+
- Snapshot 的 `observed_at` 必须是 Time。Ruby `to_h` 保留类型;JSON 必须经 `CtxRunner::Document.call`,统一为 UTC ISO8601(六位小数)。
|
|
31
|
+
|
|
32
|
+
Observation 状态包括 complete、partial、failed、unsupported、not_requested、not_applicable。不可用状态不能带 records;not_applicable 必须携带来源证据。
|
|
33
|
+
|
|
34
|
+
| 所请求的观测 | collection_status |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
| 无请求或全部 not_requested,且无采集错误 | not_requested |
|
|
37
|
+
| 有请求,但既无可用事实,也无有证据的不适用结论 | failed |
|
|
38
|
+
| 全部 complete 或有证据的 not_applicable,且无采集错误 | complete |
|
|
39
|
+
| 部分事实、部分失败或已取得事实后关闭失败 | partial |
|
|
40
|
+
|
|
41
|
+
不再创建 `observations[:collection]`。Batch 从 `snapshot.collection_status` 取结论;`snapshot.issues` 保存会话层诊断。Batch 摘要的 `dimensions` 是按维度计数的摘要,并非 Snapshot 字段别名。
|
|
42
|
+
|
|
43
|
+
VXLAN OSPF 使用 `process_id, vrf, router_id, neighbor_address, interface, state, neighbor_role`;state 为 Symbol(如 `:full`、`:two_way`),角色独立为 `:dr/:bdr/:drother/:unknown`。原有 priority 和 uptime 继续保留。厂商命令文件名与解析入口不变。
|
|
44
|
+
|
|
45
|
+
## 文件格式与 apply
|
|
46
|
+
|
|
47
|
+
两个领域 CLI 的新报告/计划使用 `schema_version: 3` 和明确的 `kind`:collection、batch、recommendations、review、fabric_review、change_plan、change、execution。离线 review/apply 拒绝旧版本;请重新采集、重新生成计划,不用字段猜测或手工只改版本号。
|
|
48
|
+
|
|
49
|
+
collection 的 snapshot 使用 `observations` 和独立 `collection_status`。读取端同时核对身份、维度、时间、状态及聚合结论,领域记录交由领域 adapter 验证。
|
|
50
|
+
|
|
51
|
+
两个领域都输出 `plan.json`,结构为 `kind: change_plan, platform, changes: { ID => change }`。每项 change 绑定设备、完整配置指纹、类型化增量及重新生成的 commands/rollback;相邻的 `plan.json.sha256` 绑定文件内容。checksum 只检测内容变化,不是签名或授权。
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
vxlan apply --plan plan.json --item CHANGE_ID
|
|
55
|
+
wireless apply --plan plan.json --item CHANGE_ID
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
必须显式选一项;终端确认绑定 host、计划摘要和 item。确认后经 Credentials 解析平台优先/通用回退凭据,再创建执行日志、回读前置配置、逐条记账和回读验收。失败后不重放、不自动回退、不保存 startup 配置。执行成功仍需要业务验收。
|
|
59
|
+
|
|
60
|
+
`CtxCli::Apply` 的 adapter 提供 `select_plan(document, item:)`、`validate_plan(plan)`、`credentials(options)`、`report(options)`、`with_session(device, settings)`。注入的 execution 实现 `run`、`started?`、`journal_failed?`。CLI 不解释厂商命令或业务健康。
|
|
61
|
+
|
|
62
|
+
## 版本及验证入口
|
|
63
|
+
|
|
64
|
+
| gem | 候选版本 | Ruby 下限 |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| expect-pty | 0.9.6(实现未改) | 3.4 |
|
|
67
|
+
| net-connector | 0.20.0 | 3.4 |
|
|
68
|
+
| ctx_cli | 0.4.0 | 3.4 |
|
|
69
|
+
| ctx_parser / ctx_driver / ctx_runner | 0.4.0 | 4.0.6 |
|
|
70
|
+
| ctx_checker | 0.5.0 | 4.0.6 |
|
|
71
|
+
| vxlan | 0.7.0 | 4.0.6 |
|
|
72
|
+
| wireless-rb | 0.8.0 | 4.0.6 |
|
|
73
|
+
|
|
74
|
+
依赖按支持的下一个 minor 设上界。使用 RVM 安装和选择运行时,例如 `rvm install ruby-4.0.6`、`rvm use ruby-4.0.6`;3.4 库另用 3.4 分支验证。
|
|
75
|
+
|
|
76
|
+
每个仓库先运行自己的 Bundler 检查;跨仓库源码联调与普通安装分别验证。工作区目录名须与下列脚本声明一致:
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
ruby ctx_runner/script/verify_stack.rb /absolute/workspace /absolute/artifacts
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
脚本构建九个候选,校验全部依赖边,将运行依赖缓存和候选装进临时 GEM_HOME,禁止源码路径进入消费环境,执行三个领域的 Batch/schema 往返、离线示例、普通 CLI 和真实 PTY,再通过最小 Bundler 消费方重复验证。manifest.json 记录源提交、候选版本与 SHA256。未提交改动以候选包摘要确定内容,不将基线提交冒充最终源码提交。
|
|
83
|
+
|
|
84
|
+
单机离线测试不等于 macOS 或网络设备型号验证;未实际运行的环境不列为通过。
|
data/docs/module-boundaries.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 网络模块的业务边界与原子操作
|
|
2
2
|
|
|
3
|
-
本设计覆盖 ctx_parser、ctx_driver、ctx_runner、ctx_cli、ctx_checker、net-connector、expect-pty、VXLAN 和 Wireless
|
|
3
|
+
本设计覆盖 ctx_parser、ctx_driver、ctx_runner、ctx_cli、ctx_checker、net-connector、expect-pty、VXLAN 和 Wireless。目录 `expect-ruby` 对应 gem expect-pty,`wireless-rb` 对应 Ruby 命名空间 Wireless。相邻 worktree 可能包含不同工作,不能当作同一版本。
|
|
4
4
|
|
|
5
5
|
## 业务链路与依赖
|
|
6
6
|
|
|
@@ -26,7 +26,7 @@ flowchart TD
|
|
|
26
26
|
| ctx_driver | 校验单条查询、执行回执、正文和原始摘要分离 | Reader、Capture、可选 Session 适配 | 借用会话;首次失同步后停止后续命令 |
|
|
27
27
|
| ctx_parser | 文本来源、命令声明、共享视图、事实快照 | Commands、Profile、Result、Immutable | 不持有连接或宿主状态 |
|
|
28
28
|
| ctx_runner | 唯一会话交付、单查询、批量结果、证据发布和已确认变更 | SessionScope、Collection、Query、Batch、Report、Execution | 借用会话;报告对象拥有自己的文件 |
|
|
29
|
-
| ctx_cli | 来源配置、输入预算、静态预览、预检顺序、交互和退出码 | Configuration、Collection、Review、Output | 借用标准流;调度任务须由宿主回收 |
|
|
29
|
+
| ctx_cli | 来源配置、输入预算、静态预览、预检顺序、交互和退出码 | Configuration、Collection、Review、Apply、Output | 借用标准流;调度任务须由宿主回收 |
|
|
30
30
|
| ctx_checker | 配置适用性、有限发现、观测关联、健康和计数策略 | Collector、Applicability、Snapshot、Evaluator | 借用连接器;规则独立于传输 |
|
|
31
31
|
| VXLAN | 配置依赖、Fabric 范围、服务身份、ACL 和类型化增量 | CollectionPlan、Collector、Fabric::Review、ChangePlan | 领域连接适配器取得操作租约 |
|
|
32
32
|
| Wireless | 控制器查询、AP 身份和选择、邻居覆盖、模板增量 | Collector、ApCollection、ApSession、Projection、ChangePlan | ApCollection 借用控制器;ApSession 管理转接租约 |
|
|
@@ -64,13 +64,13 @@ stateDiagram-v2
|
|
|
64
64
|
|
|
65
65
|
交付失败状态保留到流程结束,即使连接器 rescue 了回调异常,也不能恢复为完成。作用域结束后的回调直接抛出 IOError,且不修改已经发布的结果。
|
|
66
66
|
|
|
67
|
-
| 事实 | Collection
|
|
68
|
-
| --- | --- | --- |
|
|
69
|
-
| 没有交付 | session_not_opened |
|
|
70
|
-
| 重复交付 | session_reentered;保留首次事实 |
|
|
71
|
-
| 交付块未完成但异常被提供方吞掉 | session_incomplete |
|
|
72
|
-
| 跨线程交付 | session_out_of_scope;不调用领域块 |
|
|
73
|
-
| 关闭连接失败 | session_close_failed;保留已完成事实和先前交付故障 |
|
|
67
|
+
| 事实 | Collection | Execution |
|
|
68
|
+
| --- | --- | --- |
|
|
69
|
+
| 没有交付 | session_not_opened | failed;不发命令 |
|
|
70
|
+
| 重复交付 | session_reentered;保留首次事实 | 已发送则 uncertain;不重放 |
|
|
71
|
+
| 交付块未完成但异常被提供方吞掉 | session_incomplete,关闭失败不覆盖它 | failed/uncertain,取决于是否开始发送 |
|
|
72
|
+
| 跨线程交付 | session_out_of_scope;不调用领域块 | failed;不发命令 |
|
|
73
|
+
| 关闭连接失败 | session_close_failed;保留已完成事实和先前交付故障 | 不发布 configuration_verified |
|
|
74
74
|
|
|
75
75
|
线程池应在每个设备任务内部创建 Collection/Execution 并同步打开、使用、关闭该设备的会话。并行发生在设备任务之间,不能将已借出的会话回调移交给后台线程。
|
|
76
76
|
|
|
@@ -80,7 +80,7 @@ stateDiagram-v2
|
|
|
80
80
|
|
|
81
81
|
ApCollection 负责 AP 选择、缺失名称、覆盖范围、回执归属及逐 AP 失败隔离;`ApSession` 继续负责登录/返回控制器和嵌套操作租约。厂商 Profile 和 NeighborParser 继续维护命令及语法。公共 Runner 不承担 AP、型号、Fabric 或健康策略。
|
|
82
82
|
|
|
83
|
-
|
|
83
|
+
`Wireless::Collector#collect` 使用公共身份白名单和快照,返回结构按 schema 3 迁移。新的领域对象可以单独使用,但必须显式提供 `Wireless::Observation(name: :access_points)`;选择范围在回调前快照,非法输入在访问凭据前拒绝。
|
|
84
84
|
|
|
85
85
|
## 本次落地与验证边界
|
|
86
86
|
|
|
@@ -92,3 +92,5 @@ ApCollection 负责 AP 选择、缺失名称、覆盖范围、回执归属及逐
|
|
|
92
92
|
后续改动仍应以具体业务不变量为依据:发现策略留在 ctx_checker,配置依赖留在 VXLAN,AP 选择和租约留在 Wireless;不要因类名相似而合并这些策略,也不要新增统一工作流 DSL。对底层资源所有权的修改必须覆盖取消、关闭失败和已完成设备效果的保留。
|
|
93
93
|
|
|
94
94
|
本次验证结果、环境限制与复现证据见 [2026-10-25 验证记录](verification-2026-10-25.md)。
|
|
95
|
+
|
|
96
|
+
2026-10-29 的值对象、快照、apply 和文件格式契约见 [契约迁移](contracts-2026-10-29.md)。
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# 九模块契约改造验证记录
|
|
2
|
+
|
|
3
|
+
日期:2026-10-29。环境:Linux x86_64;运行时均由 RVM 安装。工作区为 `/root/gatework-contracts-20261029`,各仓库开发分支为 `contracts/unify`。本记录描述发布前的本地验证;远端 CI 和发布结果以对应版本标签及 GitHub Release 为准。
|
|
4
|
+
|
|
5
|
+
契约、职责和迁移说明见 [contracts-2026-10-29.md](contracts-2026-10-29.md)。本记录区分源码测试、独立安装与尚未运行的外部环境。
|
|
6
|
+
|
|
7
|
+
## 运行时
|
|
8
|
+
|
|
9
|
+
- Ruby 4.0.6,revision `03b6d3f889`:九模块完整检查。
|
|
10
|
+
- Ruby 3.4.12,revision `366f5fdc00`:最低 Ruby 版本为 3.4 的 ctx_cli、expect-pty、net-connector。
|
|
11
|
+
- Bundler 4.0.16;各仓库分别使用自己的 Gemfile 和已解析依赖。跨仓库源码联调另使用工作区 Gemfile,不能替代独立安装。
|
|
12
|
+
- 此环境的 RVM 选择命令使用完整名称,例如 `rvm use ruby-4.0.6`,避免旧版 RVM 对裸 `4.0.6` 的识别问题。
|
|
13
|
+
|
|
14
|
+
## 源码与工具检查
|
|
15
|
+
|
|
16
|
+
用例数为 RSpec examples 或 Minitest runs;Ruby 3.4 的重复运行不计入 Ruby 4 总数。
|
|
17
|
+
|
|
18
|
+
| 仓库 | Ruby 4.0.6 用例 | Ruby 3.4.12 用例 | 其他检查 |
|
|
19
|
+
| --- | ---: | ---: | --- |
|
|
20
|
+
| expect-ruby | 634 | 634 | lint、API/RBS;4.0.6 完整 script/ci、示例、七组 smoke benchmark |
|
|
21
|
+
| net-connector | 1284 | 1284 | lint、行/分支覆盖率门槛;4.0.6 源码/历史/包扫描、actionlint、benchmark、隔离包 |
|
|
22
|
+
| ctx_cli | 36 | 36 | lint、离线示例、rake build |
|
|
23
|
+
| ctx_parser | 140 | 不适用 | lint、离线示例、rake build |
|
|
24
|
+
| ctx_driver | 49 | 不适用 | lint、离线及真实 PTY 示例、rake build |
|
|
25
|
+
| ctx_runner | 78 | 不适用 | lint、离线示例、rake build |
|
|
26
|
+
| ctx_checker | 704 | 不适用 | lint、离线及真实 PTY 示例、rake build |
|
|
27
|
+
| vxlan | 482 | 不适用 | lint、离线示例、普通 CLI、rake build |
|
|
28
|
+
| wireless-rb | 340 | 不适用 | lint、离线示例、普通 CLI、rake build |
|
|
29
|
+
|
|
30
|
+
Ruby 4.0.6 共 3,747 个用例通过;Ruby 3.4.12 的三个库共 1,954 个用例通过。Parser/Driver/Runner/Checker/VXLAN/Wireless 的声明下限为 Ruby 4.0.6,不将它们列为 Ruby 3.4 已支持。
|
|
31
|
+
|
|
32
|
+
net-connector 的完整检查曾因环境缺少 GNU time 停在 benchmark;安装系统 time 后,续跑 `rake benchmark:smoke package:verify` 通过。测试、扫描和 lint 在此前已通过,分步日志共同构成完整结果。Ruby 3.4 只声明实际运行的 `bundle exec rake` 及其覆盖率检查,不将 Ruby 4 的包检查冒充为 Ruby 3.4 包检查。
|
|
33
|
+
|
|
34
|
+
原生 PTY 用例使用本地模拟设备,经过真实 expect-pty 和连接器;子进程使用 `--disable-gems`,避免把不需要的 Bundler 启动纳入两秒登录时限。没有访问网络设备。
|
|
35
|
+
|
|
36
|
+
## 独立安装
|
|
37
|
+
|
|
38
|
+
七个 ctx/领域仓库各自的 `script/verify_package.rb` 均通过,显式提供未发布依赖候选。Expect 和连接器的隔离安装由各自 CI/package 任务完成。
|
|
39
|
+
|
|
40
|
+
VXLAN/Wireless 另验证无连接器安装时的离线解析、review、帮助和计划输出,再安装连接器验证配置初始化、权限、清单预览与错误出口。安装过程不使用相邻源码目录;CLI 候选逐文件校验一致。
|
|
41
|
+
|
|
42
|
+
统一验证入口为:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
rvm use ruby-4.0.6
|
|
46
|
+
ruby ctx_runner/script/verify_stack.rb /root/gatework-contracts-20261029 /root/gatework-contracts-20261029/.artifacts
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
脚本从九个 checkout 构建候选,检查全部运行依赖约束,在临时 GEM_HOME 进行普通安装和最小 Bundler 安装。两种消费方式均检查精确候选版本、来源路径、三个领域共用 Batch、schema 3 往返、离线示例、普通 CLI 和真实 PTY。运行依赖来自已解析的本地 gem 缓存;候选不能被线上旧版替换。
|
|
50
|
+
|
|
51
|
+
最终包及 SHA256 记录在工作区 `.artifacts/manifest.json`,最终整体验证日志为 `.validation/stack-install-final.log`。manifest 中的 revision 是各仓库基线 HEAD;未提交的最终内容由候选包摘要确定。
|
|
52
|
+
|
|
53
|
+
## 重点回归
|
|
54
|
+
|
|
55
|
+
- Result 的 covered_scopes 参与 Data 值相等、hash、with 与模式匹配;不再由 ScopedResult 绕开值协议。
|
|
56
|
+
- Snapshot 对空请求、全部不可用、部分事实、关闭失败及有证据的不适用分别聚合;移除伪造的 collection 观测。
|
|
57
|
+
- Target 白名单、不可变输入、严格时刻与 schema 校验拒绝旧格式、未知身份字段、伪造的聚合结论及越界日期。
|
|
58
|
+
- 被连接器吞掉的回调失败不会被后续关闭失败覆盖;取消、重复回调、持久化失败和执行后记账失败仍保留既有事实。
|
|
59
|
+
- 共用 Apply 验证具名项和文件摘要,从领域增量重新生成命令;取消不连接、不重放、凭据空值回退及平台 enable password 均有消费端回归。
|
|
60
|
+
- 无线并发报告完整汇总、稳定排序;同一配置的模板计划共享指纹;新的报告重新计算指纹。
|
|
61
|
+
- Wireless 独立 review 缺失维度注册表 require 的问题由子进程回归复现,补齐显式加载后通过;不能依赖先加载根入口。
|
|
62
|
+
- net-connector 既有归档测试在基线上复现同一时钟粒度内覆写漏检;投递后在原描述符上复核摘要,完整测试通过。该修复增加一次有界读取,不声称零成本或对外部并发写入提供事务锁。
|
|
63
|
+
|
|
64
|
+
## 日志与范围
|
|
65
|
+
|
|
66
|
+
工作区 `.validation/` 保留原始日志:
|
|
67
|
+
|
|
68
|
+
- `*-locked-rake.log`:各仓库独立 Bundler 检查;VXLAN/Wireless 的最终结果使用 `*-final-rake.log`。
|
|
69
|
+
- `*-ruby34-rake.log`:Ruby 3.4 三库检查。
|
|
70
|
+
- `expect-ci.log`、`connector-ci.log`、`connector-package.log`:底层两库完整检查步骤。
|
|
71
|
+
- `*-build.log`、`*-package.log`、`stack-install-final.log`:构建、逐包安装和最终候选组合验证。
|
|
72
|
+
- `connector-baseline-mutation.log`、`wireless-review-loading-regression.log`:修复前的回归复现,保留失败输出以便追溯。
|
|
73
|
+
|
|
74
|
+
Wireless review(100/500/1000 模板)和 VXLAN fabric(100/1000/3000 组)基准的功能断言通过;本机共享负载下不据此宣称性能提升。
|
|
75
|
+
|
|
76
|
+
本地未运行 macOS、真实交换机/无线控制器、外部 SSH 或 PostgreSQL 联机矩阵。本次变更包含破坏性接口与 schema 3 迁移,旧报告及计划必须重新生成。本地验证不能替代发布标签对应的 CI 与制品读回校验。
|
data/lib/ctx_runner/batch.rb
CHANGED
|
@@ -87,10 +87,10 @@ module CtxRunner
|
|
|
87
87
|
snapshot = nil
|
|
88
88
|
begin
|
|
89
89
|
snapshot = yield
|
|
90
|
-
dimensions = snapshot.
|
|
90
|
+
dimensions = snapshot.observations.transform_values do |value|
|
|
91
91
|
{ status: value.status, records: value.records.size, issues: value.issues.map { |issue| issue[:code] }.uniq }
|
|
92
92
|
end
|
|
93
|
-
result = { device: device, status: snapshot.
|
|
93
|
+
result = { device: device, status: snapshot.collection_status, dimensions: dimensions }
|
|
94
94
|
rescue StandardError => error
|
|
95
95
|
result = { device: device, status: :failed, error: CtxDriver::Failure.code(error, :collection_failed), dimensions: {} }
|
|
96
96
|
end
|
|
@@ -8,9 +8,8 @@ module CtxRunner
|
|
|
8
8
|
class Collection
|
|
9
9
|
attr_reader :failure, :stage
|
|
10
10
|
|
|
11
|
-
def initialize
|
|
12
|
-
|
|
13
|
-
@strict, @used = strict, false
|
|
11
|
+
def initialize
|
|
12
|
+
@used = false
|
|
14
13
|
@stage = :connect
|
|
15
14
|
end
|
|
16
15
|
|
|
@@ -46,6 +45,7 @@ module CtxRunner
|
|
|
46
45
|
contract_failure(scope.failure) if scope.failure
|
|
47
46
|
rescue StandardError => error
|
|
48
47
|
raise unless CtxDriver::Failure.connection_error?(error, connector)
|
|
48
|
+
contract_failure(scope.failure) if scope&.failure && stage != :connect
|
|
49
49
|
details = CtxDriver::Failure.details(error, fallback: :connection_failed, stage: stage)
|
|
50
50
|
@failure ||= (stage == :close ? details.merge(code: :session_close_failed) : details).freeze
|
|
51
51
|
ensure
|
|
@@ -53,7 +53,6 @@ module CtxRunner
|
|
|
53
53
|
end
|
|
54
54
|
|
|
55
55
|
def contract_failure(code)
|
|
56
|
-
raise ArgumentError, "Connector must provide one session" if @strict
|
|
57
56
|
@failure ||= { code: code, stage: stage }.freeze
|
|
58
57
|
end
|
|
59
58
|
end
|
data/lib/ctx_runner/document.rb
CHANGED
|
@@ -6,6 +6,8 @@ module CtxRunner
|
|
|
6
6
|
# 显式证据边界:生成独立 JSON 值,不通过文本往返转换业务事实。
|
|
7
7
|
module Document
|
|
8
8
|
MAX_DEPTH = 128
|
|
9
|
+
# 组合值对象显式加入文档协议;不对任意外部对象调用 to_h。
|
|
10
|
+
module Value; end
|
|
9
11
|
|
|
10
12
|
def self.call(value)
|
|
11
13
|
convert(value, {}.compare_by_identity, 0)
|
|
@@ -14,12 +16,12 @@ module CtxRunner
|
|
|
14
16
|
def self.convert(value, active, depth)
|
|
15
17
|
raise ArgumentError, "Document nesting exceeds the evidence budget" if depth > MAX_DEPTH
|
|
16
18
|
case value
|
|
17
|
-
when Hash, Array, Data
|
|
19
|
+
when Hash, Array, Data, Value
|
|
18
20
|
raise ArgumentError, "Document must not contain cyclic data" if active[value]
|
|
19
21
|
active[value] = true
|
|
20
22
|
begin
|
|
21
23
|
case value
|
|
22
|
-
when Data then convert(value.to_h, active, depth + 1)
|
|
24
|
+
when Data, Value then convert(value.to_h, active, depth + 1)
|
|
23
25
|
when Array then value.map { |item| convert(item, active, depth + 1) }.freeze
|
|
24
26
|
when Hash
|
|
25
27
|
value.each_with_object({}) do |(key, item), result|
|
|
@@ -36,7 +38,7 @@ module CtxRunner
|
|
|
36
38
|
ensure
|
|
37
39
|
active.delete(value)
|
|
38
40
|
end
|
|
39
|
-
when Time then value.iso8601(6).freeze
|
|
41
|
+
when Time then value.getutc.iso8601(6).freeze
|
|
40
42
|
when String then value.dup.freeze
|
|
41
43
|
when Symbol then value.name
|
|
42
44
|
when Rational, Complex then value.to_s.freeze
|
data/lib/ctx_runner/evidence.rb
CHANGED
|
@@ -1,30 +1,89 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require "ipaddr"
|
|
4
|
+
require_relative "document"
|
|
5
|
+
require_relative "target"
|
|
6
|
+
require_relative "observation"
|
|
7
|
+
require_relative "snapshot"
|
|
4
8
|
|
|
5
9
|
module CtxRunner
|
|
6
10
|
# 离线证据的公共外壳;记录字段和领域语义交给消费模块校验。
|
|
7
11
|
module Evidence
|
|
8
|
-
|
|
12
|
+
VERSION = 3
|
|
13
|
+
KINDS = %w[collection batch change_plan change execution review recommendations fabric_review].freeze
|
|
14
|
+
|
|
15
|
+
def self.wrap(value, kind:)
|
|
16
|
+
raise ArgumentError, "Unknown evidence kind" unless KINDS.include?(kind)
|
|
17
|
+
Document.call(value).merge("schema_version" => VERSION, "kind" => kind.dup.freeze).freeze
|
|
18
|
+
end
|
|
19
|
+
|
|
20
|
+
# 旧报告和计划必须重新生成;拒绝以默认值猜测版本。
|
|
21
|
+
def self.validate_version!(document, kind:)
|
|
22
|
+
unless document.is_a?(Hash) && document["schema_version"] == VERSION && document["kind"] == kind
|
|
23
|
+
raise ArgumentError, "Unsupported evidence format; regenerate reports and plans with schema version #{VERSION}"
|
|
24
|
+
end
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
def self.plan(document, item:, platform:)
|
|
28
|
+
validate_version!(document, kind: "change_plan")
|
|
29
|
+
unless document["platform"] == platform && document["changes"].is_a?(Hash) && item.is_a?(String) &&
|
|
30
|
+
item.match?(/\A[A-Za-z0-9_.-]+\z/) && document["changes"].key?(item)
|
|
31
|
+
raise ArgumentError, "A supported plan and explicit --item are required"
|
|
32
|
+
end
|
|
33
|
+
selected = document["changes"].fetch(item)
|
|
34
|
+
validate_version!(selected, kind: "change")
|
|
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)
|
|
38
|
+
unless !host.include?("/") && IPAddr.new(host).to_s == host &&
|
|
39
|
+
selected["expected_config_sha256"].is_a?(String) && selected["expected_config_sha256"].match?(/\A[0-9a-f]{64}\z/)
|
|
40
|
+
raise ArgumentError, "Invalid change target or configuration fingerprint"
|
|
41
|
+
end
|
|
42
|
+
Document.call(selected)
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
def self.validate(document, names:)
|
|
46
|
+
validate_version!(document, kind: "collection")
|
|
9
47
|
unless document.is_a?(Hash) && document["device"].is_a?(Hash) &&
|
|
10
48
|
%w[name host].all? { |key| document["device"][key].is_a?(String) && !document["device"][key].empty? }
|
|
11
49
|
raise ArgumentError, "Device identity is missing"
|
|
12
50
|
end
|
|
13
51
|
host = document["device"]["host"]
|
|
52
|
+
Target.snapshot(document["device"])
|
|
14
53
|
raise ArgumentError, "Target address must be a canonical host address" unless !host.include?("/") && IPAddr.new(host).to_s == host
|
|
15
54
|
snapshot = document.fetch("snapshot")
|
|
16
55
|
return if snapshot.nil?
|
|
17
|
-
|
|
56
|
+
unless snapshot.is_a?(Hash) && snapshot["observations"].is_a?(Hash) &&
|
|
57
|
+
%w[complete partial failed not_requested].include?(snapshot["collection_status"])
|
|
58
|
+
raise ArgumentError, "Invalid snapshot structure"
|
|
59
|
+
end
|
|
18
60
|
if !snapshot["target"].is_a?(Hash) || snapshot["target"]["host"] != host
|
|
19
61
|
raise ArgumentError, "Device identity does not match the collection target"
|
|
20
62
|
end
|
|
21
|
-
snapshot["
|
|
22
|
-
|
|
63
|
+
identity = Target.snapshot(snapshot["target"])
|
|
64
|
+
%w[platform id].each do |field|
|
|
65
|
+
if document["device"].key?(field) && snapshot["target"].key?(field) && document["device"][field] != snapshot["target"][field]
|
|
66
|
+
raise ArgumentError, "Device identity does not match the collection target"
|
|
67
|
+
end
|
|
68
|
+
end
|
|
69
|
+
observations = snapshot["observations"].to_h do |dimension, observation|
|
|
70
|
+
unless names.map(&:to_s).include?(dimension) && observation.is_a?(Hash) &&
|
|
71
|
+
Observation::STATUSES.map(&:to_s).include?(observation["status"]) && observation["name"] == dimension
|
|
23
72
|
raise ArgumentError, "Invalid observation structure"
|
|
24
73
|
end
|
|
25
74
|
records = array(observation.fetch("records"))
|
|
26
|
-
|
|
75
|
+
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) },
|
|
77
|
+
covered_scopes: array(observation.fetch("covered_scopes", [])),
|
|
78
|
+
started_at: observation["started_at"] && CtxParser::Values.timestamp(observation["started_at"]),
|
|
79
|
+
completed_at: observation["completed_at"] && CtxParser::Values.timestamp(observation["completed_at"]))
|
|
27
80
|
records.each { |record| yield(record, dimension) }
|
|
81
|
+
[ dimension.to_sym, value ]
|
|
82
|
+
end
|
|
83
|
+
value = Snapshot.new(target: identity, observations: observations, names: names,
|
|
84
|
+
observed_at: CtxParser::Values.timestamp(snapshot.fetch("observed_at")), issues: array(snapshot.fetch("issues", [])))
|
|
85
|
+
unless value.collection_status.to_s == snapshot["collection_status"]
|
|
86
|
+
raise ArgumentError, "Collection status differs from its evidence"
|
|
28
87
|
end
|
|
29
88
|
end
|
|
30
89
|
|
data/lib/ctx_runner/execution.rb
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require "ctx_parser/immutable"
|
|
4
|
+
require "ctx_parser/commands"
|
|
4
5
|
require "ctx_driver/failure"
|
|
5
6
|
require_relative "fingerprint"
|
|
6
7
|
require_relative "session_scope"
|
|
8
|
+
require_relative "evidence"
|
|
7
9
|
|
|
8
10
|
module CtxRunner
|
|
9
11
|
# 只执行已确认的单项领域变更;日志、设备效果与配置验收分别记账。
|
|
@@ -19,11 +21,12 @@ module CtxRunner
|
|
|
19
21
|
raise ArgumentError, "Execution requires a typed change and journal"
|
|
20
22
|
end
|
|
21
23
|
@commands = CtxParser::Immutable.copy(change.commands)
|
|
22
|
-
unless @commands.is_a?(Array) && @commands.any?
|
|
24
|
+
unless @commands.is_a?(Array) && @commands.any?
|
|
23
25
|
raise ArgumentError, "Change commands must be individual lines"
|
|
24
26
|
end
|
|
27
|
+
@commands.each { |command| CtxParser::Commands.command_text(command) }
|
|
25
28
|
@change, @journal = change, journal
|
|
26
|
-
@state = { "status" => "confirmed", "device" => @plan["device"], "plan_sha256" => plan_sha256.dup.freeze,
|
|
29
|
+
@state = { "schema_version" => Evidence::VERSION, "kind" => "execution", "status" => "confirmed", "device" => @plan["device"], "plan_sha256" => plan_sha256.dup.freeze,
|
|
27
30
|
"expected_config_sha256" => @plan["expected_config_sha256"], "commands" => @commands, "steps" => [] }
|
|
28
31
|
@state["plan_item"] = CtxParser::Immutable.copy(item) if item
|
|
29
32
|
@started = @used = @journal_failed = false
|
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require "ctx_parser/immutable"
|
|
4
|
+
require "ctx_parser/values"
|
|
5
|
+
require "time"
|
|
4
6
|
|
|
5
7
|
module CtxRunner
|
|
6
8
|
# 不可变的事实外壳;领域可继承外壳或复用校验,记录身份和业务字段仍由领域负责。
|
|
7
|
-
class Observation < Data.define(:name, :status, :records, :issues, :evidence, :started_at, :completed_at)
|
|
8
|
-
STATUSES = %i[complete partial failed unsupported not_requested].freeze
|
|
9
|
+
class Observation < Data.define(:name, :status, :records, :issues, :evidence, :started_at, :completed_at, :covered_scopes)
|
|
10
|
+
STATUSES = %i[complete partial failed unsupported not_requested not_applicable].freeze
|
|
9
11
|
|
|
10
12
|
def self.validate(name:, status:, records:, issues:, evidence:, statuses: STATUSES)
|
|
11
13
|
raise ArgumentError, "Observation name must be a symbol" unless name.is_a?(Symbol)
|
|
@@ -18,19 +20,30 @@ module CtxRunner
|
|
|
18
20
|
end
|
|
19
21
|
end
|
|
20
22
|
|
|
21
|
-
def initialize(name:, status:, records: [], issues: [], evidence: [], started_at: nil, completed_at: nil)
|
|
23
|
+
def initialize(name:, status:, records: [], issues: [], evidence: [], started_at: nil, completed_at: nil, covered_scopes: [])
|
|
22
24
|
self.class.validate(name: name, status: status, records: records, issues: issues, evidence: evidence)
|
|
23
25
|
unless [ started_at, completed_at ].all? { |time| time.nil? || time.is_a?(Time) }
|
|
24
26
|
raise ArgumentError, "Observation timestamps must be Time values or nil"
|
|
25
27
|
end
|
|
28
|
+
unless covered_scopes.is_a?(Array) && covered_scopes.all? { |scope| scope.is_a?(Hash) } && covered_scopes.uniq == covered_scopes &&
|
|
29
|
+
(covered_scopes.empty? || %i[complete partial].include?(status))
|
|
30
|
+
raise ArgumentError, "Covered scopes require available observations and unique hashes"
|
|
31
|
+
end
|
|
32
|
+
if status == :not_applicable && evidence.empty?
|
|
33
|
+
raise ArgumentError, "Not applicable observations require evidence"
|
|
34
|
+
end
|
|
35
|
+
@observed_at = evidence.filter_map { |entry| CtxParser::Values.timestamp(entry[:observed_at]) if entry.key?(:observed_at) }.max
|
|
26
36
|
super(name: name, status: status, records: CtxParser::Immutable.copy(records),
|
|
27
37
|
issues: CtxParser::Immutable.copy(issues), evidence: CtxParser::Immutable.copy(evidence),
|
|
28
|
-
started_at: started_at&.
|
|
38
|
+
started_at: started_at&.getutc&.freeze, completed_at: completed_at&.getutc&.freeze,
|
|
39
|
+
covered_scopes: CtxParser::Immutable.copy(covered_scopes))
|
|
29
40
|
end
|
|
30
41
|
|
|
31
42
|
def complete? = status == :complete
|
|
32
43
|
def partial? = status == :partial
|
|
33
44
|
def available? = complete? || partial?
|
|
45
|
+
# 来源采样时间不由较晚的快照或报告时间替代。
|
|
46
|
+
attr_reader :observed_at
|
|
34
47
|
def inspect = "#<#{self.class.name} name=#{name} status=#{status} records=#{records.size}>"
|
|
35
48
|
alias to_s inspect
|
|
36
49
|
def pretty_print(printer) = printer.text(inspect)
|
data/lib/ctx_runner/query.rb
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require "ctx_parser/immutable"
|
|
4
|
+
require "ctx_parser/commands"
|
|
4
5
|
require "ctx_driver/failure"
|
|
5
6
|
|
|
6
7
|
module CtxRunner
|
|
@@ -16,7 +17,7 @@ module CtxRunner
|
|
|
16
17
|
raise ArgumentError, "Query views must be unique symbols"
|
|
17
18
|
end
|
|
18
19
|
names = CtxParser::Immutable.copy(names)
|
|
19
|
-
command = CtxParser::
|
|
20
|
+
command = CtxParser::Commands.command_text(command)
|
|
20
21
|
capture = @reader.read(command)
|
|
21
22
|
failure = capture.failure
|
|
22
23
|
if capture.success?
|
data/lib/ctx_runner/report.rb
CHANGED
|
@@ -5,6 +5,7 @@ require "time"
|
|
|
5
5
|
require "tempfile"
|
|
6
6
|
require "fileutils"
|
|
7
7
|
require_relative "document"
|
|
8
|
+
require_relative "evidence"
|
|
8
9
|
|
|
9
10
|
module CtxRunner
|
|
10
11
|
# 持有私有证据批次,统一检查点、发布和失败恢复;领域只提供展示内容。
|
|
@@ -65,7 +66,7 @@ module CtxRunner
|
|
|
65
66
|
summary[:report_error] = report_error if report_error
|
|
66
67
|
summary[:execution_error] = execution_error if execution_error
|
|
67
68
|
summary[:output_error] = output_error if output_error
|
|
68
|
-
summary =
|
|
69
|
+
summary = Evidence.wrap(summary, kind: "batch")
|
|
69
70
|
# 检查点共享已固定的证据;不重复转换,也不重新读取调用方对象。
|
|
70
71
|
checkpoint = summary.merge("status" => interrupted ? "interrupted" : "incomplete",
|
|
71
72
|
"report_error" => summary["report_error"] || "report_finalization_unconfirmed").freeze
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative "target"
|
|
4
|
+
require_relative "observation"
|
|
5
|
+
require_relative "document"
|
|
6
|
+
|
|
7
|
+
module CtxRunner
|
|
8
|
+
# 领域组合公共快照;采集结论与领域健康、报告持久性分别表达。
|
|
9
|
+
class Snapshot
|
|
10
|
+
include Document::Value
|
|
11
|
+
attr_reader :target, :observations, :observed_at, :issues, :collection_status
|
|
12
|
+
|
|
13
|
+
def initialize(target:, observations:, observed_at:, names:, issues: [])
|
|
14
|
+
unless names.is_a?(Array) && names.all? { |name| name.is_a?(Symbol) } && names.uniq == names
|
|
15
|
+
raise ArgumentError, "Snapshot dimensions must be unique symbols"
|
|
16
|
+
end
|
|
17
|
+
unless observations.is_a?(Hash) && observations.all? do |name, value|
|
|
18
|
+
names.include?(name) && %i[name status records issues evidence covered_scopes started_at completed_at complete? to_h].all? { |method| value.respond_to?(method) } && value.name == name && Observation::STATUSES.include?(value.status) && value.frozen?
|
|
19
|
+
end
|
|
20
|
+
raise ArgumentError, "Snapshot observations must match declared dimensions"
|
|
21
|
+
end
|
|
22
|
+
raise ArgumentError, "Snapshot time must be a Time" unless observed_at.is_a?(Time)
|
|
23
|
+
unless issues.is_a?(Array) && issues.all? { |issue| issue.is_a?(Hash) }
|
|
24
|
+
raise ArgumentError, "Snapshot issues must be hashes"
|
|
25
|
+
end
|
|
26
|
+
@target = Target.snapshot(target)
|
|
27
|
+
@names = names.dup.freeze
|
|
28
|
+
@observations = observations.to_h { |name, value| [ name, value ] }.freeze
|
|
29
|
+
@observed_at = observed_at.getutc.freeze
|
|
30
|
+
@issues = CtxParser::Immutable.copy(issues)
|
|
31
|
+
@collection_status = aggregate
|
|
32
|
+
freeze
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
def observation(name)
|
|
36
|
+
raise ArgumentError, "Unknown observation dimension" unless @names.include?(name)
|
|
37
|
+
observations.fetch(name) { Observation.new(name: name, status: :not_requested) }
|
|
38
|
+
end
|
|
39
|
+
|
|
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] }
|
|
42
|
+
|
|
43
|
+
def to_h
|
|
44
|
+
{ target: target, observations: observations.transform_values(&:to_h), observed_at: observed_at,
|
|
45
|
+
issues: issues, collection_status: collection_status }
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
def inspect = "#<#{self.class.name} collection_status=#{collection_status}>"
|
|
49
|
+
alias to_s inspect
|
|
50
|
+
def pretty_print(printer) = printer.text(inspect)
|
|
51
|
+
|
|
52
|
+
private
|
|
53
|
+
|
|
54
|
+
# 不适用必须已有来源证据;空请求不通过 all? 被提升为完整。
|
|
55
|
+
def aggregate
|
|
56
|
+
selected = observations.values.reject { |observation| observation.status == :not_requested }
|
|
57
|
+
return issues.empty? ? :not_requested : :failed if selected.empty?
|
|
58
|
+
conclusive = selected.select do |observation|
|
|
59
|
+
%i[complete partial].include?(observation.status) || observation.status == :not_applicable && observation.evidence.any?
|
|
60
|
+
end
|
|
61
|
+
return :failed if conclusive.empty?
|
|
62
|
+
return :complete if issues.empty? && conclusive.size == selected.size && selected.none? { |observation| observation.status == :partial }
|
|
63
|
+
:partial
|
|
64
|
+
end
|
|
65
|
+
end
|
|
66
|
+
end
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "ctx_parser/immutable"
|
|
4
|
+
|
|
5
|
+
module CtxRunner
|
|
6
|
+
# 设备身份与连接设置分离;边界只接受公开字段,Ruby 内部统一符号键。
|
|
7
|
+
module Target
|
|
8
|
+
FIELDS = %i[host platform name model software_version id].freeze
|
|
9
|
+
|
|
10
|
+
def self.snapshot(value)
|
|
11
|
+
raise ArgumentError, "Target must be a mapping of public identity fields" unless value.is_a?(Hash)
|
|
12
|
+
result = value.each_with_object({}) do |(key, entry), target|
|
|
13
|
+
unless (key.is_a?(String) || key.is_a?(Symbol)) && FIELDS.include?(key.to_sym) && !target.key?(key.to_sym)
|
|
14
|
+
raise ArgumentError, "Target contains unknown or duplicate identity fields"
|
|
15
|
+
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
|
+
target[key.to_sym] = entry
|
|
20
|
+
end
|
|
21
|
+
raise ArgumentError, "Target requires a host" unless result[:host].is_a?(String)
|
|
22
|
+
CtxParser::Immutable.copy(result)
|
|
23
|
+
end
|
|
24
|
+
end
|
|
25
|
+
end
|
data/lib/ctx_runner/version.rb
CHANGED
data/lib/ctx_runner.rb
CHANGED
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
|
+
version: 0.4.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Gatework contributors
|
|
@@ -15,28 +15,40 @@ dependencies:
|
|
|
15
15
|
requirements:
|
|
16
16
|
- - ">="
|
|
17
17
|
- !ruby/object:Gem::Version
|
|
18
|
-
version:
|
|
18
|
+
version: 0.4.0
|
|
19
|
+
- - "<"
|
|
20
|
+
- !ruby/object:Gem::Version
|
|
21
|
+
version: '0.5'
|
|
19
22
|
type: :runtime
|
|
20
23
|
prerelease: false
|
|
21
24
|
version_requirements: !ruby/object:Gem::Requirement
|
|
22
25
|
requirements:
|
|
23
26
|
- - ">="
|
|
24
27
|
- !ruby/object:Gem::Version
|
|
25
|
-
version:
|
|
28
|
+
version: 0.4.0
|
|
29
|
+
- - "<"
|
|
30
|
+
- !ruby/object:Gem::Version
|
|
31
|
+
version: '0.5'
|
|
26
32
|
- !ruby/object:Gem::Dependency
|
|
27
33
|
name: ctx_driver
|
|
28
34
|
requirement: !ruby/object:Gem::Requirement
|
|
29
35
|
requirements:
|
|
30
36
|
- - ">="
|
|
31
37
|
- !ruby/object:Gem::Version
|
|
32
|
-
version:
|
|
38
|
+
version: 0.4.0
|
|
39
|
+
- - "<"
|
|
40
|
+
- !ruby/object:Gem::Version
|
|
41
|
+
version: '0.5'
|
|
33
42
|
type: :runtime
|
|
34
43
|
prerelease: false
|
|
35
44
|
version_requirements: !ruby/object:Gem::Requirement
|
|
36
45
|
requirements:
|
|
37
46
|
- - ">="
|
|
38
47
|
- !ruby/object:Gem::Version
|
|
39
|
-
version:
|
|
48
|
+
version: 0.4.0
|
|
49
|
+
- - "<"
|
|
50
|
+
- !ruby/object:Gem::Version
|
|
51
|
+
version: '0.5'
|
|
40
52
|
- !ruby/object:Gem::Dependency
|
|
41
53
|
name: digest
|
|
42
54
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -130,12 +142,14 @@ files:
|
|
|
130
142
|
- CHANGELOG.md
|
|
131
143
|
- LICENSE
|
|
132
144
|
- README.md
|
|
145
|
+
- docs/contracts-2026-10-29.md
|
|
133
146
|
- docs/module-boundaries.md
|
|
134
147
|
- docs/superpowers/plans/2026-10-21-runner.md
|
|
135
148
|
- docs/superpowers/plans/2026-10-23-report-documents.md
|
|
136
149
|
- docs/superpowers/specs/2026-10-23-report-documents.md
|
|
137
150
|
- docs/verification-2026-10-22.md
|
|
138
151
|
- docs/verification-2026-10-25.md
|
|
152
|
+
- docs/verification-2026-10-29.md
|
|
139
153
|
- examples/execution.rb
|
|
140
154
|
- examples/report.rb
|
|
141
155
|
- lib/ctx_runner.rb
|
|
@@ -149,6 +163,8 @@ files:
|
|
|
149
163
|
- lib/ctx_runner/query.rb
|
|
150
164
|
- lib/ctx_runner/report.rb
|
|
151
165
|
- lib/ctx_runner/session_scope.rb
|
|
166
|
+
- lib/ctx_runner/snapshot.rb
|
|
167
|
+
- lib/ctx_runner/target.rb
|
|
152
168
|
- lib/ctx_runner/version.rb
|
|
153
169
|
licenses:
|
|
154
170
|
- MIT
|