netstack 0.1.1 → 0.2.0

data/lib/netstack/connector/tftp/file_upload.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class Tftp
+      # H3C 和华为共用已保存文件上传流程，源文件发现仍由厂商策略负责。
+      class FileUpload < Strategy
+        # 未指定目标名时，设备使用配置源文件的 basename。
+        def default_path(source_file) = File.basename(source_file)
+
+        # H3C 探测源文件之前先拒绝不支持的参数；探测本身不能放进纯校验钩子。
+        def validate_options!(_target, source_file:, vrf: nil)
+          raise ArgumentError, "TFTP file upload does not use vrf" unless vrf.nil?
+
+          TftpTarget.validate_source_file!(source_file) unless source_file.nil?
+        end
+
+        # 指定文件的内容与格式未知，不能仅凭 .cfg 后缀声称是当前运行配置。
+        def receipt_metadata(_target, source_file:, **)
+          { configuration_kind: :saved_file, source_file: source_file, format: :unknown }
+        end
+
+        # 仅在调用方指定目标名时追加参数，保留设备原生命名行为。
+        def script(target, source_file:, vrf: nil)
+          validate_options!(target, source_file: source_file, vrf: vrf)
+          TftpTarget.validate_source_file!(source_file)
+
+          destination = target.explicit_path? ? " #{target.path}" : ""
+          Script.new([Command.new("tftp #{target.host} put #{source_file}#{destination}", timeout: 180)])
+        end
+
+        # 只接受明确的成功消息、非零传输字节数或完整进度行。
+        def device_reported_complete?(result)
+          completion_lines(result).any? { |line| completed_upload?(line) }
+        end
+
+        private
+
+        # 两个厂商的上传完成消息使用相同的文本及进度格式。
+        def completed_upload?(line)
+          line.match?(/\A
+            (?:File\s+)?(?:transfer|upload)(?:\s+(?:is|was))?\s+
+            (?:success(?:ful(?:ly)?)?|succeeded|complete(?:d)?(?:\s+successfully)?)[.!]?
+            \z/ix) ||
+            line.match?(/\A[1-9]\d*\s+bytes?\s+sent(?:\s+in\s+[\d.]+\s+(?:secs?|seconds?))?[.!]?\z/i) ||
+            completed_progress?(line)
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/tftp/strategy.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class Tftp
+      class Strategy
+        # 厂商只声明格式差异，清单规划与设备直连共用同一命名规则。
+        def self.file_extension = "cfg"
+
+        # 不创建会话即可生成目标名，供批量计划检查文件覆盖风险。
+        def self.filename(host, label: nil)
+          TftpTarget.filename(host, extension: file_extension, label: label)
+        end
+
+        # 保存 TFTP 厂商策略使用的设备对象。
+        def initialize(device)
+          @device = device
+          @responses = []
+        end
+
+        # 返回调用方指定的配置源文件。
+        def resolve_source_file(value) = value
+
+        # 根据设备地址生成默认远端文件名。
+        def default_path(_source_file) = self.class.filename(@device.host)
+
+        # 返回目标中指定的远端文件名。
+        def remote_path(target, _result) = target.path
+
+        private
+
+        # 记录脚本的静态响应，避免文件名或 VRF 回显成为传输完成证据。
+        def interaction(pattern, response)
+          @responses << response.chomp
+          Interaction.new(pattern, response, capture: false)
+        end
+
+        # 只从设备消息中核对完成状态；命令、交互响应和最终提示均不是传输证据。
+        def completion_lines(result)
+          step = result.steps.last
+          return [] unless step
+
+          output = TerminalRenderer.render(step.output)
+          prompt = TerminalRenderer.render(step.prompt.to_s)
+          output = output.delete_suffix(prompt) unless prompt.empty?
+          echoes = [step.command.text, "#{prompt.strip}#{step.command.text}", *@responses]
+          output.each_line.map(&:strip).reject { |line| line.empty? || echoes.include?(line) }
+        end
+
+        # 只接受字节数非零、已发送量与总量相同的 curl 完成进度行。
+        def completed_progress?(line)
+          line.match?(/\A100\s+([1-9]\d*(?:\.\d+)?[kMGT]?)\s+0\s+0\s+100\s+\1(?:\s+[\d.:kMGT-]+)*\z/i)
+        end
+
+        # Cisco 明确报告复制完成的字节数，可附带耗时和速率。
+        def copied_bytes?(line)
+          line.match?(/\A
+            [1-9]\d*\s+bytes?\s+copied
+            (?:\s+in\s+[\d.]+\s+(?:secs?|seconds?)(?:\s+\([\d.]+\s+bytes\/sec\))?)?[.!]?
+            \z/ix)
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/tftp.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class Tftp
+      # 设备入口与功能实现共置，Device 只组合能力，不重复业务流程。
+      module Capability
+        # 要求设备直接向 TFTP 服务器导出原生配置。
+        # 完成仅表示设备报告传输成功，未读取服务器端文件。
+        def tftp_backup(host:, path: nil, source_file: nil, vrf: nil)
+          Tftp.new(self).call(host: host, path: path, source_file: source_file, vrf: vrf)
+        end
+      end
+
+      # 保存执行 TFTP 导出的设备对象。
+      def initialize(device) = @device = device
+
+      # 参数先纯校验；源探测、上传、证据核对及收尾共用一次会话租约。
+      def call(host:, path: nil, source_file: nil, vrf: nil)
+        receipt = nil
+        strategy_class = @device.profile.tftp_strategy
+        unless strategy_class
+          raise UnsupportedOperation.new("native TFTP backup is not supported for this vendor",
+                                         host: @device.host, phase: :tftp_backup)
+        end
+        strategy = strategy_class.new(@device)
+        if !vrf.nil? && (!vrf.is_a?(String) || !vrf.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/))
+          raise ArgumentError, "vrf must be a single safe name"
+        end
+        source_file = TftpTarget.validate_source_file!(source_file).dup.freeze unless source_file.nil?
+        vrf = vrf&.dup&.freeze
+        target = TftpTarget.new(host: host, path: path.nil? ? "preflight.cfg" : path, explicit_path: !path.nil?)
+        strategy.validate_options!(target, source_file: source_file, vrf: vrf)
+        @device.with_operation(:tftp_backup) do
+          source = strategy.resolve_source_file(source_file)
+          source = TftpTarget.validate_source_file!(source).dup.freeze unless source.nil?
+          target = TftpTarget.new(host: target.host, path: strategy.default_path(source), explicit_path: false) if path.nil?
+          result = @device.execute_operation(strategy.script(target, source_file: source, vrf: vrf),
+                                             name: :tftp_backup, privilege: false)
+          confirm_transfer!(strategy, target, result)
+          # 一旦看到明确完成证据就保存回执；路径解析或用户钩子失败也不能抹去上传事实。
+          requested_path = target.explicit_path? ? target.path : nil
+          receipt = TftpReceipt.new(server: target.host, path: nil, completed_at: Time.now.utc,
+                                    requested_path: requested_path, source_file: source)
+          actual_path = remote_path(strategy, target, result, receipt)
+          receipt = receipt.with(path: actual_path)
+          receipt = build_receipt(strategy, target, source, !source_file.nil?, receipt)
+          if target.explicit_path? && target.path != receipt.path
+            raise TftpCompletionError.new(receipt: receipt, code: :transfer_path_mismatch, host: @device.host), cause: nil
+          end
+          # 已完成步骤仍可能伴随后处理/清理错误；上面的回执要先构造，再重新抛出。
+          result.value! if result.failure?
+          @device.log_event("tftp_backup", status: "reported_uploaded", phase: :tftp_backup,
+                                server: target.host, path: receipt.path)
+          receipt
+        end
+      rescue StandardError => error
+        raise unless receipt
+        raise if error.instance_of?(TftpCompletionError) && error.receipt.equal?(receipt)
+
+        raise TftpCompletionError.new(receipt: receipt, host: @device.host, underlying: error), cause: nil
+      end
+
+      private
+
+      def build_receipt(strategy, target, source_file, explicit_source, receipt)
+        metadata = strategy.receipt_metadata(target, source_file: source_file, explicit_source: explicit_source)
+        unless metadata.is_a?(Hash) && (metadata.keys - %i[configuration_kind source_file format requested_path]).empty?
+          raise ArgumentError, "invalid TFTP strategy receipt metadata"
+        end
+        receipt.with(**{ source_file: source_file, requested_path: target.path }.merge(metadata))
+      end
+
+      def remote_path(strategy, target, result, receipt)
+        TftpTarget.validate_path!(strategy.remote_path(target, result))
+      rescue StandardError => error
+        raise TftpCompletionError.new(receipt: receipt, code: :transfer_path_unconfirmed,
+                                       host: @device.host, underlying: error), cause: nil
+      end
+
+      # 失败证据优先；步骤中的明确完成行可在随后清理失败时证明设备已经报告上传。
+      def confirm_transfer!(strategy, target, result)
+        if transfer_failed?(result)
+          @device.log_event("tftp_backup", level: :error, status: "transfer_failed", phase: :tftp_backup,
+                                code: :transfer_failed, server: target.host)
+          raise DeviceError.new("device reported TFTP backup failure",
+                                code: :transfer_failed, host: @device.host, phase: :tftp_backup)
+        end
+        return if strategy.device_reported_complete?(result)
+
+        result.value! if result.failure?
+        @device.log_event("tftp_backup", level: :error, status: "transfer_unconfirmed", phase: :tftp_backup,
+                              code: :transfer_unconfirmed, server: target.host)
+        raise DeviceError.new("device did not confirm TFTP backup completion",
+                              code: :transfer_unconfirmed, host: @device.host, phase: :tftp_backup)
+      end
+
+      # 识别设备回显中的传输失败信息。
+      def transfer_failed?(result)
+        result.steps.any? do |step|
+          # 文件名中的 failed.cfg、error-backup 等不属于诊断词；句末标点仍是词边界。
+          pattern = %r{(?<![\w./-])
+            (?:error|failed|failure|aborted|denied|timed\ out|timeout|not\ found|no\ such\ file|
+               unable\ to|network\ is\ unreachable|can't\ open)
+            (?![\w/-]|\.[\w])}ix
+          # 原始诊断不能被回车抹除，颜色控制符也不能掩盖失败词。
+          history = step.output.gsub(/\r(?!\n)/, "\n")
+          step.output.match?(pattern) || TerminalRenderer.render(history).match?(pattern) ||
+            TerminalRenderer.render(step.output).match?(pattern)
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/tftp_completion_error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+
+
+module Netstack
+  module Connector
+    # 上传已确认后的失败不能被解释为“尚未上传”，也不能携带原始诊断正文。
+    class TftpCompletionError < Error
+      MESSAGES = {
+        transfer_finalize_failed: "device reported TFTP completion but finalization failed",
+        transfer_path_unconfirmed: "device reported TFTP completion but its remote path is unconfirmed",
+        transfer_path_mismatch: "device reported TFTP completion at a different remote path"
+      }.freeze
+      private_constant :MESSAGES
+
+      attr_reader :receipt, :underlying_type
+
+      def initialize(receipt:, code: :transfer_finalize_failed, host: nil, underlying: nil)
+        unless receipt.instance_of?(TftpReceipt) && MESSAGES.key?(code)
+          raise ArgumentError, "TFTP completion error requires a transfer receipt and a known failure code"
+        end
+
+        @receipt = receipt
+        type = if underlying.is_a?(Error) && underlying.underlying.instance_of?(UnderlyingError)
+                 underlying.underlying.type
+               else
+                 underlying&.class&.name
+               end
+        @underlying_type = type&.match?(/\A[A-Za-z_]\w*(?:::[A-Za-z_]\w*)*\z/) && type.bytesize <= 128 ? type.freeze : nil
+        super(MESSAGES.fetch(code), code: code, host: host, phase: :tftp_backup)
+      end
+    end
+  end
+end

data/lib/netstack/connector/tftp_receipt.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+
+
+module Netstack
+  module Connector
+    # 一次设备上报上传的不可变回执；path 是实际目标，未知时保持 nil。
+    TftpReceipt = Data.define(:server, :path, :completed_at, :configuration_kind, :source_file,
+                             :format, :requested_path, :verification, :server_sha256, :server_bytes, :local_path,
+                             :archive_path)
+
+    class TftpReceipt
+      KINDS = %i[running startup saved_file native_archive unknown].freeze
+      FORMATS = %i[cfg xml dat tgz unknown].freeze
+      private_constant :KINDS, :FORMATS
+
+      def initialize(server:, path:, completed_at:, configuration_kind: :unknown, source_file: nil,
+                     format: :unknown, requested_path: nil, verification: :device_reported, server_sha256: nil,
+                     server_bytes: nil, local_path: nil, archive_path: nil)
+        raise ArgumentError, "completed_at must be a Time" unless completed_at.is_a?(Time)
+
+        TftpTarget.new(host: server, path: path.nil? ? "unconfirmed" : path)
+        TftpTarget.validate_path!(requested_path) unless requested_path.nil?
+        TftpTarget.validate_source_file!(source_file) unless source_file.nil?
+        unless KINDS.include?(configuration_kind) && FORMATS.include?(format)
+          raise ArgumentError, "invalid TFTP configuration kind or format"
+        end
+        valid_verification = (verification == :device_reported && server_sha256.nil?) ||
+          (verification == :server_verified && !path.nil? && server_sha256.is_a?(String) &&
+            server_sha256.match?(/\A[0-9a-f]{64}\z/))
+        raise ArgumentError, "invalid TFTP verification evidence" unless valid_verification
+
+        if (!server_bytes.nil? && (!server_bytes.is_a?(Integer) || !server_bytes.positive?)) ||
+          (!local_path.nil? && (!local_path.is_a?(String) || local_path.empty?)) ||
+          (!archive_path.nil? && (!archive_path.is_a?(String) || archive_path.empty?)) ||
+          (verification != :server_verified && (server_bytes || local_path || archive_path))
+          raise ArgumentError, "invalid server file metadata"
+        end
+        super(server: server.dup.freeze, path: path&.dup&.freeze, completed_at: completed_at.dup.freeze,
+              configuration_kind: configuration_kind, source_file: source_file&.dup&.freeze, format: format,
+              requested_path: requested_path&.dup&.freeze, verification: verification,
+              server_sha256: server_sha256&.dup&.freeze, server_bytes: server_bytes, local_path: local_path&.dup&.freeze,
+              archive_path: archive_path&.dup&.freeze)
+      end
+
+      # Ruby 3.2 的 Data#with 不调用 initialize；所有更新都重新校验并冻结字段。
+      def with(**attributes) = self.class.new(**to_h.merge(attributes))
+
+      def inspect = "#<#{self.class} kind=#{configuration_kind} format=#{format} verification=#{verification}>"
+    end
+  end
+end

data/lib/netstack/connector/tftp_target.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "digest"
+
+module Netstack
+  module Connector
+    # 设备主动上传使用的 TFTP 目标，服务器必须能被设备访问。
+    class TftpTarget
+      MAX_PATH_BYTES = 220
+
+      attr_reader :host, :path
+
+      # 校验并保存 TFTP 服务器、远端路径及显式文件名标记。
+      def initialize(host:, path:, explicit_path: true)
+        unless host.is_a?(String) && host.bytesize <= 253 &&
+               host.match?(/\A[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?\z/) && !host.include?("..")
+          raise ArgumentError, "TFTP host must be an IPv4 address or DNS name"
+        end
+        self.class.validate_path!(path)
+        @host, @path = host.dup.freeze, path.dup.freeze
+        @explicit_path = explicit_path
+        freeze
+      end
+
+      # 判断调用方是否明确指定了远端文件名。
+      def explicit_path? = @explicit_path
+
+      # 校验设备或调用方给出的远端相对路径。
+      def self.validate_path!(path)
+        unless path.is_a?(String) && path.bytesize <= MAX_PATH_BYTES &&
+               path.match?(/\A[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\z/) &&
+               path.split("/").none? { |part| %w[. ..].include?(part) }
+          raise ArgumentError, "TFTP path must be a relative filename or path without traversal"
+        end
+        path
+      end
+
+      # 设备地址和可选清单名称共用目标长度限制；极长地址用稳定摘要表示。
+      def self.filename(host, extension:, label: nil)
+        if label && (!label.is_a?(String) || !label.ascii_only?)
+          raise ArgumentError, "TFTP label must be an ASCII String"
+        end
+
+        address = host.gsub(/[^A-Za-z0-9._-]/, "_")
+        suffix = "#{address}.#{extension}"
+        if suffix.bytesize > MAX_PATH_BYTES - (label ? 2 : 0)
+          suffix = "#{Digest::SHA256.hexdigest(host)}.#{extension}"
+        end
+        path = label ? "#{label.byteslice(0, MAX_PATH_BYTES - suffix.bytesize - 1)}-#{suffix}" : suffix
+        validate_path!(path)
+      end
+
+      # 校验设备源文件路径是否符合命令安全约束。
+      def self.validate_source_file!(value)
+        unless value.is_a?(String) && value.match?(/\A[A-Za-z0-9._:\/-]+\z/) &&
+               !value.split("/").include?("..")
+          raise ArgumentError, "source_file must be a device file path without spaces or traversal"
+        end
+        value
+      end
+    end
+  end
+end

data/lib/netstack/connector/topology/checkpoint_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Connector
+    class Topology
+      class CheckpointError < Deployment::CheckpointError
+        attr_reader :result
+
+        def initialize(receipt:, result:)
+          @result = result
+          super(receipt: receipt)
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/topology/deployment_adapter.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Connector
+    class Topology
+      # Each write resolves its private command artifact afresh. Recovery uses only reviewed readback expectations.
+      class DeploymentAdapter
+        def initialize(topology:, device:, strategy:, artifact_resolver:)
+          raise InputError, "topology artifact resolver must be callable" unless artifact_resolver.respond_to?(:call)
+
+          @topology, @device, @strategy, @resolver = topology, device, strategy, artifact_resolver
+          @steps = []
+        end
+
+        def result = Result.new(steps: @steps, error: @error)
+
+        def record_error(error)
+          return if @error
+
+          @error = error.is_a?(Connector::Error) ? error : InternalError.new("topology execution failed", phase: :apply)
+        end
+
+        def preflight(plan:, previous:, **) # rubocop:disable Naming/PredicateMethod -- Deployment adapter protocol.
+          @plan = plan
+          validate_plan!
+          return true if plan.steps.empty?
+
+          @changes = expected_changes(plan.steps.first.expected)
+          if !previous || previous.steps.empty?
+            artifact = resolve(plan.steps.first)
+            @topology.send(:revalidate_plan!, artifact)
+          else
+            verify_neighbors!
+            verify_descriptions! if previous.steps.first[:status] == :verified
+          end
+          true
+        end
+
+        def apply(step:, target:, idempotency_key:, **)
+          raise InputError, "topology target changed" unless target == @plan.target
+
+          artifact = resolve(step)
+          stages = @topology.send(:stage_scripts, artifact.changes)
+          outcome = @device.execute_script(stages.fetch(step.id.to_sym))
+          @steps.concat(outcome.steps)
+          if step.id == "change"
+            record_error(outcome.error) if outcome.failure?
+            { status: outcome.success? ? :applied : :unknown, evidence: { completed_commands: outcome.steps.size } }
+          elsif outcome.success? && @strategy.persistence_confirmed?(outcome)
+            { status: :applied, evidence: { persistence_confirmed: true, artifact_sha256: artifact.sha256,
+                                          operation_key: idempotency_key } }
+          else
+            record_error(@topology.send(:build_persistence_error, outcome.error))
+            { status: :unknown, error_code: :persistence_unconfirmed }
+          end
+        rescue StandardError => error
+          record_error(error)
+          raise
+        end
+
+        def verify(step:, target:, receipt:, **)
+          raise InputError, "topology target changed" unless target == @plan.target
+
+          if step.id == "change"
+            verify_descriptions!
+            { status: :verified }
+          elsif receipt.dig(:evidence, :persistence_confirmed) == true &&
+                receipt.dig(:evidence, :artifact_sha256) == step.parameters[:sha256] &&
+                receipt.dig(:evidence, :operation_key) == receipt[:idempotency_key]
+            { status: :verified }
+          else
+            record_error(@topology.send(:build_persistence_error))
+            { status: :unknown, error_code: :persistence_unconfirmed }
+          end
+        rescue StandardError => error
+          record_error(error)
+          { status: :unknown, error_code: :verification_unconfirmed }
+        end
+
+        private
+
+        def validate_plan!
+          unless @plan.target.host == @device.host && @plan.target.platform == @device.vendor.to_s &&
+                 @plan.metadata[:domain] == "interface_descriptions"
+            raise InputError, "topology deployment belongs to a different device or domain"
+          end
+          return if @plan.steps.empty?
+
+          unless @plan.steps.map(&:id) == %w[change persist] &&
+                 @plan.steps.all? { |step| step.action == "interface_descriptions_#{step.id}" } &&
+                 @plan.steps.first.parameters == @plan.steps.last.parameters &&
+                 @plan.steps.first.expected == @plan.steps.last.expected
+            raise InputError, "topology deployment requires ordered change and persist steps"
+          end
+          @plan.steps.each do |step|
+            reference, digest = step.parameters.values_at(:artifact_ref, :sha256)
+            unless step.parameters.keys.sort == %i[artifact_ref sha256] && reference.is_a?(String) && !reference.empty? &&
+                   digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/) && @plan.metadata[:artifact_sha256] == digest
+              raise InputError, "invalid topology artifact reference"
+            end
+          end
+        end
+
+        def expected_changes(expected)
+          unless expected.keys.sort == %i[changes verification_commands] && expected[:changes].is_a?(Array) && !expected[:changes].empty? &&
+                 expected[:verification_commands].is_a?(Array) && !expected[:verification_commands].empty?
+            raise InputError, "invalid topology readback expectations"
+          end
+          changes = expected[:changes].map do |item|
+            neighbor = item.fetch(:neighbor)
+            neighbor = Neighbor.new(**neighbor.merge(protocol: neighbor.fetch(:protocol).to_sym))
+            unless item.keys.sort == %i[interface neighbor new_description] && neighbor.to_h.except(:protocol).values.all?(String) &&
+                   %i[cdp lldp].include?(neighbor.protocol)
+              raise InputError, "invalid topology readback identity"
+            end
+            InterfaceDescription.validate_interface!(item[:interface])
+            InterfaceDescription.validate!(item[:new_description])
+            Change.new(interface: item[:interface], old_description: "", new_description: item[:new_description], neighbor: neighbor)
+          end
+          keys = changes.map { |change| @strategy.interface_key(change.interface) }
+          raise InputError, "topology readback interfaces must be unique" unless keys.uniq == keys
+          @verification = Script.new(expected[:verification_commands])
+          changes
+        rescue KeyError, TypeError, NoMethodError, ArgumentError
+          raise InputError, "invalid topology readback expectations", cause: nil
+        end
+
+        def resolve(step)
+          begin
+            artifact = @resolver.call(step.parameters.fetch(:artifact_ref))
+          rescue StandardError
+            raise Netstack::Error.new("topology artifact resolution failed", code: :artifact_unavailable, stage: :preflight), cause: nil
+          end
+          unless artifact.is_a?(Plan) && artifact.sha256 == step.parameters[:sha256]
+            raise Netstack::Error.new("topology artifact is unavailable or changed", code: :artifact_changed, stage: :preflight)
+          end
+          artifact.validate_target!(@plan.target)
+          unless artifact.deployment_plan(target: @plan.target, artifact_ref: step.parameters[:artifact_ref]).payload == @plan.payload
+            raise InputError, "topology artifact does not match the reviewed deployment"
+          end
+          stages = @topology.send(:stage_scripts, artifact.changes)
+          unless stages.values.flat_map { |script| script.map(&:text) } == artifact.commands &&
+                 stages.fetch(:verify).map(&:text) == artifact.verification_commands
+            raise ArgumentError, "topology commands changed; regenerate the reviewed plan"
+          end
+          artifact
+        end
+
+        def verify_neighbors!
+          discovered = @topology.neighbors
+          grouped = discovered.group_by { |neighbor| @strategy.interface_key(neighbor.local_interface) }
+          return if @changes.all? { |change| grouped[@strategy.interface_key(change.interface)] == [change.neighbor] }
+
+          raise DeviceError.new("neighbors changed since topology approval", code: :stale_plan, host: @device.host, phase: :verify)
+        end
+
+        def verify_descriptions!
+          @topology.send(:verify_descriptions!, @changes, @verification, @steps)
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/topology/execution_result.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Connector
+    class Topology
+      # Durable state is separate from this attempt's write/readback evidence, not a full session transcript.
+      class ExecutionResult
+        attr_reader :receipt, :result
+
+        def initialize(receipt:, result:)
+          unless receipt.is_a?(Deployment::Receipt) && result.is_a?(Connector::Result)
+            raise InputError, "topology execution requires a receipt and a connector result"
+          end
+          @receipt, @result = receipt, result
+          freeze
+        end
+
+        def success? = receipt.verified? || receipt.no_changes?
+        def failure? = !success?
+        def no_changes? = receipt.no_changes?
+
+        def value!
+          unless success?
+            code = receipt.failed? ? :execution_failed : :execution_unconfirmed
+            raise Netstack::Error.new("interface description execution was not verified", code: code, stage: :verification), cause: nil
+          end
+          result.config || result.output
+        end
+
+        def inspect = "#<#{self.class} success=#{success?} steps=#{receipt.steps.size} response_steps=#{result.steps.size}>"
+      end
+    end
+  end
+end

data/lib/netstack/connector/topology/immediate_strategy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class Topology
+      # 接口描述立即生效的设备：退出视图、读回、保存是不同阶段，不能在 finish 中提前保存。
+      class ImmediateStrategy < Strategy
+        def verification_commands = @device.config_commands
+        def persistence_commands = @device.profile.save_commands
+
+        # TextFSM 不能静默跳过未知接口头；否则目标行正确也不足以证明读回证据完整。
+        def validate_descriptions!(config, rows)
+          expected = config.scan(/^interface[ \t]+([^\r\n]*)/).flatten.map(&:strip)
+          return if expected == rows.map { |row| row.fetch("INTERFACE").strip }
+
+          raise ParsingError.new("interface description output was not fully recognized", code: :unrecognized_output,
+                                 host: @device.host, phase: :verify)
+        end
+
+        # 完成提示必须来自保存步骤；原文和渲染文本中的失败优先，单独提示符/进度不算确认。
+        def persistence_confirmed?(result)
+          !result.steps.empty? && result.steps.all? do |step|
+            raw = step.output.delete_suffix(step.prompt.to_s)
+            rendered = TerminalRenderer.render(raw)
+            failure = /\b(?:error|failed|failure|denied|cannot|unable|unsuccessful|aborted)\b/i
+            next false if raw.match?(failure) || rendered.match?(failure)
+
+            rendered.lines.any? { |line| line.strip.match?(persistence_pattern) }
+          end
+        end
+
+        # 没有明确完成证据的策略不能借用一个泛化的成功关键词。
+        def persistence_pattern = /\A\b\B\z/
+      end
+    end
+  end
+end