mt-wall 0.1.0

data/lib/mt/wall/model/rule.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Model
+      # An access grant between two objects/groups (Layer A — abstract,
+      # device-agnostic). Compiles to one or more `/ip firewall filter` rules
+      # using `src-address-list` / `dst-address-list` (and protocol/dst-port
+      # when a service is given).
+      #
+      # DUAL-STACK: because endpoints may hold a mix of IPv4 and IPv6 addresses,
+      # ONE abstract grant compiles to a v4 filter rule for the endpoints' v4
+      # members AND a v6 filter rule for their v6 members. A family with no
+      # overlap simply yields no rule for THAT family. But a grant that yields
+      # NO rule in EITHER family (e.g. a v4-only source paired with a v6-only
+      # destination) FAILS FAST with ConfigurationError in the Compiler — it
+      # never silently produces nothing. Family selection happens entirely in
+      # the Compiler; the grant itself never names a family.
+      #
+      # RULE IDENTITY: the concrete rule this grant compiles to is tagged with a
+      # deterministic, CONTENT-ONLY `mt-wall:<stable-hash>` identity in its
+      # RouterOS `comment` (chain + normalized match + action + src/dst list
+      # references; position EXCLUDED — see Model::FilterRule and the Compiler).
+      # Diff/Plan match desired vs. current rules by that tag, NOT by the
+      # device-assigned `.id`; ordering is handled separately by the Plan
+      # (:move + Operation#position). `comment` below is the OPERATOR's
+      # human-readable note, kept distinct from (and merged alongside) the
+      # machine identity tag at compile time.
+      #
+      # RULE-LEVEL ATTRIBUTES (NOT match conditions): `log` / `log_prefix` and
+      # `disabled` are excluded from the content-only identity tag, exactly as on
+      # Model::FilterRule — toggling them is an in-place :update, not a churn.
+      #
+      # @!attribute source      [String]      name of the source object/group
+      # @!attribute destination [String]      name of the destination object/group
+      # @!attribute service     [String, nil] name of a Service, or nil for any
+      # @!attribute action      [Symbol]      :accept or :drop
+      # @!attribute comment     [String, nil] optional operator-authored note
+      # @!attribute log         [Boolean]     log matched packets (RouterOS log=yes)
+      # @!attribute log_prefix  [String, nil] optional log-prefix label
+      # @!attribute disabled    [Boolean]     keep the grant but inactive (disabled=yes)
+      Rule = Data.define(:source, :destination, :service, :action, :comment, :log, :log_prefix, :disabled) do
+        def initialize(source:, destination:, action:, service: nil, comment: nil,
+                       log: false, log_prefix: nil, disabled: false)
+          super
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/model/service.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Model
+      # A protocol/port definition referenced when granting access, e.g.
+      # Service.new(name: "https", protocols: [:tcp], ports: [443]).
+      # Compiles into the `protocol` / `dst-port` fields of a filter rule.
+      #
+      # MULTI-PROTOCOL: a service may carry MORE THAN ONE protocol (e.g. DNS is
+      # tcp+udp). A grant using such a service compiles to ONE filter rule PER
+      # protocol (RouterOS filter rows match a single protocol each). The legacy
+      # singular `protocol:` keyword is still accepted and folded into the
+      # `protocols` array; the `#protocol` reader returns the first protocol for
+      # callers that only need one.
+      #
+      # PORTS: stored as the validated spec (Integer / Array / Range / "a-b" or
+      # "n" String), so a port RANGE round-trips to RouterOS as a range
+      # (`dst-port=8000-8100`) rather than being exploded into a long list. Empty
+      # for portless protocols (e.g. icmp).
+      #
+      # @!attribute name      [String]         service name (e.g. "https")
+      # @!attribute protocols [Array<Symbol>]  one or more protocols (:tcp, :udp, ...)
+      # @!attribute ports     [Array]          destination ports / ranges (empty = portless)
+      Service = Data.define(:name, :protocols, :ports) do
+        def initialize(name:, protocol: nil, protocols: nil, ports: [])
+          list = protocols || protocol
+          # A Range is a single port-spec value — wrap it so Array() does not
+          # explode it into discrete integers (we want `dst-port=8000-8100`).
+          port_list = ports.is_a?(Range) ? [ports] : Array(ports)
+          super(name: name, protocols: Array(list), ports: port_list)
+        end
+
+        # Backward-compatible single-protocol reader: the first declared protocol.
+        # @return [Symbol, nil]
+        def protocol
+          protocols.first
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/plan.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    # The diff between a desired and a current DesiredState: an ordered list
+    # of operations. A Plan is both printable (for `mt-wall plan`) and
+    # executable (handed to a Transport by `apply`).
+    #
+    # IDENTITY MATCHING — `(tag, ordinal)`: filter/nat rows are matched
+    # desired<->current by their content-only `mt-wall:<stable-hash>` identity
+    # tag (in `comment`), never by the opaque device `.id`. The tag is
+    # content-only, so two rows CAN legitimately share a tag (different position,
+    # same content). Matching therefore keys on the pair `(tag, ordinal)` where
+    # `ordinal` is the 0-based occurrence index of that tag within its
+    # (path, chain), assigned in document order on each side. The Compiler
+    # collapses EXACT duplicates (same content + chain) into ONE row, so a
+    # surviving ordinal > 0 is a deliberate, semantically distinct repeat.
+    # Match outcomes per `(tag, ordinal)`:
+    #   * present in desired, absent in current => :create;
+    #   * a current mt-wall-tagged `(tag, ordinal)` absent from desired => :delete;
+    #   * matched pair, differing normalized payload => :update;
+    #   * matched pair in the wrong position => :move.
+    # The `.id` is carried in the payload of :update/:delete/:move only so the
+    # transport can address the existing row (PATCH/DELETE/move target it by id).
+    #
+    # ORDERING IS FIRST-CLASS because mt-wall owns the whole filter/nat table
+    # and rule order is semantically load-bearing (RouterOS evaluates top-down).
+    # Operations therefore include explicit placement; the place-before anchor is
+    # resolved against the `(tag, ordinal)` of the row it must precede:
+    #   * :create carries `position` (place-before anchor) so a new rule lands
+    #     at the right index;
+    #   * :move reorders an existing row to sit before `position`.
+    #
+    # APPLY-ORDER INVARIANTS (the Plan is emitted already sorted so a transport
+    # can execute it verbatim; see Reconciler):
+    #   1. create/insert the stateful preamble, accept rules and the
+    #      management-protection rule BEFORE any tightening;
+    #   2. create-before-delete (never delete an old rule before its
+    #      replacement exists);
+    #   3. install default-DROP policy rows LAST.
+    class Plan
+      # A single change to apply to a device.
+      #
+      # @!attribute action   [Symbol]      :create, :update, :delete or :move
+      # @!attribute path     [String]      RouterOS resource path (managed table)
+      # @!attribute payload  [Hash]        the resource attributes; for
+      #                                    :update/:delete/:move it also carries
+      #                                    the existing row's `.id`
+      # @!attribute position [Array, String, nil] place-before anchor: the
+      #                                    `(tag, ordinal)` pair (or `.id`) of the
+      #                                    row this one must precede; nil = append
+      #                                    at the table's tail
+      Operation = Data.define(:action, :path, :payload, :position) do
+        def initialize(action:, path:, payload: {}, position: nil)
+          super
+        end
+      end
+
+      # RouterOS row handle. Lives ONLY on fetched current rows; carried into the
+      # payload of :update/:delete/:move so the transport can address the row.
+      ID_KEY = :".id"
+
+      attr_reader :operations
+
+      def initialize(operations = [])
+        @operations = operations
+      end
+
+      def empty?
+        @operations.empty?
+      end
+
+      # Build a Plan by diffing two DesiredState instances. Matches rows by the
+      # `(tag, ordinal)` key (filter/nat) or the natural key (address-list), and
+      # normalizes both sides (string-coerced values, `dynamic` rows excluded)
+      # before comparing. Emits operations already sorted per the apply-order
+      # invariants above.
+      #
+      # @param desired [DesiredState]
+      # @param current [DesiredState]
+      # @return [Plan]
+      def self.diff(desired:, current:)
+        Differ.new(desired: desired, current: current).call
+      end
+
+      # Computes the ordered operation list for {Plan.diff}. Stateful, single-use:
+      # accumulates operations in document order, then sorts them once per the
+      # apply-order invariants.
+      class Differ # rubocop:disable Metrics/ClassLength
+        def initialize(desired:, current:)
+          @desired = desired
+          @current = current
+          @operations = []
+        end
+
+        # @return [Plan]
+        def call
+          DesiredState::FULL_TABLE_PATHS.each { |path| diff_full_table(path) }
+          DesiredState::ADDRESS_LIST_PATHS.each { |path| diff_address_list(path) }
+          Plan.new(sorted_operations)
+        end
+
+        private
+
+        # ── filter / nat: matched by (tag, ordinal) within (path, chain) ──────
+
+        def diff_full_table(path)
+          chains_in(path).each { |chain| diff_chain(path, chain) }
+        end
+
+        def chains_in(path)
+          (@desired[path] + @current[path]).map { |row| row[:chain] }.uniq
+        end
+
+        def diff_chain(path, chain)
+          desired = chain_entries(@desired, path, chain)
+          current = chain_entries(@current, path, chain)
+          desired_keys = index_by_key(desired)
+          current_keys = index_by_key(current)
+
+          emit_creates_and_updates(path, desired, current_keys)
+          emit_deletes(path, current, desired_keys)
+          emit_moves(path, desired, current, desired_keys, current_keys)
+        end
+
+        # Entries for one (path, chain) in document order, each tagged with its
+        # `(tag, ordinal)` identity key (ordinal = 0-based occurrence of the tag).
+        def chain_entries(state, path, chain)
+          counts = Hash.new(0)
+          state[path].filter_map do |row|
+            next unless row[:chain] == chain
+
+            tag = Compiler.tag_in_comment(row[:comment])
+            ordinal = counts[tag]
+            counts[tag] += 1
+            { key: [tag, ordinal], row: row }
+          end
+        end
+
+        def index_by_key(entries)
+          entries.to_h { |entry| [entry[:key], entry] }
+        end
+
+        def emit_creates_and_updates(path, desired, current_keys)
+          desired.each_with_index do |entry, index|
+            match = current_keys[entry[:key]]
+            if match.nil?
+              add(:create, path, entry[:row], position: anchor_after(desired, index))
+            elsif update_needed?(entry[:row], match[:row])
+              add(:update, path, with_id(entry[:row], match[:row]))
+            end
+          end
+        end
+
+        # A managed table is owned wholesale, so any current row (tagged or a
+        # leftover factory/default rule) with no desired match is removed.
+        def emit_deletes(path, current, desired_keys)
+          current.each do |entry|
+            next if desired_keys.key?(entry[:key])
+
+            add(:delete, path, entry[:row])
+          end
+        end
+
+        # Matched rows whose relative order changed are repositioned, not churned
+        # via delete+create. The stable (kept-in-place) set is the LCS of the two
+        # match-key orderings; everything outside it moves.
+        def emit_moves(path, desired, current, desired_keys, current_keys)
+          stable = stable_keys(desired, current, desired_keys, current_keys)
+          desired.each_with_index do |entry, index|
+            match = current_keys[entry[:key]]
+            next if match.nil? || stable.include?(entry[:key])
+
+            add(:move, path, id_only(match[:row]), position: anchor_after(desired, index))
+          end
+        end
+
+        # The match keys to keep in place: the LCS of the two match-key orderings.
+        def stable_keys(desired, current, desired_keys, current_keys)
+          desired_order = desired.map { |entry| entry[:key] }.select { |key| current_keys.key?(key) }
+          current_order = current.map { |entry| entry[:key] }.select { |key| desired_keys.key?(key) }
+          lcs(current_order, desired_order)
+        end
+
+        # ── address-lists: matched by natural key (list, address), name-scoped ─
+
+        def diff_address_list(path)
+          desired_keys = address_index(@desired[path])
+          current_keys = address_index(managed_current_rows(path))
+          desired_keys.each { |key, row| add(:create, path, row) unless current_keys.key?(key) }
+          current_keys.each { |key, row| add(:delete, path, row) unless desired_keys.key?(key) }
+        end
+
+        # Current rows scoped to the desired side's managed list names; foreign /
+        # static lists are never diffed or deleted.
+        def managed_current_rows(path)
+          managed = @desired[path].map { |row| row[:list] }.uniq
+          @current[path].select { |row| managed.include?(row[:list]) }
+        end
+
+        def address_index(rows)
+          rows.to_h { |row| [[row[:list], row[:address]], row] }
+        end
+
+        # ── shared helpers ───────────────────────────────────────────────────
+
+        def add(action, path, payload, position: nil)
+          @operations << Operation.new(action: action, path: path, payload: payload, position: position)
+        end
+
+        # Place-before anchor: the `(tag, ordinal)` of the next desired row in the
+        # chain, or nil to append at the tail.
+        def anchor_after(entries, index)
+          succ = entries[index + 1]
+          succ && succ[:key]
+        end
+
+        # Same `(tag, ordinal)` means identical content (the tag is a content
+        # hash), so only the operator note inside `comment` can still differ.
+        def update_needed?(desired_row, current_row)
+          desired_row.any? { |key, value| current_row[key] != value }
+        end
+
+        def with_id(desired_row, current_row)
+          id = current_row[ID_KEY]
+          id ? desired_row.merge(ID_KEY => id) : desired_row
+        end
+
+        def id_only(current_row)
+          id = current_row[ID_KEY]
+          id ? { ID_KEY => id } : {}
+        end
+
+        # Longest common subsequence of two key orderings (small chains, plain DP).
+        def lcs(left, right)
+          table = lcs_table(left, right)
+          backtrack_lcs(table, left, right)
+        end
+
+        def lcs_table(left, right) # rubocop:disable Metrics/AbcSize
+          table = Array.new(left.size + 1) { Array.new(right.size + 1, 0) }
+          left.each_index do |i|
+            right.each_index do |j|
+              table[i + 1][j + 1] = left[i] == right[j] ? table[i][j] + 1 : [table[i][j + 1], table[i + 1][j]].max
+            end
+          end
+          table
+        end
+
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def backtrack_lcs(table, left, right)
+          result = []
+          i = left.size
+          j = right.size
+          while i.positive? && j.positive?
+            if left[i - 1] == right[j - 1]
+              result.unshift(left[i - 1])
+              i -= 1
+              j -= 1
+            elsif table[i - 1][j] >= table[i][j - 1]
+              i -= 1
+            else
+              j -= 1
+            end
+          end
+          result
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+        # ── apply-order sort (anti-lockout) ──────────────────────────────────
+        #
+        # 1. address-list creates first (filter rules reference them by name);
+        # 2. preamble/accept/mgmt/operator creates + moves before tightening;
+        # 3. default-DROP policy creates LAST among creates;
+        # 4. updates (comment-only, harmless);
+        # 5. deletes LAST — never before their replacement exists.
+        def sorted_operations
+          @operations.each_with_index.sort_by { |op, index| [rank(op), index] }.map(&:first)
+        end
+
+        def rank(operation)
+          case operation.action
+          when :create then create_rank(operation)
+          when :move then 1
+          when :update then 3
+          else 4 # :delete
+          end
+        end
+
+        def create_rank(operation)
+          return 0 if DesiredState::ADDRESS_LIST_PATHS.include?(operation.path)
+
+          default_policy_row?(operation.payload) ? 2 : 1
+        end
+
+        # A trailing default-policy rule is a bare chain default: chain + action
+        # only, with no match condition.
+        def default_policy_row?(payload)
+          (payload.keys - [:comment, ID_KEY, :log, :log_prefix, :disabled]).sort == %i[action chain]
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/reconciler.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    # Orchestrates the Terraform-style workflow for a single device:
+    #
+    #   1. Compiler turns the Configuration into the DESIRED DesiredState.
+    #   2. Transport#fetch reads the CURRENT DesiredState (DesiredState::MANAGED_PATHS).
+    #   3. Plan.diff produces the (identity-matched, order-aware) change set.
+    #   4. (apply only) Transport#apply executes the Plan under commit-confirm.
+    #
+    # `#plan` is read-only and safe to run anywhere (e.g. CI on a PR).
+    # `#apply` mutates the device and should run only on the trusted path
+    # (e.g. CI on merge to the main branch).
+    #
+    # FAIL-SAFE APPLY: because mt-wall owns and replaces the whole filter/nat
+    # table over a network path that runs THROUGH that very firewall, apply uses
+    # a DEVICE-SIDE commit-confirm envelope (see Transport::Base) — client-side
+    # rollback is undeliverable if the link drops. The envelope is:
+    #   1. ARM: transport.arm_auto_revert(snapshot, timeout:) — back up the
+    #      managed tables on the device and schedule a self-restore after timeout;
+    #   2. APPLY: transport.apply(plan.operations) in fail-safe order (open
+    #      access + mgmt-protect BEFORE tightening; create-before-delete;
+    #      default-drop LAST — encoded in the Plan, re-asserted here);
+    #   3. HEALTH-CHECK: the manager re-reaches the device to confirm the
+    #      session survived;
+    #   4. CONFIRM: transport.confirm(handle) cancels the scheduled revert. If
+    #      the health-check fails or the link is lost, CONFIRM never runs and the
+    #      device-side job auto-reverts at timeout.
+    class Reconciler
+      # Default seconds the device-side auto-revert waits before self-restoring
+      # if the manager never confirms. Overridable per device via
+      # `options[:revert_timeout]`.
+      DEFAULT_REVERT_TIMEOUT = 120
+
+      # Post-apply health-check resilience. A box that has just had its filter
+      # table replaced can briefly drop a probe (sessions re-establishing,
+      # connection-tracking settling) before it is genuinely reachable. The
+      # check therefore RETRIES a bounded number of times with a short backoff
+      # before declaring the apply unhealthy (and letting the device-side
+      # auto-revert fire). Kept small and time-boxed so it never blocks long:
+      # at most MAX_ATTEMPTS probes, never exceeding TOTAL_TIMEOUT seconds.
+      HEALTH_CHECK_MAX_ATTEMPTS = 3
+      HEALTH_CHECK_BACKOFF = 0.5
+      HEALTH_CHECK_TOTAL_TIMEOUT = 5.0
+
+      # @param sleeper [#call] seconds -> void; the backoff sleeper (test seam:
+      #   inject a no-op for deterministic, instant health-check specs).
+      def initialize(configuration:, device:, transport:, sleeper: method(:sleep))
+        @configuration = configuration
+        @device = device
+        @transport = transport
+        @sleeper = sleeper
+      end
+
+      # @return [Plan] the changes needed to converge the device (no mutation)
+      def plan
+        Plan.diff(desired: desired, current: fetch_current)
+      end
+
+      # Apply the plan under the device-side commit-confirm envelope
+      # (arm_auto_revert -> apply -> health-check -> confirm; auto-revert fires
+      # on the device if confirm never runs).
+      #
+      # @param plan [Plan] defaults to a freshly computed plan
+      # @return [Plan] the plan that was applied
+      def apply(plan = nil)
+        plan ||= self.plan
+        return plan if plan.empty? # nothing to converge: skip the whole envelope
+
+        # 1. ARM the device-side auto-revert. A nil handle => offline/no-op
+        #    transport (e.g. Rsc): apply and return, no envelope to run.
+        handle = @transport.arm_auto_revert(DesiredState::MANAGED_PATHS, timeout: revert_timeout)
+
+        # 2. APPLY (operations are pre-sorted by Plan for fail-safe ordering).
+        #    If the link drops here the exception propagates and CONFIRM never
+        #    runs, so the device self-reverts at timeout.
+        @transport.apply(plan.operations)
+
+        # 3. HEALTH-CHECK + 4. CONFIRM (skipped for an offline/no-op transport).
+        confirm_or_revert(handle) unless handle.nil?
+        plan
+      end
+
+      private
+
+      # On a healthy post-apply read-back, cancel the device-side revert. On a
+      # failed check we deliberately do NOT confirm: the device restores the
+      # backup at timeout.
+      def confirm_or_revert(handle)
+        unless healthy?
+          raise TransportError, "post-apply health-check failed for device #{@device.name.inspect}; " \
+                                "device will auto-revert"
+        end
+
+        @transport.confirm(handle)
+      end
+
+      def compiler
+        @compiler ||= Compiler.new(@configuration)
+      end
+
+      def desired
+        @desired ||= compiler.compile(device: @device)
+      end
+
+      def fetch_current
+        @transport.fetch(DesiredState::MANAGED_PATHS, managed_list_names: compiler.managed_list_names)
+      end
+
+      # Manager-side health-check: re-reach the device and confirm the input
+      # chain still admits management traffic (an accept rule survives). Tolerates
+      # a brief post-apply blip by RETRYING up to HEALTH_CHECK_MAX_ATTEMPTS with
+      # a short backoff, bounded by HEALTH_CHECK_TOTAL_TIMEOUT; returns false only
+      # once every bounded attempt has failed.
+      def healthy?
+        deadline = monotonic + HEALTH_CHECK_TOTAL_TIMEOUT
+        attempt = 0
+        loop do
+          attempt += 1
+          return true if admits_management?
+          break if attempt >= HEALTH_CHECK_MAX_ATTEMPTS || monotonic >= deadline
+
+          @sleeper.call(HEALTH_CHECK_BACKOFF)
+        end
+        false
+      end
+
+      # One probe: re-fetch and confirm the input chain still admits management
+      # traffic. An unreachable device (TransportError) counts as a failed probe.
+      def admits_management?
+        current = fetch_current
+        input_rules = current[Compiler::IPV4_FILTER].select { |row| row[:chain] == "input" }
+        input_rules.any? { |row| row[:action] == "accept" }
+      rescue TransportError
+        false
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def revert_timeout
+        @device.options.fetch(:revert_timeout, DEFAULT_REVERT_TIMEOUT)
+      end
+    end
+  end
+end

data/lib/mt/wall/transport/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Transport
+      # Abstract transport adapter. A transport is the ONLY layer that knows
+      # how to talk to (or render for) a real device. Concrete adapters
+      # implement these operations against a device:
+      #
+      #   * #fetch(paths)             -> reads CURRENT state as a DesiredState
+      #   * #apply(operations)        -> writes Plan operations to the device
+      #   * #arm_auto_revert(...)     -> schedules a DEVICE-SIDE auto-revert
+      #   * #confirm(handle)          -> cancels the armed auto-revert
+      #
+      # To add a transport (binary API, SSH, ...), subclass Base and
+      # implement these. Credentials are read from ENV by the concrete adapter
+      # -- never passed through the DSL or stored in git.
+      #
+      # ── DEVICE-SIDE COMMIT-CONFIRM (auto-revert) ───────────────────────────
+      # An apply replaces the whole filter/nat table over a session that runs
+      # THROUGH the firewall, so a bad rule can sever the manager's own
+      # connection. RouterOS REST has NO native firewall transaction / safe-mode.
+      # A CLIENT-SIDE rollback is therefore USELESS: if the link drops mid-apply
+      # the rollback request is undeliverable. The revert MUST live ON THE
+      # DEVICE, armed BEFORE the apply, and self-fire on a timer if the manager
+      # never confirms:
+      #
+      #   handle = transport.arm_auto_revert(snapshot, timeout: 120)
+      #   begin
+      #     transport.apply(plan.operations)   # create-before-delete; drop LAST
+      #     # manager runs a post-apply health-check back to the device
+      #     transport.confirm(handle)          # cancels the scheduled revert
+      #   rescue TransportError, <health-check failed / link lost>
+      #     # do nothing: the device-side scheduler restores the backup at timeout
+      #   end
+      #
+      # Implementation contract for `arm_auto_revert`: back up the managed tables
+      # ON the device (e.g. `/export` of the managed paths or an `/ip/firewall`
+      # backup) and schedule a `/system/scheduler` (or delayed `/system/script`)
+      # job that RESTORES that backup after `timeout`. `confirm` cancels/deletes
+      # that scheduled job after a successful manager-side health-check.
+      # Adapters that cannot reach a live device (offline Rsc render) implement
+      # both as no-ops.
+      class Base
+        # @param paths [Array<String>] RouterOS resource paths to read
+        # @param managed_list_names [Array<String>] address-list names mt-wall
+        #   owns; foreign/static lists are excluded from the fetched state
+        # @return [DesiredState]
+        def fetch(paths, managed_list_names: [])
+          raise NotImplementedError, "#{self.class}#fetch must be implemented"
+        end
+
+        # @param operations [Array<Plan::Operation>]
+        # @return [void]
+        def apply(operations)
+          raise NotImplementedError, "#{self.class}#apply must be implemented"
+        end
+
+        # Back up the managed tables ON the device and schedule a device-side
+        # job that restores them after `timeout` unless {#confirm} cancels it.
+        # @param snapshot [Object]  identifier/handle for the on-device backup
+        #   (e.g. the managed paths to export); transport-defined
+        # @param timeout  [Integer] seconds before the device self-reverts
+        # @return [Object] an opaque handle for the scheduled revert job
+        def arm_auto_revert(snapshot, timeout:)
+          raise NotImplementedError, "#{self.class}#arm_auto_revert must be implemented"
+        end
+
+        # Cancel an armed device-side auto-revert after a healthy post-apply
+        # check; the new config becomes permanent.
+        # @param handle [Object] returned by {#arm_auto_revert}
+        # @return [void]
+        def confirm(handle)
+          raise NotImplementedError, "#{self.class}#confirm must be implemented"
+        end
+      end
+    end
+  end
+end