netstack 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eddd468b051e3a6fb12facd3f3089ba029bbc6c021adbe3578abfc3c8b50f48e
-  data.tar.gz: 656e01f7922ea127b8c839b4aeaeb26763d27205326861ca13a4a362e4710196
+  metadata.gz: a061a49349ba46f1b10443be9f63d0f33703b101ceb9332f7bdd9b1155c16af7
+  data.tar.gz: b1d581a112546d007308ca9ce0300fe51a974c89c998e0d8c718ced72750e7d0
 SHA512:
-  metadata.gz: 0e78a867a0c0a80c2d01e29198fe2aafe3520d49ddac6f4ab7b07996451db9d539b65573089d281197ab4f93008a41a92699c1b3e491b00b97e631c37d382cd7
-  data.tar.gz: 6ee7a999af13ba478903aaa5a36fbb250f75840a897934fc32450bb78cb3f824f02ea28d3af356128e4b9ab040da88c8b2b8a093d77e493ea7ade1f6173b21ea
+  metadata.gz: 3b761c5cddf8d87887f4ffac0615fc0e3514e3ebe6d25f185e6fba326d6c4cb6a894348db8fcaf8e334f0a2a56f01eb1b073bdb8c5163488921447fde4d999db
+  data.tar.gz: afb5a7bd3f5e2df4ed23e445dea4b1de7df8df7e8590107008ce2dcc134b4018dbf00c23ea427e6f7a511ab4cffc2d80cb5cdc7ce1816912cf46415ebe585bde

data/CHANGELOG.md

@@ -1,5 +1,24 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2021-10-19
+## 0.2.0 — 2026-10-01
 
-- Initial release
+- Replace the legacy 0.1.x API with the standalone Netstack API described in README; this is not a drop-in upgrade.
+- Preserve BlueCat password bytes and compare CNAME targets independently of case and the trailing root dot.
+- Reject overlapping H3C bootstrap access/uplink ranges, unordered ranges and authentication ranges outside the access scope.
+- Require global anycast MAC and bound ACL definitions during VXLAN configuration readback.
+- Merge observed wireless blacklist/whitelist fields by MAC without removing unobserved entries.
+- Reject special files when opening device logs without blocking on FIFOs; add Chinese comments for module ownership and recovery contracts.
+
+- Harden topology description writes with separate durable change/persist steps, artifact identity checks, raw-result preservation and readback-only recovery of uncertain writes. The unreleased apply API now requires a Deployment plan and host checkpoint/resolver.
+- Preserve expected VXLAN fabric coverage and mark unrecognized runtime/wireless output partial; reconcile service-template bindings by case-insensitive identity with explicit AP precedence.
+- Preserve disabled monitoring ownership and clean up circuit triggers by host/side, including repeated recovery; canonicalize backup IPv6 association and reject malformed DDI CIDRs.
+- Reject invalid optional configuration types and ambiguous numeric syntax, bound template work and known-host lock waiting, and keep sensitive configuration out of inspection and error metadata.
+- Index inventory reconciliation and reuse execution identity within each Executor call, preserving output order and receipt serialization.
+
+- Introduce an independent `Netstack` namespace for device connectivity, observations, network business plans and verified execution.
+- Adapt net-connector's single-device sessions, vendor strategies, TextFSM resources, safe backup and redaction contracts; omit Netdisco and fleet orchestration.
+- Reuse ActiveSupport and standard IPAddr; absorb Algosec interval operations and configuration Reader under responsibility-based names.
+- Add typed inventory, routing, wireless, VXLAN, monitoring/circuits, configuration, DDI and backup modules.
+- Separate complete/partial/unsupported observations and host-owned persistence. Require durable checkpoints before remote writes and readback for uncertain execution.
+- Add offline regression, Zeitwerk, lint, package isolation and Ruby/platform CI gates. Live-device and external-service acceptance remain separate.
+- Provide explicit Motor integration for wireless collection, configuration generation/delivery, external backup, and PostgreSQL-backed monitoring/DDI execution with target ownership and durable recovery.

data/{LICENSE.txt → LICENSE}

@@ -1,6 +1,7 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2021 TODO: Write your name
+Copyright (c) 2026 netstack contributors
+Copyright (c) 2026 net-connector contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +10,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/NOTICE

@@ -0,0 +1,25 @@
+Netstack includes adapted device connection code and templates from net-connector.
+Copyright (c) 2026 net-connector contributors. Licensed under the MIT License.
+The original copyright and permission notice is retained in LICENSE.
+
+Domain design draws on local Motor and PDK business implementations. Perl APIs,
+Netdisco integrations, and application authentication are not included.
+
+RangeSet, IPv4 and Configuration::Reader adapt algorithms from the user's
+algosec-rails/lib/algosec tree. The original project is not a runtime dependency.
+Source SHA-256 at adaptation:
+ipaddr.rb: a1287b0e4e87399dfc4becb38982429136c2fb350829c7de6aacfd2e8069bf68
+set.rb: a2bb791073b930e4931e1333ff74ea804c6d5ea71334415a7a74cbe449625c6d
+config/reader.rb: f93f34f37bff121b8321bdb170b6595e8557b2988b7160f4473746144caf3d57
+Netstack uses Ruby IPAddr and granular ActiveSupport extensions. It introduces
+no global IPAddr or Set patch. Reader uses SHA-256, and bare IPv4 "any" denotes
+the entire IPv4 space; these are intentional new APIs, not compatibility aliases.
+
+Configuration scenarios and restricted template syntax adapt Motor's
+backend/app/services/motor/netconf and backend/app/views/netconf implementations.
+The adapted templates are packaged under resources/configuration. Host database,
+Redis, authorization, spreadsheet uploads and notification code are not bundled.
+
+Netstack-specific hardening adds durable interface-description execution and safe
+configuration inspection. The source hashes above identify the original adaptation
+inputs, not the current modified library files; attribution remains unchanged.

data/README.md

@@ -1,43 +1,81 @@
 # Netstack
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/netstack`. To experiment with that code, run `bin/console` for an interactive prompt.
+Netstack 是独立 Ruby 网络业务库。它从 Motor、PDK 和 net-connector 的现有实现提取设备连接、网络观察、规划、配置生成与执行验证；宿主应用负责身份权限、数据库、凭据、任务队列和执行所有权。
 
-TODO: Delete this and the text above, and describe your gem
+要求 Ruby 3.4+。运行时复用 ActiveSupport、Ruby IPAddr、Zeitwerk、expect-pty 和 TextFSM，不依赖 Rails、ActiveRecord、PostgreSQL 或 Netdisco。
 
-## Installation
+## 使用
 
-Add this line to your application's Gemfile:
+安装 RubyGems 版本：
 
 ```ruby
-gem 'netstack'
+gem "netstack", "~> 0.2.0"
 ```
 
-And then execute:
+0.2.0 使用本文描述的独立 `Netstack` API，不兼容旧 0.1.x API；升级前需要调整调用代码。开发时也可显式引用本地工作树：
 
-    $ bundle install
+```ruby
+gem "netstack", path: "/path/to/netstack"
+```
 
-Or install it yourself as:
+```ruby
+require "netstack"
+
+target = Netstack::Target.new(
+  key: "leaf-1", host: "192.0.2.10", platform: :cisco_nxos
+)
+snapshot = Netstack::Inventory::Collector.new.collect(
+  target: target,
+  dimensions: %i[device interfaces],
+  connection_options: { username: username, password: password }
+)
+
+snapshot.dimensions.each do |name, dimension|
+  # 只有 complete 的对应范围可以用于完整替换；其余状态保留旧数据。
+  puts "#{name}: #{dimension.status}"
+end
+```
 
-    $ gem install netstack
+示例地址使用文档网段。真实调用需要显式传入设备、凭据和信任配置；`require "netstack"` 与 `Netstack.eager_load!` 本身不连接外部系统。
 
-## Usage
+## 模块分布
 
-TODO: Write usage instructions here
+| 路径 / 命名空间 | 职责 |
+| --- | --- |
+| `connector/` / `Connector` | 单设备 SSH/Telnet 会话、厂商命令、配置备份、邻居、TextFSM |
+| `inventory/` / `Inventory` | 设备、接口、地址、光模块、邻居值对象，CLI 采集及按来源对账 |
+| `routing/` / `Routing` | 路由快照、VRF/地址族隔离、最长前缀、优先级和 ECMP 查询 |
+| `wireless/` / `Wireless` | AP、Radio、BSS、Client、配置与运行状态、完整性和质量评估 |
+| `vxlan/` / `Vxlan` | NX-OS 配置/运行观察、Fabric 审计、Segment 增量规划与验证 |
+| `monitoring/`, `circuits/` | Zabbix 设备/链路监控规划、测量、工作日容量评估 |
+| `configuration/` / `Configuration` | 配置读取、业务输入校验、受限模板、配置工件和场景生成 |
+| `deployment/` / `Deployment` | 版本化计划、持久检查点、执行收据、未知结果恢复 |
+| `ddi/`, `backups/` | DNS/DHCP/IPAM 编排、外部配置备份访问 |
+| `integrations/` | HTTP、Zabbix、BlueCat、Oxidized 与 HTTP 配置交付协议 |
+| `ipv4.rb`, `ipv6.rb`, `range_set.rb` | 标准 IPAddr 上的领域地址与压缩区间运算 |
 
-## Development
+文件名对应 Zeitwerk 常量名。持久化与授权不下沉到领域对象；协议差异留在厂商或集成模块中。CLI 不支持的采集维度会明确返回 `unsupported`，不会伪造空的完整快照。
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## 业务边界
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- 完整、部分、失败、不支持、未请求分别记录。完整性按维度和范围判断，避免部分采集删除有效旧数据。
+- 计划可以离线检查和持久化；执行前必须有宿主的持久意图、目标所有权和同步检查点。
+- 提交、接受、外部效果确认是不同事实。未知执行先只读验证，禁止自动重放不确定 CLI 操作。
+- 接口描述变更也使用 `Deployment::Plan`：配置和保存分别先提交持久检查点；私有命令工件由引用解析并校验 SHA-256。调用方式见 [Connector](docs/connector.md)。
+- 凭据运行时注入；配置原文、备份原文和执行原始输出由宿主按敏感数据管理，不作为普通日志。
+- 不提供 Netdisco 数据库/HTTP 实现、Fleet、专用 CLI、宿主账号/RBAC 或通知发送。
 
-## Contributing
+详见 [执行与恢复](docs/deployment.md)、[设备采集与路由](docs/inventory.md)、[基础对象复用](docs/foundations.md)、[Connector](docs/connector.md)、[无线](docs/wireless.md)、[VXLAN](docs/vxlan.md)、[监控](docs/monitoring.md)、[配置生成与交付](docs/configuration.md)、[DDI](docs/ddi.md)、[外部备份](docs/backups.md) 和 [实施记录](docs/implementation.md)。
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/netstack. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/netstack/blob/master/CODE_OF_CONDUCT.md).
+## 开发验证
 
-## License
+```sh
+bundle install
+bundle exec rake ci
+```
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+`ci` 包含 eager load、Minitest、RuboCop、gem 构建和独立 GEM_HOME 安装验证。`script/verify_package.rb` 仅使用 Bundler 已解析的本地 gem 缓存；缺失依赖缓存时先执行 `bundle cache`。该验证不访问生产设备、Zabbix、BlueCat 或 Oxidized。
 
-## Code of Conduct
+CI 配置覆盖 Linux/macOS、Ruby 3.4/4.0。配置矩阵并不代表远端 CI 或真实平台验收已经完成，实际结果见实施记录。Motor 的显式接入入口与独立 bundle 见 [宿主接入](docs/motor_integration.md)。
 
-Everyone interacting in the Netstack project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/netstack/blob/master/CODE_OF_CONDUCT.md).
+源实现与改编说明见 [NOTICE](NOTICE)。版本变更见 [CHANGELOG](CHANGELOG.md)。

data/docs/acceptance.md

@@ -0,0 +1,92 @@
+# Release acceptance — 0.2.0
+
+The release preparation run on macOS arm64 / Ruby 4.0.6 passed
+`bundle exec rake ci`: 675 tests / 7752 assertions, zero failures/errors/skips,
+307 Ruby files lint clean, eager loading and isolated installation with bundled
+templates. All six follow-up findings have regression coverage observed failing
+before repair and passing afterwards. Host and live-provider validation were not
+rerun; the historical results below do not prove current host integration.
+
+Release CI runs Ruby 3.4/4.0 on Ubuntu/macOS. After all four jobs pass, a dedicated
+package job verifies and uploads the exact gem and SHA256SUMS for publication.
+Remote run and artifact provenance are recorded in the GitHub Release.
+
+## Historical review acceptance — 2026-10-01
+
+The approved reliability/performance review is implemented in Netstack only. The
+working tree at that checkpoint was uncommitted with no HEAD. Original files were preserved and
+compared with a separate pre-review source snapshot; no Motor files were changed.
+
+| Environment | Behavioral suite | Other gates |
+| --- | --- | --- |
+| macOS arm64, Ruby 3.4.11 | 664 tests, 7702 assertions; zero failures/errors/skips | Zeitwerk, 307 Ruby files lint clean, isolated installed gem passed |
+| macOS arm64, Ruby 4.0.7 | 664 tests, 7702 assertions; zero failures/errors/skips | Zeitwerk, 307 Ruby files lint clean, isolated installed gem passed |
+
+Both runs executed `bundle exec rake ci`. Ruby 3.4 used the existing isolated
+`BUNDLE_PATH=tmp/ruby34-bundle`. Package verification now also exercises the public
+topology artifact → Deployment plan → checkpointed change/readback/persist API
+from the installed gem, with its bundled templates. New regressions were first
+observed failing against the earlier implementation, then passed after repair.
+
+The review fixes incomplete collection coverage, binding/ownership reconciliation,
+checkpointed topology writes, input and diagnostic boundaries, and bounded local
+lock/template work. Cross-review also caught an unknown port-channel member token
+and preserved the existing multiline interface-input contract. Reproducible timing
+and allocation measurements are in [performance.md](performance.md).
+
+This review did not rerun Linux/Docker, Motor/PostgreSQL host integration or remote
+CI, and contacted no live device/provider. The older integration results below
+are historical evidence for the original implementation, not revalidation of
+these changes. Host persistence and real-device save confirmation remain separate
+acceptance requirements. No commit, push, publication or deployment was performed.
+
+# Original integration acceptance — 2026-09-30
+
+The approved implementation is complete in the local working trees. Netstack is an unreleased 0.1.0 gem; this repository has no commit yet. Motor integration adds explicit entrypoints and preserves the existing production dependency source and job/controller defaults.
+
+## Library gates
+
+| Environment | Behavioral suite | Other gates |
+| --- | --- | --- |
+| macOS arm64, Ruby 3.4.11 | 614 tests, 7142 assertions; zero failures/errors/skips | Eager load, RuboCop, isolated installed package passed |
+| macOS arm64, Ruby 4.0.7 | 614 tests, 7142 assertions; zero failures/errors/skips | Eager load, RuboCop, isolated installed package passed |
+| Linux aarch64, Ruby 3.4.11, `ruby:3.4-bookworm` | 614 tests, 7142 assertions; zero failures/errors/skips | Eager load, RuboCop, isolated installed package passed |
+| Linux aarch64, Ruby 4.0.7, `ruby:4.0-bookworm` | 614 tests, 7142 assertions; zero failures/errors/skips | Eager load, RuboCop, isolated installed package passed |
+
+The project gate is `bundle exec rake ci`. It checks Zeitwerk, the full Minitest suite, 294 Ruby files with RuboCop, and a real `.gem` installed under a fresh GEM_HOME outside the source tree. The installed check loads all constants, parses all TextFSM templates, loads all configuration templates, and rejects Rails/ActiveRecord/Netdisco runtime coupling. The macOS 3.4 final run used the equivalent `rake test lint zeitwerk:check` plus `rake package:verify` separately to avoid concurrent writes to the shared package output.
+
+Docker gates use a copied source tree, with the host source mounted read-only. The dependency set includes ActiveSupport 8.1.4, expect-pty 0.6.1 and TextFSM 0.2.0. Package warnings concern the absent homepage and, on older RubyGems, open-ended dependency requirements; no repository URL or unsupported upper version bound was invented to suppress them.
+
+## Motor gates
+
+Actual Motor source was copied into a separate container with Ruby 4.0.6, Rails 8.1.3.1, PostgreSQL 18 and Redis 8. `Gemfile.netstack` explicitly selected the local gem. Tests used a dedicated database, not the user's existing database.
+
+| Gate | Result |
+| --- | --- |
+| Wireless CLI integration | 17 RSpec examples passed |
+| Configuration generator contract | 16 RSpec examples passed |
+| HTTP delivery through the existing executor | 11 RSpec examples passed |
+| Oxidized repository integration | 5 RSpec examples passed |
+| Durable device monitoring | 17 RSpec examples passed |
+| Durable BlueCat DDI | 17 RSpec examples passed |
+| All six entrypoints in one invocation | 83 examples, zero failures |
+| New/changed integration Ruby files | 17 files, RuboCop clean |
+| Original Motor bundle eager loading | `rails zeitwerk:check` passed without adding Netstack to that bundle |
+| Existing executor and Oxidized behavior under the original bundle | 16 RSpec examples passed |
+
+The 34 monitoring/DDI examples commit real transactions. A separate PostgreSQL connection verifies checkpoint visibility before provider writes, active ownership uniqueness, session-lock contention and release, configuration row locks and absence of a transaction during provider I/O. They also cover connection replacement, same-session recursion, delayed checkpoints, endpoint/revision drift, fresh-service recovery, lost receipts and sensitive-data exclusion. Provider responses are controlled fixtures.
+
+The new migration was executed against the isolated database. Its generated schema was compared with the existing Motor working schema; only the version, new execution table/constraints and two foreign keys differed. Those generated changes were copied back while preserving prior Motor work. RailsAdmin excludes the execution model from generic CRUD.
+
+Motor's runtime set uses ActiveSupport 8.1.3.1 and TextFSM 0.2.1; eager loading and every bundled template also passed under that set. The library's Minitest suite uses its own development bundle. An extra attempt to run it through Motor's RSpec-oriented bundle stopped at the missing `minitest/mock` development dependency before any assertions; Motor dependencies were not changed to disguise that setup mismatch.
+
+Reproduction commands and the six explicit spec paths are in [motor_integration.md](motor_integration.md). Motor's own persistence guide is `docs/NETSTACK_EXECUTIONS.md` in its repository.
+
+## Delivery limits
+
+- No production devices, Zabbix, BlueCat, Oxidized or HTTP delivery service were contacted. No remote CI run, commit, push, gem publication or production deployment was performed.
+- The OS/version matrix above is local ARM evidence. The GitHub Actions matrix is configured but was not run remotely.
+- Default Motor jobs/controllers have not been switched. A target must leave its old writer before enabling the new durable entrypoints. Authorization, approval, queue scheduling and manual resolution remain host responsibilities.
+- Device/vendor and protocol coverage is stated in each domain document. Unsupported dimensions and uncertain external effects remain explicit; no empty snapshot or accepted request is treated as proof of completion.
+
+The implementation and cross-review completion record is [implementation.md](implementation.md); mature-library reuse is documented in [foundations.md](foundations.md).

data/docs/backups.md

@@ -0,0 +1,100 @@
+# Configuration backups and Oxidized
+
+`Integrations::Oxidized::Client` implements node inventory, current configuration,
+version history, selected-version diff and backup queue requests. `Backups::Repository`
+adds target association and version ownership. HTTP defaults verify TLS, enforce
+byte/time budgets and disable redirects and retries. There is no implicit
+Netdisco, Rails, environment configuration or filesystem backup store.
+
+```ruby
+client = Netstack::Integrations::Oxidized::Client.new(base_url: "https://backup.example.test")
+repository = Netstack::Backups::Repository.new(client: client)
+node = repository.node!(target: target, aliases: ["edge.example.test"])
+configuration = repository.configuration(node: node)
+versions = repository.versions(node: node)
+diff = repository.diff(node: node, from_oid: older_oid, to_oid: newer_oid)
+```
+
+Node matching uses explicit target identities and aliases; ambiguity raises an
+error. Version identifiers must be distinct and both belong to the selected
+node. Address matching canonicalizes IPv4/IPv6 notation on both sides; equivalent
+compressed and expanded IPv6 addresses still participate in ambiguity checks.
+Invalid rows are errors, not silently discarded. Node/group path segments
+and query values are encoded separately. `node` returns nil when no match exists;
+`node!` raises `node_not_found`.
+
+Configuration and diff return immutable `Artifact`/`Diff` objects. Inspection
+shows only size and SHA-256, and never returns original bytes. Deliberate access
+uses `artifact.content` or `diff.lines`; the host controls authorization,
+encryption, retention, download responses and audit logging. Do not log explicit
+content merely because the wrapper's default inspection is safe. Line endings
+in raw configuration are preserved.
+
+## Requesting and verifying a backup
+
+```ruby
+request = Netstack::Backups::Request.new(repository: repository)
+receipt = request.call(
+  target: target, aliases: [], execution_id: execution_id,
+  checkpoint: durable_checkpoint
+)
+result = request.recover(
+  execution_id: execution_id, events: committed_events,
+  checkpoint: durable_checkpoint
+)
+```
+
+The host persists an authorized intent and holds an exclusive execution lock
+before `call`. The callback must synchronously commit the event and return
+literal `true`. `started` precedes the queue request; `receipt` means only that
+Oxidized acknowledged it. Keep the complete event stream under the execution ID;
+recovery rejects events from another execution and never submits another backup.
+
+Checkpoints bind the target key/host/platform/serial and the node's name, group, IP,
+full name and model. A same-name node replacement does not confirm the original
+request. Legacy or incomplete checkpoints lacking that fingerprint cannot
+establish completion and require reconciliation.
+
+Oxidized Web's `/node/next` is a side-effectful GET and its implementation ignores
+group. Requests therefore require a globally unique node name even if a read
+can be selected by group. An HTTP timeout is an unknown queue result, not an
+instruction to retry. The low-level client's `request_backup` is a transport
+primitive; application writes use `Backups::Request` and the durable checkpoint.
+
+Completion requires a fresh successful attempt whose start is on or after the
+recorded request, whose end follows its start, and whose completion differs from
+the baseline. An unchanged configuration can still complete, without requiring
+a new Git commit. Old success, an attempt that started before the request,
+missing timing evidence and an in-progress attempt remain pending. A fresh
+failed attempt raises `backup_failed`. The host schedules polling with a finite
+deadline and preserves unresolved results for reconciliation.
+
+This freshness check assumes synchronized host/Oxidized clocks. Oxidized supplies
+no per-request queue ID: fresh successful observation proves a subsequent backup,
+not causal ownership against concurrent scheduled or administrator requests.
+The client accepts ISO 8601 timestamps and upstream's `Time#to_s` UTC serialization;
+invalid timestamps are rejected. No API response is interpreted as a backup
+completion merely because it is HTTP 200.
+
+## Motor integration
+
+Motor has an opt-in `Motor::Devices::NetstackRepository` facade at
+`backend/app/services/motor/devices/netstack_repository.rb`. Construct it with a
+real `Netstack::Backups::Repository`; it preserves Motor's read-response shapes
+and enabled configuration control. It exposes checkpoint-requiring backup
+requests and recovery and verifies recovery belongs to the device. Existing
+`OxidizedConfiguration` remains the default path until explicitly migrated.
+
+Use Motor's independent `Gemfile.netstack` integration bundle with explicit
+`NETSTACK_PATH`. The integration RSpec exercises the actual gem through HTTP
+fixtures. Motor retains route authorization, encrypted settings, jobs and
+durable execution storage. A test callback collecting events in memory is not
+a production persistence implementation.
+
+Offline tests cover node ambiguity, unsafe queue identity, invalid protocol
+rows, version ownership, raw-byte handling, checkpoint failure and stale/fresh
+backup evidence. Motor integration tests validate the facade with its actual
+Rails models and the gem. No live Oxidized service or network device was used.
+
+- [Oxidized Web routes and queue behavior](https://github.com/ytti/oxidized-web/blob/master/lib/oxidized/web/webapp.rb)
+- [Oxidized node serialization](https://github.com/ytti/oxidized/blob/master/lib/oxidized/node.rb)

data/docs/configuration.md

@@ -0,0 +1,198 @@
+# Configuration generation and delivery
+
+`Netstack::Configuration` extracts Motor Netconf's input contracts, validation,
+payload construction and 11 safe templates into a Ruby library. It does not own
+users, authorization, encrypted settings, template versions, jobs, artifact storage,
+ZIP archives, email or retention. Those stay in the host application.
+
+| Scenario | Vendors | Included behavior |
+| --- | --- | --- |
+| `bootstrap` | H3C, Cisco NX-OS | Management, AAA/TACACS, NTP/DNS/syslog/SNMP, users, security controls; H3C access/aggregation/core and RADIUS admission; NX-OS leaf/spine/border, OSPF underlay, BGP EVPN/NVE, external peers and optional vPC |
+| `h3c-irf` | H3C | Master links, standby renumber/reboot, standby links, BFD MAD addressing and inspection commands |
+| `distributed-gateway` | Cisco NX-OS | VLAN/VNI, EVPN, VRF SVI/gateway/ACL/MTU, NVE BGP replication |
+| `cisco-n9k-vpc` | Cisco NX-OS | Separate primary/secondary roles, keepalive and virtual peer-link, peer port-channel, fabric ports, infrastructure VLAN |
+| `server-port` | H3C, Cisco NX-OS | Standalone/IRF/vPC, access/trunk/ranges, explicit or automatic aggregates and member consistency |
+| `hillstone-policy` | Hillstone | Zones, IPv4/CIDR/ranges/Any, TCP/UDP ports/ranges/Any, address and service groups, ordered permit/deny rules and logging |
+| `load-balancer` | Radware | Real servers, groups, VIP services, proxy IP, port translation, health checks, timeout/persistence and explicit host routing |
+| `ipsec-vpn` | Palo Alto, Hillstone | IKEv1/v2, proposals, vendor crypto options, peer/PSK, subnet cross-product selectors, tunnel, optional routing and DPD |
+
+The existing Motor scenario/vendor names and nested input fields are preserved.
+`Catalog.all`, `Catalog.variables_for_template` and `InputContract.fields_for`
+describe them. Cisco templates are NX-OS-specific; they do not advertise IOS support.
+Historical cryptographic options remain expressible for existing configurations;
+the catalog is not a recommendation to choose those algorithms for new tunnels.
+
+## Generate and inspect
+
+```ruby
+require "netstack"
+
+artifact = Netstack::Configuration::Generator.call(
+  scenario: "distributed-gateway", vendor: "cisco",
+  input: { gateways: [{ vlan: 100, subnet: "10.100.0.0/24", vrf: "APP" }] }
+)
+artifact.summary # digest, size, filename, scenario, vendor, timestamp
+artifact.content # explicit access to potentially secret configuration text
+```
+
+Bootstrap requires explicit `system_config:` (or a complete `input[:system]`):
+domain, timezone, management VLAN, NTP/DNS/syslog/TACACS lists and credentials,
+SNMP community, SSH ACLs, local users and security controls. RADIUS is additionally
+required when H3C admission is enabled. Blank secret overrides preserve a saved
+secret only from the supplied defaults; a new username never borrows another
+user's password. `SystemConfiguration.frontend_defaults` removes secret values.
+Only omitted values, `nil` and blank text select optional defaults; `false`, arrays
+and objects are rejected where a text or numeric value is required. Secret overrides
+must be strings even when their optional feature is disabled.
+
+H3C access and authentication ranges must use ordered physical ports on the same
+interface type/member/slot. Uplinks must be outside both ranges; the authentication
+range must be inside the access range. Invalid topology fails before rendering.
+
+Radware generation requires `settings: { next_hop: "192.0.2.1" }`; its route metric
+defaults to 1 and may be supplied explicitly. The Motor installation's original
+`10.20.0.1` is deliberately not a universal library default. IPsec accepts explicit
+`virtual_router`, `route_metric`, `dpd_interval`, `dpd_retry`, `hillstone_sa_index`
+and `tunnel_zone` in addition to the original Motor fields.
+
+For bootstrap batch input, pass `{ devices: [...], system: {...} }`. All devices
+are validated together (including unique hostname and management address) before
+returning a frozen array of individual artifacts. The host may archive them.
+`Generator.new(clock: ...)` supplies deterministic timestamps and policy object names.
+
+`h3c-irf` and `cisco-n9k-vpc` also generate their full review document, but that
+document cannot be directly planned for execution. Select the explicit section:
+
+```ruby
+vpc.section("primary")       # or secondary
+irf.section("master")        # standby-renumber, standby-links, mad
+```
+
+IRF standby renumber contains a reboot. The host schedules the correct physical
+target for each section, accounts for reconnect/renumbering, and supplies verification.
+Automatic rollback, multi-node atomicity, save/commit insertion, and reboot recovery
+are not inferred. Built-in templates preserve their explicit save commands; Radware
+apply and Palo Alto commit are left to the reviewed workflow. A generated script is
+not evidence that a device supports every command or that its runtime converged.
+
+## Templates
+
+`TemplateStore.new(overrides: { "h3c-bootstrap.erb" => source })` captures an
+immutable template snapshot. Template digests travel with artifacts. Only catalog
+filenames are accepted; arbitrary file paths are rejected. The `.erb` extension
+denotes a restricted dialect inherited from Motor:
+
+```erb
+<% policies.each do |policy| %>
+<% if policy.log %>log session-end<% else %>no log<% end %>
+description <%= policy.description %>
+<% end %>
+```
+
+Only scalar interpolation, hash paths, array loops and if/else/end are interpreted.
+There is no Ruby evaluation, method dispatch, arbitrary expression, require, or ERB
+engine. Unknown roots, missing fields, malformed blocks and invalid collection types
+fail. Source, output, nesting and rendering work are bounded. The work budget counts
+every visited syntax node and loop iteration, including empty output and empty loop
+bodies. Hosts still authorize template edits: literal text can intentionally contain
+any device command.
+Custom templates must include their appropriate configuration-mode transitions.
+
+The validator rejects fractional integer coercion, unknown/duplicate keys, invalid
+address/range/aggregate relationships, nonboolean flags, command control characters,
+and quotes/backslashes in interpolated description/secret fields. Secret values use
+8–128 printable non-space ASCII characters excluding quotes, backslash, semicolon
+and backtick. Callers receive field-only errors, without input values.
+VLAN lists/ranges, numeric service ports and decimal OSPF areas use decimal syntax;
+leading zeroes are normalized before rendering. Hexadecimal, signed and underscored
+forms are rejected. `Validator#inspect` omits supplied values.
+
+## Durable plans and generic CLI execution
+
+```ruby
+target = Netstack::Target.new(key: "leaf1", host: "192.0.2.10", platform: "cisco_nxos")
+plan = artifact.plan(target: target, artifact_ref: "encrypted-store:artifact-42",
+  expected: { vlan: 100, vni: 10100, gateway: "10.100.0.254/24" })
+
+adapter = Netstack::Deployment::CliAdapter.new(
+  artifact_resolver: ->(reference) { encrypted_store.fetch(reference) },
+  preflight: ->(plan:, previous:, credentials:) { identity_and_baseline_match?(plan, previous, credentials) },
+  verifier: ->(step:, target:, credentials:, receipt:) { readback_result(step, target, credentials, receipt) }
+)
+receipt = Netstack::Deployment::Executor.new(adapter: adapter).apply(
+  plan: plan, execution_id: "operation-42", credentials: connection_credentials,
+  checkpoint: ->(event) { durable_store.commit!(event); true }
+)
+```
+
+The checkpoint must commit `event[:receipt]` synchronously before returning exactly
+`true`. The host holds a target lease across the execution/recovery attempt. See
+the deployment contract for restart and lock ownership. The plan contains only
+`artifact_ref` and SHA256, optional request/target identifiers and nonsecret expected
+state. Never put scripts or credentials into expected state, target attributes,
+metadata or checkpoint evidence. Store the Artifact securely, or reconstruct it
+from protected bytes with the same content digest before resolving a reference.
+
+CLI commands and outputs are marked sensitive. Comments/blank lines are omitted,
+host is pinned to `Target#host`, and there is no implicit write retry. A successful
+transport is `applied`; the verifier must return `verified`, `failed`, `unknown` or
+`not_applied` with bounded nonsecret evidence. Partial writes are unknown. Resuming
+started/unknown work invokes readback, never a second script submission, and does
+not need to reload an already submitted artifact.
+
+For an existing reviewed manual script, including Huawei or Cisco IOS:
+
+```ruby
+manual = Netstack::Configuration::Artifact.script(target: target, content: reviewed_script)
+```
+
+This artifact binds to that target's key, address and platform. It carries no template
+digest and cannot be moved to another target by changing the plan. Manual scripts
+must include their own CLI mode transitions and save/commit decisions. HTTP delivery
+may use platforms supported by the external service; CLI uses Connector's platforms.
+
+## HTTP delivery
+
+```ruby
+http = Netstack::Integrations::Http::Client.new(base_url: endpoint)
+client = Netstack::Integrations::HttpDelivery::Client.new(http: http, lookup_path: "lookup")
+adapter = Netstack::Integrations::HttpDelivery::Adapter.new(
+  client: client, artifact_resolver: ->(reference) { encrypted_store.fetch(reference) }
+)
+```
+
+POST retains Motor's `request_no`, `target_id`, `idempotency_key`, `device`,
+`credentials: { username:, password: }` and `script` fields and the
+`Idempotency-Key` header. Target attributes may provide the existing snapshot fields
+`id`, `serial`, `name`, `hostname`, `vendor`, `model`, `os`, `device_role`, `source`;
+the IP always comes from the target. Unrelated attributes are omitted.
+
+GET `<endpoint>/<encoded remote id>` reads an acknowledged task. An uncertain POST
+with no remote id instead uses GET `lookup_path?idempotency_key=<original key>`;
+the default lookup path is the submission endpoint. `lookup_parameter:` is configurable.
+The key-lookup response **must echo the same `idempotency_key`**. A missing key,
+wrong task, unsupported status, timeout or 404 remains unknown. The remote service
+must durably index each idempotency key and return that operation's terminal result;
+if it cannot, the adapter cannot safely reconcile the uncertainty.
+
+`success/succeeded/completed`, `failed/error/rejected`, and
+`accepted/pending/queued/running/processing` are normalized; absent status accepts
+only strict boolean `success`. No automatic POST retry, redirect, or polling loop
+is added. The host schedules subsequent Executor calls with the previous receipt.
+`verified` here proves the remote service reported completion of the identified
+operation; it does not independently prove device running-state convergence.
+Raw remote output is available through `Result#output`, excluded from `inspect` and
+checkpoints. Failure checkpoints use a fixed local error code, not server messages.
+
+## Validation and sources
+
+Offline tests cover all 11 templates; bootstrap roles/admission/batches, IRF/vPC
+sections, gateway and aggregate conflicts, policy objects, Radware grouping, both
+VPN vendors/IKE versions, safe template negative cases, artifact digest changes,
+sensitive CLI commands, checkpoint-before-write and unknown HTTP reconciliation.
+No real device or delivery service is exercised by these tests.
+
+Business sources: Motor `app/services/motor/netconf/{catalog,input_contract,validator,
+payload,template_manager,bootstrap/*}.rb`, its `app/views/netconf/*.erb` templates,
+and `lib/motor/api/netconf_delivery_client.rb`. The host's original persistence and
+retry implementation is not copied into the library.