ctx_runner 0.2.0 → 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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e38041886eddd4c62f64ac92bb2af4e5f82f62accfe84d276cf169463b1bfd5e
4
- data.tar.gz: 57174343df0368bf45997665c436781585d23a165a496de58b2ae2f7a7c0c612
3
+ metadata.gz: 02bf46f3be0d4d50aad62170f51daa8df2f9a2d3c25f12afd85ea864467342af
4
+ data.tar.gz: 66bbe62ffab8304baf8544c7bc5ba660c36c7ddb36b19669ce03a994aac9caa1
5
5
  SHA512:
6
- metadata.gz: 79b6a398ac323338de8656129163d6863761ee568221e55f57e465b2e14fb161a3c6bc7eebf6dc1895ba8a80aea113d041b68e576e7611e85ce6ccce66f4ccb6
7
- data.tar.gz: 83f2e533cc140782d46985cd1084d6a729a68d632718edc4ab86b4bce672a47bf2242627b24b03363a9267a76de182d3bee6654ea08362fac4eebd6fbdeb3d21
6
+ metadata.gz: 0d1196969afaf610771bf23c6d374dcfc880fff3ef8b50022979008d197ecd8429f6c9b9419b79f5b2f6968bd2c940d401fd47ae53d3ab875655a8eb0d83aaa4
7
+ data.tar.gz: 3affeb8bbc10ead46e7f533a6597b02f34f90662795465353edf4fc5e28d32724619bf6bbf171d54c0dbab7936b867db2d7cfba1e4051a1cf0bf6ea7583b3545
data/CHANGELOG.md CHANGED
@@ -2,6 +2,10 @@
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
+
5
9
  ## 0.2.0 (2026-10-23)
6
10
 
7
11
  - Breaking: report presenters, completion callbacks and progress callbacks now receive immutable string-keyed documents; remove Report#serializable and migrate consumers.
@@ -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 中记录并以当前真实消费链验证,不提供符号键回退。
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module CtxRunner
4
- VERSION = "0.2.0"
4
+ VERSION = "0.2.1"
5
5
  end
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.2.0
4
+ version: 0.2.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Gatework contributors
@@ -15,28 +15,28 @@ dependencies:
15
15
  requirements:
16
16
  - - ">="
17
17
  - !ruby/object:Gem::Version
18
- version: 0.2.7
18
+ version: '0'
19
19
  type: :runtime
20
20
  prerelease: false
21
21
  version_requirements: !ruby/object:Gem::Requirement
22
22
  requirements:
23
23
  - - ">="
24
24
  - !ruby/object:Gem::Version
25
- version: 0.2.7
25
+ version: '0'
26
26
  - !ruby/object:Gem::Dependency
27
27
  name: ctx_driver
28
28
  requirement: !ruby/object:Gem::Requirement
29
29
  requirements:
30
30
  - - ">="
31
31
  - !ruby/object:Gem::Version
32
- version: 0.2.7
32
+ version: '0'
33
33
  type: :runtime
34
34
  prerelease: false
35
35
  version_requirements: !ruby/object:Gem::Requirement
36
36
  requirements:
37
37
  - - ">="
38
38
  - !ruby/object:Gem::Version
39
- version: 0.2.7
39
+ version: '0'
40
40
  - !ruby/object:Gem::Dependency
41
41
  name: digest
42
42
  requirement: !ruby/object:Gem::Requirement
@@ -131,6 +131,8 @@ files:
131
131
  - LICENSE
132
132
  - README.md
133
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
134
136
  - docs/verification-2026-10-22.md
135
137
  - examples/execution.rb
136
138
  - examples/report.rb