enjine 0.1.0

data/lib/enjine/decisions/casting.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    CANCEL = { type: "cancel" }.freeze
+
+    # CR 734.1: a cast or activation can be rewound ("cancel") until something irreversible has been
+    # paid (Engine::Payment#cancellable?); a triggered ability being put on the stack never can.
+    def self.with_cancel(engine, options) = engine.cancellable? ? options + [CANCEL] : options
+
+    # CR 601.2b / 603.3c: choose a mode of a modal spell or ability, one per decision.
+    class ChooseMode < Base
+      def self.doc
+        'Choose a mode of a modal ("choose one") spell or ability: `{type: "mode", mode: index}` ' \
+          '(0-based, in printed order); `{type: "done"}` once enough are chosen when more are allowed; ' \
+          '`{type: "cancel"}` rewinds a cast. `choose` modes in total (at least `min`).'
+      end
+
+      def self.options(engine, _pending) = Decisions.with_cancel(engine, engine.mode_options)
+
+      def self.submit(engine, _pending, option)
+        case option[:type]
+        when "cancel" then engine.cancel_casting!
+        when "done" then engine.modes_done!
+        else engine.choose_mode!(option[:mode])
+        end
+      end
+    end
+    register("choose_mode", ChooseMode)
+
+    # CR 601.2b / 702.33a: announce whether an optional additional cost (kicker) will be paid.
+    class ChooseKicker < Base
+      def self.doc
+        'While casting a spell with kicker: `{type: "kick"}` pays the kicker cost too, `{type: "no_kick"}` ' \
+          "doesn't; `{type: \"cancel\"}` rewinds. `cost` describes the kicker cost."
+      end
+
+      def self.options(engine, _pending) = Decisions.with_cancel(engine, engine.kicker_options)
+
+      def self.submit(engine, _pending, option)
+        option[:type] == "cancel" ? engine.cancel_casting! : engine.announce_kicker!(option[:type] == "kick")
+      end
+    end
+    register("choose_kicker", ChooseKicker)
+
+    # CR 601.2b: announce which of two or more costs ("behold a Goblin or pay {2}") will be paid.
+    class ChooseCostOption < Base
+      def self.doc
+        'While casting/activating with a choice between costs (cost `one_of`): `{type: "cost_option", option: i}` ' \
+          "(0-based, in the order of `costs`) for one that could be paid; `{type: \"cancel\"}` rewinds."
+      end
+
+      def self.options(engine, _pending) = Decisions.with_cancel(engine, engine.cost_option_options)
+
+      def self.submit(engine, _pending, option)
+        option[:type] == "cancel" ? engine.cancel_casting! : engine.choose_cost_option!(option[:option])
+      end
+    end
+    register("choose_cost_option", ChooseCostOption)
+
+    # CR 601.2b / 107.3a: announce the value of X for a cost with {X}.
+    class ChooseX < Base
+      def self.doc
+        'While casting/activating a spell or ability with {X} in its cost: `{type: "x", value: n}` ' \
+          'announces X (0 up to `max`, the most the available mana could pay for); `{type: "cancel"}` rewinds.'
+      end
+
+      def self.options(engine, pending) = Decisions.with_cancel(engine, (0..pending["max"]).map { { type: "x", value: it } })
+
+      def self.submit(engine, _pending, option)
+        option[:type] == "cancel" ? engine.cancel_casting! : engine.announce_x!(option[:value])
+      end
+    end
+    register("choose_x", ChooseX)
+
+    # CR 601.2c: a variable number of targets ("X target", "any number of target", "up to N") is announced
+    # before the targets are chosen.
+    class ChooseTargetCount < Base
+      def self.doc
+        'While casting/activating: `{type: "count", count: n}` announces how many targets (from `min` to ' \
+          '`max`, at most as many as there are legal ones) target ##`index` + 1 will have; `{type: "cancel"}` rewinds.'
+      end
+
+      def self.options(engine, _pending) = Decisions.with_cancel(engine, engine.target_count_options)
+
+      def self.submit(engine, _pending, option)
+        option[:type] == "cancel" ? engine.cancel_casting! : engine.choose_target_count!(option[:count])
+      end
+    end
+    register("choose_target_count", ChooseTargetCount)
+
+    # CR 601.2c: choose the next target of the spell or ability being cast.
+    class ChooseTarget < Base
+      def self.doc
+        'While casting/activating: `{type: "target", target: ref}` for the next target (ref is an ' \
+          'object id or "player:<name>"); `{type: "done"}` chooses no more for an "up to" target; ' \
+          '`{type: "cancel"}` rewinds the whole cast.'
+      end
+
+      def self.options(engine, _pending) = Decisions.with_cancel(engine, engine.target_options)
+
+      def self.submit(engine, _pending, option)
+        case option[:type]
+        when "cancel" then engine.cancel_casting!
+        when "done" then engine.choose_target!(nil)
+        else engine.choose_target!(option[:target])
+        end
+      end
+    end
+    register("choose_target", ChooseTarget)
+
+    # CR 601.2d: divide an amount (counters, damage) among the chosen targets, one unit at a time
+    # beyond the one each target must get.
+    class Distribute < Base
+      def self.doc
+        'While casting: `{type: "assign", target: ref}` gives one more of the divided amount to that target ' \
+          '(each target already has one); `{type: "cancel"}` rewinds. `left` is what remains to divide.'
+      end
+
+      def self.options(engine, _pending) = Decisions.with_cancel(engine, engine.distribute_options)
+
+      def self.submit(engine, _pending, option)
+        option[:type] == "cancel" ? engine.cancel_casting! : engine.distribute!(option[:target])
+      end
+    end
+    register("distribute", Distribute)
+
+    # CR 601.2h / 602.2b: a cost that needs a choice, e.g. which other creature to tap (CR 702.184a)
+    # or which creature to sacrifice. Tapping happens at once; other choices are paid as it becomes
+    # cast. Cancelling rewinds it.
+    class ChooseCost < Base
+      def self.doc
+        'While casting/activating: `{type: "cost", object: id}` picks the permanent (or card) a cost uses ' \
+          '(the creature to tap for station, the creature to sacrifice, the creature beamed up, ...); `{type: "done"}` ' \
+          "stops choosing for a cost of any number of permanents once enough are chosen (crew: total power N or " \
+          'more); `{type: "cancel"}` rewinds. `cost` describes the cost.'
+      end
+
+      def self.options(engine, _pending)
+        options = engine.cost_choice_candidates.map { { type: "cost", **it } }
+        options << { type: "done" } if engine.cost_choice_finishable?
+        Decisions.with_cancel(engine, options)
+      end
+
+      def self.submit(engine, _pending, option)
+        case option[:type]
+        when "cancel" then engine.cancel_casting!
+        when "done" then engine.finish_cost_choice!
+        else engine.choose_cost!(option)
+        end
+      end
+    end
+    register("choose_cost", ChooseCost)
+
+    # CR 601.2g-h: pay the mana cost one mana at a time. Mana abilities may be activated
+    # now; mana in the pool is spent one symbol per decision. Also used for a cost paid while a
+    # spell or ability resolves (CR 118.12), where "cancel" declines to pay.
+    class PayCost < Base
+      def self.doc
+        'While casting/activating or paying a cost: `{type: "pay_mana", mana: "R"}` spends one mana from ' \
+          "the pool (`restricted: i`: restricted mana, CR 106.6; `from: i`: the pool mana an artifact made that " \
+          'pool_sources[i] names), `{type: "activate_mana", object: id, ability: ref}` ' \
+          '(plus `mana: "{G}{G}"` when the mana is chosen) taps a source, `{type: "cancel"}` ' \
+          "rewinds (or declines a payment asked for while resolving). Cancel isn't offered once a mana ability " \
+          "with a cost other than {T} (a Treasure) has been activated. `{type: \"convoke\", object: id}` taps a " \
+          "creature to pay for {1} or one mana of its color (a spell with convoke); `{type: \"improvise\", object: id}` " \
+          "taps an artifact to pay for {1} (a spell with improvise); `{type: \"waterbend\", object: id}` taps " \
+          "an artifact or creature to pay {1} of a waterbend cost. `remaining` shows what is left to pay."
+      end
+
+      def self.options(engine, _pending)
+        Decisions.with_cancel(engine, engine.payable_mana_options + engine.payment_mana_options + engine.convoke_options +
+                                       engine.waterbend_options)
+      end
+
+      def self.submit(engine, _pending, option)
+        case option[:type]
+        when "cancel" then engine.cancel_payment!
+        when "pay_mana" then engine.pay_mana!(option[:mana], option[:restricted], option[:from])
+        when "convoke", "improvise" then engine.convoke!(option[:object], option[:type]) # CR 702.51a, 702.126a
+        when "waterbend" then engine.waterbend!(option[:object]) # CR 701.67a
+        else engine.tap_for_payment!(option[:object], option[:ability], option[:mana])
+        end
+      end
+    end
+    register("pay_cost", PayCost)
+  end
+end

data/lib/enjine/decisions/combat.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    DONE = { type: "done" }.freeze
+
+    # CR 508.1: the active player declares attackers one at a time, then `done`.
+    class DeclareAttackers < Base
+      def self.doc
+        'Declare one attacker: `{type: "attack", object: id, target: ref}` (the defending player ' \
+          'or one of their planeswalkers), or `{type: "done"}` (withheld while a creature that attacks ' \
+          "each combat if able could still attack, CR 508.1d, or while a creature that can't attack alone " \
+          'attacks alone, CR 506.5; then `{type: "withdraw", object: id}` undoes an attack).'
+      end
+
+      def self.options(engine, _pending)
+        targets = engine.attack_targets
+        legal = engine.attack_declaration_legal?
+        done = engine.unmet_attack_requirements.empty? && legal ? [DONE] : [] # CR 508.1c-d
+        withdraw = legal ? [] : engine.attackers.keys.map { { type: "withdraw", object: it } }
+        done + engine.attack_candidates.flat_map { |id| targets.map { { type: "attack", object: id, target: it } } } + withdraw
+      end
+
+      def self.submit(engine, _pending, option)
+        case option[:type]
+        when "done" then engine.finish_attackers!
+        when "withdraw" then engine.withdraw_attacker!(option[:object])
+        else engine.declare_attacker!(option[:object], option[:target])
+        end
+      end
+    end
+    register("declare_attackers", DeclareAttackers)
+
+    # CR 509.1: the defending player declares blockers one at a time, then `done`.
+    class DeclareBlockers < Base
+      def self.doc
+        'Declare one blocker: `{type: "block", object: id, attacker: id}`, `{type: "done"}` (only when the ' \
+          'blocks are legal), or `{type: "unblock", object: id}` to fix an illegal menace block or free a ' \
+          "creature for an attacker that must be blocked if able (CR 509.1c)."
+      end
+
+      # "done" is offered only when the blocks are legal (menace, requirements); otherwise blocks can be removed.
+      def self.options(engine, _pending)
+        blocks = engine.block_options.map { |id, attacker| { type: "block", object: id, attacker: attacker } }
+        unblock = engine.menace_violations.flat_map { engine.blockers_of(it) } + engine.requirement_unblocks
+        removals = unblock.uniq.map { { type: "unblock", object: it } }
+        (engine.blocks_legal? ? [DONE] : []) + blocks + removals
+      end
+
+      def self.submit(engine, _pending, option)
+        case option[:type]
+        when "done" then engine.finish_blockers!
+        when "unblock" then engine.remove_blocker!(option[:object])
+        else engine.declare_blocker!(option[:object], option[:attacker])
+        end
+      end
+    end
+    register("declare_blockers", DeclareBlockers)
+
+    # CR 510.1c: assign one point of a multiply-blocked attacker's damage to one of its blockers.
+    class AssignDamage < Base
+      def self.doc
+        'Assign one point of combat damage of `attacker`: `{type: "assign", object: blocker_id}`. ' \
+          "`remaining` points are left."
+      end
+
+      def self.options(engine, pending)
+        engine.assignment_targets(pending["attacker"]).map { { type: "assign", object: it } }
+      end
+
+      def self.submit(engine, pending, option) = engine.assign_damage!(pending["attacker"], option[:object])
+    end
+    register("assign_damage", AssignDamage)
+  end
+end

data/lib/enjine/decisions/discard.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # CR 514.1: during cleanup the active player discards down to maximum hand size,
+    # one card per decision.
+    class Discard < Base
+      def self.doc
+        'Cleanup step: discard one card, `{type: "discard", object: id}`, until the hand ' \
+          "has 7 cards. `count` is how many remain (CR 514.1)."
+      end
+
+      def self.options(engine, pending)
+        engine.player(pending["player"]).hand.map { |id| { type: "discard", object: id } }
+      end
+
+      def self.submit(engine, pending, option)
+        engine.move!(option[:object], :graveyard, reason: "discard")
+        remaining = pending["count"] - 1
+        if remaining.positive?
+          engine.ask!(pending.merge("count" => remaining))
+        else
+          engine.turn_based_actions_done!
+        end
+      end
+    end
+    register("discard", Discard)
+  end
+end

data/lib/enjine/decisions/effect_choice.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # A choice an effect asks for while it resolves (scry, surveil, discard, ...). The pending
+    # decision carries a human-readable `prompt` and the exact `choices`.
+    class EffectChoice < Base
+      def self.doc
+        "A choice made while an effect resolves (scry, surveil, discard...): submit one of the " \
+          "`choices` exactly as listed; `prompt` describes it."
+      end
+
+      def self.options(_engine, pending) = pending["choices"].map { it.transform_keys(&:to_sym) }
+      def self.submit(engine, _pending, option) = engine.effect_answer!(option)
+
+      # Which library card went where is hidden from other players; discards are public anyway.
+      def self.redact(option, viewer_is_decider) = viewer_is_decider ? option : option.except(:object)
+    end
+    register("effect_choice", EffectChoice)
+  end
+end

data/lib/enjine/decisions/enter_choice.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # An "as this enters" choice (CR 614.12), e.g. pay life or enter tapped, a number or a card name.
+    class EnterChoice < Base
+      def self.doc
+        'Before `object` enters: `{type: "pay_life", life: n}` (only with enough life) or ' \
+          '`{type: "enter_tapped"}` (CR 614.12, 119.4), or `{type: "behold", object: id}` (CR 701.4a); ' \
+          '`{type: "number", number: n}` for "choose a number"; ' \
+          '`{type: "name", name: "..."}` for "choose a card name" (CR 201.4); `{type: "color", color: "R"}`, ' \
+          '`{type: "creature_type", creature_type: "elf"}`, `{type: "card_type", card_type: "artifact"}`, ' \
+          '`{type: "basic_land_type", basic_land_type: "forest"}` or ' \
+          '`{type: "option", option: "word"}` for the other "choose a ..." abilities (CR 607.2d); devour picks permanents ' \
+          'to sacrifice one at a time, `{type: "devour", object: id}` (`chosen` lists them), then `{type: "done"}` ' \
+          "(CR 702.82a). With `effect: true` the permanent " \
+          "is being put onto the battlefield by a resolving effect (a token about to be created has `card`); " \
+          "with several entering at once, each is asked in turn before any enters (CR 614.12a-b)."
+      end
+
+      def self.options(engine, pending) = engine.entering_options(pending)
+      def self.submit(engine, _pending, option) = engine.enter_choice!(option)
+    end
+    register("enter_choice", EnterChoice)
+  end
+end

data/lib/enjine/decisions/legend_rule.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # CR 704.5j: choose which of your same-named legendary permanents to keep.
+    class LegendRule < Base
+      def self.doc
+        'Keep one of your legendary permanents named `name`: `{type: "keep", object: id}`; the others go ' \
+          "to the graveyard (CR 704.5j)."
+      end
+
+      def self.options(engine, _pending)
+        frame = engine.state.frames.rfind { it["type"] == "legend_rule" }
+        engine.legend_candidates(frame).map { { type: "keep", object: it } }
+      end
+
+      def self.submit(engine, _pending, option) = engine.keep_legend!(option[:object])
+    end
+    register("legend_rule", LegendRule)
+  end
+end

data/lib/enjine/decisions/mulligan.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # CR 103.5: keep the opening hand or take a (London) mulligan.
+    class Mulligan < Base
+      def self.doc
+        'Keep the hand (`{type: "keep"}`) or take a London mulligan (`{type: ' \
+          '"mulligan"}`). Players declare in turn order; mulligans then happen ' \
+          "simultaneously (CR 103.5)."
+      end
+
+      KEEP = { type: "keep" }.freeze
+      MULLIGAN = { type: "mulligan" }.freeze
+
+      def self.options(engine, pending)
+        engine.player(pending["player"]).mulligans < Engine::MAX_MULLIGANS ? [KEEP, MULLIGAN] : [KEEP]
+      end
+
+      def self.submit(engine, pending, option)
+        engine.declare_mulligan!(pending["player"], option[:type])
+      end
+    end
+    register("mulligan", Mulligan)
+  end
+end

data/lib/enjine/decisions/order_triggers.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # CR 603.3b: a player with several triggered abilities to put on the stack chooses the
+    # order, one per decision: the chosen trigger goes on the stack next (so it resolves later).
+    class OrderTriggers < Base
+      def self.doc
+        'Put one of your pending triggered abilities on the stack next: `{type: "trigger", trigger: id}` ' \
+          "(CR 603.3b). The last one put on the stack resolves first."
+      end
+
+      def self.options(engine, pending)
+        engine.pending_triggers_for(pending["player"]).map { { type: "trigger", trigger: it["id"] } }
+      end
+
+      def self.submit(engine, _pending, option) = engine.choose_trigger!(option[:trigger])
+    end
+    register("order_triggers", OrderTriggers)
+  end
+end

data/lib/enjine/decisions/play_or_draw.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # CR 103.1: the winner of the die roll chooses to play first or draw first.
+    class PlayOrDraw < Base
+      def self.doc = 'The die-roll winner chooses `{type: "play"}` or `{type: "draw"}` (CR 103.1).'
+
+      OPTIONS = [{ type: "play" }.freeze, { type: "draw" }.freeze].freeze
+
+      def self.options(_engine, _pending) = OPTIONS
+
+      def self.submit(engine, pending, option)
+        engine.choose_starting_player!(pending["player"], option[:type] == "play")
+      end
+    end
+    register("play_or_draw", PlayOrDraw)
+  end
+end

data/lib/enjine/decisions/priority.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # CR 117: the player with priority may take any legal action or pass.
+    # Options are the union of every registered priority action (Enjine::Actions).
+    class Priority < Base
+      def self.doc
+        "The player holding priority takes an action or passes. Options come from the priority actions below (CR 117)."
+      end
+
+      def self.options(engine, pending)
+        Actions::PRIORITY.flat_map { |action| action.options(engine, pending["player"]) }
+      end
+
+      def self.submit(engine, pending, option)
+        Actions.fetch(option[:type]).perform(engine, pending["player"], option)
+      end
+    end
+    register("priority", Priority)
+  end
+end

data/lib/enjine/decisions/untap_choice.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # CR 502.3: in their untap step, the active player decides whether a permanent they "may choose not
+    # to untap" untaps. One decision per such tapped permanent (Engine::TurnStructure).
+    class UntapChoice < Base
+      def self.doc
+        'Untap step: `{type: "untap", object: id}` or `{type: "keep_tapped", object: id}` for a permanent you may ' \
+          "choose not to untap (CR 502.3)."
+      end
+
+      def self.options(_engine, pending)
+        [{ type: "untap", object: pending["object"] }, { type: "keep_tapped", object: pending["object"] }]
+      end
+
+      def self.submit(engine, _pending, option) = engine.choose_untap!(option[:object], option[:type] == "untap")
+    end
+    register("untap_choice", UntapChoice)
+  end
+
+  module Frames
+    # The active player's untap-step choices, then the untap itself (CR 502.3).
+    class UntapChoice < Base
+      def self.step(engine, frame) = engine.step_untap_choice!(frame)
+      def self.decisions = %w[untap_choice]
+
+      def self.validate(frame, data, errors)
+        ids = Array(frame["pending"]) + Array(frame["keep"])
+        errors << "frames: untap_choice permanents must be on the battlefield" unless ids.all? { data["battlefield"].include?(it) }
+      end
+    end
+    register("untap_choice", UntapChoice)
+  end
+end

data/lib/enjine/decisions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Enjine
+  # Every kind of pending decision. A decision kind is a class with:
+  #   .options(engine, pending) -> Array of option Hashes (symbol keys, JSON-safe values)
+  #   .submit(engine, pending, option)
+  #   .redact(option, viewer_is_decider) -> what another viewer may see of the chosen option
+  module Decisions
+    KINDS = {} # rubocop:disable Style/MutableConstant -- extension registry
+
+    def self.register(kind, klass)
+      KINDS[kind] = klass
+    end
+
+    def self.fetch(kind) = KINDS.fetch(kind) { raise ArgumentError, "unknown decision kind #{kind.inspect}" }
+
+    # Base class: options are public unless a subclass says otherwise.
+    class Base
+      def self.redact(option, _viewer_is_decider) = option
+    end
+  end
+end

data/lib/enjine/deck.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Enjine
+  # A player's deck: the card definitions it uses plus the main decklist, and optionally the cards the
+  # player owns outside the game.
+  #
+  #   Deck.from_h({"cards" => [{...Forest...}], "main" => [{"card" => "Forest", "count" => 60}],
+  #                "outside" => [{"card" => "Forest", "count" => 2}]})
+  #
+  # Constructed rules (CR 100.2a): at least 60 cards, at most 4 copies of any card
+  # that is not exempt (basic lands). An invalid deck can still be built and edited;
+  # it is simply not #valid?, so its player is not ready.
+  #
+  # Outside the game (CR 400.11, 400.11a): the engine doesn't track a match, so a deck carries the cards
+  # its player owns outside the game as `outside`: a constructed sideboard of at most 15 cards (CR 100.4a).
+  # The four-copy limit applies to the deck and the outside list together, and outside cards don't count
+  # toward the 60. Effects that bring a card into the game from outside it take the card from this list.
+  class Deck
+    MIN_SIZE = 60
+    MAX_COPIES = 4
+    MAX_OUTSIDE = 15
+
+    attr_reader :catalog
+    attr_writer :guard
+
+    def self.from_h(hash)
+      return hash if hash.is_a?(Deck)
+      raise InvalidDeck.new(["deck must be an object"]) unless hash.is_a?(Hash)
+
+      doc = hash.transform_keys(&:to_s).except("name", "description")
+      lists = %w[cards main outside].to_h { [it, doc.fetch(it, [])] }
+      lists.each { |key, list| raise InvalidDeck.new(["#{key}: must be a list"]) unless list.is_a?(Array) }
+
+      new(cards: lists["cards"], main: lists["main"], outside: lists["outside"])
+    end
+
+    def initialize(cards: [], main: [], outside: [])
+      @catalog = Catalog.new
+      cards.each { @catalog.add(it) }
+      @entries = {}
+      @outside = {}
+      @reference_errors = []
+      main.each_with_index { |entry, i| load_entry(entry, i, @entries, "main") }
+      outside.each_with_index { |entry, i| load_entry(entry, i, @outside, "outside") }
+    end
+
+    # Ordered {id => count}.
+    def entries = @entries.dup.freeze
+    def size = @entries.values.sum
+    def count(card) = @entries.fetch(CardDefinition.slug(card), 0)
+
+    # Flat list of definition ids, one per physical card.
+    def card_ids = @entries.flat_map { |id, n| [id] * n }
+
+    # The cards outside the game: ordered {id => count}, their number, and one definition id per card.
+    def outside_entries = @outside.dup.freeze
+    def outside_size = @outside.values.sum
+    def outside_ids = @outside.flat_map { |id, n| [id] * n }
+
+    def errors
+      errs = @reference_errors.dup
+      errs << "deck has #{size} cards; at least #{MIN_SIZE} are required (CR 100.2a)" if size < MIN_SIZE
+      errs << "outside: #{outside_size} cards; at most #{MAX_OUTSIDE} are allowed (CR 100.4a)" if outside_size > MAX_OUTSIDE
+      @entries.merge(@outside) { |_, a, b| a + b }.each do |id, n|
+        limit = @catalog.fetch(id).deck_limit # nil: any number (basic lands, "deck_limit": "any")
+        next if limit.nil? || n <= limit
+
+        errs << "#{@catalog.fetch(id).name}: #{n} copies; at most #{limit} are allowed (CR 100.2a#{", 100.4a" if @outside.key?(id)})"
+      end
+      errs
+    end
+
+    def valid? = errors.empty?
+
+    # Adds a card definition this deck can then use.
+    def define(definition)
+      check_guard!
+      @catalog.add(definition)
+    end
+
+    def add(card, count: 1)
+      check_guard!
+      id = resolve!(card)
+      @entries[id] = @entries.fetch(id, 0) + positive!(count)
+      self
+    end
+
+    # Adds cards the player owns outside the game (CR 400.11a).
+    def add_outside(card, count: 1)
+      check_guard!
+      id = resolve!(card)
+      @outside[id] = @outside.fetch(id, 0) + positive!(count)
+      self
+    end
+
+    def remove(card, count: 1)
+      check_guard!
+      id = resolve!(card)
+      have = @entries.fetch(id, 0)
+      raise InvalidDeck.new(["cannot remove #{count} #{card}: deck has #{have}"]) if have < positive!(count)
+
+      have == count ? @entries.delete(id) : @entries[id] = have - count
+      self
+    end
+
+    # Swaps cards between games; no limit on how many.
+    def swap(out:, in:, count: 1)
+      incoming = binding.local_variable_get(:in)
+      check_guard!
+      resolve!(incoming)
+      remove(out, count: count)
+      add(incoming, count: count)
+    end
+
+    def to_h
+      # Tokens aren't listed: the cards that create them bring them back (two tokens may share a name).
+      doc = { "cards" => @catalog.reject(&:token?).map(&:to_h), "main" => @entries.map { |id, n| { "card" => id, "count" => n } } }
+      doc["outside"] = @outside.map { |id, n| { "card" => id, "count" => n } } unless @outside.empty?
+      doc
+    end
+
+    private
+
+    def load_entry(entry, index, into, list)
+      card, count = entry.is_a?(Hash) ? entry.transform_keys(&:to_s).values_at("card", "count") : []
+      unless card.is_a?(String) && count.is_a?(Integer) && count.positive?
+        return @reference_errors << "#{list}[#{index}]: must be {\"card\": name, \"count\": positive integer}"
+      end
+      return @reference_errors << "#{list}[#{index}].card: #{card.inspect} is not defined in cards" unless @catalog.include?(card)
+
+      id = CardDefinition.slug(card)
+      into[id] = into.fetch(id, 0) + count
+    end
+
+    def resolve!(card)
+      raise InvalidDeck.new(["card #{card.inspect} is not defined in this deck"]) unless @catalog.include?(card)
+
+      CardDefinition.slug(card)
+    end
+
+    def positive!(count)
+      raise ArgumentError, "count must be a positive integer" unless count.is_a?(Integer) && count.positive?
+
+      count
+    end
+
+    def check_guard!
+      @guard&.call
+    end
+  end
+end