netstack 0.1.1 → 0.2.0

data/docs/monitoring.md

@@ -0,0 +1,227 @@
+# Monitoring and circuit capacity
+
+The monitoring API is plain Ruby. It does not discover devices, query Netdisco,
+load application configuration, or persist records. The host supplies authorized
+targets, Zabbix resource identifiers, credentials and durable checkpoints.
+
+## Zabbix and HTTP boundaries
+
+```ruby
+client = Netstack::Integrations::Zabbix::Client.new(
+  api_url: "https://zabbix.example.test/api_jsonrpc.php",
+  token: credential_store.fetch("zabbix/api")
+)
+client.api_version
+```
+
+The client targets the Zabbix 7.0 API shape: `selectHostGroups` returns
+`hostgroups`, normalized to `groups` in host snapshots. Trigger queries request
+expanded expressions for readback. Requests validate JSON-RPC version, exact
+integer request ID, mutually exclusive result/error, provider error types and
+resource ID receipts. Malformed query rows are errors, not absent resources.
+Only the provider's validated numeric error code is retained; remote messages
+and response bodies do not appear in exceptions.
+
+The shared `Integrations::Http::Client` takes `base_url:`, optional `headers:`,
+`open_timeout:`, `read_timeout:`, `write_timeout:`, `max_response_bytes:` and
+`verify_tls:`. Its `request(method, path = "", query: {}, headers: {}, json: nil,
+body: nil)` returns `Http::Response` with `status`, `headers`, `body` and `json`.
+TLS verification is on by default. Cross-origin paths, redirects, invalid headers
+and oversized responses are rejected. No request is implicitly retried.
+
+An injected HTTP transport implements `call(method:, url:, headers:, body:,
+open_timeout:, read_timeout:, write_timeout:, max_response_bytes:, verify_tls:)`
+and returns `Http::Response`. Client and response inspection omit credentials
+and bodies. Explicit `body` access remains available to integrations that need it.
+
+## Device and probe plans
+
+```ruby
+target = Netstack::Target.new(
+  key: "switch-serial-001", host: "192.0.2.10", platform: "h3c"
+)
+plan = Netstack::Monitoring::DevicePlan.new(client: client).call(
+  target: target, groups: ["14"], templates: ["27"],
+  community_ref: "devices/switch-serial-001/snmp",
+  previous_managed: previous_result.fetch("managed", {})
+)
+persist_plan(plan.to_h, digest: plan.digest)
+```
+
+`DevicePlan` manages an SNMPv2 interface and a secret community macro. It stores
+a credential reference, never the community itself. SNMPv3 is not claimed by this
+entry point. `ProbePlan` accepts `target`, `groups`, `templates` and optional
+`proxy_group_id`; the supplied template must implement the intended ICMP probe.
+Both accept visible `name`, `enabled`, `inventory`, `tags` and `previous_managed`.
+Group/template IDs are explicit: the library does not create shared group or
+template resources as a side effect of planning.
+
+Planning reads remote state without writing it. Old managed group/template IDs
+and tag names are removed, while unrelated members and inventory fields survive.
+Only `netstack.*` tag names may be declared as previously managed. A disabled
+absent host is not created. Matching probe state produces an empty mutation plan.
+Secret macro rotation is an explicit mutation because hidden values cannot be
+compared with their previous contents.
+
+Disabling an existing host changes only its enabled status and preserves its
+previously managed group/template IDs and tag names. Membership changes requested
+while disabled are applied when the host is enabled again. A disabled absent host
+has no managed members. Pass the last verified result's `managed` value back to
+planning; when it includes `target`, that identity must match the current target.
+Older callers may omit `target`, but all ownership fields are still validated.
+
+## Durable application and recovery
+
+```ruby
+applier = Netstack::Monitoring::Applier.new(client: client)
+result = applier.call(
+  plan: plan,
+  credentials: ->(reference) { credential_store.fetch(reference) },
+  checkpoint: ->(event) {
+    persist_event_in_its_own_committed_transaction(event)
+    true
+  }
+)
+```
+
+Each mutation emits `started` before the external write, `receipt` after a valid
+ID response, and `verified` after readback. Returning anything except literal
+`true`, or raising in the callback, stops execution. A callback inside an
+uncommitted outer database transaction is not a durable checkpoint. A progress
+observer cannot substitute for this callback.
+Callback exceptions are reported as `checkpoint_failed` without retaining their
+message or exception cause; durable events already accepted by the host remain
+the recovery source.
+
+The host owns plan storage, authorization, serialization per target, run ownership
+and revision checks. It must bind checkpoint records to the current run, enforce
+their order, and refuse stale workers. Remote Zabbix operations do not provide
+database-style compare-and-swap: the library's preflight checks detect observed
+drift but do not replace host locking. A plan and its events must remain immutable.
+
+After interruption, reconstruct with `Monitoring::Plan.from_h` and call
+`applier.recover(plan:, events:, checkpoint:, credentials:)`. Events must belong
+to the same plan digest and follow the exact stage order. Recovery reads back an
+already-started mutation; it never repeats that write. If the state is not
+confirmed, it raises `monitoring_outcome_unknown` and stops. Unstarted operations
+may continue after previous operations have been verified. Calling `call` again
+with an interrupted plan is not the recovery protocol.
+
+Secret macro values cannot be read back. A valid write receipt plus the macro's
+name/type/identity yields a `verified` event whose `verification` is `metadata`.
+This does not prove the secret's bytes or device authentication. If its receipt
+was lost, recovery leaves the macro outcome unknown even if a matching macro
+exists. Credential resolver failures are sanitized and occur before `started`.
+
+## Circuit monitoring
+
+`Circuits::Endpoint` describes side `a` or `z`. A managed endpoint requires
+`host_id`, `technical_host` and `interface_name`; an external endpoint can carry
+only its address. Optional `layer3: true` enables peer reachability when the other
+endpoint has an address.
+
+`Circuits::MonitoringPlan#call(key:, name:, bandwidth_mbps:, endpoints:,
+previous_host_ids: [], thresholds: {})` builds status, high-bandwidth and
+low-bandwidth triggers. Traffic triggers depend on interface status. At least one
+traffic direction, speed and interface-status items are required; ambiguous item
+matches fail. Numeric interface boundaries distinguish `Gi1` from `Gi10`.
+Thresholds enforce high/recovery and low/recovery hysteresis. Unsafe expression
+keys are rejected rather than interpolated into expressions.
+
+Old endpoint assignments are cleaned across all previous and current hosts, using
+the host and side together. Removing one side on a retained host or exchanging
+endpoint hosts disables the obsolete triggers. Only triggers with the exact circuit
+ownership tag are cleanup targets; manual triggers survive. A trigger associated
+with several hosts is updated once, and an assignment retained on a current endpoint
+is preserved. All started events include the
+plan's `managed.touched_host_ids`, containing old and new hosts. The host must
+persist that scope before acknowledging the first write; it is needed if endpoint
+replacement succeeds remotely but the process exits before local finalization.
+After a partial failure, retain the scope and original plan for recovery.
+
+## Measurements and capacity review
+
+`Monitoring::Measurements#history` and `#trends` accept an item ID, epoch `from` /
+`to`, and a limit. History also takes numeric `value_type` 0 or 3. They validate
+identity, numeric values, timestamps, duplicates and interval bounds. Reaching the
+limit reports `truncated`; zero rows report `empty`. Missing data is never zero.
+Trend min/average/max remain aggregates and are not raw history percentiles.
+
+`Measurements.align(inbound:, outbound:)` joins exact history timestamps, leaving
+an absent direction as `nil`. For capacity assessment, `Circuits::CapacityReview`
+buckets actual observations using an explicit sample interval. It never forwards
+a value across an empty interval. Different nanosecond observations in the same
+interval retain the latest actual value for each direction.
+Both history retrieval and capacity summaries include `from` and `to`; a sample
+at the ending timestamp is retained. Summaries record `from`, `to` and
+`interval_seconds` alongside their coverage and statistics.
+
+```ruby
+calendar = Netstack::Circuits::BusinessCalendar.new(
+  utc_offset: "+08:00", starts_at: "09:00", ends_at: "18:00", holidays: []
+)
+review = Netstack::Circuits::CapacityReview.new(calendar: calendar)
+end_epoch = Time.now.to_i
+start_epoch = end_epoch - (7 * 86_400)
+summary = review.summarize(
+  samples: samples, inbound_capacity_mbps: 100, outbound_capacity_mbps: 100,
+  from: start_epoch, to: end_epoch, complete: !truncated
+)
+decision = review.decide(windows: { "7" => summary })
+```
+
+Defaults are 300-second sampling, 90% coverage in each direction and at least 12
+business-time observations per direction. P95 uses nearest rank. Gaps break
+continuous high-utilization runs; incomplete days cannot count as continuously
+low workdays. Off-hours peaks are reported separately and do not drive resizing.
+Decisions distinguish insufficient data, watch, expand review, expand now and
+shrink review. Seven-day emergency expansion requires that window to be valid.
+Shrink review requires ten consecutive complete low workdays in a valid window,
+or both valid low 15/31-day windows. `decide` validates that
+keys `7`, `15` and `31` correspond to exactly that many elapsed 24-hour periods,
+and that compared windows share their ending timestamp. Unknown labels, wrong
+durations and legacy summaries without interval metadata cannot produce resizing
+advice. These are rolling elapsed-time windows; the business calendar determines
+which observations inside them count as business time. Units for utilization
+are ratios (`0.95`), and traffic/capacity calculations use bits per second.
+
+The bundled calendar uses an explicit fixed UTC offset, weekdays and holidays.
+For DST, inject a calendar implementing `call(Time) -> {"date", "business"}`,
+`daily_seconds`, and `consecutive_workdays?`; do not mutate process timezone.
+Capacity decisions are evidence for review, not automatic circuit resize orders.
+
+## Evidence and references
+
+The host stores each plan and checkpoint stream under a separate execution ID,
+with an exclusive execution lock and uniqueness constraints. A plan digest
+identifies content, not an execution: never reuse events from another execution
+of the same plan. Pass `execution_id:` to both `Applier#call` and `#recover` to
+bind the event stream explicitly; omitting it is supported only for hosts that
+already enforce stream isolation. Recovery also validates resource and managed
+metadata. An empty plan returns `status: "verified"` and emits no remote
+write checkpoints; the host records that terminal result itself. Checkpoint
+callbacks must return `true` only after their enclosing transaction commits.
+
+Existing SNMP interface communities and authentication/privacy passphrases are
+never copied into plan preconditions. Non-secret interface fields and host ID
+remain preconditions; concurrent changes to unreadable credential bytes cannot
+be checked. The desired community is the macro-reference string, whose readback
+can be checked. Secret macro bytes remain metadata-only verification. Existing
+manual trigger dependencies are preserved alongside the managed status dependency.
+Circuit item association requires the explicit interface name in an item key or
+name; an OID or an ifIndex is not treated as a port identity. Hosts with abbreviated
+or otherwise differing names must supply the matching interface name explicitly.
+
+HTTP defaults include a 60-second total request budget (`request_timeout`) in
+addition to open/read/write timeouts. The total budget also wraps an injected
+transport; a transport must cooperate with Ruby interruption and must not catch
+or suppress timeout exceptions. No HTTP write is automatically retried.
+
+Local tests cover protocol failures, resource ID mismatches, durable checkpoint
+failures, lost receipts, secret redaction, stale plans, manual-field preservation,
+old-host cleanup, missing measurements and capacity gaps. These are controlled
+HTTP/Zabbix fixtures; no real Zabbix server, SNMP device or host database was used.
+
+- [Zabbix 7.0 host.get](https://www.zabbix.com/documentation/7.0/en/manual/api/reference/host/get)
+- [Zabbix 7.0 trigger.get](https://www.zabbix.com/documentation/7.0/en/manual/api/reference/trigger/get)
+- [Zabbix 7.0 usermacro.get](https://www.zabbix.com/documentation/7.0/en/manual/api/reference/usermacro/get)

data/docs/motor_integration.md

@@ -0,0 +1,96 @@
+# Motor 宿主接入
+
+Netstack 不引入 Rails 持久化。Motor 保留授权、加密配置、数据库约束、锁、任务、审计和通知；下列入口在 Motor 工作树中实际实现并具有 RSpec 契约测试。
+
+## 显式集成 bundle
+
+Motor 的 `backend/Gemfile.netstack` 先读取其现有 Gemfile，再通过 `NETSTACK_PATH` 引入本库。这样可以验证尚未发布的库，而不把本地兄弟目录写死到生产依赖，也不错误地从 RubyGems 获取同名的其他包。
+
+```sh
+cd /path/to/motor/backend
+NETSTACK_PATH=/path/to/netstack BUNDLE_GEMFILE=Gemfile.netstack bundle install
+NETSTACK_PATH=/path/to/netstack BUNDLE_GEMFILE=Gemfile.netstack bundle exec rspec \
+  spec/services/motor/wireless/cli_sync_spec.rb \
+  spec/services/motor/devices/netstack_repository_spec.rb \
+  spec/netstack/netconf_generator_contract.rb \
+  spec/netstack/delivery_contract.rb \
+  spec/netstack/monitoring_execution_contract.rb \
+  spec/netstack/ddi_execution_contract.rb
+```
+
+使用 Motor 自己要求的 Ruby 版本和独立测试 PostgreSQL/Redis。集成 bundle 不改变生产 Gemfile/lock。正式切换依赖源与入口、发布 gem 或部署服务是另外的交付动作；本次没有执行这些动作。
+
+## 无线采集
+
+`Motor::Wireless::CliSync#call(controller:, platform:, dimensions: nil, expected_revision: nil)` 调用 Netstack 只读采集，再映射至 Motor 已有的 AP、Radio、BSS、Client 四张表。
+
+网络读取在事务外；写入时锁定设备及现有无线行，重新检查设备身份、lock_version、来源修订与四张表指纹。部分或失败维度保留旧记录；不会通过删除父记录级联抹去未完整采集的子维度。AP 人工管理字段保留。完整领域观察、对账与评估从 Result 返回，设置中只保留有界的水位与状态元数据。
+
+CLI 是显式新来源。现有 Netdisco 同步、job 和 controller 默认调用链没有被切换。
+
+## 配置生成
+
+`Motor::Netconf::NetstackGenerator.call(scenario:, vendor:, input:)` 从宿主读取当前选中模板、系统配置与已有 Radware 默认值，交给 Netstack 的校验、载荷与生成器处理。
+
+返回单个 Artifact 或 bootstrap 批次的 Artifact 数组。宿主继续决定加密存储、ZIP、下载、邮件与保留期；没有在库中再次实现 Redis ArtifactStore。原 Generator 的默认入口保持原契约，可逐场景替换调用。
+
+## 配置交付
+
+`Motor::Api::NetstackDeliveryClient.new(config:, target:, platform:, http: nil)` 可以显式注入现有 `Motor::Netconf::Executor`：
+
+```ruby
+client = Motor::Api::NetstackDeliveryClient.new(
+  config: delivery_settings, target: persisted_target, platform: "huawei"
+)
+Motor::Netconf::Executor.new(persisted_target.id, client: client).call
+```
+
+该入口沿用持久化目标、稳定 idempotency_key、认领次数、加密脚本和原有结果持久化。第一次提交核对设备身份及实际脚本摘要；同步成功还需按任务 ID/原 key 回读。已有认领但未保存任务 ID 时只按原 key 查询，不重新 POST。回读失败不能被误认为首次提交被明确拒绝。
+
+HTTP 服务需要提供按原 key 关联的结果查询；没有这项协议能力时结果保持未知，不能通过重试 POST 来制造确定性。HTTP 服务报告成功与独立设备运行状态验证仍是不同层次，详见 configuration.md。
+
+## 外部配置备份
+
+`Motor::Devices::NetstackRepository` 显式接收 `Netstack::Backups::Repository`。Motor 继续读取其集成开关并提供已有状态、原文、版本与 diff 响应结构。原 OxidizedConfiguration 默认 client 保持原样。
+
+备份请求要求 `execution_id` 与同步持久 checkpoint；恢复还要核对设备与节点身份。普通进度日志不能作为持久确认，也不能把队列接受视为备份完成。
+
+## 监控与 DDI 持久执行
+
+Motor 新增 `NetworkExecution` 及 `20260930000000_create_network_executions.rb`。接入前须在宿主数据库运行该迁移；本次只迁移了独立测试库。表保存 execution_id、领域计划及摘要、目标/集成配置快照、按阶段分开的检查点与结果。凭据继续从现有加密配置和设备凭据读取，不进入计划或事件。
+
+```ruby
+monitoring = Motor::Devices::NetstackMonitoring.new
+execution = monitoring.plan(device: device)
+# 宿主完成授权、计划审阅与任务调度后执行。
+monitoring.call(execution_id: execution.execution_id)
+# 进程重启后只需读取持久身份。
+Motor::Devices::NetstackMonitoring.new.recover(execution_id: execution.execution_id)
+
+ddi = Motor::Bluecat::NetstackExecution.new
+execution = ddi.plan(
+  operation: "dns_record",
+  attributes: { name: "edge.example.test", type: "A", value: "192.0.2.10" },
+  settings: ddi_settings
+)
+ddi.call(execution_id: execution.execution_id)
+Motor::Bluecat::NetstackExecution.new.recover(execution_id: execution.execution_id)
+```
+
+监控入口读取已有 `MonitoringProposal` 和 Zabbix 意图，从服务端精确解析组、模板与代理组，再保存 `DevicePlan`。执行和成功回写均核对设备身份、版本、sync_revision 和集成配置版本；成功后更新已有 Zabbix host_id、managed IDs 与同步状态。
+
+DDI 入口只接受明确列出的业务操作与参数，要求显式 `Ddi::Settings`。恢复从已保存的 scope 重建设置，核对原配置记录、endpoint 和版本，分别继续对象变更与服务器部署。`pending` 表示仍需宿主安排查询；`unknown` 保留原占用与证据，不能创建替代执行来重放。
+
+共享 `NetworkExecutions::Runner` 复用 PostgreSQL session advisory lock，网络 I/O 期间不持有数据库事务。每次检查点在独立的最外层短事务提交后才返回 `true`；所有入口拒绝调用者已有的外层事务。活跃状态的部分唯一索引限制同一目标只有一个计划/执行，进程退出后 session 锁释放，数据库意图仍保留。
+
+BlueCat 占用键使用规范化 endpoint 的 SHA-256，因此两个配置记录指向相同 endpoint 也不能并发执行；证据同时保留原配置记录与 scope。不同 DNS 别名是否对应同一物理 BAM，仍需宿主统一配置。session 锁要求直连 PostgreSQL 或保持 session 的连接代理，不能使用 transaction pooling。
+
+该锁协调这些新入口。迁移某个目标时，宿主须停用对应旧写者，不能让旧 Zabbix job、旧 BlueCat 路径与新执行同时修改它。外部管理员的操作也不受此锁约束。授权、审批、定时重试和人工处置仍属于 Motor 的工作流。
+
+执行记录从 RailsAdmin 通用 CRUD 排除，避免直接编辑状态或删除未决意图。历史记录的外键会保护设备和集成配置；保留期与显式归档由宿主统一设计，不能级联删除未知执行的证据。
+
+## 其他宿主边界
+
+链路监控、探针、容量评估和 VXLAN 仍通过 Netstack 领域 API 接入宿主工作流；上述持久适配覆盖设备 Zabbix 与 DDI。Motor 的既有 controller、job 和生产默认依赖源没有被自动切换。VXLAN 计划由宿主保存，再通过 Deployment::Executor 执行；不能将普通进度回调当作 durable checkpoint。
+
+本次接入测试证明上述显式入口可与当前 Motor/Rails/PostgreSQL 组合；它不等于默认生产路径已切换，也不等于真实设备、HTTP 交付服务、Zabbix、BlueCat 或 Oxidized 已完成联调。

data/docs/performance.md

@@ -0,0 +1,39 @@
+# Offline performance checks — 2026-10-01
+
+These measurements compare the preserved pre-review source snapshot with the
+reviewed working tree, on macOS arm64 / Ruby 4.0.7 with the same bundle. Each result
+is the median of three sequential runs; fixture construction and explicit GC run
+outside the measured interval. Timing uses the monotonic clock; allocation counts
+use `GC.stat(:total_allocated_objects)`.
+
+| Workload | Before | After | Allocated objects before / after |
+| --- | --- | --- | --- |
+| Inventory: 10,000 unchanged interfaces | 0.2948 s | 0.0190 s | 120,028 / 120,028 |
+| Inventory: 20,000 unchanged interfaces | 0.8674 s | 0.0383 s | 240,028 / 240,028 |
+| Deployment: 50 fresh steps | 0.079662 s | 0.019481 s | 1,062,924 / 139,483 |
+| Deployment: 200 fresh steps | 1.219080 s | 0.288421 s | 16,446,399 / 2,042,608 |
+| Deployment: 200 already verified steps, recovery | 0.133616 s | 0.001273 s | 2,084,005 / 16,115 |
+
+Inventory now indexes observed and retained identities instead of repeatedly
+scanning arrays. Source, scope, manual fields and output ordering retain their
+existing contracts. The fixture asserts that unchanged records produce no changes.
+
+Executor computes immutable execution identity once per call and indexes a validated
+receipt prefix directly. The adapter and checkpoint are in-memory fixtures; all
+before/after receipt JSON digests match. Complete receipt copying at each checkpoint
+still has cumulative quadratic cost for large plans. These measurements describe
+library overhead, not device, network, provider or durable database latency.
+
+Run from the project root under one Ruby version and bundle, sequentially:
+
+```sh
+bundle exec ruby script/benchmark_inventory.rb /path/to/baseline/lib
+bundle exec ruby script/benchmark_inventory.rb
+bundle exec ruby script/benchmark_deployment.rb /path/to/baseline/lib
+bundle exec ruby script/benchmark_deployment.rb
+```
+
+The scripts are optional developer checks, not timing thresholds in CI. They do
+not contact external systems. The repository had no HEAD at review time; the
+baseline was an immutable source copy with a SHA-256 manifest, rather than an
+invented commit reference.

data/docs/release.md

@@ -0,0 +1,20 @@
+# 发布
+
+0.2.0 采用新的独立 Netstack API；旧 0.1.x 调用代码需要迁移。旧 GitHub
+源码保留在历史提交中，不作为当前 gem 的资源或运行时依赖。
+
+发布前执行 `bundle exec rake ci`，检查源码、历史和最终 gem 的敏感信息，
+并确认版本尚未发布。只提交项目源码、测试、文档、模板与开发配置；IDE、
+缓存、临时文件和构建目录不提交。
+
+推送后等待 `.github/workflows/ci.yml` 的四项 Ruby/platform 验证及 package
+任务全部成功。通过 `gh run download RUN_ID --name netstack-gem --dir DEST`
+取得已验证的 gem 和 SHA256SUMS，核对摘要后将同一个 gem 上传到 GitHub
+Release 和 RubyGems。发布期间不重新构建或替换工件。
+
+RubyGems MFA 使用当前操作的交互验证；凭据、验证码不写入文件或提交。
+上传结果未知时先查询远端状态，不能为了通过验证重复上传。
+
+发布后读取标签目标、CI 结论、Release 资产和 RubyGems 版本元数据，
+下载两端 gem 并比较 SHA-256，确认 RubyGems 未撤回，再检查最终工作区状态。
+离线门禁、宿主集成和真实设备验证分别报告。

data/docs/vxlan.md

@@ -0,0 +1,91 @@
+# VXLAN fabric operations
+
+`Netstack::Vxlan` is a Ruby domain library for Cisco NX-OS fabric evidence, auditing, and additive segment changes. It does not use PDK APIs, Perl, Netdisco, a database, or a task queue. The host owns target inventory, authorization, credentials, durable checkpoints, and the target execution lease.
+
+## Configuration and runtime evidence
+
+```ruby
+target = Netstack::Target.new(key: "dc1-leaf1", host: "192.0.2.1", platform: :cisco_nxos,
+                             attributes: { role: :leaf })
+snapshot = Netstack::Vxlan::Collector.new.collect(
+  targets: [target], fabric_key: "dc1",
+  connection_options: { username: "operator", password: secret },
+  dimensions: %i[configuration nve_peers nve_vnis bgp_neighbors vpc]
+)
+findings = Netstack::Vxlan::Auditor.new.inspect(snapshot)
+```
+
+Collection uses one owned connector session per target and continues other targets after a device failure. A target's host always wins over a `host` in connection options. Configuration and each runtime dimension have separate outcomes. Unsupported platforms are reported without a connection attempt. Credentials and exception messages are not included in snapshots.
+
+The collected `Fabric#expected_node_keys` retains every requested target, including targets with failed or unsupported configuration collection. Configuration is complete only when all expected nodes are present and complete. Selecting a successful subset for a segment change does not bypass missing fabric evidence. The auditor reports each missing configuration target. Runtime failures remain separate and do not invalidate an otherwise complete configuration baseline.
+
+Configuration parsing covers VLAN/VNI, VRF and route targets, SVI addresses and ACL bindings, NVE membership/replication, EVPN, BGP peer templates/neighbors/VRF redistribution, vPC, ordered ACL entries, prefix lists, route maps, and static routes. Models are immutable. Source configuration is not retained in a `Node`; its fingerprint excludes volatile `!` show headers while retaining configuration commands, including commands not interpreted by the domain parser.
+
+For offline parsing, transport completeness is an explicit assertion by the caller:
+
+```ruby
+node = Netstack::Vxlan::CiscoNxos::ConfigParser.new.parse(text, target: target, complete: true)
+fabric = Netstack::Vxlan::Fabric.new(key: "dc1", nodes: [node])
+snapshot = Netstack::Vxlan::Snapshot.new(fabric: fabric)
+```
+
+The default is `complete: false`; a parser cannot prove that an arbitrary file is whole. Invalid/unsupported SVI addressing, ambiguous multiple NVE interfaces, and unsupported NVE member ranges mark configuration evidence incomplete. This parser models the listed NX-OS constructs, not every possible command in every firmware release. Unmodeled general configuration remains covered by the baseline fingerprint.
+
+Offline `Fabric.new` accepts `expected_node_keys:`; when omitted, its scope is the supplied node keys. Expected keys must be unique and include every supplied node. Fabric serialization and its digest include this expected coverage, so this baseline digest differs from versions that fingerprinted only successful nodes. Rebuild old fabric plans before execution.
+
+Runtime dimensions are `nve_peers`, `nve_vnis`, `bgp_neighbors`, `ospf_neighbors`, `vpc`, `interfaces`, `port_channels`, and `mac_addresses`. `RuntimeResult#status` distinguishes `complete`, `partial`, `unsupported`, `failed`, and `not_requested`. A complete empty table is different from an unrecognized output or failed command. Partial results retain recognized rows and diagnostics. Do not remove inventory from incomplete dimensions. Runtime-only collections do not establish a complete configuration baseline for planning.
+
+Runtime parsing accepts explicit known headers, separators, and protocol framing. Every other body line must parse or makes the result partial; diagnostics contain counts, not the rejected text. A table header alone cannot prove an empty table. A complete empty result requires a recognized zero-entry response; unknown firmware framing remains partial until its grammar is supported.
+
+The auditor reports cross-node segment/VNI/anycast-MAC/ACL differences, missing NVE/EVPN/VRF associations, route-target completeness, route advertisement, BGP extended communities and reflector settings, vPC peers/member differences, and abnormal runtime rows. Missing runtime objects are inferred only from complete configuration and complete relevant runtime evidence. A finding is evidence for review, not an automatic repair authorization.
+
+## Additive segment planning
+
+Configuration readback requires the global anycast gateway MAC when the segment
+uses anycast, and requires every bound ACL definition to exist. An SVI reference
+alone does not prove those prerequisites; missing prerequisites remain unknown.
+
+```ruby
+segment = Netstack::Vxlan::Segment.new(
+  vlan_id: 120, vni: 10120, vrf: "production",
+  prefix: "10.120.0.0/24", gateway: "10.120.0.1"
+)
+change = Netstack::Vxlan::SegmentPlanner.new.plan(
+  fabric: snapshot.fabric, segment: segment,
+  target_keys: ["dc1-leaf1"], prefix_list: "EXPORT"
+)
+change.plans.each { |plan| review(plan.payload, plan.digest) }
+```
+
+VLAN, VNI, VRF, network, and gateway are explicit inputs; no address, naming, or organization heuristic supplies them. The planner requires complete fabric configuration, valid target management IPs, an existing VRF/L3 VNI and NVE association, an NVE source/BGP host-reachability configuration, and the anycast MAC when needed. It rejects VLAN/VNI/prefix/address/policy conflicts before returning any plans. Conflicts are checked across the supplied fabric, including unselected nodes.
+
+The returned `SegmentPlan` reports `new`, `partial`, or `existing`, target counts, the fabric baseline digest, and per-device `Deployment::Plan` objects. Existing complete segments yield no executable plans. Partial configurations produce only missing commands; an existing SVI's VRF/address is not reapplied merely because another component is missing. Desired ACLs must already exist; planning does not create access policy.
+
+New EVPN objects use `rd auto` and automatic import/export route targets. Existing complete custom EVPN policies are preserved; incomplete custom policies are rejected instead of guessed. NVE ingress replication is explicitly `:bgp` or `:multicast` with a valid multicast group.
+
+`prefix_list:` opts into route advertisement changes. The selected prefix list must already be the sole predicate of a single permit route-map referenced by the VRF's connected/direct redistribution, with EVPN advertisement enabled. Policies with denies, extra predicates, or more complex ordering are rejected for mutation. The read-only `RoutePolicy` honors prefix-list order and prefix length ranges; unsupported predicates produce `:unknown`. Without `prefix_list:`, the segment plan does not claim to change route advertisement.
+
+## Execution and verification
+
+```ruby
+adapter = Netstack::Vxlan::CiscoNxos::DeploymentAdapter.new
+executor = Netstack::Deployment::Executor.new(adapter: adapter)
+receipt = executor.apply(plan: change.plans.first, execution_id: execution_id,
+                         credentials: credentials, checkpoint: durable_checkpoint,
+                         previous: previous_receipt)
+```
+
+The host acquires exclusive target ownership, stores the approved plan and execution identity, and provides a synchronous checkpoint callback returning `true` only after durable commit. The adapter performs a fresh configuration read before execution. Identity changes and baseline drift block a new write. On recovery, the existing receipt is reconciled by readback; an uncertain configuration command is never automatically replayed.
+
+Each device's segment change is one business step. Command timeout, disconnect, or incomplete execution means `unknown`, because preceding CLI commands may already have changed the device. Readback verifies VLAN/VNI, SVI/gateway/VRF/ACL, NVE replication, EVPN route targets, and opted-in advertisement before returning `verified`. Missing or partial readback remains `unknown`; it does not imply that nothing happened.
+
+Generated changes modify running configuration only. They do not save startup configuration, delete objects, roll back, or rebuild the fabric underlay/control plane. Saving or rollback needs a separate reviewed host operation and its own verification. Configuration verification proves desired configuration, not convergence of BGP/NVE forwarding; collect runtime dimensions after deployment when operational readiness is required.
+
+## Offline acceptance
+
+```sh
+bundle exec ruby -Ilib:test -e 'Dir["test/vxlan/*_test.rb"].sort.each { |file| require_relative file }'
+bundle exec rubocop lib/netstack/vxlan test/vxlan
+```
+
+Tests cover configuration and runtime fixtures, incomplete/unsupported/empty evidence, immutable values, conflict and prerequisite rejection, minimal partial plans, routing order, multi-device audit, collection failures, stale preflight, unknown writes, durable checkpoint ordering, and recovery by readback. These are offline parser and injected-transport checks; they are not real NX-OS firmware or device acceptance.

data/docs/wireless.md

@@ -0,0 +1,81 @@
+# Wireless 领域
+
+`Netstack::Wireless` 是单控制器的只读业务领域，直接组合内置 Connector。它不依赖 Netdisco、Perl、SQL、Active Record，也不创建任务队列或执行记录库。宿主负责凭据、授权、调度、重试、事务、人工字段以及证据文件。
+
+## 采集与结果
+
+```ruby
+require "netstack"
+
+target = Netstack::Target.new(key: "controller-1", host: "192.0.2.1", platform: "h3c")
+collector = Netstack::Wireless::Collector.new(
+  connector_factory: ->(target) {
+    Netstack::Connector.build(:h3c_wireless, host: target.host,
+      username: ENV.fetch("WLC_USERNAME"), password: ENV.fetch("WLC_PASSWORD"))
+  }
+)
+observation = collector.call(target: target)
+assessment = Netstack::Wireless::Assessor.new.call(observation)
+result = Netstack::Wireless::Reconciler.new.call(previous: nil, observed: observation)
+# 宿主持久化 result.state 和 result.observation，并在自己的事务中应用 result.changes。
+```
+
+也可传入已打开的 `connector:`；此时连接/关闭属于调用者。工厂创建的连接始终由 Collector 关闭。采集按顺序执行固定 `display` 命令，共用 AP/radio 及配置查询结果，默认 H3c 共 7 条业务查询。所有命令 `privilege: false`，使用完整已确认提示符，并标记输出敏感。不会运行 system-view、probe、save、开启 AP console 或使用默认口令。
+
+| 平台 | 实际支持维度 | 查询 |
+| --- | --- | --- |
+| H3c / h3c_wireless | access_points、radios | display wlan ap all verbose |
+| H3c | clients | display wlan client verbose |
+| H3c | bsses | display wlan bss all verbose |
+| H3c | dot1x_connections、mab_connections | display dot1x connection / display mac-authentication connection |
+| H3c | blocked_clients | display wlan client-security block-mac |
+| H3c | configuration、ap_groups、service_templates | display current-configuration |
+| Huawei | access_points、clients | display ap all / display station all |
+| H3c AP | lldp（显式请求） | display lldp neighbor-information verbose |
+
+Huawei 的 radio/BSS/配置/认证/LLDP 等返回 `unsupported`。其他平台不会连接。默认不采集 LLDP。显式 `dimensions: [:lldp]` 自动包含 AP 清单查询，并要求 `ap_connector_factory: ->(target, access_point) { ... }` 提供每台 AP 的直接连接；工厂自持凭据，不从控制器开启任何功能。只有全部 AP 覆盖且 AP 清单完整时，LLDP 才完整。
+
+每个 `Netstack::Dimension` 包含 `name/status/records/started_at/completed_at/evidence/diagnostics`。状态使用 `complete/partial/unsupported/failed/not_requested`。失败连接和失败命令不会转成成功空清单。完整零条要求明确总数/零条格式；有记录的正常完整命令可提供结束证据。未知行、非法字段、总数不符、截断与不可解析输出都保留可见诊断。
+
+黑名单只有表头或分隔线时不能认定零条；LLDP 已出现邻居索引但缺少邻居内容时保留 `incomplete_neighbor` 诊断。即使命令已结束，这些结果也不能授权删除旧记录。
+
+`evidence` 默认只包含命令、原始输出 SHA-256、字节数。可传 `evidence_writer: ->(target:, command:, output:) { reference }` 接受原始字节并返回 JSON 值引用。此显式回调可能收到配置密钥，宿主须按自身加密存储策略处理；原文不会进入 snapshot、异常消息或解析诊断。解析只在副本上移除命令回显、提示符、终端表现字符。未知配置行只记录行号，PSK 仅保留 `has_preshared_key`。
+
+## 模型与关系
+
+具体值对象包括 AccessPoint、Radio、Client、Bss、ApGroup、ServiceTemplate、AuthenticationConnection、Neighbor、Configuration、SecurityPolicy、Finding；字符串、数组、嵌套哈希均防御复制且冻结。H3c 提取 AP 在线状态/时长、CAPWAP、客户端数，radio 信道/利用率/底噪；client 地址、AP/radio/BSSID/SSID/VLAN、相对 RSSI 或 dBm、协商与吞吐 bps、终端能力、安全参数；BSS 与 dot1x/MAB 的域、协议、授权 VLAN、在线时间。
+
+配置覆盖 AP/组/型号模板/radio/service-template，保持显式 false 与缺项 nil 的差异：自动注册/持久化、客户端保活/限速、band navigation、channel/功率/开关、mandatory/supported/disabled rates、anti-sticky、RSSI 门槛、模板绑定、BTM、PSK/dot1x/MAB/portal、黑白名单。未知无线语法使配置 partial，不宣称已经覆盖所有固件语法。
+
+`observation.view` 派生 AP、radio、BSS、客户端关系。组型号 radio 配置先于 AP 显式配置；runtime 状态保留独立字段。组通过 AP 名称或 serial 关联；同一 SSID 对应多个模板时返回 `ambiguous_service_template`，不按遍历顺序挑选。认证连接优先提供 client 的认证类型，其次配置，再其次运行时 AKM。`clients_for`、`radios_for`、`bsses_for`、`neighbors_for`、`authentications_for` 及黑白名单查询支持宿主视图。
+
+记录键采用长度前缀组合，避免名称含分隔符时碰撞，并始终作用于单一 controller target。Snapshot 验证重复 AP 名称/ID/MAC/序列号、重复客户端/BSSID、AP 名称和 ID 冲突、BSS/radio 引用冲突。完整父维度缺少被引用父对象时拒绝快照；父维度不完整时允许未知关系，但不把它当删除依据。顺序查询可能遇到真实漫游竞态，矛盾快照拒绝导入后由宿主重新采集。
+
+## 对账与宿主持久化
+
+`Reconciler#call(previous: State或Snapshot或nil, observed: Snapshot)` 先验证 target key/host/platform、各维度时间和身份，再返回不可变 `Reconciliation(state:, changes:, observation:)`。相同时间的冲突内容及倒序观测会被拒绝；完全相同的重放不产生更新。
+
+| 观测状态 | State 更新 | 删除 |
+| --- | --- | --- |
+| complete | 按该维度替换 | 只删除该维度中已证实不存在的键 |
+| partial | 有效记录合并；缺项 nil 不覆盖旧值，显式 false 可更新 | 无 |
+| failed / unsupported / not_requested | 保留旧记录 | 无 |
+
+部分配置中的黑白名单按 MAC 身份合并；新观察的非 nil 字段覆盖旧字段，
+未观察的 MAC 和未观察字段保留，避免旧记录吞掉已观察的更新。
+
+部分配置还按 AP/组/模板及嵌套绑定合并，避免顶层 singleton 更新间接抹去旧子对象。`State.records` 是保留后的事实，`State.watermarks` 是各维度观测水位；`observation` 是本次状态。故失败维度没有记录与保留旧事实并不冲突。宿主须保留两者区别，不可把 State 当作最新的完整观测。`changes` 包含每维 added/updated/removed/retained/status，引用字段属于运行数据，宿主映射到自己的模型时仍须保护人工字段和来源边界。
+
+同一 radio 的 service-template 绑定以不区分大小写的模板名称为身份，保留展示拼写。partial 更新已观察绑定的非 nil 字段并保留未观察绑定；AP 显式绑定优先于组内同名绑定。同一输入作用域重复绑定同名模板会被拒绝，配置解析返回 failed，直接构建 Snapshot 抛出 `InvalidSnapshot`；不会任取其中一条。该规则只适用于模板绑定，不改变速率等其他数组的含义。名称身份和 AP 覆盖组设置依据 [H3C service-template 命令](https://www.h3c.com/en/d_202208/1675573_294551_0.htm)。
+
+Reconciler 不执行数据库写入，不保证两个宿主并发事务的互斥。宿主须在持锁/事务内重读旧 State、检查来源修订号并提交；采集网络 IO 应在持锁前完成。
+
+## 评估
+
+Assessor 生成具体 Finding。AP 非在线、预期 AP 缺失、近期上线、radio down/忙信道/高底噪、客户端弱信号/近期上线/明确漫游异常、关联歧义与维度不完整分别有独立代码。AP 清单不完整时预期缺失仅为 `expected_ap_unconfirmed`。普通 `Intra-AC roam` 不是故障；近期上线不被描述为反复掉线。H3c 正 RSSI 相对量与 Huawei 负 dBm 使用独立阈值；0 RSSI/非负底噪是未知遥测。健康判定要求实际完整证据。
+
+## 来源与验证
+
+业务语法和关系来自本地 PDK：`Inspection/Runtime/H3c/WirelessAp/Parser.pm`、`Inspection/Runtime/Huawei/WirelessAp.pm`、`Inspection/Runtime/WirelessController/{Profile,Parser,ApLldpDiscovery}.pm`、`Wireless/H3c/ConfigParser.pm` 及其 AccessPoint/ApGroup/Radio/ServiceTemplate/Global/LineOption、`Wireless/H3c/DomainBuilder.pm`、无线各模型、`Wireless/Util.pm` 与 Controller/IssueEvaluator。这里按 Ruby 值对象/组合职责重新实现，未保留 Perl/Netdisco 入口。PDK LLDP 的隐式控制台启用步骤明确未迁入。
+
+`test/fixtures/wireless` 全部是合成实验数据：192.0.2.0/24、2001:db8::/32、02 开头 MAC、LAB 序列号和测试密钥。未搬现场采集文件。Minitest 覆盖解析、配置覆盖、认证关系、身份冲突、完整空结果、异常/partial 不删除、嵌套配置保留、时间水位、证据回调、只读命令、连接清理、LLDP 覆盖与诊断、RSSI尺度。离线样例及 mock Connector 的通过不等同于真实设备/所有固件验收。

data/lib/netstack/backups/artifact.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Netstack
+  module Backups
+    # Access to raw secrets is deliberate; logging this object never prints bytes.
+    class Artifact
+      attr_reader :content, :sha256, :bytesize
+
+      def initialize(content)
+        raise InputError, "Backup content must be text" unless content.is_a?(String)
+        @content = content.dup.freeze
+        @sha256 = Digest::SHA256.hexdigest(content).freeze
+        @bytesize = content.bytesize
+        freeze
+      end
+
+      def inspect = "#<#{self.class.name} bytesize=#{bytesize} sha256=#{sha256}>"
+      alias to_s inspect
+    end
+  end
+end

data/lib/netstack/backups/diff.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Backups
+    class Diff < Artifact
+      attr_reader :lines
+
+      def initialize(lines)
+        raise InputError, "Backup diff must contain text lines" unless lines.is_a?(Array) && lines.all? { |line| line.is_a?(String) }
+        @lines = Values.copy(lines)
+        super(lines.join)
+      end
+    end
+  end
+end