ctx_parser 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 207ae07b7f1f12d8d8a91ce6ea1a89fc39bb2c566f3d1cebe289ab71012aadd5
-  data.tar.gz: 1249139af57dd39b634ad948028af664af72eea4af7e5cb9a0137e4117f8eecd
+  metadata.gz: dfdec0a6366bcb4f65cca5025dacb968ec838de632dbed9b02424b1eadfe7ba9
+  data.tar.gz: c7b1eadc4fc4f6baa24b0e9c2c94e40080097e60da3ba25a6b4693c5d4735a42
 SHA512:
-  metadata.gz: 43e613f54ffa2b660d9badc6e2ce1195ed9fbf5b3fd864c8b85102c0cfae4eb9aa3cac477c7e7c9e92116d3c3e40234ce58e0e6c08db1757106c78a1c0e976f4
-  data.tar.gz: d8a2b623628265babbcaedc0f3d15b29257945917e6e4db13d6958680457c1d4f3028066d416c77ff2c2d29a3da8dde5d7520da920d8a40b8ca3794a7247bf04
+  metadata.gz: aa1e066001a118d610be8fd777844ddd53dab4627ab976eefaf076218d7ec77d62d15011ae203804cb8c3117f03cee079aa83315cd909bb2eaae192817201d4f
+  data.tar.gz: 0e1f197af6d134e9fa86989b62b4e82e6b4cecc103336a213128b211f1c35060e337903c04b91cd8f365729ce602a8f18acdba5cb1d7409efef01eb2ef07ca33

data/CHANGELOG.md

@@ -4,6 +4,25 @@ Changes to the public contract are recorded here. Versions follow Semantic Versi
 
 ## Unreleased
 
+## 0.5.1 (2026-10-30)
+
+- Add `Document#build_blocks` for native syntax trees and `Document::Flat` for independent command lines, sharing initialization, finalization and root validation.
+- Validate Block children by source ownership, containment and order; indentation remains the responsibility of the default tree builder.
+- Add cached `Cursor#block(index)` source ranges whose state stays live across rewind and reset.
+
+## 0.5.0 (2026-10-30)
+
+- Add Cursor#resolved? with a lazy, invalidated prefix index; Block/Capture completeness remains live after state changes and reset.
+- Snapshot declaration, request, child, capture-source and record arrays before validation or callbacks without inheriting caller copy hooks.
+
+- Make immutable `Commands` the single declaration boundary; add query grouping/selection and accept empty catalogs.
+- Add `Profile#declarations`, constructor injection and `with_declarations`; remove the independent `COMMANDS`/`PARSERS` declaration protocol and mutable-directory caches.
+- Reject foreign configuration blocks before callbacks; snapshot scope paths before entering callbacks and preserve live source completeness.
+- Strip string subclasses, attached state and singleton behavior at snapshot, command, input and source-line boundaries.
+- Rebuild frozen containers instead of reusing external object identity; preserve sharing within each copy and use Ruby string deduplication without an application-level cache.
+- Keep selected model overrides stable in derived profiles; retain Result/Results fields, projection isolation and Records ownership semantics.
+- Provide standalone configuration benchmarks and a 0.5 migration guide.
+
 ## 0.4.0 (2026-10-29)
 
 - Add immutable `covered_scopes` to Result, including equality, hashing, pattern matching and `with` semantics.

data/README-zh.md

@@ -72,6 +72,8 @@ result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
 
 `complete: true` 只表示调用方确认输入完整接收，不证明所有语法都已理解。未知行、身份冲突及空表证据不足必须明确表达。结果的记录和诊断均须为 Hash 数组；结果及构建完成的文档诊断持有不可变快照。`inspect`、`to_s` 和 pretty printing 不输出结果正文与诊断内容，显式读取记录仍返回原始事实。来源游标有意保留输入原文，含秘密时不可写入日志。
 
+`Cursor#resolved?(first_index, last_index)` 查询零起始闭区间；Block/Capture 完整性继续读取实时来源状态。惰性前缀索引在解决状态变化后失效，reset 时清空，详见 [0.5 契约](docs/contracts-0.5.md)。
+
 本 gem 不提供厂商命令目录、传输、持久化或健康策略。参数和注册表配置错误保持异常，由调用方在对应边界处理。
 
 详细厂商语义、历史验证记录和 Motor 专用集成说明保留在[架构参考](docs/architecture-zh.md)。其中宿主集成代码需要 Motor，不属于独立 gem API。适配层位于 [Motor 仓库](https://github.com/gatework/motor/tree/main/backend/lib) 的 `backend/lib/baseline`、`backend/lib/vxlan` 和 `backend/lib/wireless`。
@@ -86,11 +88,13 @@ result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
 
 `Cursor.new(text, max_bytes: limit)` 和 `Document.new(source, max_bytes: limit)` 可在构建或消费来源行前限制输入字节数。传入已有游标时，限制针对其归一化内容。非法编码仍抛出错误；已知为 Latin-1 的输入可先标记 `Encoding::ISO_8859_1`，随后自动转为 UTF-8，不静默替换字节并生成事实。
 
-`MODEL_PARSERS` 的型号键与请求型号一样去除两侧空白并转为小写，归一化冲突和无效覆盖均被拒绝。`Registry` 在注册时校验静态命令与解析器目录；动态目录在使用时仍需校验，缺失实现抛出 `ArgumentError`。
+`MODEL_PARSERS` 的型号键与请求型号一样去除两侧空白并转为小写，归一化冲突和无效覆盖均被拒绝。`Registry` 在注册时校验 Commands 声明及型号覆盖；Profile 创建时快照选中的覆盖，派生实例继续持有原先的型号设置。
+
+`Commands` 独立持有不可变查询序列及命令到视图的索引。静态声明使用 `DECLARATIONS = CtxParser::Commands.new(...)`，也可向 `Profile.new` 传入 `declarations:`。发现阶段通过 `profile.with_declarations(new_catalog)` 返回副本，原实例保留原目录。`commands`、`parsers` 只是派生查询接口，旧的 `COMMANDS/PARSERS` 双目录声明会被拒绝。空目录合法，查询不存在的维度仍抛出 `ArgumentError`。详见 [0.5 契约与迁移](docs/contracts-0.5.md)。`benchmark/profile.rb` 覆盖 32–4096 条命令，`benchmark/commands.rb` 同时测量声明构造成本。
 
-Profile 为深冻结的普通命令目录复用查询列表与成员索引，包括发现阶段产生的目录。替换目录后重建索引；可变条目仍在每次查找时校验。`bundle exec ruby -Ilib benchmark/profile.rb` 测量 32、128、512 条合成命令的准备开销，并校验选择顺序与未知命令拒绝行为。
+`Records` 持有自己的筛选数组，行对象仍属于调用方；使用期间应保持行不变，需要快照时传入 `Immutable.copy(rows)`。`Immutable.copy` 即使遇到冻结容器也重建普通容器，单次复制中保留共享引用并拒绝循环；不扫描方法表，也不引入应用级全局缓存。字符串经 `String.new` 和 Ruby 去重后冻结，保留编码与字节。不同次复制不保证容器对象身份相同；`Immutable.copy_string` 提供相同的文本边界并省去容器遍历表。整数转换仅在 `min` 允许负数或为 `nil` 时接受负号，默认仍只接受非负数。
 
-`Records` 持有自己的筛选数组，行对象仍属于调用方；使用期间应保持行不变，需要快照时传入 `Immutable.copy(rows)`。`Immutable.copy` 在逐层校验后可复用深冻结普通容器；浅冻结、特殊 Hash 行为及循环引用仍按原规则复制或拒绝。整数转换仅在 `min` 允许负数或为 `nil` 时接受负号，默认仍只接受非负数。
+`Document` 默认按缩进建树；原生语法可以覆盖受保护的 `build_blocks`，返回同一游标内按来源排序、互不重叠的根 Block，随后仍执行 `finish`。子块必须处于父范围内并保持顺序，不要求更深缩进。`Document::Flat` 将命令行作为独立来源块；`cursor.block(index)` 复用单行范围，rewind/reset 保留其身份，完整性始终读取当前游标状态。这些 API 由配套 0.5.1 候选提供，厂商语法由消费模块拥有。
 
 ## 开发与测试
 

data/README.md

@@ -72,6 +72,8 @@ result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
 
 `complete: true` confirms that the caller received the entire input; it does not certify that all syntax was understood. Unknown rows, identity conflicts, and insufficient empty-table evidence must remain explicit. Result records and issues must be arrays of hashes. Results and completed document diagnostics own immutable snapshots. `inspect`, `to_s`, and pretty printing omit result facts and diagnostics; explicit record access still returns the original facts. Source cursors intentionally retain original input and must not be logged when it contains secrets.
 
+`Cursor#resolved?(first_index, last_index)` queries a zero-based inclusive source range. Block and Capture completeness stays live; a lazy prefix index is invalidated when resolved state changes and cleared by reset. See the [0.5 contracts](docs/contracts-0.5.md).
+
 This gem supplies no vendor command declarations, transport, persistence, or health policy. Parser/registry argument errors remain exceptions for callers to handle at their own boundary.
 
 Detailed vendor behavior, historical validation notes, and Motor-only integration are preserved in [the architecture reference](docs/architecture-zh.md). Host integration examples in that reference require Motor; they are not standalone gem APIs. Motor adapters live under `backend/lib/baseline`, `backend/lib/vxlan`, and `backend/lib/wireless` in the [Motor repository](https://github.com/gatework/motor/tree/main/backend/lib).
@@ -86,11 +88,13 @@ Address conversion uses `Values.ip_address`, `Values.ip_address?`, and `Values.m
 
 `Cursor.new(text, max_bytes: limit)` and `Document.new(source, max_bytes: limit)` enforce an optional input byte budget before constructing or consuming lines. For an existing cursor, the budget applies to its normalized content. Invalid encoding remains an error: known Latin-1 input can be tagged as `Encoding::ISO_8859_1` before parsing and is transcoded to UTF-8; bytes are never silently scrubbed into facts.
 
-`MODEL_PARSERS` model names are stripped and lowercased just like the requested model. Normalization collisions and invalid overrides are rejected. `Registry` validates static command/parser declarations when registering a profile; dynamic directory lookup remains validated when used and reports missing implementations as `ArgumentError`.
+`MODEL_PARSERS` model names are stripped and lowercased just like the requested model. Normalization collisions and invalid overrides are rejected. `Registry` validates Commands declarations and model overrides when registering a profile. `Profile` snapshots the selected overrides; a derived profile retains those overrides even if the original model mapping is later changed.
+
+`Commands` owns immutable query lists and a command-to-view index. Declare `DECLARATIONS = CtxParser::Commands.new(...)`, or pass `declarations:` to `Profile.new`. Discovery returns `profile.with_declarations(new_catalog)`; existing profiles keep their original catalog. `commands` and `parsers` are read-only derived views. Independent `COMMANDS`/`PARSERS` declarations are rejected. Empty catalogs are valid, while selecting an absent dimension raises `ArgumentError`. See [the 0.5 contract and migration guide](docs/contracts-0.5.md). `benchmark/profile.rb` exercises 32, 128, 512 and 4096 commands; `benchmark/commands.rb` also measures catalog construction.
 
-Profiles reuse query lists and membership indexes for fully frozen plain command directories, including directories created by discovery. Replacing a directory rebuilds its index; mutable entries are validated on each lookup. `bundle exec ruby -Ilib benchmark/profile.rb` measures preparation of 32, 128 and 512 synthetic commands and checks selection order and rejection of unknown commands.
+`Records` owns selection arrays, while row objects remain caller-owned: treat those rows as stable during use, or pass `Immutable.copy(rows)` when a snapshot is needed. `Immutable.copy` rebuilds containers even when frozen, preserves shared references within each copy, and rejects cycles. This removes attached state, Hash defaults and singleton behavior without scanning method tables or maintaining a global cache. String snapshots use `String.new` followed by Ruby string deduplication; encoding and bytes are preserved. Container identity is not preserved across separate copies. `Immutable.copy_string` provides the same text boundary without allocating a container traversal map. Integer conversion accepts a minus sign only when `min` permits negative values (or is `nil`); the default remains nonnegative.
 
-`Records` owns selection arrays, while row objects remain caller-owned: treat those rows as stable during use, or pass `Immutable.copy(rows)` when a snapshot is needed. `Immutable.copy` can reuse fully frozen plain trees after validating all descendants; shallow-frozen containers, custom Hash behavior, and cycles receive the existing copy or rejection behavior. Integer conversion accepts a minus sign only when `min` permits negative values (or is `nil`); the default remains nonnegative.
+`Document` builds indentation-based trees by default. Native grammars may override protected `build_blocks` and return ordered, non-overlapping root Blocks from the same cursor; `finish` still runs afterward. Block children must be contained and ordered, but need not have greater indentation. `Document::Flat` treats each command as an independent source block. `cursor.block(index)` reuses a one-line range; rewind/reset preserve its identity while completeness follows current cursor state. These APIs are provided by the paired 0.5.1 candidate; vendor grammar remains in consumers.
 
 ## Development and tests
 
@@ -126,4 +130,4 @@ MIT. See [LICENSE](LICENSE).
 
 `Result#partial?` identifies partial parsing; `#available?` is true for complete or partial results. Failed and unsupported results cannot contain records. Availability does not establish completeness or network health.
 
-本次使用 ctx_parser 0.4 系列契约；`Result` 新增 `covered_scopes`，单行命令统一由 `CtxParser::Commands.command_text` 校验。跨模块约定见 [ctx_runner 契约迁移](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-29.md)。
+The 0.5 series changes profile declarations; Result fields, including `covered_scopes`, remain unchanged. Cross-module contracts are described in the [Runner migration guide](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-29.md).

data/docs/contracts-0.5.md

@@ -0,0 +1,70 @@
+# ctx_parser 0.5 契约与迁移
+
+本轮保持现有生产类和模块，收敛声明入口及状态边界。最低运行时为 Ruby 4.0.6。
+
+## 职责与所有权
+
+| 抽象 | 职责及所有权 |
+| --- | --- |
+| `Commands` | 校验一次声明，拥有冻结的命令、视图和解析器索引；解析器类本身由调用方维护 |
+| `Profile` | 持有一份声明和已选型号覆盖，选择解析器并隔离视图投影错误 |
+| `Parser` | 文本与传输完整性入口；厂商子类负责解释语法 |
+| `Configuration` | 每次解析独立维护文档、来源状态和临时结果路径 |
+| `Cursor` / `Document` / `Block` | 来源行、缩进范围及实时语义状态；读过不等于解析成功 |
+| `Capture` | 事实和路径是不可变快照，完整性继续查询来源状态 |
+| `Result` / `Results` | 不可变事实与诊断；共享回显的每个视图独立保留状态 |
+| `Immutable` / `Values` / `Records` | 纯数据快照、严格值转换、逻辑身份分组；Records 借用行对象 |
+
+## 单一声明入口
+
+```ruby
+class DeviceProfile < CtxParser::Profile
+  DECLARATIONS = CtxParser::Commands.new([
+    { dimensions: %i[interfaces counters], command: "show interfaces", parser: InterfacesParser },
+    { dimensions: [ :counters ], command: "show counters", parser: CountersParser }
+  ], multi_command: true)
+end
+
+profile = DeviceProfile.new(model: "fixture")
+profile.commands_for(:counters) # 两条独立命令，不能拼接其正文
+profile.queries(%i[interfaces counters]) # 命令 => 请求视图，保持顺序
+profile.parser_for(:counters, command: "show counters")
+
+expanded = profile.with_declarations(CtxParser::Commands.new(
+  profile.declarations.entries + additional_entries, multi_command: true
+))
+```
+
+`Profile.new(model: nil, declarations: self.class::DECLARATIONS)` 允许显式注入目录。`Commands.new([])` 表示无查询；`queries([])` 返回冻结空映射，选择不存在的维度或从空请求推断命令仍抛出 `ArgumentError`。
+
+删除子类的 `COMMANDS`、`PARSERS` 常量，改用 `DECLARATIONS`。读取旧常量的代码迁移到 `Profile::DECLARATIONS.by_dimension` / `.parsers`，或实例的 `commands` / `parsers`。旧的双目录声明会报告迁移错误；覆盖 `commands` 或 `parsers` 不再改变解析器选择。
+
+`Commands#commands_for` 总是返回冻结数组；`by_dimension` 保持单命令为 String、多命令为 Array 的既有读取形状。`select_command(dimensions, command: nil)` 要求非空、唯一且已声明的维度；只有唯一公共命令才能隐式推断。显式命令必须提供全部请求视图，选择结果返回目录中已经校验并冻结的命令文本。
+
+每次 Profile 操作只读取一次目录，命令与实现来自同一快照。型号键仍去除外围空白并转为小写；所有声明的型号覆盖在注册或实例创建时校验。`with_declarations` 保留已经选定的覆盖和子类状态，不重跑初始化；若新目录删除了选中覆盖需要的命令，则拒绝替换。改变类常量仅影响新实例。
+
+## 来源与快照边界
+
+`analyze`、`analyze_children`、`ignore`、`scope` 在回调前拒绝其他游标的块。参数失败不修改来源状态。`scope` 进入前固定路径，结束时复制产生的事实；嵌套异常仍恢复父路径。
+
+`Immutable.copy` 和 `copy_string` 不保留字符串子类、附加状态或单例行为。输入、命令和来源行采用同一纯文本原则；编码及原始换行策略不变。循环容器仍拒绝。容器即使冻结也重建，单次复制通过身份索引保留共享引用；不同次复制不保证同一容器对象身份。字符串通过 `String.new` 后调用 Ruby 的一元 `-` 去重并冻结。该策略隔离所有可见性的单例行为，也避免枚举每个值的方法表；不新增应用级缓存。
+
+这是对原计划复用冻结容器策略的调整：全量反射检查在本机让重复包装冻结记录慢约 9 倍，且空扩展模块后续新增方法仍可能改变已冻结输入的行为。重建容器消除了这两类问题。记录的值、顺序和一次快照内部的共享引用关系不变。
+
+未更改 Result 字段 `status/records/issues/covered_scopes`、complete/partial/failed/unsupported 状态、共享视图失败隔离、来源完整性的实时查询或 Records 的借用约定。`complete: true` 仍只是调用方的接收完整性声明。
+
+## 消费模块与验证
+
+候选版本为 ctx_parser 0.5.0、ctx_driver/ctx_runner 0.5.1、ctx_checker 0.7.0、vxlan 0.9.0、wireless-rb 0.10.0。Driver/Runner 接受 parser 0.4 与 0.5；迁移后的三个领域模块要求 parser 0.5 及相应 Driver/Runner 补丁版本。报告 schema 不变。
+
+运行 `bundle exec rake`、`bundle exec rake build` 和 `ruby script/verify_package.rb pkg/ctx_parser-0.5.0.gem`。`examples/declarations.rb` 演示新入口；`benchmark/commands.rb`、`profile.rb`、`snapshots.rb`、`source.rb`、`configuration.rb` 分别覆盖声明、选择、事实快照与来源追溯。性能比较必须同时包含构建、首次使用与复用成本，并校验结果相同。
+
+本地测量与正确性成本见 [性能记录](performance-0.5.md)。
+
+## 后续打磨：容器与来源区间
+
+声明、解析请求、子块、捕获来源列表和 Records 行列表在校验及回调前通过 Array.new 固定普通数组。列表由库拥有，解析器类、来源块与 Records 行仍按原契约借用；不继承调用方的 dup/map 行为。
+
+`Cursor#resolved?(first_index, last_index)` 接受零起始闭区间。越界参数抛出 IndexError，逆序区间抛出 ArgumentError；空文档没有可查询的有效闭区间。Block#complete? 委托该查询，Capture 的完整性仍跟随当前来源状态。
+
+Cursor 按需构建未解决行数量的前缀索引，只延伸到已查询末行。mark 在 resolved/unresolved 分组变化时将有效边界退回修改位置，parsed 与 ignored 互换不使索引失效。unread/defer 通过 mark 更新，reset! 释放索引；读取、回退和 rewind 不改变语义状态。稳定查询 O(1)，失效登记 O(1)，重建成本与需要重算的前缀区间长度成正比，空间最多 O(n)。索引属于单次解析游标，不承诺线程共享或缓存旧完整性结论。

data/docs/performance-0.5.md

@@ -0,0 +1,64 @@
+# ctx_parser 0.5 本地性能记录
+
+环境：RVM Ruby 4.0.6，Linux x86_64；基线为 ctx_parser 0.4.0（提交 `0aacc77a7b247f00ad59350517849474aca49726`）。上一轮候选生产源码摘要：`a6cada37ed67e8048a1ea9a41bfa126b1474af4494135d4daa2964929be0d4c1`。
+
+声明与快照基准按 baseline/candidate/candidate/baseline 顺序运行两轮，取四个独立进程样本中位数；来源基准采用一轮交错顺序，各进程执行三次。测量时没有并行测试。所有场景校验命令顺序、解析值或来源范围。以下是合成数据结果，不代表设备或网络吞吐。
+
+## 声明、选择与快照
+
+| 场景 | 工作量 | 基线 ms | 候选 ms | 基线分配 | 候选分配 |
+| --- | --- | ---: | ---: | ---: | ---: |
+| 构建完整目录 | 4096 条目录 × 10 次 | 178.155 | 204.748 | 245813 | 286793 |
+| 构建目录并解析前 128 个命令 | 4096 条目录 × 10 次 | 195.480 | 189.548 | 354813 | 312443 |
+| 复用目录创建 Profile 并首次选择 | 100 个 Profile | 342.825 | 0.420 | 821403 | 603 |
+| 重复显式选择 | 12800 次选择 | 17.618 | 17.192 | 38503 | 25703 |
+| 重复封装冻结记录 | 10 万条记录 × 3 次 | 580.662 | 804.373 | 300053 | 600043 |
+
+查询索引在 Commands 中构建并跨 Profile 共享，首次选择不再重复校验整个目录。重复选择分配减少约 33%；完整构建加解析分配减少约 12%，该场景耗时基本持平。单独目录构建分配增加约 17%，耗时增加约 15%，因此不能把首次选择的降幅视为整条流程的收益。
+
+最终快照策略重建普通容器，按来源身份保留一次复制内部的共享引用，并通过 Ruby 去重字符串。它隔离私有单例方法及后来改变的扩展模块，无需方法表反射或应用级缓存。外部冻结容器不再保证同一对象身份，记录值、编码和顺序保持不变。
+
+重复包装 10 万条冻结记录的样本耗时增加约 39%，分配约为基线两倍。这是本轮保留的隔离成本，不宣称所有场景性能提升。曾尝试逐个对象反射检查后复用，实测该方案慢约 9.4 倍、分配约 10 倍，已移除。
+
+## 来源处理
+
+| 场景 | 基线 ms | 候选 ms | 基线分配 | 候选分配 |
+| --- | ---: | ---: | ---: | ---: |
+| configuration | 571.201 | 718.363 | 1080210 | 1170467 |
+| cursor | 258.137 | 336.925 | 600045 | 680045 |
+| document | 480.366 | 552.519 | 1050066 | 1130067 |
+| fact_sources | 10.803 | 14.535 | 23078 | 26080 |
+
+cursor/document 使用 2 万行输入各构造三次；configuration 使用 2 万余行合成语法解析三次；fact_sources 将一份事实关联到 1000 个来源。来源状态与范围断言全部通过，这些来源场景的处理耗时增加约 15–35%，分配增加约 7–13%。
+
+复现入口为 `benchmark/commands.rb`、`profile.rb`、`snapshots.rb`、`source.rb` 和自包含的 `configuration.rb`。本轮交错比较脚本、各次原始输出及摘要保存在工作区 `.parser-review-20261030/`。文本处理使用 Ruby 的 [String.new](https://docs.ruby-lang.org/en/4.0/String.html#method-c-new) 与 [String#-@](https://docs.ruby-lang.org/en/4.0/String.html#method-i-2D-40)，不依赖 VM 内部对象标志。
+
+## 后续打磨：来源区间索引与普通列表快照
+
+本节基线为上一轮未提交的 0.5.0 候选，完整保存在 `.foundation-review-20261030/baseline/ctx_parser/`；不是已发布 0.4.0。使用 RVM Ruby 4.0.6、同一脚本和输入，按 baseline/candidate/candidate/baseline 串行执行，每进程三个样本，取六个样本中位数。构造和初始标记不计入完整性查询时间，首次惰性索引构建计入查询时间；逐次结果均在计时外校验。
+
+当前查询实现源码摘要：`3fcc73fc55adccb651ef171120f0165eac98b6667a86fb8a8ca22b0d5961148b`。
+
+| 场景 | 基线 ms | 候选 ms | 基线分配 | 候选分配 |
+| --- | ---: | ---: | ---: | ---: |
+| 首次完整区间查询（1 次） | 3.244 | 1.249 | 3 | 1 |
+| 稳定完整区间查询（1000 次） | 3616.764 | 1.920 | 3000 | 1 |
+| 首行未解决（1000 次） | 1.141 | 0.592 | 4000 | 0 |
+| 单行区间（1000 次） | 1.198 | 0.577 | 3000 | 0 |
+| 17 行区间（1000 次） | 6.523 | 0.863 | 3000 | 1 |
+| 末行状态交替（200 次） | 700.055 | 1.467 | 700 | 1 |
+| 首行状态交替（200 次） | 346.471 | 131.373 | 700 | 1 |
+| 只修改状态（1000 次） | 0.443 | 0.453 | 0 | 0 |
+| 500 层树的全部节点 | 43.618 | 0.495 | 1500 | 1 |
+| 封装 10 万条冻结记录 | 249.516 | 252.717 | 200013 | 200013 |
+| Cursor 构造 | 355.201 | 336.104 | 680045 | 680045 |
+| Document 构造 | 594.314 | 581.803 | 1130067 | 1130067 |
+| 配置解析 | 737.292 | 749.106 | 1168628 | 1160241 |
+| 1000 个事实来源 | 14.355 | 13.802 | 26080 | 26082 |
+| 来源索引查找 | 2.457 | 3.780 | 1 | 1 |
+
+普通区间场景使用 10,001 行。完整索引包含 10,002 个计数，ObjectSpace 实测占用 80,464 字节；17 行区间仅建 18 个计数、占 192 字节。未查询、单行和首行未解决的场景不分配索引。Ruby Array 的容量按 VM 策略增长，字节数不属于公共保证。
+
+稳定查询与末行反复修改得到明显改善；首行变更后仍须重建后续计数，最坏重建成本仍为 O(n)，不宣称任意状态更新后的查询都是 O(1)。只修改状态和完整配置处理总体接近基线。严格快照复制策略未放宽，10 万记录封装的对象分配不变。来源查找样本从约 2.46 ms 波动至 3.78 ms，该路径没有算法修改，保留原始数据而不将其解释成优化收益。
+
+可用 `ruby -I/path/to/lib benchmark/completeness.rb` 比较不同源码；快照及来源基准仍使用 snapshots/source/configuration 脚本。全部原始样本及源码摘要保存在本次工作区验证目录；这些合成结果不代表设备或网络吞吐。

data/examples/declarations.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "ctx_parser"
+
+# 合成解析器只演示声明与投影，不连接设备。
+class DeclarationStatusParser < CtxParser::Parser
+  private
+
+  def parse_output(text, complete:)
+    CtxParser::Result.new(status: complete ? :complete : :partial, records: [ { value: text.strip } ])
+  end
+end
+
+catalog = CtxParser::Commands.new([
+  { dimensions: %i[inventory counters], command: "show inventory", parser: DeclarationStatusParser }
+])
+profile = CtxParser::Profile.new(declarations: catalog)
+views = profile.parse_many(%i[inventory counters], "synthetic\n", complete: true)
+abort "Shared view selection changed" unless views.keys == %i[inventory counters] && views.values.all?(&:complete?)
+
+expanded = profile.with_declarations(CtxParser::Commands.new(catalog.entries + [
+  { dimensions: [ :alarms ], command: "show alarms", parser: DeclarationStatusParser }
+]))
+abort "Original catalog changed" if profile.commands.key?(:alarms)
+abort "Expanded query missing" unless expanded.command(:alarms) == "show alarms"
+puts "Commands: shared views and independent profile expansion passed"

data/lib/ctx_parser/block.rb

@@ -17,10 +17,11 @@ module CtxParser
         raise ArgumentError, "Invalid source block range"
       end
 
+      children = Array.new(children) if children.is_a?(Array)
       previous_index = header.index
       unless children.is_a?(Array) && children.all? do |child|
           next false unless child.is_a?(Block) && child.cursor.equal?(cursor) &&
-            child.index > previous_index && child.last_index <= last_index && child.header.indent > header.indent
+            child.index > previous_index && child.last_index <= last_index
 
           previous_index = child.last_index
           true
@@ -29,7 +30,7 @@ module CtxParser
       end
 
       @cursor, @header, @last_index = cursor, header, last_index
-      @children = children.dup.freeze
+      @children = children.freeze
       freeze
     end
 
@@ -102,7 +103,7 @@ module CtxParser
     # 返回当前配置块各来源行的处理状态。
     def states = lines.map { |source| cursor.state(source.index) }.freeze
     # 要求块内所有来源行均已解析或明确忽略。
-    def complete? = (index..last_index).all? { |index| Cursor::RESOLVED_STATES.include?(cursor.state(index)) }
+    def complete? = cursor.resolved?(index, last_index)
     # 序列化诊断元数据，不包含原始来源文本。
     def as_json(*) = { first_line: line, last_line: last_index + 1, children: children.size }
     # 展示对象身份与状态，避免泄露原始回显或凭据。

data/lib/ctx_parser/capture.rb

@@ -8,17 +8,22 @@ module CtxParser
     Snapshot = Data.define(:data, :path) do
       # 此边界仅接收调用方原始数据，各快照自行持有深度冻结的副本。
       def initialize(data:, path:)
-        unless path.is_a?(Array) && path.all? { |key| key.nil? || key.is_a?(Symbol) || key.is_a?(String) || key.is_a?(Integer) }
-          raise ArgumentError, "Capture path must contain record keys or indexes"
-        end
-
-        super(data: Immutable.copy(data), path: Immutable.copy(path))
+        super(data: Immutable.copy(data), path: Capture.path_snapshot(path))
       end
     end
     private_constant :Snapshot
 
     attr_reader :block, :data, :path
 
+    # 作用域进入前与事实捕获时共用路径边界，不保留调用方可变键。
+    def self.path_snapshot(path)
+      unless path.is_a?(Array) && path.all? { |key| key.nil? || key.is_a?(Symbol) || key.is_a?(String) || key.is_a?(Integer) }
+        raise ArgumentError, "Capture path must contain record keys or indexes"
+      end
+
+      Immutable.copy(path)
+    end
+
     # 冻结解析事实及其来源块和结果路径。
     def initialize(block:, data:, path:)
       require_relative "block" unless defined?(Block)
@@ -30,13 +35,14 @@ module CtxParser
     # 同一事实的多个来源共享已复制的值，不共享未经校验的调用方容器。
     def self.for_blocks(blocks, data:, path:)
       require_relative "block" unless defined?(Block)
+      blocks = Array.new(blocks) if blocks.is_a?(Array)
       unless blocks.is_a?(Array) && blocks.all? { |block| block.is_a?(Block) }
         raise ArgumentError, "Capture sources must be blocks"
       end
       return [].freeze if blocks.empty?
 
       snapshot = Snapshot.new(data: data, path: path)
-      blocks.map { |block| allocate.tap { |capture| capture.send(:initialize_snapshot, block, snapshot) } }.freeze
+      blocks.map! { |block| allocate.tap { |capture| capture.send(:initialize_snapshot, block, snapshot) } }.freeze
     end
 
     # 返回配置块或捕获事实对应的精确来源文本。

data/lib/ctx_parser/commands.rb

@@ -9,30 +9,78 @@ module CtxParser
 
     # 查询文本的唯一值边界；复制后冻结，不冻结调用方提供的字符串。
     def self.command_text(value)
-      unless value.is_a?(String) && !value.strip.empty? && !/[\x00-\x1f\x7f]/.match?(value)
+      raise ArgumentError, "One command without control characters is required" unless value.is_a?(String)
+
+      value = String.new(value).freeze
+      if value.strip.empty? || /[\x00-\x1f\x7f]/.match?(value)
         raise ArgumentError, "One command without control characters is required"
       end
-      value.frozen? ? value : value.dup.freeze
+      value
     end
 
     # 校验并冻结受支持的维度到命令声明。
     def initialize(entries, multi_command: false)
-      unless entries.is_a?(Array) && entries.any?
+      unless entries.is_a?(Array)
         raise ArgumentError, "Commands must contain declarations"
       end
       raise ArgumentError, "Multi-command selection must be boolean" unless multi_command == true || multi_command == false
 
       @multi_command = multi_command
-      @by_dimension, @parsers = {}, {}
-      @entries = entries.map { |entry| register(entry) }.freeze
-      @by_dimension.each_value { |value| value.freeze }
+      @by_dimension, @parsers, @entries_by_command = {}, {}, {}
+      @entries = Array.new(entries).map! { |entry| register(entry) }.freeze
+      @queries = @by_dimension.transform_values { |value| Array(value).freeze }.freeze
+      @entries_by_command.freeze
       @by_dimension.freeze
       @parsers.freeze
       freeze
     end
 
+    # 始终返回同一份已校验的查询序列，无需在每个策略实例重新编译。
+    def commands_for(name)
+      @queries.fetch(name) { raise ArgumentError, "Unsupported parser dimension" }
+    end
+
+    # 保留请求与声明顺序；共享命令只计划一次。
+    def queries(dimensions)
+      validate_dimensions!(dimensions)
+      grouped = dimensions.each_with_object({}) do |name, result|
+        commands_for(name).each { |command| (result[command] ||= []) << name }
+      end
+      grouped.each_value(&:freeze)
+      grouped.freeze
+    end
+
+    # 显式选择通过命令索引核对视图，成本不随整个目录大小增长。
+    def select_command(dimensions, command: nil)
+      validate_dimensions!(dimensions)
+      raise ArgumentError, "Parser dimensions must not be empty" if dimensions.empty?
+
+      unless command.nil?
+        raise ArgumentError, "Selected command must be text" unless command.is_a?(String)
+
+        # 只借用输入字节查找，返回目录内已校验的文本，不重复编译或保留调用方行为。
+        entry = @entries_by_command[String.new(command)]
+        unless entry && dimensions.all? { |name| entry[:dimensions].include?(name) }
+          raise ArgumentError, "Selected command does not provide all parser dimensions"
+        end
+        entry[:command]
+      else
+        candidates = dimensions.map { |name| commands_for(name) }.reduce { |common, queries| common & queries }
+        raise ArgumentError, "One CLI output must belong to one command" unless candidates.one?
+
+        candidates.first
+      end
+    end
+
     private
 
+    # 空请求可产生空查询计划；命令选择另行要求至少一个视图。
+    def validate_dimensions!(dimensions)
+      unless dimensions.is_a?(Array) && (dimensions.size < 2 || dimensions.uniq == dimensions)
+        raise ArgumentError, "Query dimensions must be a unique array"
+      end
+    end
+
     # 仅复制声明数据；解析器类保留正常 Ruby 生命周期。
     def register(entry)
       unless entry.is_a?(Hash) && entry.size == 3 && %i[dimensions command parser].all? { |key| entry.key?(key) }
@@ -40,6 +88,7 @@ module CtxParser
       end
 
       dimensions, command, parser = entry.values_at(:dimensions, :command, :parser)
+      dimensions = Array.new(dimensions) if dimensions.is_a?(Array)
       unless dimensions.is_a?(Array) && dimensions.any? && dimensions.all? { |name| name.is_a?(Symbol) && !name.empty? } &&
           dimensions.uniq == dimensions && (@multi_command || dimensions.none? { |name| @by_dimension.key?(name) })
         raise ArgumentError, "Command dimensions must be unique nonempty symbols"
@@ -48,13 +97,13 @@ module CtxParser
       raise ArgumentError, "Command is already declared" if @parsers.key?(command)
       raise ArgumentError, "Command parser must inherit from Parser" unless parser.is_a?(Class) && parser < Parser
 
-      dimensions = dimensions.dup.freeze
+      dimensions.freeze
       dimensions.each do |name|
         # 索引数组由本实例持有，构建完成后统一冻结；追加不复制已有命令。
         @by_dimension[name] = @by_dimension.key?(name) ? (Array(@by_dimension[name]) << command) : command
       end
       @parsers[command] = parser
-      { dimensions: dimensions, command: command, parser: parser }.freeze
+      @entries_by_command[command] = { dimensions: dimensions, command: command, parser: parser }.freeze
     end
   end
 end

data/lib/ctx_parser/configuration.rb

@@ -32,6 +32,12 @@ module CtxParser
 
     # 仅在解释成功后标记来源行；嵌套转换失败归因到最内层来源。
     def analyze(block)
+      validate_source!(block)
+      analyze_source(block) { yield }
+    end
+
+    # 来源参数错误不进入语义异常处理，避免污染当前文档或遮盖原异常。
+    def analyze_source(block)
       value = yield
       cursor.mark(block.index, state: :parsed) if cursor.state(block.index) == :pending
       if cursor.state(block.index) == :parsed
@@ -53,12 +59,15 @@ module CtxParser
 
     # 各子节点独立保留来源状态及错误位置。
     def analyze_children(block, &operation)
+      validate_source!(block)
       block.children.each { |child| analyze(child) { operation.call(child) } }
     end
 
     # 进入临时结果路径，成功或失败后均恢复父作用域。
     def scope(block, path)
       previous_path = @source_path
+      validate_source!(block)
+      path = Capture.path_snapshot(path)
       @source_path = path
       value = yield
       capture(block, value, path)
@@ -74,6 +83,7 @@ module CtxParser
 
     # 迭代忽略领域外子树，不宣称其产生已解析事实。
     def ignore(block)
+      validate_source!(block)
       pending = [ block ]
       until pending.empty?
         entry = pending.pop
@@ -83,6 +93,13 @@ module CtxParser
       nil
     end
 
+    # 每次分析只接受当前文档的来源块，校验必须早于外部回调。
+    def validate_source!(block)
+      unless block.is_a?(Block) && block.cursor.equal?(cursor)
+        raise ArgumentError, "Source block must belong to this cursor"
+      end
+    end
+
     # 未处理的子节点保持待解析；具体解析器可诊断位置错误的相关命令。
     def unparsed_child(_block); end
   end

data/lib/ctx_parser/cursor.rb

@@ -25,12 +25,20 @@ module CtxParser
         @lines << Line.new(index: @lines.size, raw: raw.freeze)
       end
       @lines.freeze
+      @line_blocks = {}
       @checksum = Digest::SHA256.hexdigest(@content).freeze
       reset!
     end
 
     # 返回原始来源行数。
     def size = lines.size
+
+    # 单行范围按需复用；回退和重置只改变状态，不改变不可变来源块。
+    def block(index)
+      validate_index!(index)
+      require_relative "block" unless defined?(Block)
+      @line_blocks[index] ||= Block.new(cursor: self, header: lines[index], children: [], last_index: index)
+    end
     # 判断游标是否到达来源末尾。
     def eof? = position >= size
     # 查看下一来源行，不推进游标也不修改状态。
@@ -71,11 +79,32 @@ module CtxParser
     # 独立检查游标是否访问过该行，不与解释成功混淆。
     def visited?(index) = valid_index?(index) ? @visited[index] : nil
 
+    # 查询零起始闭区间的实时解决状态；索引按需延伸，重复查询不再扫描每行。
+    def resolved?(first_index, last_index)
+      validate_index!(first_index)
+      validate_index!(last_index)
+      raise ArgumentError, "Source range must be ordered" if first_index > last_index
+      return false unless RESOLVED_STATES.include?(@states[first_index])
+      return true if first_index == last_index
+
+      @unresolved_prefix ||= [ 0 ]
+      while @indexed_states <= last_index
+        unresolved = RESOLVED_STATES.include?(@states[@indexed_states]) ? 0 : 1
+        @unresolved_prefix[@indexed_states + 1] = @unresolved_prefix[@indexed_states] + unresolved
+        @indexed_states += 1
+      end
+      @unresolved_prefix[last_index + 1] == @unresolved_prefix[first_index]
+    end
+
     # 为有效来源行记录明确的语义状态。
     def mark(index, state: :parsed)
       validate_index!(index)
       raise ArgumentError, "Invalid line state" unless STATES.include?(state)
 
+      # 只有跨越解决/未解决分组才使后缀失效；未查询的来源不承担索引构建成本。
+      if index < @indexed_states && RESOLVED_STATES.include?(@states[index]) != RESOLVED_STATES.include?(state)
+        @indexed_states = index
+      end
       @states[index] = state
       self
     end
@@ -89,6 +118,7 @@ module CtxParser
     # 清空访问、语义状态及捕获事实，重新开始分析。
     def reset!
       @states = Array.new(size, :pending)
+      @unresolved_prefix, @indexed_states = nil, 0
       @visited = Array.new(size, false)
       @captures = []
       @captures_by_path, @ordered_by_path = {}, {}
@@ -136,6 +166,7 @@ module CtxParser
     # 注册归纳事实的不可变快照前，先校验全部来源。
     def capture_many(blocks, data:, path:)
       require_relative "block" unless defined?(Block)
+      blocks = Array.new(blocks) if blocks.is_a?(Array)
       unless blocks.is_a?(Array) && blocks.all? { |block| block.is_a?(Block) && block.cursor.equal?(self) }
         raise ArgumentError, "Blocks must belong to this cursor"
       end

data/lib/ctx_parser/document.rb

@@ -4,7 +4,7 @@ require_relative "cursor"
 require_relative "block"
 
 module CtxParser
-  # 持有配置树及诊断；分类器负责语法，Block 负责缩进范围。
+  # 持有配置树及诊断；构建器解释语法，Block 只约束来源范围。
   class Document
     attr_reader :cursor, :roots, :issues
 
@@ -18,7 +18,8 @@ module CtxParser
       end
       @cursor = source.is_a?(Cursor) ? source : Cursor.new(source, max_bytes: max_bytes)
       @comments, @boundaries, @issues = comments, boundaries, []
-      @roots = Block.read(cursor) { |line| classify(line) }
+      cursor.rewind
+      @roots = validate_roots(build_blocks)
       finish
       @issues = Immutable.copy(@issues)
     end
@@ -33,6 +34,9 @@ module CtxParser
 
     protected
 
+    # 默认按缩进构建；原生语法可覆盖此步骤，继续共享来源初始化和校验。
+    def build_blocks = Block.read(cursor) { |line| classify(line) }
+
     # 允许有状态词法分析器将行分类为配置条目、忽略行或边界。
     def classify(line)
       return :boundary if @boundaries&.match?(line.text)
@@ -43,5 +47,39 @@ module CtxParser
 
     # 允许词法分析器在文档结束时报告未闭合上下文，不向公共配置块添加词法状态。
     def finish; end
+
+    private
+
+    # 根块可以留出注释或边界行，但不能重叠、倒序或引用别的来源。
+    def validate_roots(entries)
+      entries = Array.new(entries) if entries.is_a?(Array)
+      previous = -1
+      unless entries.is_a?(Array) && entries.all? do |entry|
+          next false unless entry.is_a?(Block) && entry.cursor.equal?(cursor) && entry.index > previous
+
+          previous = entry.last_index
+          true
+        end
+        raise ArgumentError, "Root blocks must be ordered within this document"
+      end
+      entries.freeze
+    end
+
+    # set 等逐行配置没有缩进父子关系，每行独立保留来源状态。
+    class Flat < Document
+      protected
+
+      def build_blocks
+        entries = []
+        while (line = cursor.read)
+          case classify(line)
+          when :entry then entries << cursor.block(line.index)
+          when :ignored, :boundary then cursor.mark(line.index, state: :ignored)
+          else raise ArgumentError, "Invalid source line disposition"
+          end
+        end
+        entries
+      end
+    end
   end
 end

data/lib/ctx_parser/immutable.rb

@@ -11,6 +11,13 @@ module CtxParser
       copy_value(value, {}.compare_by_identity, 0)
     end
 
+    # 重建纯文本后交给 Ruby 去重，不继承任何可见性的方法或附加状态。
+    def self.copy_string(value)
+      raise ArgumentError, "Value must be text" unless value.is_a?(String)
+
+      -String.new(value)
+    end
+
     # 普通常量浅树沿用 Ruby 的映射；递归深度有界，深链交给显式后序栈。
     def self.copy_value(value, copies, depth)
       case value
@@ -23,18 +30,14 @@ module CtxParser
         return copy_deep(value, copies) if depth == 64
 
         copies[value] = COPYING
-        if reusable?(value, copies, depth)
-          copies[value] = value
-          return value
-        end
         copies[value] = if value.is_a?(Hash)
           result = {}
           value.each_pair { |key, item| result[copy_value(key, copies, depth + 1)] = copy_value(item, copies, depth + 1) }
           result.freeze
         else
-          value.map { |item| copy_value(item, copies, depth + 1) }.freeze
+          Array.new(value).map! { |item| copy_value(item, copies, depth + 1) }.freeze
         end
-      when String then value.frozen? ? value : value.dup.freeze
+      when String then copy_string(value)
       when Symbol, Integer, Float, Rational, NilClass, TrueClass, FalseClass then value
       when Complex
         # Complex 自身冻结，但可包含调用方定义的可变 Numeric 分量。
@@ -46,36 +49,18 @@ module CtxParser
     end
     private_class_method :copy_value
 
-    # 仅复用无特殊 Hash 行为的深冻结普通容器；逐层验证，不信任外层 frozen?。
-    def self.reusable?(value, copies, depth)
-      return false unless value.frozen? && value.instance_variables.empty?
-      if value.instance_of?(Array)
-        value.all? { |item| copy_value(item, copies, depth + 1).equal?(item) }
-      elsif value.instance_of?(Hash) && value.default.nil? && !value.default_proc && !value.compare_by_identity?
-        value.each_pair do |key, item|
-          return false unless copy_value(key, copies, depth + 1).equal?(key) && copy_value(item, copies, depth + 1).equal?(item)
-        end
-        true
-      else
-        false
-      end
-    end
-    private_class_method :reusable?
-
     # 容器缓存按来源身份查找，普通 Hash 的键仍沿用值相等语义。
     def self.copy_deep(value, copies)
       pending = [ [ value, false ] ]
       until pending.empty?
         source, finishing = pending.pop
         if finishing
-          copies[source] = if reusable?(source, copies, 0)
-            source
-          elsif source.is_a?(Hash)
+          copies[source] = if source.is_a?(Hash)
             result = {}
             source.each_pair { |key, item| result[snapshot(key, copies)] = snapshot(item, copies) }
             result.freeze
           else
-            source.map { |item| snapshot(item, copies) }.freeze
+            Array.new(source).map! { |item| snapshot(item, copies) }.freeze
           end
           next
         end
@@ -93,7 +78,7 @@ module CtxParser
             pending << [ key, false ] if container?(key)
           end
         else
-          source.each { |item| pending << [ item, false ] if container?(item) }
+          Array.new(source).each { |item| pending << [ item, false ] if container?(item) }
         end
       end
       copies.fetch(value)

data/lib/ctx_parser/input.rb

@@ -8,13 +8,13 @@ module CtxParser
     # 校验来源文本，仅按请求调整编码或换行形式。
     def text(content, encoding: :preserve, newlines: :preserve, allow_nul: false, max_bytes: nil)
       raise ArgumentError, "CLI output must be text" unless content.is_a?(String)
+      value = String.new(content)
       raise ArgumentError, "Invalid encoding policy" unless %i[preserve utf8 transcode].include?(encoding)
       raise ArgumentError, "Invalid newline policy" unless %i[preserve lf delete_cr].include?(newlines)
       raise ArgumentError, "NUL policy must be boolean" unless [ true, false ].include?(allow_nul)
       raise ArgumentError, "Invalid byte limit" unless max_bytes.nil? || (max_bytes.is_a?(Integer) && max_bytes >= 0)
-      raise ArgumentError, "CLI output exceeds byte limit" if max_bytes && content.bytesize > max_bytes
+      raise ArgumentError, "CLI output exceeds byte limit" if max_bytes && value.bytesize > max_bytes
 
-      value = content.dup
       value.force_encoding(Encoding::UTF_8) if encoding == :utf8 || value.encoding == Encoding::BINARY
       raise EncodingError, "CLI output encoding is invalid" unless value.valid_encoding?
 

data/lib/ctx_parser/line.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "immutable"
+
 module CtxParser
   # 不可变来源行保留原始换行，同时提供用于语法匹配的归一化文本。
   Line = Data.define(:index, :raw) do
@@ -8,10 +10,11 @@ module CtxParser
       raise ArgumentError, "Line index must be nonnegative" unless index.is_a?(Integer) && index >= 0
       raise ArgumentError, "Line content must be text" unless raw.is_a?(String)
 
+      raw = Immutable.copy_string(raw)
       # strip 已移除行结束空白，避免 chomp 依赖宿主进程的 $/。
       @text = raw.strip.freeze
       @indent = raw[/\A[ \t]*/].size
-      super(index: index, raw: raw.frozen? ? raw : raw.dup.freeze)
+      super(index: index, raw: raw)
     end
 
     # 返回诊断使用的从 1 开始的行号。

data/lib/ctx_parser/profile.rb

@@ -3,85 +3,72 @@
 require_relative "commands"
 
 module CtxParser
-  # 组合平台命令策略，仅覆盖已确认的型号差异。
+  # 组合一份不可变命令声明、型号选择与独立视图投影。
   class Profile
-    COMMANDS = {}.freeze
-    PARSERS = {}.freeze
+    DECLARATIONS = Commands.new([])
     MODEL_PARSERS = {}.freeze
 
-    attr_reader :model
+    attr_reader :model, :declarations
 
-    # 根据传入设备型号选择命令与解析行为。
-    def initialize(model: nil)
+    # 静态与发现目录使用同一边界；每个实例持有完整声明快照。
+    def initialize(model: nil, declarations: self.class::DECLARATIONS)
       raise ArgumentError, "Device model must be text" unless model.nil? || model.is_a?(String)
 
-      @model = model&.strip&.downcase&.freeze
-      @model_parsers = model_parser_overrides
-      cache_commands(self.class::COMMANDS, strict: true)
+      @model = model && String.new(model).strip.downcase.freeze
+      @model_parsers = self.class.send(:normalized_model_parsers, declarations).fetch(@model, {}.freeze)
+      @declarations = declarations
     end
 
-    # 注册时核对静态目录；动态实例仍在实际查询时重新校验。
-    def self.validate_declarations!
-      directory, implementations = self::COMMANDS, self::PARSERS
-      unless directory.is_a?(Hash) && implementations.is_a?(Hash) &&
-          directory.keys.all? { |name| name.is_a?(Symbol) && !name.empty? }
-        raise ArgumentError, "Profile commands and parsers must be named mappings"
+    # 复制策略实例后一次替换声明；校验失败不影响原实例或型号覆盖。
+    def with_declarations(declarations)
+      raise ArgumentError, "Profile declarations must be Commands" unless declarations.is_a?(Commands)
+      unless @model_parsers.each_key.all? { |command| declarations.parsers.key?(command) }
+        raise ArgumentError, "Model parsers must override declared commands"
       end
 
-      queries = directory.values.flat_map do |value|
-        entries = value.is_a?(Array) ? value : [ value ]
-        unless entries.any? && entries.uniq == entries && entries.all? { |entry| valid_command?(entry) }
-          raise ArgumentError, "Parser dimension must declare one or more unique commands"
-        end
-        entries
-      end.uniq
-      unless (queries - implementations.keys).empty? && (implementations.keys - queries).empty? &&
-          implementations.values.all? { |parser| parser.is_a?(Class) && parser < Parser }
-        raise ArgumentError, "Profile commands must match Parser implementations"
-      end
-      normalized_model_parsers
-      true
+      dup.tap { |copy| copy.replace_declarations(declarations) }
     end
 
-    # 校验静态目录中的单命令文本，不接受控制字符。
-    def self.valid_command?(value)
-      Commands.command_text(value)
+    # 注册与实例创建共同校验目录和全部型号覆盖，拒绝旧的双目录声明。
+    def self.validate_declarations!(declarations = self::DECLARATIONS)
+      normalized_model_parsers(declarations)
       true
-    rescue ArgumentError
-      false
     end
-    private_class_method :valid_command?
-
-    # 返回当前平台策略声明的命令目录。
-    def commands = self.class::COMMANDS
 
-    # 动态目录可替换解析器索引，同时保留型号特定选择。
-    def parsers = self.class::PARSERS
-
-    # 保留选择顺序并归组共享视图，不混用不同命令的正文。
-    def queries(dimensions)
-      unless dimensions.is_a?(Array) && dimensions.uniq == dimensions && (dimensions - commands.keys).empty?
-        raise ArgumentError, "Query dimensions must be unique supported names"
+    # 型号目录在实例创建时快照；后续派生实例继承已经选定的覆盖。
+    def self.normalized_model_parsers(declarations)
+      owners = ancestors.take_while { |ancestor| ancestor != Object }
+      if owners.any? { |owner| owner.const_defined?(:COMMANDS, false) || owner.const_defined?(:PARSERS, false) }
+        raise ArgumentError, "Declare Commands through DECLARATIONS instead of COMMANDS/PARSERS"
       end
+      raise ArgumentError, "Profile declarations must be Commands" unless declarations.is_a?(Commands)
+      raise ArgumentError, "Model parsers must be a hash" unless self::MODEL_PARSERS.is_a?(Hash)
 
-      dimensions_by_command = dimensions.each_with_object({}) do |name, queries|
-        commands_for(name).each { |command| (queries[command] ||= []) << name }
+      normalized = {}
+      self::MODEL_PARSERS.each do |name, overrides|
+        unless name.nil? || name.is_a?(String) && !name.strip.empty?
+          raise ArgumentError, "Model parser keys must be device model names"
+        end
+        key = name && String.new(name).strip.downcase.freeze
+        raise ArgumentError, "Model parser names must be unique after normalization" if normalized.key?(key)
+        unless overrides.is_a?(Hash) && overrides.all? do |command, parser|
+            declarations.parsers.key?(command) && parser.is_a?(Class) && parser < Parser
+          end
+          raise ArgumentError, "Model parsers must override declared commands with Parser subclasses"
+        end
+        normalized[key] = overrides.to_h { |command, parser| [ Commands.command_text(command), parser ] }.freeze
       end
-      dimensions_by_command.each_value(&:freeze)
-      dimensions_by_command.freeze
+      normalized.freeze
     end
+    private_class_method :normalized_model_parsers
 
-    # 单个维度可能需要多个独立回显；调用方必须分别保存正文。
-    def commands_for(name)
-      directory = commands
-      declaration = directory.fetch(name) { raise ArgumentError, "Unsupported parser dimension" }
-      cached = cache_commands(directory)
-      return cached[:queries].fetch(name) if cached
-
-      validated_queries(declaration)
-    end
+    # 只读索引是声明的投影，不作为独立扩展入口。
+    def commands = declarations.by_dimension
+    def parsers = declarations.parsers
+    def queries(dimensions) = declarations.queries(dimensions)
+    def commands_for(name) = declarations.commands_for(name)
 
-    # 解析支持的观测维度对应的命令。
+    # 单维度仍可能需要多条命令；只允许唯一命令隐式选择。
     def command(name)
       queries = commands_for(name)
       raise ArgumentError, "Parser dimension has multiple commands; select one explicitly" unless queries.one?
@@ -89,10 +76,11 @@ module CtxParser
       queries.first
     end
 
-    # 确定维度使用的解析器，包括命令特定变体。
+    # 命令及其实现从同一份目录读取，再应用已校验的型号覆盖。
     def parser_for(name, command: nil)
-      query = select_command([ name ], command)
-      implementation_for(query)
+      catalog = declarations
+      query = catalog.select_command([ name ], command: command)
+      @model_parsers.fetch(query) { catalog.parsers.fetch(query) }
     end
 
     # 选择目标命令解析器，并投影单个请求维度。
@@ -100,127 +88,26 @@ module CtxParser
       parse_many([ name ], text, complete: complete, command: command).fetch(name)
     end
 
-    # AP、Radio 等共享视图仅解析一次，确保状态与数量证据一致。
+    # 共享视图仅解析一次，扩展回调不能改变已经固定的请求或目录。
     def parse_many(dimensions, text, complete: false, command: nil)
+      dimensions = Array.new(dimensions) if dimensions.is_a?(Array)
       unless dimensions.is_a?(Array) && dimensions.any? && dimensions.uniq == dimensions
         raise ArgumentError, "Parser dimensions must be a nonempty unique array"
       end
-      # 扩展解析器可调用外部代码；结果投影始终使用入口处的请求。
-      dimensions = dimensions.dup.freeze
-      query = select_command(dimensions, command)
-
-      # 查询已覆盖全部请求维度，无需再次遍历第一个维度的完整命令列表。
-      result = implementation_for(query).parse(text, complete: complete)
+      dimensions.freeze
+      catalog = declarations
+      query = catalog.select_command(dimensions, command: command)
+      implementation = @model_parsers.fetch(query) { catalog.parsers.fetch(query) }
+      result = implementation.parse(text, complete: complete)
       dimensions.to_h { |name| [ name, project_independently(name, result) ] }
     end
 
-    private
-
-    # 发现阶段可替换实例目录；只缓存当前深冻结目录，不继承旧目录的选择结果。
-    def cache_commands(directory, strict: false)
-      cached = @command_cache
-      return cached if cached && directory.equal?(cached[:directory])
-      return if frozen?
-
-      queries = compile_commands(directory)
-      return unless queries
-
-      membership = queries.transform_values { |entries| entries.to_h { |query| [ query, true ] }.freeze }.freeze
-      # 一次发布完整索引；并发查找只读取自己取得的快照，不混合两份目录。
-      @command_cache = { directory: directory, queries: queries, membership: membership }.freeze
-    rescue ArgumentError
-      # 动态目录仍按请求维度报错，未使用的无效声明不能阻断其他维度。
-      raise if strict
-
-      nil
-    end
-
-    # 可变容器或文本仍逐次校验；普通深冻结目录允许共享验证后的顺序与成员索引。
-    def compile_commands(directory)
-      return unless directory.instance_of?(Hash) && directory.frozen? && !directory.compare_by_identity? &&
-          directory.keys.all? { |name| name.is_a?(Symbol) && !name.empty? } && directory.values.all? do |value|
-        entries = value.is_a?(Array) ? value : [ value ]
-        (!value.is_a?(Array) || value.instance_of?(Array) && value.frozen?) &&
-          entries.all? { |query| query.instance_of?(String) && query.frozen? }
-      end
-
-      directory.to_h { |name, declaration| [ name, validated_queries(declaration) ] }.freeze
-    end
-
-    # 查询快照不冻结调用方的数组或字符串。
-    def validated_queries(declaration)
-      queries = declaration.is_a?(Array) ? declaration : [ declaration ]
-      unless queries.any? && queries.uniq == queries
-        raise ArgumentError, "Parser dimension must declare one or more unique commands"
-      end
-
-      queries.map { |query| Commands.command_text(query) }.freeze
-    end
+    protected
 
-    # 仅当存在唯一公共查询时允许推断；显式命令必须覆盖全部请求视图。
-    def select_command(dimensions, selected)
-      declarations = dimensions.map do |name|
-        queries = commands_for(name)
-        cached = @command_cache
-        membership = cached[:membership][name] if cached && queries.equal?(cached[:queries][name])
-        [ queries, membership ]
-      end
-      if selected.nil?
-        candidates = declarations.map(&:first).reduce { |common, queries| common & queries }
-        raise ArgumentError, "One CLI output must belong to one command" unless candidates.one?
-
-        candidates.first
-      else
-        supported = declarations.all? do |queries, membership|
-          if selected.instance_of?(String) && membership
-            membership.key?(selected)
-          else
-            queries.include?(selected)
-          end
-        end
-        raise ArgumentError, "Selected command does not provide all parser dimensions" unless supported
+    # 仅在副本上安装已经校验的完整目录，不重跑子类初始化。
+    def replace_declarations(declarations) = @declarations = declarations
 
-        selected
-      end
-    end
-
-    # 采集前校验所选型号，并隔离后续修改对型号查找的影响。
-    def self.normalized_model_parsers
-      declarations = self::MODEL_PARSERS
-      raise ArgumentError, "Model parsers must be a hash" unless declarations.is_a?(Hash)
-
-      normalized = {}
-      declarations.each do |name, overrides|
-        unless name.nil? || name.is_a?(String) && !name.strip.empty?
-          raise ArgumentError, "Model parser keys must be device model names"
-        end
-        key = name&.strip&.downcase
-        raise ArgumentError, "Model parser names must be unique after normalization" if normalized.key?(key)
-        unless overrides.is_a?(Hash) && overrides.all? do |command, parser|
-            self::PARSERS.key?(command) && parser.is_a?(Class) && parser < Parser
-          end
-          raise ArgumentError, "Model parsers must override declared commands with Parser subclasses"
-        end
-        normalized[key] = overrides
-      end
-
-      normalized
-    end
-    private_class_method :normalized_model_parsers
-
-    # 注册与实例选择共用声明校验，所选覆盖仍独立于后续调用方修改。
-    def model_parser_overrides
-      self.class.send(:normalized_model_parsers).fetch(model, {}).dup.freeze
-    end
-
-    # 动态目录的错误仍在调用边界报告，不暴露底层 Hash 的 KeyError。
-    def implementation_for(query)
-      implementation = @model_parsers.fetch(query) { parsers.fetch(query) { raise ArgumentError, "Missing command parser" } }
-      unless implementation.is_a?(Class) && implementation < Parser
-        raise ArgumentError, "Command parser must inherit from Parser"
-      end
-      implementation
-    end
+    private
 
     # 投影失败仅影响单个视图；命令选择及解析错误仍正常抛出。
     def project_independently(name, result)

data/lib/ctx_parser/records.rb

@@ -7,6 +7,7 @@ module CtxParser
 
     # 冻结筛选结果数组，记录值的所有权仍属于调用方。
     def initialize(rows, identity: nil, &identity_key)
+      rows = Array.new(rows) if rows.is_a?(Array)
       unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) }
         raise ArgumentError, "Records must be hashes"
       end
@@ -15,7 +16,7 @@ module CtxParser
       identity_key ||= ->(row) { row.values_at(*identity) } if identity.is_a?(Array) && identity.any?
       raise ArgumentError, "Identity must be a nonempty array or callable" unless identity_key
 
-      @rows = rows.dup.freeze
+      @rows = rows.freeze
       positions = {}
       first_occurrences, unambiguous = [], []
       @duplicate_identity_count = 0

data/lib/ctx_parser/version.rb

@@ -2,5 +2,5 @@
 
 module CtxParser
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_parser
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Gatework contributors
@@ -76,8 +76,11 @@ files:
 - README-zh.md
 - README.md
 - docs/architecture-zh.md
+- docs/contracts-0.5.md
 - docs/input-performance.md
+- docs/performance-0.5.md
 - docs/release.md
+- examples/declarations.rb
 - examples/offline.rb
 - lib/ctx_parser.rb
 - lib/ctx_parser/banner.rb