netstack 0.1.1 → 0.2.0

data/lib/netstack/monitoring/applier.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Monitoring
+    # The host must persist every checkpoint synchronously and return true. A
+    # recovery never repeats a write for which a started checkpoint exists.
+    class Applier
+      def initialize(client:)
+        @client = client
+      end
+
+      def call(plan:, checkpoint:, credentials: nil, execution_id: nil)
+        execute(plan, checkpoint: checkpoint, credentials: credentials, events: [], execution_id: execution_id)
+      end
+
+      def recover(plan:, events:, checkpoint:, credentials: nil, execution_id: nil)
+        execute(plan, checkpoint: checkpoint, credentials: credentials, events: events, execution_id: execution_id)
+      end
+
+      private
+
+      def execute(plan, checkpoint:, credentials:, events:, execution_id:)
+        Inputs.invalid!("Expected a monitoring plan") unless plan.is_a?(Plan)
+        Inputs.invalid!("A durable checkpoint callback is required") unless checkpoint.respond_to?(:call)
+        execution_id = Inputs.text(execution_id, name: "execution ID") unless execution_id.nil?
+        history = validate_events!(plan, events, execution_id)
+        ids = {}
+        plan.operations.each do |operation|
+          prior = history.fetch(operation.key, [])
+          attributes = resolve(operation.attributes, ids, credentials: credentials, secrets: false)
+          if prior.empty?
+            preflight!(operation, ids)
+            payload = resolve(operation.attributes, ids, credentials: credentials, secrets: true)
+            emit!(checkpoint, event(plan, operation, "started", execution_id: execution_id))
+            id = if operation.action == "create"
+                   @client.create(operation.resource, payload)
+                 else
+                   @client.update(operation.resource, resolve(operation.id, ids), payload)
+                 end
+            id = Inputs.identifier(id)
+            emit!(checkpoint, event(plan, operation, "receipt", id: id, execution_id: execution_id))
+          else
+            receipt = prior.find { |item| item["stage"] == "receipt" }
+            id = receipt && receipt["id"]
+            id ||= recover_id(operation, ids, attributes)
+            Inputs.invalid!("Recovery receipt belongs to a different resource") if operation.action == "update" && id != resolve(operation.id, ids)
+            emit!(checkpoint, event(plan, operation, "receipt", id: id, recovered: true, execution_id: execution_id)) unless receipt
+          end
+          verify!(operation, id, attributes)
+          unless prior.any? { |item| item["stage"] == "verified" }
+            emit!(checkpoint, event(plan, operation, "verified", id: id, execution_id: execution_id,
+                                                                 verification: operation.resource == "usermacro" ? "metadata" : "readback"))
+          end
+          ids[operation.key] = id
+        end
+        Values.copy({ "status" => "verified", "plan_digest" => plan.digest, "resources" => ids, "managed" => plan.managed, "execution_id" => execution_id })
+      end
+
+      def preflight!(operation, ids)
+        if operation.action == "create"
+          current = @client.find(operation.resource, resolve(operation.selector, ids))
+          fail!("Plan no longer matches the remote state", "stale_monitoring_plan") if current
+        else
+          current = @client.get(operation.resource, resolve(operation.id, ids))
+          fail!("Plan no longer matches the remote state", "stale_monitoring_plan") unless current && matches?(normalize(current), operation.before)
+        end
+      end
+
+      def recover_id(operation, ids, attributes)
+        current = if operation.action == "create"
+                    @client.find(operation.resource, resolve(operation.selector, ids))
+                  else
+                    @client.get(operation.resource, resolve(operation.id, ids))
+                  end
+        # Hidden macro values cannot prove whether a lost response represented a
+        # successful write. Require the original receipt or manual reconciliation.
+        if operation.resource == "usermacro" || !current || !matches?(normalize(current), verifiable(attributes))
+          fail!("Write outcome remains unknown; do not replay it", "monitoring_outcome_unknown")
+        end
+        Inputs.identifier(current.fetch(@client.resource_keys(operation.resource).first))
+      end
+
+      def verify!(operation, id, attributes)
+        current = @client.get(operation.resource, id)
+        return if current && matches?(normalize(current), verifiable(attributes))
+
+        fail!("Remote readback did not confirm the intended state", "monitoring_verification_failed")
+      end
+
+      def verifiable(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), result|
+            next if item.is_a?(Hash) && item.key?("$secret")
+
+            result[key] = verifiable(item)
+          end
+        when Array then value.map { |item| verifiable(item) }
+        else value
+        end
+      end
+
+      def normalize(row)
+        value = Inputs.object(row)
+        value["templates"] = value["parentTemplates"] if value.key?("parentTemplates")
+        value
+      end
+
+      def matches?(actual, expected)
+        StateComparison.matches?(actual, expected)
+      end
+
+      def resolve(value, ids, credentials: nil, secrets: false)
+        case value
+        when Hash
+          if value.keys == ["$ref"]
+            ids.fetch(value.fetch("$ref"))
+          elsif value.keys == ["$secret"]
+            return value unless secrets
+
+            Inputs.invalid!("A credentials resolver is required") unless credentials.respond_to?(:call)
+            secret = resolve_secret(credentials, value.fetch("$secret"))
+            Inputs.invalid!("Credential reference did not resolve") unless secret.is_a?(String) && !secret.empty?
+            secret
+          else
+            value.transform_values { |item| resolve(item, ids, credentials: credentials, secrets: secrets) }
+          end
+        when Array then value.map { |item| resolve(item, ids, credentials: credentials, secrets: secrets) }
+        else value
+        end
+      end
+
+      def resolve_secret(credentials, key)
+        credentials.call(key)
+      rescue StandardError
+        raise Netstack::Error.new("Credential resolution failed", code: "credential_unavailable", stage: "credentials"), cause: nil
+      end
+
+      def validate_events!(plan, events, execution_id)
+        Inputs.invalid!("Recovery events must be an array") unless events.is_a?(Array)
+        history = {}
+        current_index = 0
+        events.each do |raw|
+          item = Inputs.object(raw)
+          operation = plan.operations[current_index]
+          previous = operation && history.fetch(operation.key, [])
+          expected_stage = %w[started receipt verified][previous&.size || 0]
+          unless operation && item["plan_digest"] == plan.digest && item["operation"] == operation.key && item["stage"] == expected_stage &&
+                 item["execution_id"] == execution_id && item["resource"] == operation.resource && item["managed"] == plan.managed
+            Inputs.invalid!("Recovery events do not match this plan or stage order")
+          end
+          Inputs.identifier(item["id"]) unless expected_stage == "started"
+          Inputs.invalid!("Recovery resource ID changed") if expected_stage == "verified" && previous.last["id"] != item["id"]
+          (history[operation.key] ||= []) << item
+          current_index += 1 if expected_stage == "verified"
+        end
+        history
+      end
+
+      def event(plan, operation, stage, **fields)
+        Values.copy({ "plan_digest" => plan.digest, "operation" => operation.key, "resource" => operation.resource,
+                      "stage" => stage, "managed" => plan.managed }.merge(fields.transform_keys(&:to_s)))
+      end
+
+      def emit!(checkpoint, event)
+        begin
+          acknowledged = checkpoint.call(event)
+        rescue StandardError
+          raise Netstack::Error.new("Checkpoint persistence failed", code: "checkpoint_failed", stage: "monitoring"), cause: nil
+        end
+        fail!("Checkpoint was not durably acknowledged", "checkpoint_not_committed") unless acknowledged == true
+      end
+
+      def fail!(message, code)
+        raise Netstack::Error.new(message, code: code, stage: "monitoring")
+      end
+    end
+  end
+end

data/lib/netstack/monitoring/device_plan.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Monitoring
+    class DevicePlan
+      def initialize(client:)
+        @hosts = HostPlan.new(client: client)
+      end
+
+      def call(target:, groups:, community_ref:, templates: [], proxy_group_id: nil, name: nil,
+               enabled: true, inventory: {}, tags: {}, previous_managed: {})
+        address = Inputs.ip(target.host)
+        secret = Inputs.text(community_ref, name: "SNMP community reference")
+        @hosts.call(target: target, kind: "device", groups: groups, templates: templates,
+                    proxy_group_id: proxy_group_id, name: name, enabled: enabled, inventory: inventory, tags: tags,
+                    previous_managed: previous_managed,
+                    interface: { "type" => 2, "main" => 1, "useip" => 1, "ip" => address, "dns" => "", "port" => "161",
+                                 "details" => { "version" => 2, "bulk" => 1, "community" => "{$SNMP_COMMUNITY}" } },
+                    secret_macro: { "macro" => "{$SNMP_COMMUNITY}", "value" => { "$secret" => secret }, "type" => 1 })
+      end
+    end
+  end
+end

data/lib/netstack/monitoring/host_plan.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Monitoring
+    # Build a read-only plan. Only previously owned collection members are
+    # removed; manual groups, templates, tags and inventory fields survive.
+    class HostPlan
+      def initialize(client:)
+        @client = client
+      end
+
+      def call(target:, kind:, groups:, templates: [], proxy_group_id: nil, name: nil, enabled: true,
+               inventory: {}, tags: {}, interface: nil, secret_macro: nil, previous_managed: {})
+        Inputs.boolean(enabled)
+        identity = Inputs.text(target.key, name: "technical host")
+        Inputs.invalid!("Technical host contains expression delimiters") if identity.match?(%r{[/\[\](),]})
+        old = previous_ownership(previous_managed, target.key)
+        group_ids = Inputs.ids(groups)
+        template_ids = Inputs.ids(templates)
+        existing = @client.find("host", "filter" => { "host" => [identity] })
+        Inputs.invalid!("Host lookup returned a different identity") if existing && existing["host"] != identity
+        unless enabled
+          operations = if existing && existing["status"].to_s != "1"
+                         [Mutation.new(key: "host", resource: "host", action: "update",
+                                       id: existing.fetch("hostid"), attributes: { "status" => 1 }, before: { "status" => existing.fetch("status") })]
+                       else
+                         []
+                       end
+          managed = existing ? old : previous_ownership({}, target.key)
+          return Plan.new(key: "#{kind}:#{target.key}", operations: operations, managed: managed)
+        end
+        managed = { "target" => target.key, "group_ids" => group_ids, "template_ids" => template_ids }
+        Inputs.invalid!("At least one host group is required") if group_ids.empty?
+        inventory = Inputs.object(inventory)
+        Inputs.invalid!("Inventory fields must be text") unless inventory.values.all? { |value| value.is_a?(String) }
+        desired_tags = Inputs.object(tags).merge("kind" => kind.to_s, "target" => target.key).map do |key, value|
+          { "tag" => "netstack.#{Inputs.text(key, name: "tag name")}", "value" => Inputs.text(value, name: "tag value") }
+        end
+        attributes = {
+          "host" => identity, "name" => Inputs.text(name || target.key, name: "visible host name"),
+          "status" => 0, "groups" => references(group_ids, "groupid"),
+          "templates" => references(template_ids, "templateid"), "tags" => desired_tags,
+          "inventory_mode" => 0, "inventory" => inventory
+        }
+        attributes.merge!("monitored_by" => 2, "proxy_groupid" => Inputs.identifier(proxy_group_id)) if proxy_group_id
+        managed["tag_names"] = desired_tags.map { |tag| tag.fetch("tag") }
+        if existing
+          groups_before = refs!(existing["groups"], "groupid")
+          templates_before = refs!(existing["parentTemplates"], "templateid")
+          attributes["groups"] = references((groups_before - old.fetch("group_ids")) | group_ids, "groupid")
+          attributes["templates"] = references((templates_before - old.fetch("template_ids")) | template_ids, "templateid")
+          removed_tags = old.fetch("tag_names") | managed.fetch("tag_names")
+          tags_before = tag_rows!(existing["tags"])
+          attributes["tags"] = tags_before.reject { |tag| removed_tags.include?(tag.fetch("tag")) } + desired_tags
+          attributes["inventory"] = Inputs.object(existing["inventory"]).merge(inventory)
+          before = attributes.keys.to_h do |key|
+            current = key == "templates" ? references(templates_before, "templateid") : existing[key]
+            [key, current]
+          end
+          before.compact!
+          changes = attributes.reject { |key, value| equivalent?(before[key], value) }
+          operations = if changes.empty?
+                         []
+                       else
+                         [Mutation.new(key: "host", resource: "host", action: "update", id: existing.fetch("hostid"), attributes: changes, before: before)]
+                       end
+          host_id = existing.fetch("hostid").to_s
+        else
+          operations = [Mutation.new(key: "host", resource: "host", action: "create", attributes: attributes,
+                                     selector: { "filter" => { "host" => [identity] } })]
+          host_id = { "$ref" => "host" }
+        end
+        append_interface(operations, host_id, interface, existing) if interface
+        append_macro(operations, host_id, secret_macro, existing) if secret_macro
+        Plan.new(key: "#{kind}:#{target.key}", operations: operations, managed: managed)
+      end
+
+      private
+
+      def previous_ownership(value, target_key)
+        previous = Inputs.object(value)
+        if previous.key?("target") && previous["target"] != target_key
+          Inputs.invalid!("Previously managed state belongs to a different target")
+        end
+        tags = previous.fetch("tag_names", [])
+        unless tags.is_a?(Array) && tags.all? { |key| key.is_a?(String) && key.start_with?("netstack.") }
+          Inputs.invalid!("Previously managed tags must belong to Netstack")
+        end
+        { "target" => target_key, "group_ids" => Inputs.ids(previous.fetch("group_ids", [])),
+          "template_ids" => Inputs.ids(previous.fetch("template_ids", [])), "tag_names" => tags.uniq }
+      end
+
+      def references(ids, key) = ids.map { |id| { key => id } }
+
+      def equivalent?(actual, desired)
+        StateComparison.matches?(actual, desired)
+      end
+
+      def refs!(rows, key)
+        Inputs.invalid!("Malformed remote reference collection") unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) && row.key?(key) }
+        Inputs.ids(rows.map { |row| row.fetch(key) })
+      end
+
+      def tag_rows!(rows)
+        unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) && row["tag"].is_a?(String) && row["value"].is_a?(String) }
+          Inputs.invalid!("Malformed remote tag collection")
+        end
+        rows.map { |row| row.slice("tag", "value") }
+      end
+
+      def append_interface(operations, host_id, interface, existing)
+        attributes = Inputs.object(interface)
+        selector = { "hostids" => [host_id], "filter" => { "type" => attributes.fetch("type"), "main" => 1 } }
+        current = existing && @client.find("hostinterface", selector)
+        if current
+          unless current["hostid"].to_s == host_id.to_s && current["type"].to_s == attributes.fetch("type").to_s && current["main"].to_s == "1" && attributes.keys.all? { |key| current.key?(key) }
+            Inputs.invalid!("Interface lookup returned incomplete or foreign state")
+          end
+          before = attributes.keys.to_h { |key| [key, current.fetch(key)] }
+          return if equivalent?(before, attributes)
+
+          before["hostid"] = current.fetch("hostid")
+          if before["details"].is_a?(Hash)
+            before["details"] = before["details"].except("community", "authpassphrase", "privpassphrase")
+          end
+
+          operations << Mutation.new(key: "interface", resource: "hostinterface", action: "update",
+                                     id: current.fetch("interfaceid"), attributes: attributes, before: before)
+        else
+          operations << Mutation.new(key: "interface", resource: "hostinterface", action: "create",
+                                     attributes: attributes.merge("hostid" => host_id), selector: selector)
+        end
+      end
+
+      def append_macro(operations, host_id, macro, existing)
+        attributes = Inputs.object(macro)
+        selector = { "hostids" => [host_id], "filter" => { "macro" => attributes.fetch("macro") } }
+        current = existing && @client.find("usermacro", selector)
+        if current && (current["hostid"].to_s != host_id.to_s || current["macro"] != attributes.fetch("macro") || !current.key?("type"))
+          Inputs.invalid!("Macro lookup returned incomplete or foreign state")
+        end
+        operations << if current
+                        Mutation.new(key: "macro", resource: "usermacro", action: "update", id: current.fetch("hostmacroid"),
+                                     attributes: attributes, before: current.slice("hostid", "macro", "type"))
+                      else
+                        Mutation.new(key: "macro", resource: "usermacro", action: "create",
+                                     attributes: attributes.merge("hostid" => host_id), selector: selector)
+                      end
+      end
+    end
+  end
+end

data/lib/netstack/monitoring/inputs.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Netstack
+  module Monitoring
+    module Inputs
+      module_function
+
+      def object(value)
+        invalid!("Expected an object") unless value.is_a?(Hash)
+        value.each_with_object({}) do |(key, item), result|
+          invalid!("Object keys must be strings or symbols") unless key.is_a?(String) || key.is_a?(Symbol)
+          invalid!("Duplicate object key") if result.key?(key.to_s)
+          result[key.to_s] = normalize(item)
+        end
+      end
+
+      def normalize(value)
+        case value
+        when Hash then object(value)
+        when Array then value.map { |item| normalize(item) }
+        when Float
+          invalid!("Numbers must be finite") unless value.finite?
+          value
+        when String, Integer, TrueClass, FalseClass, NilClass then value
+        else invalid!("Value must be JSON-compatible")
+        end
+      end
+
+      def text(value, name:)
+        invalid!("#{name} must be nonempty text") unless value.is_a?(String) && !value.strip.empty? && !value.match?(/[\x00-\x1f\x7f]/)
+        value.strip
+      end
+
+      def identifier(value)
+        valid = (value.is_a?(Integer) && value.positive?) || (value.is_a?(String) && value.match?(/\A[1-9][0-9]*\z/))
+        invalid!("Invalid monitoring identifier") unless valid
+        value.to_s
+      end
+
+      def ids(values)
+        invalid!("Expected an identifier array") unless values.is_a?(Array)
+        values.map { |value| identifier(value) }.uniq
+      end
+
+      def boolean(value)
+        invalid!("Expected a boolean") unless [true, false].include?(value)
+        value
+      end
+
+      def number(value, positive: false)
+        numeric = value.is_a?(Integer) || value.is_a?(Float) || (value.is_a?(String) && value.match?(/\A-?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?\z/))
+        invalid!("Expected a finite number") unless numeric
+        number = Float(value)
+        invalid!("Expected a finite nonnegative number") unless number.finite? && (positive ? number.positive? : number >= 0)
+        number
+      end
+
+      def ip(value)
+        value = text(value, name: "IP address")
+        invalid!("Expected an IP address without a prefix") if value.include?("/")
+        IPAddr.new(value).to_s
+      rescue IPAddr::InvalidAddressError
+        invalid!("Invalid IP address")
+      end
+
+      def invalid!(message)
+        raise Netstack::InputError.new(message, code: "invalid_monitoring_input", stage: "input")
+      end
+    end
+  end
+end

data/lib/netstack/monitoring/measurements.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Monitoring
+    class Measurements
+      class Series < Data.define(:item_id, :source, :from, :to, :points, :status)
+        def initialize(item_id:, source:, from:, to:, points:, status:)
+          super(item_id: item_id.freeze, source: source.freeze, from: from, to: to,
+                points: Values.copy(points), status: status.freeze)
+        end
+      end
+
+      def initialize(client:)
+        @client = client
+      end
+
+      def history(item_id:, value_type:, from:, to:, limit: 10_000)
+        item_id = Inputs.identifier(item_id)
+        rows = @client.history(item_id: item_id, value_type: value_type, from: from, to: to, limit: limit)
+        points = rows.map do |row|
+          validate_identity!(row, item_id)
+          clock = integer!(row.fetch("clock"))
+          ns = integer!(row.fetch("ns", 0))
+          Inputs.invalid!("Invalid measurement nanoseconds") unless ns < 1_000_000_000
+          { "clock" => clock, "ns" => ns, "value" => Inputs.number(row.fetch("value")) }
+        end
+        build_series(item_id, "history", from, to, points, limit)
+      rescue KeyError
+        Inputs.invalid!("Measurement row is incomplete")
+      end
+
+      def trends(item_id:, from:, to:, limit: 10_000)
+        item_id = Inputs.identifier(item_id)
+        rows = @client.trends(item_id: item_id, from: from, to: to, limit: limit)
+        points = rows.map do |row|
+          validate_identity!(row, item_id)
+          count = integer!(row.fetch("num"))
+          Inputs.invalid!("Trend row must contain actual samples") unless count.positive?
+          minimum = Inputs.number(row.fetch("value_min"))
+          average = Inputs.number(row.fetch("value_avg"))
+          maximum = Inputs.number(row.fetch("value_max"))
+          Inputs.invalid!("Invalid trend bounds") unless minimum <= average && average <= maximum
+          { "clock" => integer!(row.fetch("clock")), "ns" => 0, "count" => count,
+            "minimum" => minimum, "average" => average, "maximum" => maximum }
+        end
+        build_series(item_id, "trend", from, to, points, limit)
+      rescue KeyError
+        Inputs.invalid!("Trend row is incomplete")
+      end
+
+      # Exact timestamp joins: missing direction stays nil. Trend averages are
+      # not traffic samples and cannot be used to claim a raw-sample percentile.
+      def self.align(inbound:, outbound:)
+        Inputs.invalid!("Alignment requires raw history series") unless [inbound, outbound].all? { |series| series.is_a?(Series) && series.source == "history" }
+        Inputs.invalid!("Measurement intervals must match") unless inbound.from == outbound.from && inbound.to == outbound.to
+        indexed = [inbound, outbound].map do |series|
+          series.points.to_h { |point| [[point.fetch("clock"), point.fetch("ns")], point.fetch("value")] }
+        end
+        Values.copy((indexed[0].keys | indexed[1].keys).sort.map do |clock, ns|
+          { "clock" => clock, "ns" => ns, "in_bps" => indexed[0][[clock, ns]], "out_bps" => indexed[1][[clock, ns]] }
+        end)
+      end
+
+      private
+
+      def validate_identity!(row, item_id)
+        Inputs.invalid!("Measurement belongs to a different item") unless row.is_a?(Hash) && Inputs.identifier(row["itemid"]) == item_id
+      end
+
+      def integer!(value)
+        number = value.is_a?(Integer) ? value : (Integer(value, 10) if value.is_a?(String) && value.match?(/\A\d+\z/))
+        Inputs.invalid!("Invalid measurement timestamp or count") unless number && number >= 0
+        number
+      end
+
+      def build_series(item_id, source, from, to, points, limit)
+        Inputs.invalid!("Measurement falls outside the requested interval") unless points.all? { |point| (from..to).cover?(point["clock"]) }
+        keys = points.map { |point| [point["clock"], point["ns"]] }
+        Inputs.invalid!("Duplicate measurement timestamp") unless keys.uniq.size == keys.size
+        status = if points.size >= limit then "truncated"
+                 elsif points.empty? then "empty"
+                 else "available"
+                 end
+        Series.new(item_id: item_id, source: source, from: from, to: to,
+                   points: points.sort_by { |point| [point["clock"], point["ns"]] }, status: status)
+      end
+    end
+  end
+end

data/lib/netstack/monitoring/mutation.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Monitoring
+    class Mutation
+      attr_reader :key, :resource, :action, :attributes, :id, :before, :selector
+
+      def initialize(key:, resource:, action:, attributes:, id: nil, before: {}, selector: {})
+        @key = Inputs.text(key, name: "operation key").freeze
+        @resource = resource.to_s.freeze
+        Inputs.invalid!("Unsupported monitoring resource") unless %w[host hostinterface usermacro item trigger].include?(@resource)
+        @action = action.to_s.freeze
+        Inputs.invalid!("Unsupported monitoring action") unless %w[create update].include?(@action)
+        @attributes = Values.copy(Inputs.object(attributes))
+        @before = Values.copy(Inputs.object(before))
+        @selector = Values.copy(Inputs.object(selector))
+        @id = if id.nil?
+                nil
+              else
+                Values.copy(id.is_a?(Hash) ? Inputs.object(id) : Inputs.identifier(id))
+              end
+        Inputs.invalid!("Update requires a resource ID") if @action == "update" && @id.nil?
+        Inputs.invalid!("Create requires a recovery selector") if @action == "create" && @selector.empty?
+        if @resource == "usermacro" && @attributes.key?("value")
+          secret = @attributes["value"]
+          Inputs.invalid!("Macro values must use a secret reference") unless secret.is_a?(Hash) && secret.keys == ["$secret"] && secret["$secret"].is_a?(String)
+        end
+        freeze
+      end
+
+      def to_h
+        { "key" => key, "resource" => resource, "action" => action, "attributes" => attributes,
+          "id" => id, "before" => before, "selector" => selector }
+      end
+    end
+  end
+end

data/lib/netstack/monitoring/plan.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module Netstack
+  # 监控意图与确认；提供方 RPC 细节由集成模块管理。
+  module Monitoring
+    # 不可变的有序变更；引用只能指向更早的操作。
+    # 秘密通过解析器引用传递；受管理资源的归属由宿主提供。
+    class Plan
+      attr_reader :key, :operations, :managed, :digest
+
+      def initialize(key:, operations:, managed: {})
+        @key = Inputs.text(key, name: "plan key").freeze
+        Inputs.invalid!("Expected monitoring mutations") unless operations.is_a?(Array) && operations.all? { |item| item.is_a?(Mutation) }
+        known = []
+        operations.each do |operation|
+          Inputs.invalid!("Duplicate operation key") if known.include?(operation.key)
+          validate_references!(operation.to_h, known)
+          known << operation.key
+        end
+        @operations = operations.dup.freeze
+        @managed = Values.copy(Inputs.object(managed))
+        @digest = Digest::SHA256.hexdigest(JSON.generate(canonical(to_h))).freeze
+        freeze
+      end
+
+      def to_h
+        { "key" => key, "operations" => operations.map(&:to_h), "managed" => managed }
+      end
+
+      def self.from_h(value)
+        value = Inputs.object(value)
+        operations = value.fetch("operations").map do |operation|
+          Mutation.new(**operation.transform_keys(&:to_sym))
+        end
+        new(key: value.fetch("key"), operations: operations, managed: value.fetch("managed", {}))
+      rescue KeyError, NoMethodError, ArgumentError
+        Inputs.invalid!("Invalid persisted monitoring plan")
+      end
+
+      private
+
+      def validate_references!(value, known)
+        case value
+        when Hash
+          if value.key?("$ref")
+            Inputs.invalid!("Reference must identify an earlier operation") unless value.keys == ["$ref"] && known.include?(value["$ref"])
+          elsif value.key?("$secret")
+            Inputs.invalid!("Invalid secret reference") unless value.keys == ["$secret"] && value["$secret"].is_a?(String) && !value["$secret"].empty?
+          else
+            value.each_value { |item| validate_references!(item, known) }
+          end
+        when Array
+          value.each { |item| validate_references!(item, known) }
+        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/monitoring/probe_plan.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Monitoring
+    class ProbePlan
+      def initialize(client:)
+        @hosts = HostPlan.new(client: client)
+      end
+
+      def call(target:, groups:, templates:, proxy_group_id: nil, name: nil, enabled: true,
+               inventory: {}, tags: {}, previous_managed: {})
+        Inputs.invalid!("An ICMP probe template is required") if Inputs.ids(templates).empty?
+        @hosts.call(target: target, kind: "probe", groups: groups, templates: templates, proxy_group_id: proxy_group_id,
+                    name: name, enabled: enabled, inventory: inventory, tags: tags, previous_managed: previous_managed,
+                    interface: { "type" => 1, "main" => 1, "useip" => 1, "ip" => Inputs.ip(target.host), "dns" => "", "port" => "10050" })
+      end
+    end
+  end
+end