enjine 0.1.0

data/lib/enjine/mechanics/values.rb

@@ -0,0 +1,675 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    # A number an effect uses, computed when the effect resolves (CR 608.2h):
+    #   3                                             a fixed number
+    #   "x"                                           the X announced for this spell or ability (CR 107.3)
+    #   {"count": selector}                           how many objects/players match ({"count": {"result": 0}}:
+    #                                                 how many the first effect moved or created, e.g. cards drawn)
+    #   {"power": selector} / {"toughness": ...}      total power / toughness ("Picard's power": {"power": "self"})
+    #   {"greatest_power" | "greatest_toughness": selector}  the greatest power / toughness among them (0 for none)
+    #   {"hand_size" | "life" | "graveyard_size": player selector}
+    #   {"distinct_names": selector}                  how many different names they have (strange new worlds)
+    #   {"mana_value": selector}                      their total mana value (a spell's X counts on the stack; a spell
+    #                                                 countered by the resolving one: as it last existed, CR 608.2h)
+    #   {"distinct_types": selector}                  how many different creature types they have (CR 205.3m)
+    #   {"distinct_colors": selector}                 how many colors among them (CR 105.2, 202.2)
+    #   {"distinct_land_types": selector}             how many basic land types among them (domain, CR 305.6)
+    #   {"distinct_planeswalker_types": selector}     how many planeswalker types among them (CR 205.3j)
+    #   {"counters": {"of": selector, "kind": name}}  counters on them, objects or players (any kind without "kind", CR 122)
+    #   {"life_gained_this_turn" | "life_lost_this_turn" | "dilemmas_this_turn" | "returned_this_turn"
+    #    | "cards_drawn_this_turn" | "cards_discarded_this_turn" | "noncombat_damage_this_turn"
+    #    | "noncombat_damage_last_turn"
+    #    | "spells_cast_this_game" | "turns_taken": player selector}  this turn's (or game's) history, see
+    #                                                 Engine::TurnHistory ("turns_taken": turns begun, this one included)
+    #   {"spells_cast_this_turn" | "lands_played_this_turn": {"by": player selector, "matching": filter,
+    #    "from" | "not_from": zone}}                spells cast / lands played this turn
+    #   {"died_this_turn" | "entered_this_turn" | "left_this_turn" | "sacrificed_this_turn" | "attackers_this_turn"
+    #    | "exiled_this_turn": {"each": filter, "controller": you|opponent|any}}  objects in this turn's history
+    #   {"this_way": n}                               how much effect n of this list changed (life it took)
+    #   {"mana_spent": {"of": ..., "color" | "colors": ...}}  mana spent to cast a spell (CR 601.2h), see mana_spent.rb
+    #   {"times": [a, b]} / {"plus": [a, b]} / {"divide": [a, b]}   arithmetic on amounts; division rounds down
+    #                                                 (CR 107.1a). "-X" is {"times": ["x", -1]}.
+    # A source that has left the battlefield is used as it last existed (CR 608.2h).
+    class Amount
+      SELECTOR_KINDS = %w[count power toughness greatest_power hand_size life graveyard_size distinct_names distinct_types
+                          distinct_colors distinct_land_types distinct_planeswalker_types
+                          life_gained_this_turn life_lost_this_turn dilemmas_this_turn returned_this_turn
+                          cards_drawn_this_turn cards_discarded_this_turn spells_cast_this_game speed
+                          noncombat_damage_this_turn noncombat_damage_last_turn turns_taken greatest_toughness
+                          mana_value].freeze
+      ARITHMETIC = %w[times plus divide].freeze
+      BASIC_LAND_TYPES = %i[plains island swamp mountain forest].freeze # CR 305.6
+      # Object history lists: kind -> turn_log key (Engine::TurnHistory).
+      DEPARTED = { "died_this_turn" => "died", "entered_this_turn" => "entered", "left_this_turn" => "left",
+                   "sacrificed_this_turn" => "sacrificed", "attackers_this_turn" => "attackers",
+                   "exiled_this_turn" => "exiled" }.freeze
+      KINDS = (SELECTOR_KINDS + ARITHMETIC + DEPARTED.keys + %w[counters spells_cast_this_turn lands_played_this_turn this_way
+                                                                mana_spent]).freeze
+      # Player history counters: kind -> turn_log/game_log key.
+      HISTORY = { "life_gained_this_turn" => "life_gained", "life_lost_this_turn" => "life_lost",
+                  "dilemmas_this_turn" => "dilemmas", "returned_this_turn" => "returned",
+                  "cards_drawn_this_turn" => "drawn", "cards_discarded_this_turn" => "discarded",
+                  "noncombat_damage_this_turn" => "noncombat_damage" }.freeze
+      # The same, read from the previous turn's log ("was dealt noncombat damage last turn").
+      LAST_TURN = { "noncombat_damage_last_turn" => "noncombat_damage" }.freeze
+
+      # `min`: the smallest fixed number allowed (computed amounts may be anything their parts give).
+      def self.build(data, errors, path, targets_count:, min: 0, results_count: 0)
+        return Fixed.new(data) if data.is_a?(Integer) && data >= min
+        return X::INSTANCE if data == "x"
+        return Triggering::INSTANCE if data == { "triggering" => "amount" } # "that many" (CR 603.2)
+
+        unless data.is_a?(Hash) && data.size == 1 && KINDS.include?(data.keys.first.to_s)
+          errors << "#{path}: must be an integer >= #{min}, \"x\" or one of {#{KINDS.join("|")}: ...}"
+          return Fixed.new(0)
+        end
+        kind, ref = data.first
+        kind = kind.to_s
+        context = { targets_count: targets_count, results_count: results_count }
+        return Arithmetic.build(kind, ref, errors, "#{path}.#{kind}", **context) if ARITHMETIC.include?(kind)
+        return Counters.build(ref, errors, "#{path}.#{kind}", **context) if kind == "counters"
+        return SpellsCast.build(ref, errors, "#{path}.#{kind}", kind: kind, **context) if SpellsCast::LOGS.key?(kind)
+        return Departed.build(kind, ref, errors, "#{path}.#{kind}") if DEPARTED.key?(kind)
+        return ThisWay.build(ref, errors, "#{path}.#{kind}", results_count) if kind == "this_way"
+        return ManaSpent.build(ref, errors, "#{path}.#{kind}", **context) if kind == "mana_spent" # mana_spent.rb
+
+        new(kind, Selector.build(ref, errors, "#{path}.#{kind}", **context))
+      end
+
+      # Whether the amount can be computed during the layer pass (CR 613): it may count objects by
+      # their types, but must not read power or toughness (that would depend on the pass's result).
+      def self.layer_safe?(amount) = !amount.respond_to?(:reads_power?) || !amount.reads_power?
+
+      def initialize(kind, selector)
+        @kind = kind
+        @selector = selector
+        freeze
+      end
+
+      def reads_power? = %w[power toughness greatest_power greatest_toughness].include?(@kind)
+
+      def value(engine, ctx)
+        refs = @selector.resolve(engine, ctx) # built without errors: a selector
+        case @kind
+        when "count" then refs.size
+        when "power", "toughness" then refs.empty? ? Amount.last_known(engine, ctx, @selector, @kind) : stats(engine, refs).sum
+        when "greatest_power", "greatest_toughness" then stats(engine, refs).max.to_i
+        when "mana_value" then refs.sum do
+          Amount.mana_value(engine, engine.state.objects[it]) || engine.resolving_last_known(it)&.[]("mana_value").to_i
+        end
+        when "distinct_names" then live(engine, refs).map { engine.chars(it).name }.uniq.size
+        when "distinct_types" then live(engine, refs).flat_map { Amount.creature_types(engine.chars(it)) }.uniq.size
+        when "distinct_colors" then live(engine, refs).flat_map { engine.chars(it).colors }.uniq.size # CR 105.2
+        when "distinct_land_types" then (live(engine, refs).flat_map { engine.chars(it).subtypes } & BASIC_LAND_TYPES).size
+        when "distinct_planeswalker_types" # CR 205.3j: a planeswalker's subtypes are planeswalker types
+          live(engine, refs).flat_map { (c = engine.chars(it)).type?(:planeswalker) ? c.subtypes : [] }.uniq.size
+        else players(engine, refs).sum { player_value(engine, it) }
+        end
+      end
+
+      def to_s = "the #{@kind.tr("_", " ")} of #{@selector}"
+
+      # CR 202.3: the mana value of an object (0 without a mana cost); a spell on the stack counts its X (CR 202.3e).
+      # Nil for an object that's gone.
+      def self.mana_value(engine, obj)
+        return nil if obj.nil?
+
+        cost = engine.chars(obj).mana_cost or return 0
+        (obj.zone == :stack ? cost.with_x(obj.x.to_i) : cost).mana_value
+      end
+
+      # CR 205.3m: a creature's or kindred's subtypes are creature types, except those of its other card types.
+      def self.creature_types(chars)
+        chars.creature? || chars.type?(:kindred) ? chars.subtypes - Engine::Characteristics::NON_CREATURE_SUBTYPES : []
+      end
+
+      # CR 608.2h: "its power" of a source that has left the battlefield is its last known value.
+      def self.last_known(engine, ctx, selector, key)
+        return 0 unless selector.kind == :self
+
+        lki = source_lki(engine, ctx)
+        lki ? lki[key].to_i : 0
+      end
+
+      # How a source that has left the battlefield last existed: remembered by the resolving ability, or,
+      # while its leaves-the-battlefield trigger is being checked (CR 603.4, 603.10a), the engine's.
+      def self.source_lki(engine, ctx)
+        engine.state.objects[ctx.object]&.memory&.[]("source_lki") || engine.last_known(ctx.source)
+      end
+
+      private
+
+      def live(engine, refs) = refs.select { engine.state.objects.key?(it) }
+
+      def stats(engine, refs)
+        live(engine, refs).map { engine.public_send(@kind.end_with?("toughness") ? :toughness : :power, engine.object(it)) }
+      end
+
+      def players(engine, refs) = refs.filter_map { Filters.player_index(engine, it) }
+
+      def player_value(engine, index)
+        case @kind
+        when "hand_size" then engine.player(index).hand.size
+        when "life" then engine.player(index).life
+        when "speed" then engine.speed(index) # CR 702.179f: 0 without speed
+        when "graveyard_size" then engine.player(index).graveyard.size
+        when "spells_cast_this_game" then engine.game_log(index).fetch("spells", 0)
+        when "turns_taken" then engine.game_log(index).fetch("turns", 0) # this turn included, if it's theirs
+        when *LAST_TURN.keys then engine.last_turn_log(index).fetch(LAST_TURN.fetch(@kind), 0)
+        else engine.turn_log(index).fetch(HISTORY.fetch(@kind), 0)
+        end
+      end
+
+      # X (CR 107.3a): the value announced for the resolving spell or ability. An enters-the-battlefield
+      # trigger carries the X its permanent was cast with (CR 107.3m). 0 when none was announced.
+      class X
+        INSTANCE = new.freeze
+
+        def value(engine, ctx) = engine.state.objects[ctx.object]&.x.to_i
+        def to_s = "X"
+      end
+
+      # "That many": the number in the event that triggered the resolving ability (damage dealt, life
+      # gained, counters put), see Triggers.event_facts. 0 outside a triggered ability.
+      class Triggering
+        INSTANCE = new.freeze
+
+        def value(engine, ctx) = Selector.memory(engine, ctx).fetch("triggering", {})["amount"].to_i
+        def to_s = "that many"
+      end
+
+      # A fixed number.
+      class Fixed
+        attr_reader :n
+
+        def initialize(number)
+          @n = number
+          freeze
+        end
+
+        def value(_engine, _ctx) = @n
+        def to_s = @n.to_s
+      end
+
+      # {"times" | "plus" | "divide": [a, b]}: a × b, a + b, or a ÷ b rounded down (CR 107.1a).
+      class Arithmetic
+        def self.build(kind, parts, errors, path, **context)
+          unless parts.is_a?(Array) && parts.size == 2
+            errors << "#{path}: must be a list of two amounts"
+            return Fixed.new(0)
+          end
+          left, right = parts.each_with_index.map { |p, i| Amount.build(p, errors, "#{path}[#{i}]", min: -1000, **context) }
+          errors << "#{path}[1]: must be a positive integer" if kind == "divide" && !(parts[1].is_a?(Integer) && parts[1].positive?)
+          new(kind, left, right)
+        end
+
+        def initialize(kind, left, right)
+          @kind = kind
+          @left = left
+          @right = right
+          freeze
+        end
+
+        def reads_power? = [@left, @right].any? { !Amount.layer_safe?(it) }
+
+        def value(engine, ctx)
+          a = @left.value(engine, ctx)
+          b = @right.value(engine, ctx)
+          case @kind
+          when "times" then a * b
+          when "plus" then a + b
+          else a.div(b) # b was checked positive
+          end
+        end
+
+        def to_s = "#{@left} #{{ "times" => "×", "plus" => "+", "divide" => "÷" }[@kind]} #{@right}"
+      end
+
+      # {"this_way": n}: how much effect n of the same list changed, e.g. the life a lose_life effect took
+      # (CR 608.2c).
+      class ThisWay
+        def self.build(index, errors, path, results_count)
+          unless index.is_a?(Integer) && index >= 0 && index < results_count
+            errors << "#{path}: must refer to one of the #{results_count} earlier effects"
+          end
+          new(index.to_i)
+        end
+
+        def initialize(index)
+          @index = index
+          freeze
+        end
+
+        def value(_engine, ctx) = ctx.amounts&.[](@index).to_i
+        def to_s = "the amount from effect ##{@index + 1}"
+      end
+
+      # {"counters": {"of": selector, "kind": name}}: counters of one kind (or of every kind) on the
+      # objects or players (CR 122). A source that has left the battlefield counts as it last existed (CR 608.2h).
+      class Counters
+        def self.build(data, errors, path, **context)
+          data = data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+          Mechanics.check_keys(data, %w[of kind], errors, path)
+          errors << "#{path}.of: required" unless data.key?("of")
+          kind = data["kind"] && Mechanics::Counters.parse(data["kind"], errors, "#{path}.kind")
+          new(Selector.build(data.fetch("of", "self"), errors, "#{path}.of", **context), kind)
+        end
+
+        def initialize(selector, kind)
+          @selector = selector
+          @kind = kind
+          freeze
+        end
+
+        def value(engine, ctx)
+          all = @selector.resolve(engine, ctx)
+          refs = all.select { engine.state.objects.key?(it) }
+          counters = refs.map { engine.object(it).counters } +
+                     all.filter_map { Filters.player_index(engine, it) }.map { engine.player_counters(it) } # CR 122.1
+          counters = [Amount.source_lki(engine, ctx)&.[]("counters") || {}] if refs.empty? && @selector.kind == :self
+          counters.sum { @kind ? it.fetch(@kind, 0) : it.values.sum }
+        end
+
+        def to_s = "the number of #{"#{@kind} " if @kind}counters on #{@selector}"
+      end
+
+      # {"spells_cast_this_turn": {"by": "you", "matching": {"spell": {"not": ["creature"]}}}}: spells the
+      # players cast this turn whose card types match (CR 601.2i; a cancelled cast never counts).
+      # {"lands_played_this_turn": {"by": "you"}}: lands they played this turn (CR 305.1). `from` / `not_from`:
+      # only those cast or played from (not from) that zone (CR 601.2a).
+      class SpellsCast
+        LOGS = { "spells_cast_this_turn" => "spells", "lands_played_this_turn" => "lands_played" }.freeze
+
+        def self.build(data, errors, path, kind: "spells_cast_this_turn", **context)
+          data = data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+          Mechanics.check_keys(data, %w[by matching from not_from], errors, path)
+          casters = Selector.build(data.fetch("by", "you"), errors, "#{path}.by", **context)
+          filter = data["matching"] && Mechanics.build_entry(:filter, data["matching"], errors, "#{path}.matching")
+          new(casters, filter, CastFrom.build(data, errors, path), LOGS.fetch(kind))
+        end
+
+        def initialize(casters, filter, zones = CastFrom.new(nil, nil), log = "spells")
+          @by = casters
+          @filter = filter
+          @zones = zones
+          @log = log
+          freeze
+        end
+
+        def value(engine, ctx)
+          players = @by.resolve(engine, ctx).filter_map { Filters.player_index(engine, it) }
+          players.sum do |index|
+            entries(engine.turn_log(index)).count do |card, zone|
+              @zones.match?(zone) && (@filter.nil? || Departed.facts_match?(engine, @filter, card, nil))
+            end
+          end
+        end
+
+        def to_s
+          what = @log == "spells" ? "#{@filter || "spell"}s cast" : "lands played"
+          "the number of #{what}#{@zones} this turn by #{@by}"
+        end
+
+        private
+
+        # [card, zone] per spell or land; a spell cast before zones were recorded counts as cast from the hand.
+        def entries(log)
+          return Array(log["lands_played"]) unless @log == "spells"
+
+          zones = Array(log["spells_from"])
+          Array(log["spells"]).each_with_index.map { |card, i| [card, zones[i] || "hand"] }
+        end
+      end
+
+      # {"died_this_turn" | "entered_this_turn" | ...: {"each": filter, "controller": ...}}: permanents that
+      # died (CR 700.4), entered, left the battlefield (CR 400.7) or were sacrificed (CR 701.21a) this turn,
+      # creatures that attacked (CR 508.1) and cards put into exile, matched by their card and the card types
+      # (and subtypes, except for died and exiled ones) they had then. `controller`: whose they were (the
+      # attacking player; for a card exiled from another zone, its owner). Without `each`, every one counts.
+      class Departed
+        def self.build(kind, data, errors, path)
+          errors << "#{path}: must be an object {\"each\": filter, \"controller\": ...}" unless data.is_a?(Hash)
+          data = data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+          Mechanics.check_keys(data, %w[each controller], errors, path)
+          filter = data.key?("each") ? Mechanics.build_entry(:filter, data["each"], errors, "#{path}.each") : nil
+          controller = data.fetch("controller", "any")
+          errors << "#{path}.controller: must be one of you, opponent, any" unless %w[you opponent any].include?(controller)
+          new(DEPARTED.fetch(kind), filter, controller)
+        end
+
+        # Whether a card (with the card types it had, when given) matches a filter's characteristics.
+        def self.facts_match?(engine, filter, card, types, subtypes = nil)
+          defn = engine.catalog.fetch(card)
+          chars = defn.printed_characteristics
+          chars = chars.with(types: types.map(&:to_sym)) if types
+          chars = chars.with(subtypes: subtypes.map(&:to_sym)) if subtypes
+          filter.matches_facts?(Filters::Facts.new(chars: chars, counters: {}, token: defn.token?))
+        end
+
+        def initialize(key, filter, controller)
+          @key = key
+          @filter = filter
+          @controller = controller
+          freeze
+        end
+
+        def value(engine, ctx)
+          engine.state.players.each_index.sum do |index|
+            next 0 unless @controller == "any" || (@controller == "you") == (index == ctx.controller)
+
+            Array(engine.turn_log(index)[@key]).count do |card, types, subtypes|
+              @filter.nil? || Departed.facts_match?(engine, @filter, card, types, subtypes)
+            end
+          end
+        end
+
+        WORDS = { "died" => "that died", "entered" => "that entered", "left" => "that left the battlefield",
+                  "sacrificed" => "sacrificed", "attackers" => "that attacked", "exiled" => "put into exile" }.freeze
+
+        def to_s = "the number of #{Triggers.filter_words(@filter) || "object"}s #{WORDS.fetch(@key)} this turn"
+      end
+    end
+
+    # A yes/no test about the game, checked when an effect resolves (CR 608.2c) or, as an
+    # intervening "if" (CR 603.4), both when a trigger condition is met and on resolution:
+    #   {"amount": amount, "at_least": n, "at_most": n}   any Amount compared with bounds (each a number or an amount),
+    #                                    e.g. total power
+    #                                    of creatures you control N or more: {"amount": {"power": {"each":
+    #                                    "creature", "controller": "you"}}, "at_least": 8}; "if you do" after a
+    #                                    mandatory effect: {"amount": {"count": {"result": 0}}, "at_least": 1}
+    #   {"controls": selector, "at_least": 3} / {"life": "you", ...} / {"hand_size": "you", ...}  (short forms)
+    #   {"your_turn": true}
+    #   {"max_speed": true}        you have max speed: your speed is 4 (CR 702.179e)
+    #   {"was_cast": true}                          "if you cast it": the source permanent was cast (CR 400.7d)
+    #   {"cast_with": "warp"} / {"cast_from": "graveyard"}   how this spell (or the spell this permanent was) was
+    #                              cast; {"cast_with_this_turn": "warp"}: a spell was cast with it this turn
+    #   {"targets": filter}        one of the chosen targets matches (e.g. "if it targets a tapped creature")
+    #   {"attacked": true}         a creature is attacking you (CR 508.1b)
+    #   {"source": filter}         the source is on the battlefield and matches ("if this isn't a creature":
+    #                              {"not": {"source": "creature"}})
+    #   {"attacked_this_turn": true}  the source attacked this turn
+    #   {"you_attacked_this_turn": true}  you attacked with one or more creatures this turn (raid, CR 508.1)
+    #   {"nth_resolution": n}      this is the nth time this turn this ability resolves (CR 608.2)
+    #   {"share_card_type": selector | [selectors]}  the referenced objects share a card type ("exiled_with": linked cards)
+    #   {"chosen": word}           that word was chosen for this object (choose_option, CR 607.2f)
+    #   {"meld_with": name}        you both own and control the source and a creature named so (CR 713.1a)
+    #   {"not": condition}, {"all": [conditions]}, {"any": [conditions]}
+    class Condition
+      FLAGS = %w[your_turn was_cast attacked attacked_this_turn max_speed
+                 you_attacked_this_turn].freeze
+      # Kinds named by one key and built by their class (ChosenIs: abilities/chosen_values.rb; Designation:
+      # keywords/storied.rb).
+      KEYED = { "targets" => :Targets, "triggering" => :TriggeringIs, "source" => :Source,
+                "nth_resolution" => :NthResolution, "chosen" => :ChosenIs, "designation" => :Designation,
+                "first_combat_phase" => :FirstCombatPhase, "meld_with" => :MeldWith }.freeze # MeldWith: effects/meld.rb
+
+      def self.build(data, errors, path, targets_count: 0, results_count: 0)
+        unless data.is_a?(Hash)
+          errors << "#{path}: must be a condition object"
+          return nil
+        end
+        data = data.transform_keys(&:to_s)
+        context = { targets_count: targets_count, results_count: results_count }
+        if data.key?("not") then Not.new(build(data["not"], errors, "#{path}.not", **context))
+        elsif data.key?("all") || data.key?("any")
+          key = data.key?("all") ? "all" : "any"
+          parts = Array(data[key]).each_with_index.map { |c, i| build(c, errors, "#{path}.#{key}[#{i}]", **context) }
+          Many.new(key, parts.compact)
+        elsif data.key?("kicked") then WasKicked.new(data["kicked"] != false)
+        elsif data.key?("sacrificed") then Sacrificed.build(data, errors, path)
+        elsif (flag = FLAGS.find { data.key?(it) }) then Flag.new(flag, data[flag] != false)
+        elsif data.key?("began_extra_turn") then BeganExtraTurn.new(data["began_extra_turn"] != false) # CR 500.7
+        elsif data.key?("share_card_type") then ShareCardType.build(data, errors, path, targets_count) # linked.rb
+        elsif (key = KEYED.keys.find { data.key?(it) }) then const_get(KEYED[key]).build(data, errors, path)
+        else build_more(data, errors, path, context)
+        end
+      end
+
+      # How a spell was cast (CastHow, keywords/alternative_costs.rb), or a comparison.
+      def self.build_more(data, errors, path, context)
+        key = CastHow::KEYS.find { data.key?(it) }
+        key ? CastHow.build(key, data, errors, path) : Compare.build(data, errors, path, **context)
+      end
+
+      # An Amount compared with bounds: {"amount": amount, "at_least": n, "at_most": n}, or a short form
+      # {"controls"|"life"|"hand_size": selector, ...}.
+      class Compare
+        SUBJECTS = { "controls" => "count", "life" => "life", "hand_size" => "hand_size" }.freeze
+
+        def self.build(data, errors, path, targets_count:, results_count: 0)
+          subject = (data.keys & (SUBJECTS.keys + ["amount"])).first
+          unless subject
+            errors << "#{path}: unknown condition (use amount, controls, life, hand_size, your_turn, was_cast, targets, " \
+                      "attacked, source, attacked_this_turn, you_attacked_this_turn, nth_resolution, kicked, " \
+                      "sacrificed, cast_with, cast_from, cast_with_this_turn, chosen, max_speed, designation, not, all, any)"
+            return nil
+          end
+          Mechanics.check_keys(data, [subject, "at_least", "at_most"], errors, path)
+          raw = subject == "amount" ? data[subject] : { SUBJECTS[subject] => data[subject] }
+          amount = Amount.build(raw, errors, "#{path}.#{subject}", targets_count: targets_count, results_count: results_count)
+          bounds = %w[at_least at_most].to_h { [it, data[it]] }.compact
+          errors << "#{path}: needs at_least and/or at_most" if bounds.empty?
+          bounds = bounds.to_h do |k, v| # a bound may itself be an amount ("less than its mana value")
+            [k, Amount.build(v, errors, "#{path}.#{k}", targets_count: targets_count, results_count: results_count, min: -1000)]
+          end
+          new(amount, bounds["at_least"], bounds["at_most"])
+        end
+
+        attr_reader :amount
+
+        def initialize(amount, at_least, at_most)
+          @amount = amount
+          @at_least = at_least
+          @at_most = at_most
+          freeze
+        end
+
+        def true?(engine, ctx)
+          n = @amount.value(engine, ctx)
+          (@at_least.nil? || n >= @at_least.value(engine, ctx)) && (@at_most.nil? || n <= @at_most.value(engine, ctx))
+        end
+
+        def to_s = "#{@amount} is #{[@at_least && "at least #{@at_least}", @at_most && "at most #{@at_most}"].compact.join(" and ")}"
+      end
+
+      # A yes/no fact about the turn or the source.
+      class Flag
+        def initialize(flag, wanted)
+          @flag = flag
+          @wanted = wanted
+          freeze
+        end
+
+        def true?(engine, ctx) = holds?(engine, ctx) == @wanted
+
+        WORDS = { "your_turn" => ["it's your turn", "it's not your turn"], "was_cast" => ["it was cast", "it wasn't cast"],
+                  "attacked" => ["a creature is attacking you", "no creature is attacking you"],
+                  "attacked_this_turn" => ["it attacked this turn", "it didn't attack this turn"],
+                  "max_speed" => ["you have max speed", "you don't have max speed"],
+                  "you_attacked_this_turn" => ["you attacked this turn", "you didn't attack this turn"] }.freeze
+
+        def to_s = WORDS.fetch(@flag)[@wanted ? 0 : 1]
+
+        private
+
+        def holds?(engine, ctx)
+          case @flag
+          when "your_turn" then engine.state.active == ctx.controller
+          when "attacked" # a creature is attacking the controller, not a planeswalker they control (CR 508.1b)
+            you = Filters.player_ref(engine, ctx.controller)
+            engine.attackers.values.any? { it["target"] == you }
+          when "attacked_this_turn" then engine.attacked_this_turn?(ctx.source)
+          when "max_speed" then engine.max_speed?(ctx.controller) # CR 702.179e
+          when "you_attacked_this_turn" then !engine.turn_log(ctx.controller).fetch("attackers", []).empty?
+          else was_cast?(engine, ctx)
+          end
+        end
+
+        # "If you cast it": the source permanent entered as a resolving spell (CR 400.7d). Once the
+        # source has left, its triggered ability remembers it (last known information, CR 603.4 / 608.2h).
+        def was_cast?(engine, ctx)
+          source = engine.state.objects[ctx.source]
+          cast = source ? source.memory["cast"] : engine.state.objects[ctx.object]&.memory&.[]("source_cast")
+          cast == true
+        end
+      end
+
+      # One of the chosen targets matches a filter. Before targets are chosen (`ctx.targets` nil, as when
+      # checking whether a cost reduction could apply) it counts as met.
+      class Targets
+        def self.build(data, errors, path)
+          Mechanics.check_keys(data, %w[targets], errors, path)
+          new(Mechanics.build_entry(:filter, data["targets"], errors, "#{path}.targets"))
+        end
+
+        def initialize(filter)
+          @filter = filter
+          freeze
+        end
+
+        def true?(engine, ctx)
+          return true if ctx.targets.nil?
+
+          ctx.targets.flatten.compact.any? { @filter&.match?(engine, it, ctx.controller) }
+        end
+
+        def to_s = "it targets a #{@filter.respond_to?(:primitive_name) ? @filter.primitive_name : @filter}"
+      end
+
+      # The source is on the battlefield and matches a filter, by its current characteristics.
+      class Source
+        def self.build(data, errors, path)
+          Mechanics.check_keys(data, %w[source], errors, path)
+          new(Mechanics.build_entry(:filter, data["source"], errors, "#{path}.source"))
+        end
+
+        def initialize(filter)
+          @filter = filter
+          freeze
+        end
+
+        def true?(engine, ctx)
+          !@filter.nil? && engine.state.battlefield.include?(ctx.source) && @filter.match?(engine, ctx.source, ctx.controller)
+        end
+
+        def to_s = "it's a #{@filter}"
+      end
+
+      # The nth resolution of an ability this turn: the resolving ability (ctx.object)
+      # has finished resolving n - 1 times this turn (Engine::TurnHistory counts completed resolutions).
+      class NthResolution
+        def self.build(data, errors, path)
+          Mechanics.check_keys(data, %w[nth_resolution], errors, path)
+          n = data["nth_resolution"]
+          errors << "#{path}.nth_resolution: must be a positive integer" unless n.is_a?(Integer) && n.positive?
+          new(n)
+        end
+
+        def initialize(nth)
+          @nth = nth
+          freeze
+        end
+
+        def true?(engine, ctx)
+          obj = engine.state.objects[ctx.object]
+          !obj.nil? && obj.ability? && engine.times_resolved(obj.source, obj.ability) + 1 == @nth
+        end
+
+        def to_s = "this is resolution number #{@nth} of this ability this turn"
+      end
+
+      # "If this spell was kicked" (CR 702.33d): the resolving spell (or the spell a permanent was) paid
+      # its kicker cost. Recorded on the stack object as it became cast, and carried to the permanent it
+      # becomes (CR 400.7d) and to that permanent's triggered abilities. While a trigger is being checked
+      # (no ability object yet, CR 603.4) the source permanent answers.
+      class WasKicked
+        def initialize(wanted)
+          @wanted = wanted
+          freeze
+        end
+
+        def true?(engine, ctx)
+          holder = engine.state.objects[ctx.object || ctx.source]
+          (holder&.memory&.[]("kicked") == true) == @wanted
+        end
+
+        def to_s = @wanted ? "it was kicked" : "it wasn't kicked"
+      end
+
+      # "If you sacrificed a Klingon this way" (CR 608.2h): a permanent sacrificed to pay the resolving
+      # spell's or ability's cost had these subtypes / card types as it last existed.
+      #   {"sacrificed": {"subtypes": ["klingon"]}}   {"sacrificed": {"types": ["artifact"]}}
+      class Sacrificed
+        def self.build(data, errors, path)
+          Mechanics.check_keys(data, %w[sacrificed], errors, path)
+          spec = data["sacrificed"]
+          ok = spec.is_a?(Hash) && !spec.empty? && (spec.keys - %w[types subtypes]).empty? &&
+               spec.values.all? { it.is_a?(Array) && !it.empty? && it.all?(String) }
+          errors << "#{path}.sacrificed: must be {\"types\": [...]} and/or {\"subtypes\": [...]}" unless ok
+          new(ok ? spec : {})
+        end
+
+        def initialize(spec)
+          @spec = spec
+          freeze
+        end
+
+        def true?(engine, ctx)
+          paid = engine.state.objects[ctx.object]&.paid || []
+          paid.any? { |entry| entry["subtypes"] && @spec.all? { |key, wanted| entry[key].intersect?(wanted) } }
+        end
+
+        def to_s = "a sacrificed permanent was #{@spec.values.flatten.join(" or ")}"
+      end
+
+      # {"triggering": filter}: "if it's a Saga spell" — the card the trigger event was about matches a
+      # filter on its card's characteristics (types, subtypes, ...), wherever it is now.
+      class TriggeringIs
+        def self.build(data, errors, path)
+          Mechanics.check_keys(data, %w[triggering], errors, path)
+          new(Mechanics.build_entry(:filter, data["triggering"], errors, "#{path}.triggering"))
+        end
+
+        def initialize(filter)
+          @filter = filter
+          freeze
+        end
+
+        def true?(engine, ctx)
+          card = Selector.memory(engine, ctx).fetch("triggering", {})["card"]
+          return false unless card && @filter
+
+          defn = engine.catalog.fetch(card)
+          @filter.matches_facts?(Filters::Facts.new(chars: defn.printed_characteristics, counters: {}, token: defn.token?))
+        end
+
+        def to_s = "it's a #{@filter.respond_to?(:primitive_name) ? @filter.primitive_name.tr("_", " ") : @filter}"
+      end
+
+      # Negation.
+      class Not
+        def initialize(inner)
+          @inner = inner
+          freeze
+        end
+
+        def true?(engine, ctx) = !@inner&.true?(engine, ctx)
+        def to_s = "not (#{@inner})"
+      end
+
+      # all / any.
+      class Many
+        def initialize(mode, parts)
+          @mode = mode
+          @parts = parts
+          freeze
+        end
+
+        def true?(engine, ctx) = @mode == "all" ? @parts.all? { it.true?(engine, ctx) } : @parts.any? { it.true?(engine, ctx) }
+        def to_s = @parts.join(@mode == "all" ? " and " : " or ")
+      end
+    end
+  end
+end