netstack 0.1.1 → 0.2.0

data/docs/connector.md

@@ -0,0 +1,187 @@
+# Connector
+
+`Netstack::Connector` 从 net-connector 当前工作树移植单设备能力，源 HEAD 为 `63935c0`。源工作树含未提交修改，以下 SHA-256 记录实际读取内容。保留 MIT 版权归属；全项目许可与归属见 LICENSE 和 NOTICE。
+
+不包含 Netdisco、设备清单查询、批量 Worker、报告、批量 TFTP 归档、旧命令行入口或 PostgreSQL 依赖。显式 `backup(path:)` 仍提供单设备原子配置备份，不承担执行任务历史。
+
+入口 `require "netstack/connector"`；`build`、`open`、`vendors`、`vendor_class`。源 `Base` 为新 `Device`；厂商为 `Vendors::H3c` 等类，策略嵌套在厂商类内。没有旧常量别名。所有文件按真实常量由统一 Zeitwerk 加载。
+
+原始命令输出保持字节；终端展示、解析文本与脱敏诊断分别处理。能力查询不联网。`open` 保证资源清理；会话锁只在当前进程内有效。设备配置变更不具备跨系统事务，未知执行结果不能自动重放。TFTP 回执的 `device_reported` 不代表服务器文件已验证。
+
+模板位于 gem 内 `resources/textfsm`。每次解析新建 TextFSM 状态，禁止多个线程共享可变 parser。测试使用合成传输/本地 PTY，未证明真实设备固件兼容。
+
+`known_hosts` 合并使用跨进程锁；锁等待单独以 `login_timeout` 为上限，超时返回 `LoginTimeout`，关闭连接并丢弃会话副本，不改变共享信任文件。该上限不是整个登录流程的总时限。
+错误归一化只保留固定错误码/阶段，目标地址取自会话配置，敏感输出上下文同时保护 source 等诊断字段；明确返回的原始命令结果仍保留原文。
+
+设备日志只接受普通文件；打开时使用非阻塞模式，并在同一文件描述符上校验类型。
+FIFO、目录等特殊文件返回 `LogError`，不会等待管道读者而阻塞会话。
+
+## 接口描述的持久执行
+
+`plan_interface_descriptions` 保留只读规划入口，返回私有 `Topology::Plan` 工件。
+工件的版本化 `payload` 可交给宿主安全存储，并由 `Topology::Plan.from_h` 恢复；
+其中包含旧描述和批准的命令，不应写入普通日志。`sha256` 绑定其完整内容，`inspect` 不展开正文。
+
+```ruby
+artifact = device.plan_interface_descriptions
+target = Netstack::Target.new(key: device_id, host: device.host, platform: device.vendor)
+# 宿主先保存 artifact.payload，再创建执行记录并取得目标执行所有权。
+plan = artifact.deployment_plan(target: target, artifact_ref: stored_artifact_id)
+outcome = device.apply_interface_descriptions(
+  plan, execution_id: execution_id, confirmed: true,
+  artifact_resolver: ->(reference) { Netstack::Connector::Topology::Plan.from_h(private_store.fetch(reference)) },
+  checkpoint: ->(event) { execution_store.commit_checkpoint!(event); true },
+  previous: previous_receipt
+)
+outcome.receipt # 可序列化的执行状态；不含命令或配置正文
+outcome.result  # 本次写入和批准的状态读回步骤的 Connector::Result 原始证据
+```
+
+`apply_interface_descriptions` 接收 `Deployment::Plan`，必须提供同步 checkpoint 和工件解析器；
+旧的 `apply_interface_descriptions(topology_plan, confirmed: true)` 不再允许写入。
+Deployment Plan 只保存工件引用、SHA-256 和批准的读回期望。
+每次首次提交修改或保存步骤前重新解析工件，验证摘要、目标、命令序列与批准的 Deployment Plan。
+普通 SSH/Telnet 命令、`save_config` 等显式 I/O 原语保持原有职责；宿主应通过持久业务执行入口协调业务变更。
+
+执行分为 `change` 和 `persist` 两个步骤：每步发送前都须先持久提交 `started`；
+修改后的完整配置读回得到确认，且 `change/verified` checkpoint 已提交，才允许保存。
+回调必须完成宿主持久事务并返回恰好 `true`，不能仅入队或等待外层事务以后提交。
+宿主负责验证执行身份与目标租约，checkpoint 失败立即停止后续写入。
+
+恢复验证 execution、target、plan、step 和幂等身份。未知修改只读回，全部目标描述匹配后才可能推进尚未提交的保存步骤；
+恢复尚未开始的保存前会重新核验邻居和目标描述。已提交的未知步骤不会自动重放，也不重新取其命令工件。
+未知保存缺少已持久化的明确成功回执时保持 `unknown`，运行配置正确不能证明启动配置已经保存。
+当前 IOS、NX-OS、H3C、Hillstone 使用明确保存完成行；未新增启动配置读回协议。PAN-OS 的自动描述变更仍不开放。
+
+返回的 `Topology::ExecutionResult#success?` 仅在回执全部验证通过或计划无变更时成立；
+`value!` 对未知或失败状态抛错，即使本次普通命令输出看起来成功。
+`result` 延续原业务结果的步骤边界，保留修改、批准的描述读回及保存输出；
+它不是完整会话记录，不包含前置邻居查询和基线重验。前置门禁失败仍抛出既有领域错误。
+恢复结果只含本次状态读回，不伪造前次原始输出。`Topology::CheckpointError` 继承 `Deployment::CheckpointError`，
+保留 `receipt` 和本次 `result`，便于宿主保存已取得的原始证据并安排恢复。
+
+拓扑回归与安装包检查使用内存 checkpoint 和合成设备，只证明离线协议、包内模板和资源加载，
+不证明宿主数据库持久性、目标租约或真实设备保存介质。
+
+## 源文件映射
+
+| 源 `lib/net/connector/` | 新路径 | 源 SHA-256 |
+| --- | --- | --- |
+| `device/base.rb` | `lib/netstack/connector/device.rb` | `42709ab64057e304ec9cd21d11ad88a134acca63ca17fd30521f9ed9e7168dea` |
+| `device/local_backup.rb` | `lib/netstack/connector/backup.rb` | `a5a5edb84dc33020d93aa512bbfe3eaf7c8f8c155f8d924d397d48bb07608e76` |
+| `device/local_backup.rb` | `lib/netstack/connector/backup_persistence_error.rb` | `a5a5edb84dc33020d93aa512bbfe3eaf7c8f8c155f8d924d397d48bb07608e76` |
+| `device/local_backup.rb` | `lib/netstack/connector/local_backup.rb` | `a5a5edb84dc33020d93aa512bbfe3eaf7c8f8c155f8d924d397d48bb07608e76` |
+| `device/profile/builder.rb` | `lib/netstack/connector/profile/builder.rb` | `419f5849d914289a8a6f9cf4e4027a432593129650215e0a3ad82975e8761999` |
+| `device/profile.rb` | `lib/netstack/connector/profile.rb` | `fdbbef914ef66c7ec74d3ddcd9eda212cbbcf858ebc23f343899a889c0020e44` |
+| `device/running_config/strategy.rb` | `lib/netstack/connector/running_config/strategy.rb` | `0af92cff14da30127dc480bf94c72efd1ded9938a8066e10cd5cb01e2e6fd7d1` |
+| `device/running_config/strategy.rb` | `lib/netstack/connector/running_config/rendered.rb` | `0af92cff14da30127dc480bf94c72efd1ded9938a8066e10cd5cb01e2e6fd7d1` |
+| `device/running_config.rb` | `lib/netstack/connector/running_config.rb` | `d85003303c073ba3f22d63175c47546867edbbf29c665de52110358e41aff246` |
+| `device/save_config.rb` | `lib/netstack/connector/save_config.rb` | `8ead7fe2e34e948e1254d4e4170d262674df9d3864c05209246c703fef0798cd` |
+| `device/tftp/file_upload.rb` | `lib/netstack/connector/tftp/file_upload.rb` | `825bd77d5b35562b2bc698705646e8d169b439000d47376b523e3b4977aea696` |
+| `device/tftp/receipt.rb` | `lib/netstack/connector/tftp_receipt.rb` | `4e3622bbf4b3e2bfbe8000501d9a2be996ed07b4e034fe30996421aea0890224` |
+| `device/tftp/receipt.rb` | `lib/netstack/connector/tftp_completion_error.rb` | `4e3622bbf4b3e2bfbe8000501d9a2be996ed07b4e034fe30996421aea0890224` |
+| `device/tftp/strategy.rb` | `lib/netstack/connector/tftp/strategy.rb` | `0f004cef8e98dd5b5883da2a4610f870d2115839cef15ab7cd1af1704215cf70` |
+| `device/tftp/target.rb` | `lib/netstack/connector/tftp_target.rb` | `dbc1b912776809d67221850315482177ffa70d666b8e90d9fdd8a41f5b84c36c` |
+| `device/tftp.rb` | `lib/netstack/connector/tftp.rb` | `dac1d20d76e9b97cc167788b77f179b34d778e5dfe48b944fd34f7b0a871a5f9` |
+| `device/topology/immediate_strategy.rb` | `lib/netstack/connector/topology/immediate_strategy.rb` | `a738030eae4ef1d784c426c6d07e6405771b21d2d754dbb69bbecd13572fe902` |
+| `device/topology/interface_description.rb` | `lib/netstack/connector/topology/interface_description.rb` | `d8def28e63ddc48f96f8c949da3220ebc2477bee78b3940f09f4fb23c193007f` |
+| `device/topology/interface_name.rb` | `lib/netstack/connector/topology/interface_name.rb` | `8c21239d54e772a83acd67aea171178f2c5ea3f8a46a1061bda00ee227a4a0ba` |
+| `device/topology/strategy.rb` | `lib/netstack/connector/topology/strategy.rb` | `be8f5f63a914688d8e1b19633b1506fb8a5b01acf2e4f3204e19128defa8d224` |
+| `device/topology.rb` | `lib/netstack/connector/topology.rb` | `8b9c554a3828d53328d8c43c3c1095b3d9c185397b2be2bcfd8d4ae596949b92` |
+| `engine/authentication.rb` | `lib/netstack/connector/authentication.rb` | `a1f6ecbd0046809847a2887d5c47de9d952f1bbae6cc4ceed69e1a6f38ad98e3` |
+| `engine/command.rb` | `lib/netstack/connector/command.rb` | `987943274b4bccdf8d81806907f44f54c301b612e3e14d1da889a94ab51bcbf3` |
+| `engine/command.rb` | `lib/netstack/connector/script.rb` | `987943274b4bccdf8d81806907f44f54c301b612e3e14d1da889a94ab51bcbf3` |
+| `engine/configuration.rb` | `lib/netstack/connector/configuration.rb` | `aa02c8bf824bf1579d0eb2b8614353d645a0fa35eed20c420fb1f3519be5c50b` |
+| `engine/dialogue.rb` | `lib/netstack/connector/interaction.rb` | `d9a79bd40987375ceb8b721493a336c61cdd317c016a58ff331079f26d3ff2fe` |
+| `engine/dialogue.rb` | `lib/netstack/connector/dialogue.rb` | `d9a79bd40987375ceb8b721493a336c61cdd317c016a58ff331079f26d3ff2fe` |
+| `engine/dialogue.rb` | `lib/netstack/connector/response.rb` | `d9a79bd40987375ceb8b721493a336c61cdd317c016a58ff331079f26d3ff2fe` |
+| `engine/dialogue.rb` | `lib/netstack/connector/response_reader.rb` | `d9a79bd40987375ceb8b721493a336c61cdd317c016a58ff331079f26d3ff2fe` |
+| `engine/error_metadata.rb` | `lib/netstack/connector/error_metadata.rb` | `bac378c4f7853b315b3564acdb3257d5512470781f27e66722bedb29789655b5` |
+| `engine/errors.rb` | `lib/netstack/connector/error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/connection_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/authentication_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/login_timeout.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/command_timeout.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/write_timeout.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/prompt_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/connection_closed.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/transport_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/device_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/script_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/internal_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/output_limit_exceeded.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/script_output_limit_exceeded.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/session_busy.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/unsupported_operation.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/log_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/parsing_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/underlying_error.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/errors.rb` | `lib/netstack/connector/redactor.rb` | `b7c0d7e95312b666609acb00d466c2b8cb58188cf92601cc6bbcf2ab55a95caa` |
+| `engine/execution.rb` | `lib/netstack/connector/execution.rb` | `25161c179e88c20326087db80337435ab06922d3697af24216a55626324baca2` |
+| `engine/known_hosts.rb` | `lib/netstack/connector/known_hosts.rb` | `a65141f63180f61a4df3268772ecd2b25faa0698e9421fc6b4ecf6a21f818d7a` |
+| `engine/log/event.rb` | `lib/netstack/connector/log/event.rb` | `014174c54a2b98dd1e94700928214aa21a4a6502e54978dfff3de3b4f6d2171f` |
+| `engine/log/formatter.rb` | `lib/netstack/connector/log/formatter.rb` | `f114d8747ba7348f52212395942f13d331aeec6f585b46ecbaf0875daa1dae72` |
+| `engine/log/messages.rb` | `lib/netstack/connector/log/messages.rb` | `75cf3261b06a9b2f8ce20034f291f93603fdddf80816e39f93d54f021f0932d5` |
+| `engine/log/stream.rb` | `lib/netstack/connector/log/redacting_writer.rb` | `95bcc9ed2a09cb1acd7f4224394cabee226b4bded175bc6c6968ef1f6b72cc18` |
+| `engine/log/stream.rb` | `lib/netstack/connector/log/transcript.rb` | `95bcc9ed2a09cb1acd7f4224394cabee226b4bded175bc6c6968ef1f6b72cc18` |
+| `engine/log.rb` | `lib/netstack/connector/log.rb` | `40cfd01ffc4da113f1c6bcdd0e4efa95213f4e67a40db2170a2c439cd9efdc73` |
+| `engine/recovery.rb` | `lib/netstack/connector/recovery.rb` | `2fce303db923a77cf3fa99d7bbc70196ae5b4a5bb88b648fc5db0e7f0a42c229` |
+| `engine/result.rb` | `lib/netstack/connector/command_result.rb` | `e16174105375bac53ea00ddc6d3a65a91fab5a0d094c7cd4e02fa50c8253aa69` |
+| `engine/result.rb` | `lib/netstack/connector/result.rb` | `e16174105375bac53ea00ddc6d3a65a91fab5a0d094c7cd4e02fa50c8253aa69` |
+| `engine/session.rb` | `lib/netstack/connector/session.rb` | `307353d6183c402b420cf673551cc3779284b11ee825e195a28500f15651d73e` |
+| `engine/terminal_renderer.rb` | `lib/netstack/connector/terminal_renderer.rb` | `1c716223aecb738e77b3ef6321631413fb39749f8ebbba1196f7eca474d21639` |
+| `engine/terminal_text.rb` | `lib/netstack/connector/terminal_text.rb` | `80851db198f0008026d989eb8da9be7ab44d7f5a071389da19079bf090c6d3b8` |
+| `engine/transport.rb` | `lib/netstack/connector/event.rb` | `ff59a03ab55e25b207d04864c52b7ca6ebfbe54fde666f82934f5f69c65d4183` |
+| `engine/transport.rb` | `lib/netstack/connector/transports.rb` | `ff59a03ab55e25b207d04864c52b7ca6ebfbe54fde666f82934f5f69c65d4183` |
+| `storage/backup_lock.rb` | `lib/netstack/connector/backup_busy.rb` | `4dbb5806e4b92580f8af6f34e7b1cf11f7aad3c0a8bfc5427d81c80964ea4fa6` |
+| `storage/backup_lock.rb` | `lib/netstack/connector/storage/backup_lock.rb` | `4dbb5806e4b92580f8af6f34e7b1cf11f7aad3c0a8bfc5427d81c80964ea4fa6` |
+| `storage/private_file.rb` | `lib/netstack/connector/storage/private_file.rb` | `59992bb0dc264ef7e6d82ea3a20769b60624f805bea810a3f4154b84bbe136ca` |
+| `storage/safe_file.rb` | `lib/netstack/connector/storage/safe_file.rb` | `571d99db152a3947337b1b27d8818f6fd6c1076a37229141e24b37cd6c4e075a` |
+| `storage/saved_config.rb` | `lib/netstack/connector/storage/saved_config.rb` | `6f52412351acf4a1f6d4e5c98d0cbd4598b7eaf19a067b31c0a42f7e22dcec2d` |
+| `textfsm.rb` | `lib/netstack/connector/textfsm.rb` | `1e8197da9a37cf9af6b757a0696dbb93164b14e0705fd2a037279e39dffe577f` |
+| `vendor/cisco_ios/running_config.rb` | `lib/netstack/connector/vendors/cisco_ios/running_config.rb` | `11d809feea41de17c823da3fe6bd107e3df2db444ec1eb285d0ae8d3434f7b9d` |
+| `vendor/cisco_ios/tftp_backup.rb` | `lib/netstack/connector/vendors/cisco_ios/tftp_backup.rb` | `a56aa18d79b42d2dffd720230d4124560acbdeebbfa95536dbb67943ce6d9e4c` |
+| `vendor/cisco_ios/topology.rb` | `lib/netstack/connector/vendors/cisco_ios/topology.rb` | `e0630d2de8adfcdbbc2fe9dc2aca10bee912fd7d26cd2c94d7f733520156a62d` |
+| `vendor/cisco_ios.rb` | `lib/netstack/connector/vendors/cisco_ios.rb` | `302478cc6ff55ce2a5ca90707f2caad4a1d67735fe71e242194a65fc888d09fb` |
+| `vendor/cisco_nxos/running_config.rb` | `lib/netstack/connector/vendors/cisco_nxos/running_config.rb` | `259aae62625b8f37c65e7391486c4e994dc92187a1482152bfc4eb54968d2664` |
+| `vendor/cisco_nxos/tftp_backup.rb` | `lib/netstack/connector/vendors/cisco_nxos/tftp_backup.rb` | `b57e008bdaf726a1501ab37d784bb112cb5bba708b2622b7ed97acdca07ef806` |
+| `vendor/cisco_nxos.rb` | `lib/netstack/connector/vendors/cisco_nxos.rb` | `8ee07b00730437b736d5313473eb2e6765be9aa0f69d70584427c217548b4c3d` |
+| `vendor/h3c/tftp_backup.rb` | `lib/netstack/connector/vendors/h3c/tftp_backup.rb` | `76136351c3af90f28914b79c1706e1662aca58a6b3d3e0fc4938078c155ef8d5` |
+| `vendor/h3c/topology.rb` | `lib/netstack/connector/vendors/h3c/topology.rb` | `b1b10bf5d2d71ad79aa082fdba715db11b65c360fbee939448b1c04209f4f16c` |
+| `vendor/h3c.rb` | `lib/netstack/connector/vendors/h3c.rb` | `1b03458c1a11ef3f2dde2d5cdadf6b16ce556c24a35c9558400ad9ea70797f75` |
+| `vendor/h3c_wireless.rb` | `lib/netstack/connector/vendors/h3c_wireless.rb` | `b702b34128b8b6e8cdc6275392d5420d640319f7e001327c5229622bd582eef3` |
+| `vendor/hillstone/running_config.rb` | `lib/netstack/connector/vendors/hillstone/running_config.rb` | `c84649f204dd00f08a2e9f4706995495fdd12fcd43179c9095a2f3177d10ec1e` |
+| `vendor/hillstone/tftp_backup.rb` | `lib/netstack/connector/vendors/hillstone/tftp_backup.rb` | `e4dcf44e784c7b66610631d6cb726690aa02bc7c2301ba023e75d64f6810646f` |
+| `vendor/hillstone/topology.rb` | `lib/netstack/connector/vendors/hillstone/topology.rb` | `81606694aa18a3372057b5080adb64346165859f63b28e287b6ee1661407cabc` |
+| `vendor/hillstone.rb` | `lib/netstack/connector/vendors/hillstone.rb` | `c921078be010469d762f1820420c08e03a2eaba917a4ab1c00d6a6c8da74bdc8` |
+| `vendor/huawei/tftp_backup.rb` | `lib/netstack/connector/vendors/huawei/tftp_backup.rb` | `702310f7096b9d9624463bc6547f60d1aa1c4a9c65ed70c401303c67457cbf6e` |
+| `vendor/huawei.rb` | `lib/netstack/connector/vendors/huawei.rb` | `eb6fa5b3ec88b9450f183757cfdcf065c3cfcb881427f2513039200f896dd323` |
+| `vendor/palo_alto/running_config.rb` | `lib/netstack/connector/vendors/palo_alto/running_config.rb` | `d0e93012023a06aebeddceebe70c0fee4d3bd840899cac24c63ce82ae1117e07` |
+| `vendor/palo_alto/tftp_backup.rb` | `lib/netstack/connector/vendors/palo_alto/tftp_backup.rb` | `46a277288bddf9b61f99251d32d54c4ba19b92835f17d7f5f5b28e2bf5fd7ec3` |
+| `vendor/palo_alto/topology.rb` | `lib/netstack/connector/vendors/palo_alto/topology.rb` | `0f96170056e7eed570e2e691b1666d04264eb65e24ab54ddd7b258f5a2393f0b` |
+| `vendor/palo_alto.rb` | `lib/netstack/connector/vendors/palo_alto.rb` | `e057bf2c0dd5c2e3e4fddc8953304aeacb05e1970409838dce47f70ce11326c3` |
+| `vendor/radware/running_config.rb` | `lib/netstack/connector/vendors/radware/running_config.rb` | `4022095e149c8c53fbef55bf9967d9c8994cfeceb428a52a6110751b494bf1c7` |
+| `vendor/radware/tftp_backup.rb` | `lib/netstack/connector/vendors/radware/tftp_backup.rb` | `04109e95a5242ab389247b4b2079ce86e71d76a7636e1ccd49b35886180ca1fc` |
+| `vendor/radware/topology.rb` | `lib/netstack/connector/vendors/radware/topology.rb` | `527d34cdbc4ed96e598b871a466db773c4fee3d9ed0a98abc3d59075be5662aa` |
+| `vendor/radware.rb` | `lib/netstack/connector/vendors/radware.rb` | `17a32d794cb2e860a0aca2411cee22bd208e5d6c866b2c81b7084f5e8625884e` |
+
+## 资源与测试来源
+
+模板全部源于同一 net-connector 工作树的 `lib/net/connector/templates/`。下面记录原始资源摘要，方便后续核对厂商模板变更。
+
+| 模板 | 源 SHA-256 |
+| --- | --- |
+| `cisco_cdp_neighbors_detail.textfsm` | `c45cdab78fcf4247987c9e37a9c2ff523aac6c43cde96a795649049174612b3e` |
+| `cisco_ios_running_config_interfaces.textfsm` | `5584b009427874edb879c7e99988352e2f7392ca658a0c17764fb479c748cf08` |
+| `cisco_ios_show_ip_interface_brief.textfsm` | `ae9f850599b4f2d5c28ed1176e2121debac8fe90cf4bdb88d9c652b67702b4cd` |
+| `h3c_interface_descriptions.textfsm` | `1e7ecb6d0355c71956b2e4edc732a554899e3b6acdc1f0b15f2c63e7796f768d` |
+| `h3c_lldp_local_first.textfsm` | `409ce4393aee6d58b0971e4114096f81a986e7a467788ef0f8ecb4768506c660` |
+| `h3c_lldp_name_first.textfsm` | `88d6a00ef3a44f6fd6c080387052944d26c9ebccd56b5e87051e2494ba553055` |
+| `hillstone_interface_descriptions.textfsm` | `c7074cdad05f3193b135148d6b5d4ef7652b2b005b8a351d282afc9023267766` |
+| `hillstone_lldp_neighbors.textfsm` | `96e0f60add044bd3701c5b64aa7a3cb5b563dc046675ced0115afc269e17b97f` |
+| `index` | `4f7a3228d20bb378811a465a0bc1daa8ba86e0dc6ca757a3f671bb4852175443` |
+| `palo_alto_interface_descriptions.textfsm` | `d6a97dfd473354d78a4af767608b4eeca0b6ea9c24c258d09c3d20841ba69f8f` |
+| `palo_alto_lldp_neighbors.textfsm` | `39ce5e20281e41af06987044198c3d5aa5466a6fc1f8123eed987b03beaf8740` |
+| `radware_port_names.textfsm` | `65c7430b724f3796318f3dde59e0742f7eb74dfb6bc39983679ba8066c3fc9c5` |
+
+Minitest 用例保留源断言，仅调整命名空间与加载路径。`backup_lock_test.rb`、`file_persistence_test.rb`、`tftp_boundary_test.rb`、`value_object_contract_test.rb` 只摘取单设备契约；原文件的 Fleet、报告、CLI、批次结果用例不属于此模块。`module_loading_test.rb` 验证新的统一 Zeitwerk、独立入口与安装资源路径。合成 TFTP/拓扑样本的来源说明保存在 `test/support/connector/*_samples.md`。

data/docs/ddi.md

@@ -0,0 +1,142 @@
+# DDI and BlueCat
+
+`Ddi::Manager` owns DNS, DHCP and IPv4 allocation rules. The BlueCat Legacy v1
+client owns authentication, wire methods, pagination and response validation.
+Neither reads environment variables, Motor models, Netdisco or global settings.
+The host owns authorization, durable intents, locks, transactions and jobs.
+
+Passwords retain their original bytes, including surrounding spaces. CNAME target
+comparison ignores DNS name case and the trailing root dot, so an equivalent
+existing record is a no-op rather than a conflict.
+
+```ruby
+client = Netstack::Integrations::Bluecat::Client.new(
+  base_url: "https://bam.example.test", username: username, password: password
+)
+settings = Netstack::Ddi::Settings.new(
+  configuration_id: configuration_id,
+  views: [{ id: view_id, roles: [
+    { interface_id: master_interface_id, type: "MASTER" },
+    { interface_id: slave_interface_id, type: "SLAVE" }
+  ] }],
+  server_ids: deployment_server_ids, policy_id: response_policy_id,
+  protected_ids: protected_object_ids
+)
+manager = Netstack::Ddi::Manager.new(client: client, settings: settings)
+plan = manager.dns_record(name: "edge.example.test", type: "A", value: "192.0.2.10")
+# Authorize and persist plan.to_h, execution_id and scope before applying it.
+result = Netstack::Ddi::Applier.new(client: client, settings: settings).call(
+  plan: plan, execution_id: execution_id, checkpoint: durable_checkpoint
+)
+```
+
+`Settings` takes real server IDs and interface IDs separately. It never assumes
+that one is the other plus or minus one. Configuration, views, servers, configured
+interfaces, response policy and extra protected IDs cannot be deletion targets.
+Plans include a stable digest and explicit settings scope. Restore them with
+`Ddi::Plan.from_h`; changing settings requires replanning and review.
+Object ownership is independently checked through `getParent` ancestry, up to
+64 nodes, ending at the configured Configuration. Missing, cyclic or malformed
+ancestry fails closed. Deletes also reject ancestors of protected objects, and
+the write boundary rechecks scope and the previously observed object identity.
+
+| Intent | Planning method | Rules |
+| --- | --- | --- |
+| DNS zone | `dns_zone(name:, replace: false)` | Exact labels in each managed view; explicit role topology |
+| A/CNAME | `dns_record(name:, value:, type: "A", replace: false)` | IPv4/FQDN validation; conflicting A/CNAME rejected |
+| Forward zone | `dns_forward(name:, roles:, replace: false)` | Explicit MASTER/SLAVE/FORWARDER interfaces; at least one FORWARDER |
+| Response policy | `blacklist(name:, present: true)` | Exact FQDN membership in configured policy; removal with `present: false` |
+| Delete zone | `delete_zone(name:, recursive: true)` | Explicit recursive intent; exact view/label selection; no fuzzy deletion |
+| IPv4 block | `block(cidr:, parent_id:)` | Aligned IPv4 CIDR; parent configuration or larger block |
+| IPv4 network | `network(cidr:, block_id:, gateway:)` | Explicit parent and usable in-subnet gateway |
+| Delete network | `delete_network(cidr:, block_id:)` | Exact CIDR and parent; protected IDs rejected |
+| DHCP range | `dhcp_range(cidr:, network_id:, start:, end_address:)` | Exact network ID/CIDR; usable endpoints; excludes gateway |
+| Tail policy | `dhcp_range(cidr:, network_id:, reserve_tail: 55)` | Explicit source-business reserve tail; too-small networks rejected |
+| Fixed address | `fixed_address(ip:, mac:)` | Usable non-gateway address; reject another MAC's binding |
+| Reserve address | `reserve_address(ip:)` | Requires existing MAC; preserves that binding |
+
+DNS follows the Motor/PDK operation's whole-name zone and apex generic-record
+semantics across configured views. `replace: true` deliberately deletes the
+exact existing zone and its descendants before recreating it. The host must
+authorize that broader destructive intent; use the default conflict rejection
+for ordinary edits. Unrelated records are preserved unless replacement or
+recursive deletion is explicitly requested. The first version supports IPv4,
+A/CNAME and the listed DHCP actions; IPv6 and arbitrary RR types are not implied.
+
+Creating a block, network and DHCP range is an explicit sequence of reviewed
+plans: verify the parent first, then plan the child using its actual ID. No
+environment-specific supernet, gateway, server topology or tail policy is
+silently inferred. A DNS plan automatically orders zone creation, roles and
+record creation; subsequent operations pin the verified parent object's ID.
+CIDR input must contain exactly one address and one prefix separated by `/`.
+Extra or trailing slash components are rejected before selecting any object,
+including for network deletion; they are never discarded during normalization.
+
+## Writes, recovery and deployment
+
+For every operation, `Applier` requires current state to match the reviewed
+precondition, then commits `started`, performs one write, commits its `receipt`,
+reads exact state and commits `verified`. The callback must return literal
+`true` only after durable commit. A callback failure stops the sequence. Persist
+the plan, the complete ordered event stream and the terminal result under an
+exclusive execution ID. Never return `true` from inside an uncommitted outer
+transaction. The gem provides no database implementation or automatic write retry.
+
+```ruby
+result = applier.recover(
+  plan: plan, execution_id: execution_id, events: committed_events,
+  checkpoint: durable_checkpoint
+)
+deployment = Netstack::Ddi::Deployment.new(client: client, settings: settings)
+deployment.submit(plan: plan, mutation_result: result, checkpoint: deployment_checkpoint)
+states = deployment.recover(
+  plan: plan, execution_id: execution_id, events: deployment_events,
+  checkpoint: deployment_checkpoint
+)
+```
+
+Recovery reads back started writes and never replays them. A matching desired
+object and, when available, matching receipt ID are required. Missing or
+conflicting evidence raises `unknown_result`; the host keeps the intent for
+reconciliation. Empty plans complete without writes; the host persists that
+terminal result separately.
+
+Verified configuration writes are separate from deployment submission.
+`Deployment` accepts a matching verified mutation result and submits only the
+plan's DNS/DHCP services to explicit server IDs. Legacy v1 exposes server-wide
+status without a correlation ID. A receipt or an old `DONE` is insufficient:
+completion requires observing an active phase after submission, then `DONE`.
+Lost receipts and missed active transitions remain unknown. The host must
+serialize deployments per server and schedule bounded polling; these APIs do
+not establish causal identity against concurrent administrator deployments.
+Warnings remain a distinct non-success outcome. Never convert unknown to success
+or replay a server submission merely because a job timed out.
+
+After an interrupted submission batch, call `submit` with `events:` containing
+the committed deployment stream. It skips servers with receipts and submits
+only servers never started. A started server lacking its receipt stops with
+`unknown_result`; failed or warning deployments stop further submissions.
+`recover` itself only polls and never submits. Active and terminal status
+evidence is also checkpointed. Each server's Configuration ancestry is checked
+before accessing it.
+
+The HTTP client verifies TLS by default, enforces response size, per-stage and
+total request budgets, and never follows redirects or retries writes. BlueCat
+credentials and its session token live only in the client instance; inspection
+does not expose them. Invalid JSON, malformed object identities, repeated
+pagination pages, response limits and unknown write receipts fail closed.
+
+## Validation and upstream contracts
+
+Offline tests cover complete DNS/IPAM/DHCP flows, deliberate replacement,
+protected deletion, stale plans, mismatched receipt IDs, failed checkpoint
+commits, lost receipts, and deployment phase separation. These tests use
+controlled protocol fixtures; no production BAM or DNS/DHCP server was contacted.
+The adapter follows the source system's Legacy v1 API; compatibility with a
+particular BAM release must be checked with its actual responses before rollout.
+
+- [BlueCat Legacy v1 API guide](https://docs.bluecatnetworks.com/r/Address-Manager-Legacy-v1-API-Guide/Overview/9.6.0)
+- [Exact CIDR lookup](https://docs.bluecatnetworks.com/r/Address-Manager-Legacy-v1-API-Guide/GET/v1/getEntityByCIDR/9.6.0)
+- [Exact response-policy membership](https://docs.bluecatnetworks.com/r/Address-Manager-Legacy-v1-API-Guide/GET/v1/findResponsePoliciesWithItem/9.6.0)
+- [Deployment submission](https://docs.bluecatnetworks.com/r/Address-Manager-Legacy-v1-API-Guide/POST/v1/deployServerServices/9.6.0)
+- [Deployment status values](https://docs.bluecatnetworks.com/r/Address-Manager-Legacy-v1-API-Guide/Deployment-status/9.6.0)

data/docs/deployment.md

@@ -0,0 +1,47 @@
+# Execution and recovery
+
+`Deployment::Plan` contains one immutable `Target`, ordered business `Step` values, preconditions and metadata. A SHA-256 digest identifies its canonical JSON payload. Persist `plan.payload`; recover with `Plan.from_h`. Do not put credentials or configuration text in a plan: configuration plans contain an artifact reference and digest, and adapters resolve the encrypted artifact only at execution.
+
+## Host contract
+
+Before calling the executor, the host must durably create an execution identity and claim the target. The claim must exclude concurrent conflicting work, and checkpoints must reject workers that no longer own it. The gem does not own a database, distributed lease or authorization policy.
+
+The `checkpoint` callback receives an immutable event with `execution_id`, `plan_digest`, `target_key`, `step_id`, status, observation time and the full versioned `receipt` payload. Commit that payload and any audit record atomically in the host database, then return **true**. Enqueuing another job, writing an ordinary application log or returning a truthy object does not acknowledge durability. A callback inside an uncommitted outer transaction is also insufficient: the remote side cannot be rolled back by that transaction.
+
+```ruby
+receipt = Netstack::Deployment::Executor.new(adapter: adapter).apply(
+  plan: persisted_plan,
+  execution_id: execution.id.to_s,
+  previous: persisted_receipt && Netstack::Deployment::Receipt.from_h(persisted_receipt),
+  credentials: credentials,
+  checkpoint: lambda do |event|
+    execution.persist_checkpoint!(event, claim_token: claim_token)
+    true # persist_checkpoint! must have committed before this point
+  end
+)
+```
+
+`persist_checkpoint!` above belongs to the host and must validate the execution, digest, target and current claim under its database concurrency control. Do not copy this example as a callback that blindly updates a record. No network I/O belongs inside a database row lock.
+
+## State transitions
+
+Each fresh step follows `started` (committed before remote I/O), then `applied` or `accepted`, then readback to `verified`. A transport timeout or malformed response after submission means `unknown`, even when the transport says the connection closed. A verified prefix is not an overall success; every planned step must be verified. An empty plan reports `no_changes` without contacting the device.
+
+On restart, `started`, `applied`, `accepted` and `unknown` steps are verified without resubmission. Subsequent steps start only after that readback proves success. `failed` and `not_applied` require review and a deliberate new execution or plan. The executor never resumes at an arbitrary CLI line or replays an uncertain command.
+
+`CheckpointError#receipt` preserves the last in-memory observation when a durable acknowledgement fails. It is evidence for recovery; the exception does not claim that the event was committed. The host should reload its durable receipt and perform readback before any further write.
+
+## Adapter protocol
+
+- `preflight(plan:, previous:, credentials:)` returns exactly true only when target identity, artifact integrity and required baseline conditions are confirmed. Recovery must tolerate already completed planned effects while still detecting unrelated drift.
+- `apply(step:, target:, credentials:, idempotency_key:)` returns a Hash with `status` (`applied`, `accepted`, `failed` or `unknown`) and optional safe `remote_id`, `error_code`, `evidence`.
+- `verify(step:, target:, credentials:, receipt:)` returns `verified`, `failed`, `unknown` or `not_applied` using read-only evidence.
+
+HTTP keys are stable for an execution, plan and step. This does not invent server-side idempotency: an HTTP provider must document and honor that contract. Adapter evidence must exclude credentials and raw sensitive response bodies. `save` or platform-specific disruptive operations need their own verifiable step; a successful command acknowledgement alone is insufficient.
+
+The executor computes the immutable plan digest and ordered step identities once
+per `apply` invocation. Separate invocations share no cached execution state.
+Checkpoint events still contain the complete receipt, and recovery checks the
+same execution, target, plan, step order and idempotency identities before I/O.
+
+Monitoring and DDI have provider-specific journals for object identities and deployment stages. Their documentation describes those journals separately; do not mix their events with `Deployment::Receipt`.

data/docs/foundations.md

@@ -0,0 +1,45 @@
+# 基础能力复用
+
+通用功能优先使用成熟库：IP 地址解析、网络掩码与包含判断来自 Ruby `IPAddr`；对象复制和空白文本判断使用按需加载的 ActiveSupport 扩展；文件加载使用 Zeitwerk。没有全局修改 `IPAddr`、`Set` 或 Rails 配置。
+
+`IPAddr` 属于 Ruby 标准库，ActiveSupport 提供的是另外一组扩展。当前复用边界如下：
+
+| 通用能力 | 使用的实现 | Netstack 保留的业务部分 |
+| --- | --- | --- |
+| IP 解析、掩码、包含关系 | `IPAddr` | 设备地址记法、通配掩码、压缩区间与服务编码 |
+| 深复制、空白判断 | 按需加载 ActiveSupport `deep_dup`、`blank` | 值对象不可变、严格类型与范围校验 |
+| 文件与常量加载 | Zeitwerk | 按领域职责划分命名空间 |
+| HTTP、TLS、JSON、摘要 | `Net::HTTP`、OpenSSL、JSON、Digest | 服务协议、身份关联、超时预算和错误契约 |
+| 交互会话与表格解析 | `expect-pty`、TextFSM | 厂商提示符、命令、恢复与采集完整性 |
+
+配置模板沿用 Motor 已有的受限语法与变量契约，只解释插值、循环和条件。它不是可执行任意 Ruby 的 ERB 环境；宿主保存的模板不会获得执行 Ruby 代码的权限。
+
+## 地址与区间
+
+`Netstack::IPv4 < ::IPAddr` 增加设备配置领域所需的十进制前导零、主机 CIDR 保留、通配掩码、地址区间和服务编码。`IPv6` 复用标准 IPAddr 并增加等价的地址区间与 CIDR 输出。两者不自行实现 IP 字符串语法。
+
+```ruby
+Netstack::IPv4.host_cidr("192.0.2.10", "255.255.255.0") # "192.0.2.10/24"
+Netstack::IPv4.network_cidr("192.0.2.10/24")           # "192.0.2.0/24"
+Netstack::IPv4.parse("192.0.2.10-192.0.2.20")          # RangeSet
+Netstack::IPv4.parse("any").cardinality              # 4294967296
+Netstack::IPv6.canonical("2001:db8::10/64", host: true)
+```
+
+`RangeSet` 对有序、互不相交的非负整数闭区间做并集 `|`、交集 `&`、差集 `-` 和关系判断。它按区间遍历，不枚举所有 IP。Ruby `Set` 适合离散元素，不能代替覆盖 IPv6 空间的压缩区间集合，因此保留这部分经过回归验证的领域算法。
+
+`RangeSet#size` 是区间段数，`#cardinality` 才是元素总数。端点都是非负整数；禁止无穷、倒置或非法区间。对外持久化请使用 JSON 范围端点或 CIDR，不加载不可信 Marshal 数据。
+
+## 配置 Reader
+
+`Configuration::Reader.new(content, vendor: nil, device_id: nil, device_name: nil, created_at: Time.now.utc)` 接受 UTF-8 原文，保留 CRLF/CR/LF 边界与原始内容，拒绝无效编码和 NUL。它提供游标读取、已解析行标记、未解析行遍历、回退和重置，供厂商解析器共享。
+
+Reader 不猜测厂商，也不加载 Algosec 的防火墙策略模块。`checksum` 使用 SHA-256；`parsed_flags` 与未解析行用于保留解析覆盖证据。空白行处理复用 ActiveSupport。来源文件和 SHA-256 记录于根目录 NOTICE。
+
+`Reader#inspect` 只显示字节数、行数和摘要，不展开配置正文；读取原始内容仍需显式访问 `content`。
+
+## 值对象
+
+`Values.copy` 复用 ActiveSupport `deep_dup`，额外施加领域所需的深度不可变约束。它接受 JSON 类型、Time 与本库的 Data 值对象，拒绝无法证明可复制的任意对象；它不会为了冻结结果而冻结调用者持有的原值。
+
+边界整数解析仍然显式区分缺失、nil、false、浮点数和十进制文本。ActiveSupport 的便利转换不会代替业务校验，也不会把未知值默认为 0 或 false。

data/docs/implementation.md

@@ -0,0 +1,68 @@
+# Implementation record
+
+The approved objective is the complete Netstack network business library, with host-owned persistence and no Netdisco implementation. Partial milestones do not constitute completion.
+
+## Confirmed choices
+
+- Independent Ruby gem; Netstack owns the adapted device Connector implementation.
+- Perl PDK supplies business evidence, not compatibility requirements.
+- No Netdisco client, database access, Fleet, dedicated CLI or synchronization jobs.
+- Host owns authorization, inventory source, credentials, execution checkpoints, target ownership, jobs and recovery scheduling.
+- First usable milestone is direct device and wireless collection, then monitoring, VXLAN, configuration delivery, DDI, external backup and Motor integration.
+- Reuse mature external libraries. ActiveSupport is a runtime dependency for suitable core extensions; IPAddr is Ruby's standard implementation. The gem does not require Rails or ActiveRecord.
+- Absorb Algosec's interval/IP operations and configuration Reader. Netstack names them RangeSet, IPv4, IPv6 and Configuration::Reader without shadowing ::Set or ::IPAddr.
+
+## Review follow-up — 2026-10-01
+
+The deep review repaired collection completeness and expected Fabric coverage,
+wireless binding identity, monitoring ownership and circuit cleanup, strict input
+and diagnostic boundaries, and bounded template/known-host lock work. Topology
+description writes now use separate durable change and persistence steps with
+artifact verification and readback-only recovery. Inventory reconciliation uses
+identity indexes; Executor reuses identity only within each call.
+
+The revised library passes all 664 tests / 7702 assertions on macOS Ruby 3.4.11 and
+4.0.7, 307-file lint, eager loading and isolated installation including the new
+topology API. See [acceptance.md](acceptance.md) for limits and
+[performance.md](performance.md) for reproducible offline measurements. The
+original host/Linux evidence below predates these review changes.
+
+## Original delivered scope and evidence — 2026-09-30
+
+| Area | Current state |
+| --- | --- |
+| Gem, loader, dependency resolution | Implemented; local Bundler resolution, eager loading and installed-package gates succeed on Ruby 3.4.11 and 4.0.7 |
+| Connector | Adapted by connector task; tests cover sessions, partial results, security, locks, backups, parsing and TFTP; source manifest in connector.md |
+| IP/range operations and configuration Reader | Implemented using IPAddr, granular ActiveSupport and the adapted interval/Reader contracts; included in the full passing suite |
+| Inventory and Routing | Typed models, CLI configuration parser, collection, scoped reconciliation and lookup implemented; provider coverage and explicit unsupported dimensions documented in inventory.md |
+| Wireless | H3C/Huawei collection, parsing, strong identities, reconciliation, views and assessment implemented; focused and integration tests pass |
+| Monitoring and Circuits | Zabbix planning/application/recovery, history sampling and business-calendar capacity review implemented; boundary audit and regression checks passed |
+| VXLAN | NX-OS configuration/runtime parsing, Fabric audit, Segment incremental planning and verified deployment implemented; offline tests pass |
+| Deployment | Versioned JSON plans/receipts, strict operation identity, durable-checkpoint executor, CLI and HTTP adapters implemented; offline recovery tests pass |
+| Configuration scenarios | All eight scenarios and eleven bundled templates implemented, with single-target IRF/vPC sections and explicit manual-script artifacts |
+| BlueCat/DDI, Oxidized/Backups | Protocol clients, business operations, object journals and separate deployment/backup verification implemented; configuration ancestry, protected descendants and target identity regressions passed |
+| Motor integration | Actual CLI wireless, configuration generation, HTTP delivery, backup, persistent device monitoring and DDI entrypoints implemented; 83 combined RSpec examples passed, including 34 real PostgreSQL persistence/recovery examples |
+| Documentation, package isolation, full CI/version matrix | Full local macOS/Linux × Ruby 3.4/4.0 gates passed: 614 tests / 7142 assertions per environment, 294 files lint clean, eager load and isolated installed gem with bundled resources verified; remote CI was not run |
+
+## Contract coordination
+
+- `Netstack::Values.copy` uses ActiveSupport deep copying and enforces deeply immutable accepted values. Boundary parsing still rejects invalid types rather than coercing them silently.
+- `Target.new(key:, host:, platform:, attributes: {})` is an immutable host-supplied identity.
+- `Dimension` distinguishes complete, partial, unsupported, failed and not_requested. An empty array alone does not establish completeness.
+- `Deployment::Plan` owns target, ordered steps, preconditions, metadata and a canonical SHA-256 digest.
+- `Executor#apply(plan:, execution_id:, checkpoint:, credentials:, previous: nil)` requires synchronous checkpoints returning true. The host must persist execution ownership before invoking it.
+- Provider adapter: `preflight(plan:, previous:, credentials:)` returns true, `apply(step:, target:, credentials:, idempotency_key:)` returns a typed status hash, `verify(step:, target:, credentials:, receipt:)` returns a verification status hash.
+- Incomplete execution receipts retain the full planned step identity list. A verified prefix cannot report overall completion.
+- Host checkpoint failures stop further writes. Unknown writes are read back before any further decision and are never replayed automatically.
+- HTTP adapter API is documented by `Integrations::Http::Client` and shared by Zabbix and future integration clients.
+
+## Reference trees
+
+- net-connector HEAD at start: `63935c03bcd340991075b04faa14741df535d4c1`; current worktree source hashes are required because it includes uncommitted changes.
+- Motor HEAD at start: `46a959ebcfadc35b07d11e1bdfe222f499ddc650`; its worktree also includes uncommitted changes.
+- PDK was inspected from the current crated worktree.
+- Algosec reference checkout has no usable HEAD; source file hashes, rather than an invented commit, identify the absorbed implementations.
+
+No production devices or external services have been contacted. Local protocol fixtures and PTY tests establish only their respective boundaries.
+
+Final commands, environment versions and delivery limits are recorded in [acceptance.md](acceptance.md). Motor entrypoints and migration requirements are in [motor_integration.md](motor_integration.md). The implementation is local and uncommitted; publication and production routing changes were not performed.

data/docs/inventory.md

@@ -0,0 +1,42 @@
+# Inventory and Routing
+
+`Target` is the host's stable key, management address and connector platform. `Inventory::Snapshot` holds typed dimensions for device, interfaces, transceivers and neighbors; each has its own completeness and observation window. Snapshot completeness means every requested dimension is complete. A request for no dimensions is not a complete observation.
+
+## Direct collection
+
+`Inventory::Collector#collect(target:, dimensions:, connection_options:, scope:)` collects device identity/version and configured interfaces for H3C, H3C wireless, Huawei, Cisco IOS and Cisco NX-OS. Interface configuration establishes administrative state and configured addresses; it does not establish operational link state. Neighbor collection uses the Connector's advertised capability and parsing strategy.
+
+Transceivers have a typed model and reconciliation support, but no generic CLI collection capability is claimed. Supply a complete typed dimension from a dedicated host/provider collector when available; the direct collector reports `unsupported`. Routing has typed snapshot and lookup APIs; provider collection is external to this module. Netdisco integration is deliberately outside this gem.
+
+Configuration and version commands are read-only. Input dimensions, scope and target-host overrides are checked before opening a connection. Errors are recorded with safe codes, without including credentials or raw exception text. Failed reads do not become empty complete observations.
+
+`scope: { interfaces: ["Ethernet1/1"] }` declares exactly the interface identities collected. Interface identity comparisons normalize case while preserving host display spelling. IPv4 and IPv6 interface addresses preserve host bits; route destinations normalize to network prefixes. Scoped IPv6 text needs an explicit future interface-scope contract and is rejected rather than silently stripped.
+
+## Reconciliation
+
+`Inventory::Reconciler#call(current:, snapshot:, target:)` returns `Changes`, not database writes. `current` maps dimensions to rows shaped as:
+
+```ruby
+{ key: "Ethernet1/1", source: "cli", managed_fields: %i[description addresses],
+  attributes: { name: "Ethernet1/1", description: "old", addresses: [] } }
+```
+
+Only complete dimensions produce changes. Only fields listed in an existing row's `managed_fields` are updated, and only rows owned by the snapshot source can be updated or removed. Removal is constrained to the declared collection scope. A manually managed row or another provider's row cannot be overwritten merely because its identity matches.
+
+Creates and updates retain observation order; removals retain the order of current host rows. Identity indexing preserves these orders and the same source, field ownership, and scope rules for large collections.
+
+The host must validate its current device identity and snapshot revision under a short database lock before applying changes. It owns uniqueness constraints, source ownership, collection revision and transaction boundaries. Collect outside the lock, reconcile/apply inside the transaction, and retain old data for partial/failed/unsupported dimensions.
+
+## Route lookup
+
+`Routing::Route` contains target key, VRF, destination prefix, protocol, optional preference/metric, next hop and interface. `Routing::Snapshot` rejects foreign target keys, foreign VRFs and duplicate routes.
+
+```ruby
+result = Netstack::Routing::Lookup.new.call(
+  routes: routes, destination: "192.0.2.15", target_key: "leaf-1", vrf: "default"
+)
+result.status # matched, not_found or ambiguous
+result.routes # preserves equal-cost next hops
+```
+
+Lookup selects the longest prefix, then lower preference and metric. It does not compare metrics across different protocols or invent missing costs. Such cases return `ambiguous` with the candidate routes, rather than an arbitrary winner. VRF, device and address family remain isolated.