netstack 0.1.1 → 0.2.0

data/lib/netstack/ddi/plan.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Netstack
+  module Ddi
+    class Plan
+      KINDS = %w[zone record role blacklist block network range address].freeze
+      attr_reader :operations, :services, :scope, :digest
+
+      def initialize(operations:, services:, scope:)
+        unless operations.is_a?(Array) && operations.all? { |op| op.is_a?(Hash) && KINDS.include?(op["kind"]) && op["identity"].is_a?(Hash) && op.key?("before") && op.key?("desired") }
+          raise InputError, "Invalid DDI operations"
+        end
+        raise InputError, "Invalid DDI deployment services" unless services.is_a?(Array) && (services - %w[DNS DHCP]).empty?
+        @operations = Values.copy(operations)
+        @operations.each { |operation| validate_operation!(operation) }
+        @services = Values.copy(services.uniq.sort)
+        raise InputError, "Invalid DDI scope" unless scope.is_a?(Hash)
+        @scope = Values.copy(scope)
+        validate_duplicates!
+        @digest = Digest::SHA256.hexdigest(JSON.generate(canonical(to_h))).freeze
+        freeze
+      end
+
+      def to_h = { "operations" => operations, "services" => services, "scope" => scope }
+      def self.from_h(value) = new(operations: value.fetch("operations"), services: value.fetch("services"), scope: value.fetch("scope"))
+
+      private
+
+      def validate_operation!(operation)
+        kind, identity, before, desired = operation.values_at("kind", "identity", "before", "desired")
+        required = {
+          "zone" => %w[view_id name], "record" => %w[view_id name type], "role" => %w[view_id name interface_id],
+          "blacklist" => %w[policy_id name], "block" => %w[parent_id cidr], "network" => %w[parent_id cidr],
+          "range" => %w[network_id start end], "address" => %w[ip]
+        }.fetch(kind)
+        optional = %w[record role].include?(kind) ? ["zone_id"] : []
+        unless (required - identity.keys).empty? && (identity.keys - required - optional).empty? && (operation.keys - %w[kind identity before desired]).empty?
+          raise InputError, "Invalid DDI operation fields"
+        end
+        identity.each do |key, value|
+          case key
+          when /_id\z/ then raise InputError, "DDI identity ID must be an integer" unless value.is_a?(Integer) && value.positive?
+          when "name" then raise InputError, "DNS names must be canonical" unless Inputs.domain(value) == value
+          when "cidr" then raise InputError, "Network must be canonical" unless Inputs.cidr(value) == value
+          when "ip", "start", "end" then raise InputError, "Address must be canonical" unless Inputs.ipv4(value) == value
+          when "type" then raise InputError, "Invalid DNS record type" unless %w[A CNAME].include?(value)
+          end
+        end
+        raise InputError, "Invalid DDI precondition" unless before.nil? || before.is_a?(Hash)
+        if before && kind != "blacklist"
+          raise InputError, "DDI precondition requires an object ID" unless before["id"].is_a?(Integer) && before["id"].positive?
+        end
+        if desired.nil?
+          raise InputError, "Invalid DDI deletion" unless before && %w[zone network blacklist].include?(kind)
+          return
+        end
+        raise InputError, "DDI desired state must be an object" unless desired.is_a?(Hash)
+        valid = case kind
+        when "zone" then desired == { "name" => identity["name"], "deployable" => "true" }
+        when "record"
+          desired.keys.sort == %w[rdata type] && desired["type"] == identity["type"] &&
+            (desired["type"] == "A" ? Inputs.ipv4(desired["rdata"]) : Inputs.domain(desired["rdata"])) == desired["rdata"]
+        when "role" then desired.keys == ["type"] && %w[MASTER SLAVE FORWARDER].include?(desired["type"])
+        when "blacklist" then desired == { "present" => true }
+        when "block" then desired == { "cidr" => identity["cidr"] }
+        when "network"
+          desired.keys.sort == %w[cidr gateway] && desired["cidr"] == identity["cidr"] && Inputs.ipv4(desired["gateway"]) == desired["gateway"]
+        when "range" then desired == identity.slice("start", "end")
+        when "address" then desired.keys.sort == %w[mac state] && desired["state"] == "DHCP_RESERVED" && Inputs.mac(desired["mac"]) == desired["mac"]
+        end
+        raise InputError, "Invalid DDI desired state" unless valid
+        raise InputError, "Existing DDI objects cannot be overwritten implicitly" if before && kind != "address"
+      end
+
+      def validate_duplicates!
+        seen = {}
+        operations.each do |operation|
+          key = [operation["kind"], canonical(operation["identity"])]
+          previous = seen[key]
+          if previous && !(operation["kind"] == "zone" && previous["desired"].nil? && previous["before"].is_a?(Hash) && operation["before"].nil? && operation["desired"].is_a?(Hash))
+            raise InputError, "Duplicate DDI operation identity"
+          end
+          seen[key] = operation
+        end
+      end
+
+      def canonical(value)
+        case value
+        when Hash then value.keys.sort.to_h { |key| [key, canonical(value[key])] }
+        when Array then value.map { |item| canonical(item) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/netstack/ddi/scope.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Ddi
+    # CIDR containment does not prove configuration ownership. Walk the actual
+    # entity hierarchy on every boundary; do not cache it across plan/apply.
+    class Scope
+      MAX_ANCESTORS = 64
+
+      def initialize(client:, settings:)
+        @client = client
+        @settings = settings
+      end
+
+      def validate_identity!(kind, identity)
+        case kind
+        when "zone", "record", "role"
+          unless @settings.views.any? { |view| view["id"] == identity.fetch("view_id") }
+            raise InputError, "DNS view is outside the managed scope"
+          end
+          entity!(identity.fetch("view_id"), types: ["View"])
+          entity!(identity.fetch("interface_id"), types: %w[NetworkServerInterface PublishedServerInterface NetworkInterface VirtualInterface]) if kind == "role"
+        when "blacklist"
+          raise InputError, "Response policy is outside the managed scope" unless identity.fetch("policy_id") == @settings.policy_id
+
+          entity!(identity.fetch("policy_id"), types: ["ResponsePolicy"])
+        when "block", "network"
+          parent_id = identity.fetch("parent_id")
+          if kind == "block" && parent_id == @settings.configuration_id
+            entity!(parent_id, types: ["Configuration"])
+          else
+            parent = entity!(parent_id, types: ["IP4Block"])
+            network = Inputs.network(Inputs.properties(parent.fetch("properties")).fetch("CIDR"))
+            child = Inputs.network(identity.fetch("cidr"))
+            raise InputError, "Network must be inside the parent block" unless network.include?(child) && network.prefix < child.prefix
+          end
+        when "range"
+          row = entity!(identity.fetch("network_id"), types: ["IP4Network"])
+          props = Inputs.properties(row.fetch("properties"))
+          network = Inputs.network(props.fetch("CIDR"))
+          first, last = identity.values_at("start", "end").map { |address| usable!(network, address).to_i }
+          raise InputError, "DHCP range end precedes start" if last < first
+          if props["gateway"] && (first..last).cover?(IPAddr.new(Inputs.ipv4(props["gateway"])).to_i)
+            raise InputError, "DHCP range includes the gateway"
+          end
+        when "address"
+          row = @client.entity("getIPRangedByIP", containerId: @settings.configuration_id, type: "IP4Network", address: identity.fetch("ip"))
+          invalid_scope! unless row
+          row = entity!(row.fetch("id"), types: ["IP4Network"])
+          props = Inputs.properties(row.fetch("properties"))
+          usable!(Inputs.network(props.fetch("CIDR")), identity.fetch("ip"))
+          raise InputError, "Gateway cannot be reserved as a client address" if props["gateway"] == identity["ip"]
+        else
+          raise InputError, "Unknown DDI resource"
+        end
+      rescue KeyError
+        invalid_scope!
+      end
+
+      def entity!(id, types: nil)
+        id = Inputs.id(id)
+        row = @client.entity("getEntityById", id: id)
+        validate_row!(row)
+        invalid_scope! unless row["id"] == id && (!types || types.include?(row["type"]))
+        ancestors!(row)
+        row
+      end
+
+      def validate_delete!(id)
+        id = Inputs.id(id)
+        raise InputError, "Protected BlueCat object cannot be deleted" if @settings.protected_ids.include?(id)
+
+        @settings.protected_ids.each do |protected_id|
+          row = @client.entity("getEntityById", id: protected_id)
+          validate_row!(row)
+          invalid_scope! unless row["id"] == protected_id
+          if ancestors!(row).include?(id)
+            raise InputError, "Deletion contains a protected BlueCat object"
+          end
+        end
+      end
+
+      def validate_entity!(row, types:)
+        validate_row!(row)
+        entity!(row.fetch("id"), types: types)
+      end
+
+      private
+
+      def ancestors!(row)
+        seen = []
+        MAX_ANCESTORS.times do
+          validate_row!(row)
+          invalid_scope! if seen.include?(row["id"])
+          seen << row["id"]
+          if row["type"] == "Configuration"
+            invalid_scope! unless row["id"] == @settings.configuration_id
+            return seen
+          end
+          invalid_scope! if row["id"] == @settings.configuration_id
+          # Address Manager REST v1: GET getParent?entityId=<child ID> -> APIEntity.
+          row = @client.entity("getParent", entityId: row["id"])
+        end
+        invalid_scope!
+      end
+
+      def validate_row!(row)
+        unless row.is_a?(Hash) && row["id"].is_a?(Integer) && row["id"].positive? &&
+          row["name"].is_a?(String) && row["type"].is_a?(String) && row["properties"].is_a?(String)
+          invalid_scope!
+        end
+      end
+
+      def usable!(network, address)
+        address = IPAddr.new(Inputs.ipv4(address))
+        unless network.include?(address) && ![network.to_range.first, network.to_range.last].include?(address)
+          raise InputError, "Address must be a usable host inside the network"
+        end
+        address
+      end
+
+      def invalid_scope!
+        raise Netstack::Error.new("BlueCat configuration ownership could not be confirmed", code: :scope_unconfirmed, stage: :preflight)
+      end
+    end
+  end
+end

data/lib/netstack/ddi/settings.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Ddi
+    class Settings
+      attr_reader :configuration_id, :views, :server_ids, :protected_ids, :policy_id
+
+      def initialize(configuration_id:, views:, server_ids:, protected_ids: [], policy_id: nil)
+        @configuration_id = Inputs.id(configuration_id)
+        raise InputError, "DDI views must be an array" unless views.is_a?(Array)
+        @views = Values.copy(views.map do |view|
+          raise InputError, "Invalid DDI view" unless view.is_a?(Hash)
+          view = view.transform_keys(&:to_s)
+          { "id" => Inputs.id(view.fetch("id")), "roles" => self.class.roles(view.fetch("roles", [])) }
+        end)
+        raise InputError, "Duplicate DDI views" unless @views.map { |view| view["id"] }.uniq.size == @views.size
+        raise InputError, "DDI server IDs must be an array" unless server_ids.is_a?(Array) && protected_ids.is_a?(Array)
+        @server_ids = server_ids.map { |id| Inputs.id(id) }.uniq.freeze
+        @policy_id = policy_id.nil? ? nil : Inputs.id(policy_id)
+        @protected_ids = [@configuration_id, *@views.map { |view| view["id"] }, *@server_ids,
+                          *@views.flat_map { |view| view["roles"].map { |role| role["interface_id"] } }, @policy_id,
+                          *protected_ids.map { |id| Inputs.id(id) }].compact.uniq.freeze
+        freeze
+      end
+
+      def self.roles(values)
+        raise InputError, "DNS roles must be an array" unless values.is_a?(Array)
+        result = values.map do |role|
+          raise InputError, "Invalid DNS role" unless role.is_a?(Hash)
+          role = role.transform_keys(&:to_s)
+          raise InputError, "Invalid DNS role type" unless %w[MASTER SLAVE FORWARDER].include?(role["type"])
+          { "interface_id" => Inputs.id(role.fetch("interface_id")), "type" => role["type"] }
+        end
+        raise InputError, "Duplicate DNS role interface" unless result.map { |role| role["interface_id"] }.uniq.size == result.size
+        Values.copy(result)
+      end
+
+      def to_h
+        { "configuration_id" => configuration_id, "views" => views, "server_ids" => server_ids,
+          "protected_ids" => protected_ids, "policy_id" => policy_id }
+      end
+    end
+  end
+end

data/lib/netstack/ddi/state.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Ddi
+    # Exact selectors and verified representations for the DDI changes we own.
+    class State
+      def initialize(client:, settings:)
+        @client = client
+        @settings = settings
+        @scope = Scope.new(client: client, settings: settings)
+      end
+
+      def read(kind, identity)
+        @scope.validate_identity!(kind, identity)
+        case kind
+        when "zone"
+          row = zone(identity.fetch("view_id"), identity.fetch("name"))
+          row && { "id" => row["id"], "name" => identity["name"], "deployable" => properties(row)["deployable"] }
+        when "record"
+          parent = zone(identity.fetch("view_id"), identity.fetch("name"))
+          validate_parent!(parent, identity)
+          return nil unless parent
+          rows = @client.entities(parent_id: parent["id"], type: "GenericRecord").select do |row|
+            props = properties(row)
+            props["absoluteName"]&.delete_prefix(".")&.delete_suffix(".")&.downcase == identity["name"] && props["type"] == identity["type"]
+          end
+          row = unique(rows)
+          @scope.validate_entity!(row, types: ["GenericRecord"]) if row
+          return nil unless row
+
+          props = properties(row)
+          rdata = props["rdata"]&.delete_suffix(".")
+          # CNAME 目标按 DNS 名称比较；provider 的大小写和根点不改变身份。
+          rdata = rdata&.downcase if props["type"] == "CNAME"
+          { "id" => row["id"], "type" => props["type"], "rdata" => rdata }
+        when "role"
+          parent = zone(identity.fetch("view_id"), identity.fetch("name"))
+          validate_parent!(parent, identity)
+          return nil unless parent
+          rows = @client.json("getDeploymentRoles", entityId: parent["id"])
+          invalid! unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) && row["id"].is_a?(Integer) && row["id"].positive? && row["serverInterfaceId"].is_a?(Integer) && %w[MASTER SLAVE FORWARDER].include?(row["type"]) }
+          row = unique(rows.select { |role| role["serverInterfaceId"] == identity["interface_id"] })
+          row && { "id" => row["id"], "type" => row["type"] }
+        when "blacklist"
+          rows = @client.json("findResponsePoliciesWithItem", configurationId: @settings.configuration_id, itemName: identity.fetch("name"), options: "")
+          invalid! unless rows.is_a?(Array)
+          rows = rows.map { |row| @client.validate_entity(row) }
+          rows.any? { |row| row["id"] == identity["policy_id"] } ? { "present" => true } : nil
+        when "block", "network"
+          type = kind == "block" ? "IP4Block" : "IP4Network"
+          row = @client.entity("getEntityByCIDR", parentId: identity.fetch("parent_id"), cidr: identity.fetch("cidr"), type: type)
+          return nil unless row
+          @scope.validate_entity!(row, types: [type])
+          invalid! unless row["type"] == type && properties(row)["CIDR"] == identity["cidr"]
+          state = { "id" => row["id"], "cidr" => properties(row)["CIDR"] }
+          state["gateway"] = properties(row)["gateway"] if kind == "network"
+          state
+        when "range"
+          row = @client.entity("getEntityByRange", parentId: identity.fetch("network_id"), address1: identity.fetch("start"), address2: identity.fetch("end"), type: "DHCP4Range")
+          return nil unless row
+          @scope.validate_entity!(row, types: ["DHCP4Range"])
+          invalid! unless row["type"] == "DHCP4Range"
+          { "id" => row["id"], "start" => properties(row)["start"], "end" => properties(row)["end"] }
+        when "address"
+          row = @client.entity("getIP4Address", containerId: @settings.configuration_id, address: identity.fetch("ip"))
+          return nil unless row
+          @scope.validate_entity!(row, types: ["IP4Address"])
+          props = properties(row)
+          invalid! unless row["type"] == "IP4Address" && props["address"] == identity["ip"]
+          { "id" => row["id"], "mac" => props["macAddress"]&.downcase&.tr("-", ":"), "state" => props["state"] }
+        else
+          raise InputError, "Unknown DDI resource"
+        end
+      end
+
+      def write(operation)
+        kind, identity, desired, before = operation.values_at("kind", "identity", "desired", "before")
+        unless read(kind, identity) == before
+          raise Netstack::Error.new("DDI object changed before submission", code: :state_conflict, stage: :preflight)
+        end
+        if kind == "network" && desired
+          network = Inputs.network(identity.fetch("cidr"))
+          gateway = IPAddr.new(Inputs.ipv4(desired.fetch("gateway")))
+          unless network.include?(gateway) && ![network.to_range.first, network.to_range.last].include?(gateway)
+            raise InputError, "Gateway must be a usable host inside the network"
+          end
+        end
+        if desired.nil?
+          if kind == "blacklist"
+            return @client.write(:delete, "deleteResponsePolicyItem", query: { policyId: identity.fetch("policy_id"), itemName: identity.fetch("name"), option: "" })
+          end
+          id = Inputs.id(before.fetch("id"))
+          @scope.validate_delete!(id)
+          return @client.write(:delete, "deleteWithOptions", query: { objectId: id, options: "" })
+        end
+
+        case kind
+        when "zone"
+          create("addZone", absoluteName: identity.fetch("name"), parentId: identity.fetch("view_id"), properties: "deployable=true")
+        when "record"
+          create("addGenericRecord", absoluteName: ".#{identity.fetch("name")}", viewId: identity.fetch("view_id"), type: desired.fetch("type"), rdata: desired.fetch("rdata"), ttl: -1, properties: "")
+        when "role"
+          parent = zone(identity.fetch("view_id"), identity.fetch("name")) || raise(Netstack::Error.new("DNS zone disappeared", code: :state_conflict))
+          validate_parent!(parent, identity)
+          create("addDNSDeploymentRole", entityId: parent.fetch("id"), serverInterfaceId: identity.fetch("interface_id"), type: desired.fetch("type"), properties: "")
+        when "blacklist"
+          @client.write(:post, "addResponsePolicyItem", query: { policyId: identity.fetch("policy_id"), itemName: identity.fetch("name"), option: "" })
+        when "block"
+          create("addIP4BlockByCIDR", parentId: identity.fetch("parent_id"), CIDR: identity.fetch("cidr"), properties: "")
+        when "network"
+          create("addIP4Network", blockId: identity.fetch("parent_id"), CIDR: identity.fetch("cidr"), properties: "gateway=#{desired.fetch("gateway")}")
+        when "range"
+          create("addDHCP4Range", networkId: identity.fetch("network_id"), start: identity.fetch("start"), end: identity.fetch("end"), properties: "")
+        when "address"
+          if before && before["mac"] && before["mac"] != desired["mac"]
+            raise InputError, "Address is bound to another MAC"
+          end
+          if before
+            @client.write(:put, "changeStateIP4Address", query: { addressId: before.fetch("id"), macAddress: desired.fetch("mac"), targetState: "MAKE_DHCP_RESERVED" })
+          else
+            create("assignIP4Address", configurationId: @settings.configuration_id, ip4Address: identity.fetch("ip"), macAddress: desired.fetch("mac"), action: "MAKE_DHCP_RESERVED", hostInfo: "", properties: "")
+          end
+        end
+      end
+
+      def matches?(actual, desired)
+        return actual.nil? if desired.nil?
+        actual.is_a?(Hash) && desired.all? { |key, value| actual[key] == value }
+      end
+
+      def validate_delete!(id) = @scope.validate_delete!(id)
+
+      def zone(view_id, name)
+        parent_id = Inputs.id(view_id)
+        result = nil
+        Inputs.domain(name).split(".").reverse_each do |label|
+          result = @client.entity("getEntityByName", parentId: parent_id, name: label, type: "Zone")
+          return nil unless result
+          @scope.validate_entity!(result, types: ["Zone"])
+          invalid! unless result["type"] == "Zone" && result["name"].downcase == label
+          parent_id = result.fetch("id")
+        end
+        result
+      end
+
+      private
+
+      def validate_parent!(parent, identity)
+        return unless identity.key?("zone_id")
+        raise Netstack::Error.new("DNS parent identity changed", code: :state_conflict) unless parent && parent["id"] == identity["zone_id"]
+      end
+
+      def create(endpoint, **query) = @client.write(:post, endpoint, query: query, returns_id: true)
+      def properties(row) = Inputs.properties(row.fetch("properties"))
+
+      def unique(rows)
+        raise Netstack::Error.new("DDI selector matched multiple objects", code: :ambiguous_object) if rows.length > 1
+        rows.first
+      end
+
+      def invalid!
+        raise Netstack::Error.new("Invalid BlueCat object identity or properties", code: :invalid_response)
+      end
+    end
+  end
+end

data/lib/netstack/deployment/checkpoint_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Deployment
+    class CheckpointError < Error
+      attr_reader :receipt
+
+      def initialize(receipt:)
+        @receipt = receipt
+        super("execution checkpoint was not committed", code: :checkpoint_unconfirmed, stage: :checkpoint)
+      end
+    end
+  end
+end

data/lib/netstack/deployment/cli_adapter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Deployment
+    # Generic scripts require domain-specific identity checks and readback verification.
+    class CliAdapter
+      def initialize(artifact_resolver:, preflight:, verifier:, connector: Connector)
+        unless preflight.respond_to?(:call) && verifier.respond_to?(:call)
+          raise InputError, "CLI delivery requires explicit preflight and readback verification"
+        end
+        @artifacts = Configuration::ArtifactResolver.new(resolver: artifact_resolver)
+        @preflight = preflight
+        @verifier = verifier
+        @connector = connector
+      end
+
+      def preflight(plan:, previous:, credentials:) # rubocop:disable Naming/PredicateMethod -- Deployment adapter protocol.
+        raise InputError, "unsupported CLI target platform" unless Connector.vendors.include?(plan.target.platform.to_sym)
+
+        previous_ids = previous ? previous.steps.map { |step| step.fetch(:step_id) } : []
+        plan.steps.each do |step|
+          next if previous_ids.include?(step.id)
+
+          artifact = @artifacts.resolve(step)
+          artifact.validate_target!(plan.target)
+          commands(artifact)
+        end
+        unless @preflight.call(plan: plan, previous: previous, credentials: credentials) == true
+          raise Error.new("CLI preconditions were not confirmed", code: :precondition_failed, stage: :preflight)
+        end
+        true
+      end
+
+      def apply(step:, target:, credentials:, idempotency_key:)
+        artifact = @artifacts.resolve(step)
+        artifact.validate_target!(target)
+        script = commands(artifact)
+        result = @connector.open(target.platform.to_sym, **credentials, host: target.host) do |session|
+          session.execute_script(script)
+        end
+        { status: result.success? ? :applied : :unknown,
+          evidence: { sha256: artifact.sha256, completed_commands: result.steps.size, operation_key: idempotency_key } }
+      end
+
+      def verify(step:, target:, credentials:, receipt:)
+        @verifier.call(step: step, target: target, credentials: credentials, receipt: receipt)
+      end
+
+      private
+
+      def commands(artifact)
+        script = artifact.content.lines.filter_map.with_index do |line, index|
+          text = line.strip
+          next if text.empty? || text.start_with?("#", "!")
+
+          Connector::Command.new(text, sensitive: true, output_sensitive: true, line: index + 1)
+        end
+        raise InputError, "configuration script has no commands" if script.empty?
+
+        script
+      end
+    end
+  end
+end

data/lib/netstack/deployment/executor.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Netstack
+  # 计划与收据分别表达持久意图、提交和已确认的远端效果。
+  module Deployment
+    # 推进业务步骤；持久化、授权和目标执行租约由宿主负责。
+    class Executor
+      def initialize(adapter:, clock: -> { Time.now.utc })
+        @adapter = adapter
+        @clock = clock
+      end
+
+      # 宿主必须持有目标执行权，并在每次检查点持久化后
+      # 严格返回 true；此前已开始或结果未知的写入只进行验证。
+      # 凭据只传给适配器，不进入检查点。
+      def apply(plan:, execution_id:, checkpoint:, credentials:, previous: nil)
+        execution_id = Values.text(execution_id, name: "execution id")
+        raise InputError, "plan must be a Deployment::Plan" unless plan.is_a?(Plan)
+
+        identity = { execution_id: execution_id, plan_digest: plan.digest, target_key: plan.target.key,
+          planned_step_ids: plan.steps.map(&:id).freeze }.freeze
+        validate_input!(identity, checkpoint, previous)
+        records = previous ? previous.steps.map(&:dup) : []
+        return receipt(identity, records) if plan.steps.empty?
+
+        unless @adapter.preflight(plan: plan, previous: previous, credentials: credentials) == true
+          raise Error.new("execution preconditions were not confirmed", code: :precondition_failed, stage: :preflight)
+        end
+        plan.steps.each_with_index do |step, index|
+          current = records[index]
+          next if current && current[:status] == :verified
+          break if current && %i[failed not_applied].include?(current[:status])
+
+          if current
+            result = verify(step, plan, credentials, current)
+          else
+            current = { step_id: step.id, status: :started, idempotency_key: operation_key(identity, step.id) }
+            records << current
+            checkpoint!(checkpoint, identity, records, current)
+            result = submit(step, plan, credentials, current)
+            current.replace(current.merge(result))
+            checkpoint!(checkpoint, identity, records, current)
+            result = verify(step, plan, credentials, current) if %i[applied accepted].include?(current[:status])
+          end
+
+          current.replace(current.merge(result))
+          checkpoint!(checkpoint, identity, records, current)
+          break unless current[:status] == :verified
+        end
+        receipt(identity, records)
+      end
+
+      private
+
+      def validate_input!(identity, checkpoint, previous)
+        raise InputError, "a synchronous checkpoint is required" unless checkpoint.respond_to?(:call)
+        return unless previous
+
+        unless previous.is_a?(Receipt) && previous.execution_id == identity[:execution_id] && previous.plan_digest == identity[:plan_digest] && previous.target_key == identity[:target_key]
+          raise InputError, "receipt does not belong to this execution and plan"
+        end
+        planned_step_ids = identity.fetch(:planned_step_ids)
+        raise InputError, "receipt plan steps do not match" unless previous.planned_step_ids == planned_step_ids
+        expected_ids = planned_step_ids.first(previous.steps.size)
+        raise InputError, "receipt steps are not a plan prefix" unless expected_ids == previous.steps.map { |step| step[:step_id] }
+        previous.steps.each_with_index do |record, index|
+          unless record[:idempotency_key] == operation_key(identity, planned_step_ids.fetch(index))
+            raise InputError, "receipt operation identity does not match the execution step"
+          end
+        end
+        return if previous.steps[0...-1].all? { |step| step[:status] == :verified }
+
+        raise InputError, "receipt advances past an unverified step"
+      end
+
+      def submit(step, plan, credentials, current)
+        response = @adapter.apply(step: step, target: plan.target, credentials: credentials, idempotency_key: current.fetch(:idempotency_key))
+        checked_response(response, allowed: %i[applied accepted failed unknown])
+      rescue StandardError => error
+        # 提交后的适配器异常不能证明远端未产生效果。
+        { status: :unknown, error_code: error.is_a?(Netstack::Error) ? error.code : :execution_unconfirmed }
+      end
+
+      def verify(step, plan, credentials, current)
+        response = @adapter.verify(step: step, target: plan.target, credentials: credentials, receipt: Values.copy(current))
+        checked_response(response, allowed: %i[verified failed unknown not_applied])
+      rescue StandardError => error
+        { status: :unknown, error_code: error.is_a?(Netstack::Error) ? error.code : :verification_unconfirmed }
+      end
+
+      def checked_response(response, allowed:)
+        raise Error.new("invalid execution response", code: :invalid_response) unless response.is_a?(Hash)
+
+        unless response.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) } && response.keys.map(&:to_s).uniq.size == response.size
+          raise Error.new("ambiguous execution response", code: :invalid_response)
+        end
+        item = response.transform_keys(&:to_sym)
+        status = item.fetch(:status).to_sym
+        raise Error.new("invalid execution status", code: :invalid_response) unless allowed.include?(status)
+
+        # 检查点仅包含限定字段的收据，不包含任意传输响应正文。
+        result = { status: status }
+        result[:remote_id] = Values.text(item[:remote_id], name: "remote id") if item[:remote_id]
+        result[:error_code] = item[:error_code].to_sym if item[:error_code]
+        result[:evidence] = Values.copy(item[:evidence]) if item[:evidence]
+        result
+      end
+
+      def checkpoint!(callback, identity, records, current)
+        event = Values.copy({ **identity.slice(:execution_id, :plan_digest, :target_key),
+          observed_at: @clock.call.getutc.iso8601(6), receipt: receipt(identity, records).payload }.merge(current))
+        begin
+          committed = callback.call(event)
+        rescue StandardError
+          committed = false
+        end
+        raise CheckpointError.new(receipt: receipt(identity, records)), cause: nil unless committed == true
+      end
+
+      def receipt(identity, records)
+        Receipt.new(**identity, steps: records)
+      end
+
+      def operation_key(identity, step_id)
+        Digest::SHA256.hexdigest([identity[:execution_id], identity[:plan_digest], step_id].join("\0"))
+      end
+    end
+  end
+end