ctx_runner 0.1.1 → 0.2.1
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 +11 -0
- data/README.md +7 -0
- data/docs/superpowers/plans/2026-10-23-report-documents.md +67 -0
- data/docs/superpowers/specs/2026-10-23-report-documents.md +25 -0
- data/examples/report.rb +2 -2
- data/lib/ctx_runner/batch.rb +26 -5
- data/lib/ctx_runner/document.rb +10 -5
- data/lib/ctx_runner/evidence.rb +7 -7
- data/lib/ctx_runner/report.rb +55 -43
- data/lib/ctx_runner/version.rb +1 -1
- metadata +7 -17
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 02bf46f3be0d4d50aad62170f51daa8df2f9a2d3c25f12afd85ea864467342af
|
|
4
|
+
data.tar.gz: 66bbe62ffab8304baf8544c7bc5ba660c36c7ddb36b19669ce03a994aac9caa1
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 0d1196969afaf610771bf23c6d374dcfc880fff3ef8b50022979008d197ecd8429f6c9b9419b79f5b2f6968bd2c940d401fd47ae53d3ab875655a8eb0d83aaa4
|
|
7
|
+
data.tar.gz: 3affeb8bbc10ead46e7f533a6597b02f34f90662795465353edf4fc5e28d32724619bf6bbf171d54c0dbab7936b867db2d7cfba1e4051a1cf0bf6ea7583b3545
|
data/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.2.1 (2026-10-24)
|
|
6
|
+
|
|
7
|
+
- Leave ctx_parser and ctx_driver dependencies unconstrained in the gemspec; retain the current collection, immutable report and execution contracts.
|
|
8
|
+
|
|
9
|
+
## 0.2.0 (2026-10-23)
|
|
10
|
+
|
|
11
|
+
- Breaking: report presenters, completion callbacks and progress callbacks now receive immutable string-keyed documents; remove Report#serializable and migrate consumers.
|
|
12
|
+
- Validate summary and execution documents before publication, remove stale completion after conversion failures, and confirm recovery checkpoint durability.
|
|
13
|
+
- Preserve collected evidence and the original exit when final progress abandons a batch without replaying progress.
|
|
14
|
+
- Use English evidence validation and report publication diagnostics.
|
|
15
|
+
|
|
5
16
|
## 0.1.1 (2026-10-23)
|
|
6
17
|
|
|
7
18
|
- Add shared offline evidence validation with mandatory target identity.
|
data/README.md
CHANGED
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
| `Observation` | 事实外壳、可用性、时间类型、深度快照及安全展示 |
|
|
12
12
|
| `Batch` | 单设备结果登记、报告交付、输出失败补写 |
|
|
13
13
|
| `Report` | 私有批次目录、文件发布、检查点、完成判定及恢复 |
|
|
14
|
+
| `Document` | 有界、无歧义、深冻结的 JSON 值;统一报告和进度交付表示 |
|
|
14
15
|
| `Fingerprint` | 稳定配置身份,拒绝归一化键冲突 |
|
|
15
16
|
| `Execution` | 已确认增量的前提核验、执行记账、效果不确定状态及回读验收 |
|
|
16
17
|
|
|
@@ -42,6 +43,12 @@ end
|
|
|
42
43
|
|
|
43
44
|
`Report.new(root)` 创建排他的私有批次,目录 0700、文件 0600。`finish(results, requested:) { |summary| text }` 先保存未完成检查点,再发布领域文本,最后发布最终 JSON。`Report::Error#committed?` 区分是否已替换;失败不能被当作可靠发布。`recovery_failed?` 提示恢复也未确认。
|
|
44
45
|
|
|
46
|
+
`finish` 的展示块、返回摘要与最终 JSON 使用相同的字符串键/状态文档,例如 `summary.fetch("status") == "complete"`;展示回调不能改变这份深冻结快照。`Batch::Completion#status` 仍是符号,`#summary` 是该文档。`progress.result` 与 `progress.finish` 同样接收字符串键文档;`Batch#collect` 的返回值及领域 `report.write` 输入保持 Ruby 设备结果结构。这些交付边界没有符号键兼容分支,旧的 `Report#serializable` 已移除。
|
|
47
|
+
|
|
48
|
+
最终进度输出发生取消或非局部退出时,Batch 仅补写中断报告,保留已经采集和保存的事实及原退出值,不再调用进度展示或重采设备。普通进度异常记录为输出错误;恢复中的存储异常不会替换最先观察到的退出。
|
|
49
|
+
|
|
50
|
+
`Document.call(value)` 复制键和值,支持普通 Hash/Array、Time 的 ISO-8601 字符串和 Data 记录,拒绝正规化后的同名键、循环、不透明对象、非有限数以及超过 128 层的嵌套。`checkpoint(relative, value)`、`finalize(relative, value, checkpoint:)` 和 `write_execution(state)` 使用同一转换规则。检查点必须包含非空且不为 `complete` 的状态;最终提交失败只能恢复未完成事实。转换、编码或取消失败也会撤销旧完成结论;撤销文件后的目录同步失败会设置 `recovery_failed?`,原失败仍交还调用者。
|
|
51
|
+
|
|
45
52
|
`Execution` 只接受宿主已经校验、向用户展示且明确确认的计划。领域 change 实现 `commands`、`eligible?(before)`、`satisfied?(after, before:)`;journal 实现 `write_execution(state)`。每次回调获得快照。发送前保存 pending,发送后保留 acknowledged;失败后的 uncertain 禁止自动重放。`run { |operation| connector.open(&operation) }` 在连接器正常退出后才发布 configuration_verified;这不表示业务健康已验收。
|
|
46
53
|
|
|
47
54
|
完整可运行离线例子见 [examples](examples)。
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Report Documents Implementation Plan
|
|
2
|
+
|
|
3
|
+
> **For agentic workers:** Use executing-plans to implement this plan task-by-task. Preserve unrelated work; no commits, pushes or releases are authorized.
|
|
4
|
+
|
|
5
|
+
**Goal:** 统一持久化文档与摘要交付,并把输入转换纳入检查点撤销/恢复边界。
|
|
6
|
+
|
|
7
|
+
**Architecture:** Document 独占 JSON 值正规化;Report 持有发布协议。Batch 和领域报告显式交付/读取字符串键文档,采集结果保持原业务类型。连接器只消费文档,不依赖 Runner。
|
|
8
|
+
|
|
9
|
+
**Tech Stack:** Ruby 4.0.6、RSpec、Minitest、RuboCop、Rake、本地 gem 安装;连接器保持 Ruby >= 3.4。
|
|
10
|
+
|
|
11
|
+
**Spec:** ../specs/2026-10-23-report-documents.md
|
|
12
|
+
|
|
13
|
+
## Global Constraints
|
|
14
|
+
|
|
15
|
+
- 中文 lib 注释、英文业务字面量;不新增兼容参数或旧入口别名。
|
|
16
|
+
- Document 128 层预算;目录 0700、文件 0600;非法路径不执行收尾副作用。
|
|
17
|
+
- 不重放设备操作;不把证据/报告完成视为业务健康。
|
|
18
|
+
- 保留已有 WIP;不提交、推送或发布。五个隔离工作树从当前真实工作树逐文件复制,最终仅回写本计划修改且原始哈希未变的文件。
|
|
19
|
+
|
|
20
|
+
## Review Focus
|
|
21
|
+
|
|
22
|
+
- 输入转换或编码失败/取消发生在第一次 checkpoint 写入之前,旧 complete 必须撤销。
|
|
23
|
+
- finalize 的恢复文档含冲突键、循环或 complete,不得提交最终状态或恢复假成功。
|
|
24
|
+
- 展示回调改变原结果/诊断对象,文本与 JSON 仍读取已固定的文档。
|
|
25
|
+
- 两个字符串键文档在中断时合并 status,不能产生符号/字符串同名键。
|
|
26
|
+
- 进度输出失败后重新收尾、未保存但采集完整、非局部退出,不能重复采集或提升完成状态。
|
|
27
|
+
- 撤销旧完成文件后的目录同步失败须置 recovery_failed?,不覆盖输入主异常。
|
|
28
|
+
|
|
29
|
+
## Tasks
|
|
30
|
+
|
|
31
|
+
### Task 1: Document publication and batch delivery
|
|
32
|
+
|
|
33
|
+
**Files:** lib/ctx_runner/report.rb、lib/ctx_runner/batch.rb、spec/report_spec.rb、spec/batch_spec.rb、examples/report.rb、README.md、CHANGELOG.md。
|
|
34
|
+
|
|
35
|
+
**Interfaces:**
|
|
36
|
+
- 消费 `Document.call(value)`,返回深冻结字符串键 JSON 值;不新增另一套递归转换器。
|
|
37
|
+
- `Report#finish` 的展示块与返回值共享同一文档;`finalize` 返回正规化文档;`checkpoint` 及 `write_execution` 接受可转换文档输入。
|
|
38
|
+
- `Batch#collect` 仍返回 Ruby 结果,但向 progress.result 交付 Document;Batch 的 summary 使用字符串键,Completion.status 保持符号。
|
|
39
|
+
|
|
40
|
+
- [x] **Step 1:** 补实际文件回归:finish 的展示/返回/磁盘内容一致,Time/Data 保留;原输入可变而文档不可变。调整既有摘要断言与 Batch 桩为字符串键;补真实进度文档交付断言。
|
|
41
|
+
- [x] **Step 2:** 补 checkpoint/finish/finalize 的循环、冲突键、不透明值、非有限数、超深、编码错误及转换中 throw 的负向输入。断言 ArgumentError 或编码原异常;旧 complete 撤销,已有 incomplete 保留,非法路径不删除外部文件。
|
|
42
|
+
- [x] **Step 3:** 补拒绝 complete 恢复文档、中断恢复 status 为 interrupted,以及合法 120 层文档可编码的测试。运行 `bundle exec rspec spec/report_spec.rb spec/batch_spec.rb spec/document_spec.rb`,预期新增行为失败,保存 RED。
|
|
43
|
+
- [x] **Step 4:** 删除 serializable;在受保护的 checkpoint 准备范围内构造一次 Document,复用最终文档和检查点 JSON。finalize 预检失败仍撤销旧完成结论;write_execution 同样使用 Document。JSON 编码在已验证文档上关闭重复的较低嵌套限制。更新 Batch 与离线示例。
|
|
44
|
+
- [x] **Step 5:** 运行同一聚焦命令并运行完整 `bundle exec rake`,预期零失败;更新接口说明与变更记录。以文件哈希记录代替未授权的 commit。
|
|
45
|
+
|
|
46
|
+
### Task 2: Consumer migration and actual installation
|
|
47
|
+
|
|
48
|
+
**Files:** ../ctx_checker/ctx_checker.gemspec、各版本/依赖声明与当前 README;../vxlan/lib/vxlan/cli/report.rb、../wireless/lib/wireless/cli/report.rb、各 spec/cli/report_spec.rb;../net-connector-trunk/lib/net/connector/collect/progress.rb、test/collect_progress_test.rb;各 CHANGELOG.md。
|
|
49
|
+
|
|
50
|
+
**Interfaces:**
|
|
51
|
+
- 两个领域 finish 展示仅从传入的字符串键文档获取设备、状态、待处理和诊断;不再重新读取调用者容器。
|
|
52
|
+
- Collect::Progress.result/finish 接收字符串键文档;保留未交付完整证据计失败、部分状态、诊断优先级和待处理/筛除区分。
|
|
53
|
+
|
|
54
|
+
- [x] **Step 1:** 将消费协议测试输入与期待迁移为文档,运行两个领域 report specs 和连接器 collect_progress_test,确认当前实现无法消费新协议,保存 RED。
|
|
55
|
+
- [x] **Step 2:** 同步三个消费者,不添加双键回退;更新 CHANGELOG,运行聚焦测试,预期全部通过。
|
|
56
|
+
- [x] **Step 3:** 核对当前源码哈希后,仅把计划文件写回原 checkout;再次执行 Runner、VXLAN、Wireless 的完整默认 rake 及 net-connector 的 script/ci。
|
|
57
|
+
- [x] **Step 4:** 构建八个本地候选,逐字节核对包内容,运行普通/Bundler 依赖闭包安装及 CLI/review/实际报告文档验证。未通过不得以源码联调替代。
|
|
58
|
+
- [x] **Step 5:** fresh-context 独立审查整个本轮变更;处理实质发现,记录 ruling、测试、打包哈希和仍未验证范围。保留账本,不提交、不删除未提交证据。
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
## Final verification and rulings
|
|
62
|
+
|
|
63
|
+
- 普通实际 checkout 门禁:Runner 58、VXLAN 461、Wireless 323、Checker 701;连接器完整 script/ci 1233 runs、12500 assertions,共 2776 项测试。连接器门禁后未改变其生产代码;最终 Runner 修复又完整验证其实际消费者。
|
|
64
|
+
- 独立审查找到最终进度 throw 留下 complete;三个真实 CLI 退出回归先失败后通过。修复仅补写报告,不重放采集/进度;无未处理 Critical/Important/Minor。
|
|
65
|
+
- JSON 文档接口是明确迁移:Runner 0.2.0、net-connector 0.18.0、VXLAN 0.5.0、Wireless 0.6.0 为本地候选;消费端拒绝旧依赖。Checker 不消费摘要,允许不变的 Runner 0.1/0.2 采集接口;没有双键兼容。
|
|
66
|
+
- 五次合成报告发布的 3000 设备中位数:基线 21.709 ms/111171 allocations;首次正规化 25.667 ms/222200;消除逐键数组与重复符号字符串后 17.573 ms/99172。语义断言在计时外,含文件发布 IO;不外推网络收益。
|
|
67
|
+
- 全部 WIP 保留,不提交/推送/发布;不删除未提交审查账本。真实设备、断电、远端 CI 及平台矩阵未在本轮执行。完整证据位于工作区 .ctx-report-20261023。
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# 报告文档与发布边界
|
|
2
|
+
|
|
3
|
+
## 问题与目标
|
|
4
|
+
|
|
5
|
+
Report 保留独立的 serializable 递归实现,绕过 Document 对循环、冲突键、深度和不透明值的校验。当前探针确认:循环检查点产生 SystemStackError;JSON 编码或转换失败时旧 complete 留在磁盘;Object.new 被写成对象描述字符串。重复转换还让返回摘要与 JSON 使用两套键和值表示。
|
|
6
|
+
|
|
7
|
+
用 Document 作为唯一 JSON 值边界,Report 只负责发布及恢复。摘要在展示回调、返回值和最终文件中使用同一份深冻结、字符串键文档;Time/Data 等已有文档能力继续保留。明确迁移当前全部消费者,不保留 serializable、双格式读取或兼容参数。内部采集和领域结果仍使用自己的类型;文档转换发生在报告与进度交付边界。
|
|
8
|
+
|
|
9
|
+
## 必须保持的行为
|
|
10
|
+
|
|
11
|
+
- finish 先发布未完成检查点,再调用展示,再提交最终 JSON;报告完成不等于领域健康。
|
|
12
|
+
- 转换、JSON 编码、普通异常、Interrupt、throw/非局部退出都不能让旧 complete 代表未完成的新发布。非法路径在任何清理副作用之前拒绝。
|
|
13
|
+
- checkpoint 必须是带有非空、非 complete 状态的对象;finalize 的恢复参数遵守同一契约,不能用成功文档恢复一次失败提交。
|
|
14
|
+
- 仅完成文件替换而目录同步未确认时恢复检查点;恢复失败仍保留主异常并通过 recovery_failed? 显式报告。已有未完成检查点不因新输入校验失败被删除。
|
|
15
|
+
- 输入不冻结、不被回调修改后重新读取;返回/展示文档深度不可变。Document 的 128 层预算是 JSON 编码的嵌套边界;超限为 ArgumentError,不是栈溢出。
|
|
16
|
+
- write_execution 使用相同文档校验,失败继续交给 Execution 停止后续写入;不改变命令记账、回读或禁止重放规则。
|
|
17
|
+
- Batch 的 Completion.status 仍为 Ruby 符号;Completion.summary 和进度交付文档使用字符串键/状态。设备采集结果与领域 Report#write 的 Ruby 结构不改变。
|
|
18
|
+
- 连接器独立支持 Ruby 3.4,不依赖 Runner。其 Collect::Progress 直接接收文档,不自行引入转换器。
|
|
19
|
+
- lib 注释中文、业务字面量英文;Wireless 仅迁移消费协议,不扩大此前语言规范的八模块范围。
|
|
20
|
+
|
|
21
|
+
## 验收与范围
|
|
22
|
+
|
|
23
|
+
Runner 现有取消/路径/恢复/设备执行测试以及新增实际文件回归通过;两个领域完整默认 rake 和连接器完整 script/ci 通过。从实际 checkout 验证普通 CLI,再构建精确候选、比对打包源码和隔离安装。无需真实设备、远程发布或版本上线;不提交或推送。保留全部已有 WIP。
|
|
24
|
+
|
|
25
|
+
新的接口会要求外部摘要/进度消费者改用字符串键;明确在 README/CHANGELOG 中记录并以当前真实消费链验证,不提供符号键回退。
|
data/examples/report.rb
CHANGED
|
@@ -9,8 +9,8 @@ Dir.mktmpdir do |root|
|
|
|
9
9
|
report.publish("evidence.json", JSON.generate(source: "synthetic", records: []))
|
|
10
10
|
device = { "host" => "192.0.2.1", "name" => "example" }
|
|
11
11
|
summary = report.finish([ { device: device, status: :complete, report_saved: true } ], requested: [ device ]) do |value|
|
|
12
|
-
"Evidence: #{value.fetch(
|
|
12
|
+
"Evidence: #{value.fetch('status')}; health was not evaluated.\n"
|
|
13
13
|
end
|
|
14
|
-
raise "Report incomplete" unless summary
|
|
14
|
+
raise "Report incomplete" unless summary.fetch("status") == "complete"
|
|
15
15
|
raise "Missing evidence" unless File.file?(File.join(report.directory, "evidence.json"))
|
|
16
16
|
end
|
data/lib/ctx_runner/batch.rb
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
require "ctx_parser/immutable"
|
|
4
4
|
require "ctx_driver/failure"
|
|
5
|
+
require_relative "document"
|
|
5
6
|
|
|
6
7
|
module CtxRunner
|
|
7
8
|
# 批量采集的交付账本;调度器负责并发与回收,领域块只返回设备快照。
|
|
@@ -53,7 +54,7 @@ module CtxRunner
|
|
|
53
54
|
elsif failure || finalization_error
|
|
54
55
|
:failed
|
|
55
56
|
else
|
|
56
|
-
summary
|
|
57
|
+
summary.fetch("status") == "complete" ? :complete : :incomplete
|
|
57
58
|
end
|
|
58
59
|
completion = Completion.new(status: status, summary: summary, failure: failure, finalization_error: finalization_error,
|
|
59
60
|
recovery_failed: @report.respond_to?(:recovery_failed?) && @report.recovery_failed?)
|
|
@@ -99,7 +100,7 @@ module CtxRunner
|
|
|
99
100
|
@report.write(CtxParser::Immutable.copy(result), snapshot: snapshot)
|
|
100
101
|
@lock.synchronize { result[:report_saved] = true }
|
|
101
102
|
saved = CtxParser::Immutable.copy(result)
|
|
102
|
-
@progress.result(saved)
|
|
103
|
+
@progress.result(Document.call(saved))
|
|
103
104
|
saved
|
|
104
105
|
end
|
|
105
106
|
|
|
@@ -112,8 +113,8 @@ module CtxRunner
|
|
|
112
113
|
snapshot = results
|
|
113
114
|
options = { interrupted: interrupted, requested: @requested, report_error: report_error, execution_error: execution_error }
|
|
114
115
|
summary = @report.finish(snapshot, **options, output_error: @progress.output_error)
|
|
115
|
-
|
|
116
|
-
if @progress.output_error && !summary[
|
|
116
|
+
finish_progress(summary, snapshot, options)
|
|
117
|
+
if @progress.output_error && !summary["output_error"]
|
|
117
118
|
summary = @report.finish(snapshot, **options, output_error: @progress.output_error)
|
|
118
119
|
end
|
|
119
120
|
summary
|
|
@@ -123,12 +124,32 @@ module CtxRunner
|
|
|
123
124
|
|
|
124
125
|
private
|
|
125
126
|
|
|
127
|
+
# 终端收尾退出时只补写报告;保留已完成事实及原退出,不重放进度或采集。
|
|
128
|
+
def finish_progress(summary, snapshot, options)
|
|
129
|
+
recovery = { interrupted: true, output_error: summary["output_error"] }
|
|
130
|
+
@progress.finish(summary)
|
|
131
|
+
completed = true
|
|
132
|
+
rescue StandardError, LoadError => error
|
|
133
|
+
recovery = { output_error: { error_type: error.class.name } }
|
|
134
|
+
raise
|
|
135
|
+
ensure
|
|
136
|
+
unless completed
|
|
137
|
+
begin
|
|
138
|
+
@report.finish(snapshot, **options, **recovery)
|
|
139
|
+
rescue StandardError, LoadError, Interrupt
|
|
140
|
+
nil
|
|
141
|
+
end
|
|
142
|
+
end
|
|
143
|
+
end
|
|
144
|
+
|
|
126
145
|
def settle(options)
|
|
127
146
|
[ CtxParser::Immutable.copy(finish(**options)), nil ]
|
|
128
147
|
rescue Interrupt
|
|
129
148
|
options[:interrupted] = true
|
|
130
149
|
begin
|
|
131
|
-
|
|
150
|
+
# 取消后的终端不可再次调用;仅确认中断报告的交付状态。
|
|
151
|
+
summary = @report.finish(results, **options, requested: @requested, output_error: @progress.output_error)
|
|
152
|
+
[ CtxParser::Immutable.copy(summary), nil ]
|
|
132
153
|
rescue StandardError, LoadError, Interrupt => error
|
|
133
154
|
[ nil, diagnostic(error) ]
|
|
134
155
|
end
|
data/lib/ctx_runner/document.rb
CHANGED
|
@@ -5,12 +5,14 @@ require "time"
|
|
|
5
5
|
module CtxRunner
|
|
6
6
|
# 显式证据边界:生成独立 JSON 值,不通过文本往返转换业务事实。
|
|
7
7
|
module Document
|
|
8
|
+
MAX_DEPTH = 128
|
|
9
|
+
|
|
8
10
|
def self.call(value)
|
|
9
11
|
convert(value, {}.compare_by_identity, 0)
|
|
10
12
|
end
|
|
11
13
|
|
|
12
14
|
def self.convert(value, active, depth)
|
|
13
|
-
raise ArgumentError, "Document nesting exceeds the evidence budget" if depth >
|
|
15
|
+
raise ArgumentError, "Document nesting exceeds the evidence budget" if depth > MAX_DEPTH
|
|
14
16
|
case value
|
|
15
17
|
when Hash, Array, Data
|
|
16
18
|
raise ArgumentError, "Document must not contain cyclic data" if active[value]
|
|
@@ -21,10 +23,12 @@ module CtxRunner
|
|
|
21
23
|
when Array then value.map { |item| convert(item, active, depth + 1) }.freeze
|
|
22
24
|
when Hash
|
|
23
25
|
value.each_with_object({}) do |(key, item), result|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
+
# 符号名已由 Ruby 持有并冻结;其他键复制后才冻结,不占用调用方对象。
|
|
27
|
+
name = case key
|
|
28
|
+
when Symbol then key.name
|
|
29
|
+
when String, Integer, Float, Rational, Complex, NilClass, TrueClass, FalseClass then String.new(key.to_s)
|
|
30
|
+
else raise ArgumentError, "Document keys must be plain values"
|
|
26
31
|
end
|
|
27
|
-
name = String.new(key.to_s)
|
|
28
32
|
raise ArgumentError, "Document keys collide after normalization" if result.key?(name)
|
|
29
33
|
result[name.freeze] = convert(item, active, depth + 1)
|
|
30
34
|
end.freeze
|
|
@@ -34,7 +38,8 @@ module CtxRunner
|
|
|
34
38
|
end
|
|
35
39
|
when Time then value.iso8601(6).freeze
|
|
36
40
|
when String then value.dup.freeze
|
|
37
|
-
when Symbol
|
|
41
|
+
when Symbol then value.name
|
|
42
|
+
when Rational, Complex then value.to_s.freeze
|
|
38
43
|
when Float
|
|
39
44
|
raise ArgumentError, "Document numbers must be finite" unless value.finite?
|
|
40
45
|
value
|
data/lib/ctx_runner/evidence.rb
CHANGED
|
@@ -8,19 +8,19 @@ module CtxRunner
|
|
|
8
8
|
def self.validate(document)
|
|
9
9
|
unless document.is_a?(Hash) && document["device"].is_a?(Hash) &&
|
|
10
10
|
%w[name host].all? { |key| document["device"][key].is_a?(String) && !document["device"][key].empty? }
|
|
11
|
-
raise ArgumentError, "
|
|
11
|
+
raise ArgumentError, "Device identity is missing"
|
|
12
12
|
end
|
|
13
13
|
host = document["device"]["host"]
|
|
14
|
-
raise ArgumentError, "
|
|
14
|
+
raise ArgumentError, "Target address must be a canonical host address" unless !host.include?("/") && IPAddr.new(host).to_s == host
|
|
15
15
|
snapshot = document.fetch("snapshot")
|
|
16
16
|
return if snapshot.nil?
|
|
17
|
-
raise ArgumentError, "
|
|
17
|
+
raise ArgumentError, "Invalid snapshot structure" unless snapshot.is_a?(Hash) && snapshot["dimensions"].is_a?(Hash)
|
|
18
18
|
if !snapshot["target"].is_a?(Hash) || snapshot["target"]["host"] != host
|
|
19
|
-
raise ArgumentError, "
|
|
19
|
+
raise ArgumentError, "Device identity does not match the collection target"
|
|
20
20
|
end
|
|
21
21
|
snapshot["dimensions"].each do |dimension, observation|
|
|
22
22
|
unless observation.is_a?(Hash) && %w[complete partial failed unsupported not_requested].include?(observation["status"])
|
|
23
|
-
raise ArgumentError, "
|
|
23
|
+
raise ArgumentError, "Invalid observation structure"
|
|
24
24
|
end
|
|
25
25
|
records = array(observation.fetch("records"))
|
|
26
26
|
array(observation.fetch("issues", []))
|
|
@@ -29,12 +29,12 @@ module CtxRunner
|
|
|
29
29
|
end
|
|
30
30
|
|
|
31
31
|
def self.array(value)
|
|
32
|
-
raise ArgumentError, "
|
|
32
|
+
raise ArgumentError, "Expected a list of records" unless value.is_a?(Array) && value.all? { |entry| entry.is_a?(Hash) }
|
|
33
33
|
value
|
|
34
34
|
end
|
|
35
35
|
|
|
36
36
|
def self.map(value)
|
|
37
|
-
raise ArgumentError, "
|
|
37
|
+
raise ArgumentError, "Expected a mapping of records" unless value.is_a?(Hash) && value.values.all? { |entry| entry.is_a?(Hash) }
|
|
38
38
|
value
|
|
39
39
|
end
|
|
40
40
|
end
|
data/lib/ctx_runner/report.rb
CHANGED
|
@@ -4,7 +4,7 @@ require "json"
|
|
|
4
4
|
require "time"
|
|
5
5
|
require "tempfile"
|
|
6
6
|
require "fileutils"
|
|
7
|
-
|
|
7
|
+
require_relative "document"
|
|
8
8
|
|
|
9
9
|
module CtxRunner
|
|
10
10
|
# 持有私有证据批次,统一检查点、发布和失败恢复;领域只提供展示内容。
|
|
@@ -18,7 +18,7 @@ module CtxRunner
|
|
|
18
18
|
# 保留安全的发布阶段与提交状态,不携带底层异常正文。
|
|
19
19
|
def initialize(relative:, phase:, committed:)
|
|
20
20
|
@relative, @phase, @committed = relative.dup.freeze, phase, committed
|
|
21
|
-
super("
|
|
21
|
+
super("Report publication failed: #{relative}; phase #{phase}; #{committed ? 'replaced; finalization unconfirmed' : 'not replaced'}")
|
|
22
22
|
end
|
|
23
23
|
|
|
24
24
|
# 区分原子替换已完成与目录同步尚未确认。
|
|
@@ -33,7 +33,7 @@ module CtxRunner
|
|
|
33
33
|
prepare_directory(root)
|
|
34
34
|
stat = File.lstat(root)
|
|
35
35
|
unless stat.directory? && (stat.mode & 0o077).zero?
|
|
36
|
-
raise ArgumentError, "
|
|
36
|
+
raise ArgumentError, "Report root must be a real private directory with mode 0700; use a dedicated directory and check chmod 0700"
|
|
37
37
|
end
|
|
38
38
|
stem = Time.now.utc.strftime("%Y-%m-%d_%H-%M-%S")
|
|
39
39
|
sequence = 0
|
|
@@ -51,46 +51,55 @@ module CtxRunner
|
|
|
51
51
|
def finish(results, interrupted: false, requested: [], report_error: nil, execution_error: nil, output_error: nil, review: nil)
|
|
52
52
|
raise ArgumentError, "Report requires a presentation block" unless block_given?
|
|
53
53
|
@recovery_failed = false
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
54
|
+
summary = checkpoint = nil
|
|
55
|
+
# 转换和编码也属于发布;失败或取消不能让上一轮完成结论继续生效。
|
|
56
|
+
checkpoint_body = publish_checkpoint("summary.json") do
|
|
57
|
+
# 按地址索引一次,避免大批次逐个扫描所有已完成结果。
|
|
58
|
+
completed_hosts = results.to_h { |result| [ result.fetch(:device).fetch("host"), true ] }
|
|
59
|
+
pending = requested.reject { |device| completed_hosts.key?(device.fetch("host")) }
|
|
60
|
+
complete = !report_error && !execution_error && !output_error && pending.empty? && results.any? && results.all? { |r| r[:status] == :complete && r[:report_saved] != false }
|
|
61
|
+
summary = { status: interrupted ? :interrupted : (complete ? :complete : :incomplete),
|
|
62
|
+
total: [ requested.size, results.size ].max, completed: results.size, pending: pending, counts: results.map { |r| r[:status] }.tally, devices: results,
|
|
63
|
+
directory: directory, evidence_only: true }
|
|
64
|
+
summary[:review] = review if review
|
|
65
|
+
summary[:report_error] = report_error if report_error
|
|
66
|
+
summary[:execution_error] = execution_error if execution_error
|
|
67
|
+
summary[:output_error] = output_error if output_error
|
|
68
|
+
summary = Document.call(summary)
|
|
69
|
+
# 检查点共享已固定的证据;不重复转换,也不重新读取调用方对象。
|
|
70
|
+
checkpoint = summary.merge("status" => interrupted ? "interrupted" : "incomplete",
|
|
71
|
+
"report_error" => summary["report_error"] || "report_finalization_unconfirmed").freeze
|
|
72
|
+
document_body(checkpoint)
|
|
73
|
+
end
|
|
71
74
|
publish("summary.txt", yield(summary))
|
|
72
75
|
commit_summary("summary.json", summary, checkpoint: checkpoint, checkpoint_body: checkpoint_body)
|
|
73
76
|
end
|
|
74
77
|
|
|
75
78
|
# 新一轮发布必须先撤销旧完成结论;非局部退出也不能绕过这条边界。
|
|
76
79
|
def checkpoint(relative, value)
|
|
77
|
-
publish_checkpoint(relative
|
|
80
|
+
publish_checkpoint(relative) { document_body(checkpoint_document(value)) }
|
|
78
81
|
end
|
|
79
82
|
|
|
80
83
|
# 领域报告正文完成后提交最终状态;取消和提交后失败共用恢复协议。
|
|
81
84
|
def finalize(relative, summary, checkpoint:)
|
|
82
85
|
relative = checked_relative(relative)
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
+
validated = true
|
|
87
|
+
summary = Document.call(summary)
|
|
88
|
+
checkpoint = checkpoint_document(checkpoint)
|
|
89
|
+
commit_summary(relative, summary, checkpoint: checkpoint, checkpoint_body: document_body(checkpoint))
|
|
90
|
+
finalized = true
|
|
91
|
+
summary
|
|
92
|
+
ensure
|
|
93
|
+
invalidate_completed_summary(relative: relative) if validated && !finalized
|
|
86
94
|
end
|
|
87
95
|
|
|
88
|
-
def publish_checkpoint(relative
|
|
96
|
+
def publish_checkpoint(relative)
|
|
89
97
|
relative = checked_relative(relative)
|
|
90
98
|
validated = true
|
|
91
|
-
|
|
99
|
+
body = yield
|
|
92
100
|
publish(relative, body)
|
|
93
101
|
published = true
|
|
102
|
+
body
|
|
94
103
|
ensure
|
|
95
104
|
invalidate_completed_summary(relative: relative) if validated && !published
|
|
96
105
|
end
|
|
@@ -99,7 +108,7 @@ module CtxRunner
|
|
|
99
108
|
def commit_summary(relative, summary, checkpoint:, checkpoint_body:)
|
|
100
109
|
finalized = false
|
|
101
110
|
begin
|
|
102
|
-
publish(relative,
|
|
111
|
+
publish(relative, document_body(summary))
|
|
103
112
|
finalized = true
|
|
104
113
|
rescue Error => error
|
|
105
114
|
# 未替换时原检查点仍安全,不做可能破坏它的多余恢复写入。
|
|
@@ -107,7 +116,7 @@ module CtxRunner
|
|
|
107
116
|
finalized = true
|
|
108
117
|
raise
|
|
109
118
|
rescue Interrupt
|
|
110
|
-
restore_checkpoint(
|
|
119
|
+
restore_checkpoint(document_body(checkpoint.merge("status" => "interrupted")), relative: relative)
|
|
111
120
|
finalized = true
|
|
112
121
|
raise
|
|
113
122
|
ensure
|
|
@@ -120,7 +129,7 @@ module CtxRunner
|
|
|
120
129
|
|
|
121
130
|
# 每次发送配置前后发布检查点;失败由执行器停止后续写入。
|
|
122
131
|
def write_execution(state)
|
|
123
|
-
publish("execution.json",
|
|
132
|
+
publish("execution.json", document_body(Document.call(state)))
|
|
124
133
|
end
|
|
125
134
|
|
|
126
135
|
# 恢复写入或删除受阻时,调用方须把退出码及此状态作为未确认诊断。
|
|
@@ -149,7 +158,7 @@ module CtxRunner
|
|
|
149
158
|
def invalidate_completed_summary(relative: "summary.json")
|
|
150
159
|
relative = checked_relative(relative)
|
|
151
160
|
Thread.handle_interrupt(Exception => :never) do
|
|
152
|
-
saved = JSON.parse(File.read(File.join(directory, relative)))
|
|
161
|
+
saved = JSON.parse(File.read(File.join(directory, relative)), max_nesting: Document::MAX_DEPTH + 1)
|
|
153
162
|
discard_summary(relative: relative) if saved["status"] == "complete"
|
|
154
163
|
end
|
|
155
164
|
rescue Errno::ENOENT
|
|
@@ -176,24 +185,15 @@ module CtxRunner
|
|
|
176
185
|
# 存储拒绝恢复时尽力移除不可信摘要,不删除已获得的设备事实。
|
|
177
186
|
def discard_summary(relative: "summary.json")
|
|
178
187
|
relative = checked_relative(relative)
|
|
179
|
-
File.
|
|
188
|
+
target = File.join(directory, relative)
|
|
189
|
+
File.unlink(target)
|
|
190
|
+
sync_directory(File.dirname(target))
|
|
180
191
|
rescue Errno::ENOENT
|
|
181
192
|
nil
|
|
182
|
-
rescue SystemCallError
|
|
193
|
+
rescue SystemCallError, IOError, NotImplementedError
|
|
183
194
|
@recovery_failed = true
|
|
184
195
|
end
|
|
185
196
|
|
|
186
|
-
# Time 使用 ISO-8601,递归转换 Data 只发生在显式持久化边界。
|
|
187
|
-
def serializable(value)
|
|
188
|
-
case value
|
|
189
|
-
when Time then value.iso8601(6)
|
|
190
|
-
when Data then serializable(value.to_h)
|
|
191
|
-
when Hash then value.transform_values { |item| serializable(item) }
|
|
192
|
-
when Array then value.map { |item| serializable(item) }
|
|
193
|
-
else value
|
|
194
|
-
end
|
|
195
|
-
end
|
|
196
|
-
|
|
197
197
|
# 临时文件与目标在同一目录,写入失败不发布半份报告。
|
|
198
198
|
def publish(relative, body)
|
|
199
199
|
relative = checked_relative(relative)
|
|
@@ -218,6 +218,18 @@ module CtxRunner
|
|
|
218
218
|
end
|
|
219
219
|
private
|
|
220
220
|
|
|
221
|
+
# 恢复只能保留未完成事实,不能把完成摘要当作安全检查点。
|
|
222
|
+
def checkpoint_document(value)
|
|
223
|
+
document = Document.call(value)
|
|
224
|
+
unless document.is_a?(Hash) && document["status"].is_a?(String) && !document["status"].empty? && document["status"] != "complete"
|
|
225
|
+
raise ArgumentError, "Checkpoint requires a non-complete status"
|
|
226
|
+
end
|
|
227
|
+
document
|
|
228
|
+
end
|
|
229
|
+
|
|
230
|
+
# 深度由 Document 校验;编码阶段不再施加 JSON 默认的更低嵌套限制。
|
|
231
|
+
def document_body(document) = JSON.pretty_generate(document, max_nesting: false) + "\n"
|
|
232
|
+
|
|
221
233
|
# 发布、恢复与删除使用同一条路径契约;拒绝路径时不能执行收尾副作用。
|
|
222
234
|
def checked_relative(relative)
|
|
223
235
|
unless relative.is_a?(String) && !relative.empty? && !relative.start_with?("/") &&
|
data/lib/ctx_runner/version.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.2.1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Gatework contributors
|
|
@@ -13,42 +13,30 @@ dependencies:
|
|
|
13
13
|
name: ctx_parser
|
|
14
14
|
requirement: !ruby/object:Gem::Requirement
|
|
15
15
|
requirements:
|
|
16
|
-
- - "~>"
|
|
17
|
-
- !ruby/object:Gem::Version
|
|
18
|
-
version: '0.2'
|
|
19
16
|
- - ">="
|
|
20
17
|
- !ruby/object:Gem::Version
|
|
21
|
-
version: 0
|
|
18
|
+
version: '0'
|
|
22
19
|
type: :runtime
|
|
23
20
|
prerelease: false
|
|
24
21
|
version_requirements: !ruby/object:Gem::Requirement
|
|
25
22
|
requirements:
|
|
26
|
-
- - "~>"
|
|
27
|
-
- !ruby/object:Gem::Version
|
|
28
|
-
version: '0.2'
|
|
29
23
|
- - ">="
|
|
30
24
|
- !ruby/object:Gem::Version
|
|
31
|
-
version: 0
|
|
25
|
+
version: '0'
|
|
32
26
|
- !ruby/object:Gem::Dependency
|
|
33
27
|
name: ctx_driver
|
|
34
28
|
requirement: !ruby/object:Gem::Requirement
|
|
35
29
|
requirements:
|
|
36
|
-
- - "~>"
|
|
37
|
-
- !ruby/object:Gem::Version
|
|
38
|
-
version: '0.2'
|
|
39
30
|
- - ">="
|
|
40
31
|
- !ruby/object:Gem::Version
|
|
41
|
-
version: 0
|
|
32
|
+
version: '0'
|
|
42
33
|
type: :runtime
|
|
43
34
|
prerelease: false
|
|
44
35
|
version_requirements: !ruby/object:Gem::Requirement
|
|
45
36
|
requirements:
|
|
46
|
-
- - "~>"
|
|
47
|
-
- !ruby/object:Gem::Version
|
|
48
|
-
version: '0.2'
|
|
49
37
|
- - ">="
|
|
50
38
|
- !ruby/object:Gem::Version
|
|
51
|
-
version: 0
|
|
39
|
+
version: '0'
|
|
52
40
|
- !ruby/object:Gem::Dependency
|
|
53
41
|
name: digest
|
|
54
42
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -143,6 +131,8 @@ files:
|
|
|
143
131
|
- LICENSE
|
|
144
132
|
- README.md
|
|
145
133
|
- docs/superpowers/plans/2026-10-21-runner.md
|
|
134
|
+
- docs/superpowers/plans/2026-10-23-report-documents.md
|
|
135
|
+
- docs/superpowers/specs/2026-10-23-report-documents.md
|
|
146
136
|
- docs/verification-2026-10-22.md
|
|
147
137
|
- examples/execution.rb
|
|
148
138
|
- examples/report.rb
|