enjine 0.1.0

data/lib/enjine/engine/zones.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Objects and zones (CR 400): creating objects, moving them between zones through replacement
+    # effects (CR 614), tokens, drawing, shuffling and tapping; looking at and revealing cards
+    # (CR 701.20), putting cards on the bottom of a library (CR 401.4), cards "exiled with" a source
+    # (linked abilities, CR 607.2a, 406.6) and "until" exiles (CR 610.3).
+    module Zones
+      # Zone changes inside the block aren't results of the running effect (CR 400.7j names only
+      # what the effect's instruction moved, e.g. not "the rest" put into a graveyard).
+      def unrecorded
+        saved = @recorded
+        @recorded = nil
+        yield
+      ensure
+        @recorded = saved
+      end
+
+      # CR 701.20a: every player sees the card; it stays where it is (701.20b).
+      def reveal!(index, ids)
+        ids.each { emit Events::CardRevealed.new(player: name(index), object: it, card: object(it).card) }
+      end
+
+      # CR 701.20e: only the looking player (and the cards' owner) learn which cards they are.
+      def look_at!(index, owner, ids)
+        return if ids.empty?
+
+        emit Events::LookedAt.new(player: name(index), owner: name(owner), objects: ids.dup,
+                                  cards: ids.map { object(it).card })
+      end
+
+      # Puts library cards (already in `index`'s library) on its bottom, the first id highest (CR 401.4).
+      # `random`: the order is randomized with the game's RNG, so replays stay deterministic.
+      def put_on_bottom!(index, ids, random: false)
+        return if ids.empty?
+
+        ids = ids.dup
+        state.rng.shuffle!(ids) if random
+        library = player(index).library
+        library.replace((library - ids) + ids)
+        emit Events::LibraryReordered.new(player: name(index), top: 0, bottom: ids.size)
+      end
+
+      # CR 607.2a: cards an ability of `source` exiled, for its linked abilities ("exiled with it").
+      def link_exiled!(source, id)
+        obj = state.objects[source] or return
+        (obj.memory[Mechanics::Linked::EXILED] ||= []) << id
+      end
+
+      # CR 610.3, 610.3c: once the source of an "exile ... until this leaves the battlefield" effect has
+      # left, the cards it exiled return to the battlefield under their owners' control. A token that left
+      # can't come back (CR 111.8).
+      def return_exiled_until_leaves!(old)
+        ids = old.memory[Mechanics::Linked::UNTIL_LEAVES] or return
+        unrecorded do
+          ids.each do |id|
+            card = state.objects[id]
+            next unless card && card.zone == :exile && !token?(card)
+
+            move!(id, :battlefield, reason: "return")
+          end
+        end
+      end
+
+      # ---- objects & zones (CR 400) ------------------------------------------
+
+      # A card exiled face down gets an id that doesn't name it (CR 406.3); a card's id names its front face.
+      def create_object(card, owner, zone, hidden: false)
+        id = "#{hidden ? FACE_DOWN_ID : card.split(CardDefinition::FACE_SEPARATOR).first}##{state.next_id}"
+        state.next_id += 1
+        state.objects[id] = GameObject.new(id: id, card: card, owner: owner, controller: owner, zone: zone,
+                                           tapped: false, controlled_since: nil, kind: "card", counters: {},
+                                           damage: 0, source: nil, ability: nil, targets: nil, loyalty_turn: nil,
+                                           deathtouched: false, modes: nil, memory: {}, attached_to: nil)
+      end
+
+      # Moves an object to a zone as a new object (CR 400.7). Returns the new object.
+      # Proposes a state change, lets replacement effects modify it (CR 614), and returns
+      # the final proposal for the caller to execute.
+      # `applied`: replacement effects that already modified the event this one replaces (CR 614.5).
+      def propose(kind, data, applied = []) = Replacements.apply(self, Proposal.new(kind, data, applied.dup))
+
+      # `face_down`: exile it face down (CR 406.3); the list of player indices who may look at it.
+      def move!(id, to, reason:, position: :top, controller: nil, enters: nil, face_down: nil)
+        data = plan_move(id, to, reason: reason, position: position, controller: controller, enters: enters,
+                                 face_down: face_down)
+        data && execute_zone_change!(data)
+      end
+
+      # The zone change `move!` would make, after replacement effects (CR 614), not yet executed; nil if a
+      # replacement cancelled it. Planning several before executing any lets them happen at once (CR 614.12).
+      def plan_move(id, to, reason:, position: :top, controller: nil, enters: nil, face_down: nil)
+        data = { "object" => id, "to" => to, "position" => position, "reason" => reason, "controller" => controller }
+        data["face_down"] = face_down if face_down && to == :exile
+        data["enters"] = { "tapped" => enters&.fetch("tapped", false) == true, "counters" => {} } if to == :battlefield
+        data["enters"]["face"] = enters["face"] if data["enters"] && enters&.key?("face") # seen by its own replacements
+        data = propose("zone_change", data).data
+        return nil if data["cancelled"] # e.g. a shield counter instead of being destroyed (CR 122.1c)
+
+        merge_enters!(data["enters"], enters.except("tapped")) if enters && data["enters"] # tapped: replaceable (614.12)
+        data
+      end
+
+      # Takes the object out of its zone; returns its last known information if it was a permanent.
+      def depart!(old)
+        lki = old.zone == :battlefield ? last_known_info(old) : nil # before it leaves (CR 603.10a)
+        remember_last_known!(old.id, lki) if lki # CR 608.2h (see Engine::TurnHistory)
+        remember_spell!(old) if old.zone == :stack && !old.ability? # a countered spell's mana spent (Engine::TurnHistory)
+        state.zone_list(old.zone, old.owner).delete(old.id)
+        state.objects.delete(old.id)
+        lki
+      end
+
+      def execute_zone_change!(data)
+        id = data["object"]
+        to = data["to"]
+        old = object(id)
+        lki = depart!(old)
+        face_down = to == :exile ? data["face_down"] : nil
+        fresh = create_object(card_after_move(old, to), old.owner, to, hidden: !face_down.nil?) # front face up (Engine::Faces)
+        carry_copy_status!(fresh, old, to) # a token or copy stays one (Engine::Copies)
+        if old.zone == :battlefield
+          leave_combat!(id)
+          end_while_source_effects!(id) # CR 611.2b
+        end
+        arrive!(fresh, old, data)
+        fresh.memory.merge!("face_down" => true, "may_look" => face_down.uniq.sort) if face_down
+        list = state.zone_list(to, old.owner)
+        data["position"] == :bottom ? list.push(fresh.id) : list.unshift(fresh.id)
+        record_result!(fresh.id)
+        event = Events::ZoneChanged.new(card: old.card, old_id: id, new_id: fresh.id, owner: name(old.owner),
+                                        from: old.zone.to_s, to: to.to_s, reason: data["reason"],
+                                        lookers: face_down&.map { name(it) })
+        lki ? with_last_known(id, lki) { emit event } : emit(event)
+        return_exiled_until_leaves!(old) if lki # CR 610.3
+        unmeld!(old, to, data) if old.memory["melded"] # CR 713.8 (Engine::Faces)
+        prepare!(fresh) if to == :battlefield && data["enters"]["prepared"] # "enters prepared" (CR 723.3a)
+        run_follow_ups!(data, "object" => fresh.id) # "exile it instead. When you do, ..." (Engine::FollowUps)
+        fresh
+      end
+
+      # Status of the new object in its new zone (CR 110.2, 614.12 entering status).
+      def arrive!(fresh, old, data)
+        case data["to"]
+        when :battlefield
+          fresh.controller = data["controller"] || old.owner
+          fresh.controlled_since = state.turn
+          fresh.memory["entered"] = state.turn # "if it entered this turn" (power-up, CR 702.193a)
+          fresh.memory["cast"] = true if data["enters"]["cast"] # CR 400.7d: it remembers it was cast
+          fresh.memory.merge!(data["enters"]["memory"]) if data["enters"]["memory"] # CR 614.12: an "as this enters" choice
+          enter_face!(fresh, data["enters"]["face"]) if data["enters"]["face"] # CR 712.9, 712.11a (Engine::Faces)
+          enter_as_copy!(fresh, data["enters"]["copy"]) if data["enters"]["copy"] # CR 707.5 (Engine::Copies)
+          fresh.tapped = data["enters"]["tapped"]
+          fresh.counters.merge!(data["enters"]["counters"])
+          carry_from_stack!(fresh, old) if old.zone == :stack
+          fresh.attached_to = data["enters"]["attached_to"] # CR 608.3c: an Aura enters attached
+          enter_attacking!(fresh, data["enters"]["attacking"]) if data["enters"]["attacking"] # CR 508.4, 506.3a
+        when :stack
+          fresh.controller = data["controller"] || old.owner
+        end
+      end
+
+      # A permanent spell becoming a permanent remembers how it was cast (CR 400.7d): its X (its ETB abilities
+      # use the spell's X, CR 107.3m), that it was kicked (CR 702.33d) and the mana spent to cast it (CR 601.2h).
+      def carry_from_stack!(fresh, old)
+        fresh.x = old.x
+        fresh.memory.merge!(old.memory.slice("kicked", "kicked_with", "gift")) # gift: CR 702.174b
+        fresh.mana_spent = old.mana_spent&.dup
+      end
+
+      # CR 111.1: a token enters the battlefield under its creator's control. Entering replacement
+      # effects apply to it like to any permanent (CR 614.1c, 614.12).
+      # `memory`: a token that's a copy (Engine::Copies#create_token_copy!).
+      # A replacement may create several instead ("twice that many", CR 614.1a): the extra ones are part of the
+      # replaced event (`replaced`), so the replacement effects don't apply to them again (CR 614.5).
+      def create_token!(definition, controller, tapped: false, memory: nil, enters: nil, replaced: false)
+        definition = replace_token_creation!(definition, controller, tapped:, memory:, enters:) unless replaced
+        obj = create_object(definition.id, controller, :battlefield)
+        obj.memory.merge!(memory) if memory
+        entering = enters # an "as this enters" choice made before it's created (CR 614.12a)
+        tapped ||= entering&.dig("tapped") == true
+        enters = propose("zone_change", { "object" => obj.id, "to" => :battlefield, "controller" => controller,
+                                          "reason" => "create_token",
+                                          "enters" => { "tapped" => tapped, "counters" => {} } }).data["enters"]
+        merge_enters!(enters, entering.except("tapped")) if entering
+        obj.memory.merge!(enters["memory"]) if enters["memory"]
+        obj.controlled_since = state.turn
+        obj.memory["entered"] = state.turn
+        obj.tapped = enters["tapped"]
+        obj.counters.merge!(enters["counters"])
+        enter_as_copy!(obj, enters["copy"]) if enters["copy"] # CR 707.5 (Engine::Copies)
+        state.battlefield.unshift(obj.id)
+        enter_attacking!(obj) if enters["attacking"] # CR 508.4
+        record_result!(obj.id)
+        emit Events::ZoneChanged.new(card: definition.id, old_id: nil, new_id: obj.id, owner: name(controller),
+                                     from: "none", to: "battlefield", reason: "create_token")
+        prepare!(obj) if enters["prepared"] # CR 723.3a (Engine::Faces)
+        obj
+      end
+
+      # The create_token replacements (CR 614.1a): the token definition to create, after creating the extra
+      # ones a "twice that many" replacement adds.
+      def replace_token_creation!(definition, controller, memory:, **)
+        data = propose("create_token", { "player" => controller, "token" => definition.id, "count" => 1 }).data
+        definition = catalog.fetch(data["token"])
+        (data["count"] - 1).times do
+          create_token!(definition, controller, memory: memory && Snapshot.deep_copy(memory), replaced: true, **)
+        end
+        definition
+      end
+
+      # CR 121.2: one card at a time. A replacement may turn one draw into several (CR 614.11); those
+      # draws are the modified event, so the replacement that made them doesn't apply again (CR 614.5).
+      def draw!(index, applied: [])
+        proposal = propose("draw", { "player" => index, "count" => 1 }, applied)
+        return unless proposal.data["player"]
+        return proposal.data["count"].times { draw!(index, applied: proposal.applied) } if proposal.data["count"] != 1
+
+        pl = player(index)
+        if pl.library.empty?
+          pl.drew_from_empty = true # CR 704.5b, checked as a state-based action
+        else
+          move!(pl.library.first, :hand, reason: "draw")
+        end
+      end
+
+      def shuffle_library!(index)
+        state.rng.shuffle!(player(index).library)
+        emit Events::LibraryShuffled.new(player: name(index))
+      end
+
+      def tap!(object)
+        object.tapped = true
+        emit Events::Tapped.new(object: object.id)
+      end
+
+      # CR 701.26b: only tapped permanents can be untapped. Replacement effects (a stun counter,
+      # CR 122.1d) may stop it.
+      def untap!(object)
+        return unless object.tapped
+        return if propose("untap", { "object" => object.id }).data["cancelled"]
+
+        object.tapped = false
+        emit Events::Untapped.new(object: object.id)
+        end_while_source_effects!(object.id, %w[while_source_tapped]) # CR 611.2b: "for as long as it remains tapped" ends
+      end
+
+      # CR 502.3: the active player's permanents untap, except those effects keep from untapping and those
+      # they chose to keep tapped (`keep`, see Engine::TurnStructure).
+      # An exerted permanent skips this one untap step (CR 701.43a).
+      def untap_all!(index, keep: [])
+        state.battlefield.each do |id|
+          obj = object(id)
+          next unless obj.controller == index
+
+          exerted = obj.memory.delete("exerted")
+          untap!(obj) unless keep.include?(id) || exerted || chars(obj).keyword?(:doesnt_untap)
+        end
+      end
+
+      # CR 701.43a-b: exerting it (again) means it won't untap during its controller's next untap step.
+      def exert!(obj) = obj.memory["exerted"] = true
+
+      # CR 302.6: a creature's {T} abilities need it under continuous control since
+      # the start of its controller's most recent turn.
+      def summoning_sick_for_tap?(object)
+        current = chars(object)
+        return false if !current.creature? || current.keyword?(:haste)
+
+        most_recent_turn = state.active == object.controller ? state.turn : state.turn - 1
+        object.controlled_since.nil? || object.controlled_since >= most_recent_turn
+      end
+    end
+
+    include Zones
+  end
+end

data/lib/enjine/engine.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Enjine
+  # The rules state machine.
+  #
+  # No Ruby call stack ever holds game progress: everything lives in State, so a
+  # game can be exported at any decision and resumed elsewhere. #advance! runs the
+  # game forward until a player must decide something (state.pending) or the game ends.
+  class Engine
+    HAND_SIZE = 7
+    MAX_MULLIGANS = 7
+
+    attr_accessor :state
+    attr_reader :catalog
+
+    def initialize(catalog, state, &emit)
+      @catalog = catalog
+      @state = state
+      @emit = emit
+    end
+
+    def emit(event)
+      touch! if volatile_layers? || Characteristics::LAYER_EVENTS.include?(event.class)
+      record_history!(event) # before triggers look at it (see Engine::TurnHistory)
+      @emit.call(event)
+      watch_triggers!(event)
+    end
+
+    def name(index) = state.players[index].name
+    def names = state.players.map(&:name)
+    def player(index) = state.players[index]
+    def active_player = state.players[state.active]
+    def definition(object) = catalog.fetch(object.card)
+    def object(id) = state.objects.fetch(id)
+    def ask!(pending) = state.pending = pending
+    def step = Steps.fetch(state.step)
+    def attackers = state.attackers
+
+    # ---- decisions --------------------------------------------------------------
+
+    def options
+      return [] unless state.pending
+
+      @options_memo = {}
+      Decisions.fetch(state.pending["kind"]).options(self, state.pending)
+    ensure
+      @options_memo = nil
+    end
+
+    def submit!(option)
+      Decisions.fetch(state.pending["kind"]).submit(self, state.pending, option)
+      advance!
+    end
+  end
+end

data/lib/enjine/errors.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Enjine
+  # Base class of every error raised by Enjine.
+  class Error < StandardError; end
+
+  # Raised when an error carries a list of individual problems.
+  class ErrorList < Error
+    attr_reader :errors
+
+    def initialize(errors, prefix)
+      @errors = errors.freeze
+      super("#{prefix}:\n" + errors.map { |e| "  - #{e}" }.join("\n"))
+    end
+  end
+
+  # A submitted option is not legal for the pending decision.
+  class IllegalDecision < Error
+    attr_reader :option, :legal_options, :index
+
+    def initialize(message, option: nil, legal_options: [], index: nil)
+      @option = option
+      @legal_options = legal_options
+      @index = index
+      super(index.nil? ? message : "decision ##{index}: #{message}")
+    end
+  end
+
+  # A card data block failed validation. #errors lists every problem with its path.
+  class InvalidCardDefinition < ErrorList
+    def initialize(errors, name: nil)
+      super(errors, "invalid card definition#{" (#{name})" if name}")
+    end
+  end
+
+  # A deck document is malformed or references unknown cards.
+  class InvalidDeck < ErrorList
+    def initialize(errors)
+      super(errors, "invalid deck")
+    end
+  end
+
+  # A player whose deck is not valid tried to take a seat.
+  class PlayerNotReady < ErrorList
+    def initialize(errors, name:)
+      super(errors, "player #{name} is not ready")
+    end
+  end
+
+  # A snapshot could not be imported because it is inconsistent.
+  class InvalidSnapshot < ErrorList
+    def initialize(errors)
+      super(errors, "invalid snapshot")
+    end
+  end
+
+  # Two definitions with the same id but different contents.
+  class CatalogConflict < Error; end
+
+  # A deck was edited while its player is seated in an unfinished game.
+  class DeckLocked < Error; end
+end

data/lib/enjine/events.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Enjine
+  # Typed, serializable game events. Every state change emits one.
+  #
+  # Players are referenced by name. Each event knows how to present itself to a
+  # viewer (a player name or :observer); hidden information is redacted.
+  module Events
+    PUBLIC_ZONES = %w[battlefield graveyard stack exile].freeze
+    REGISTRY = {} # rubocop:disable Style/MutableConstant -- extension registry
+
+    # Behavior shared by every event class.
+    module Base
+      def type = self.class.event_type
+
+      def to_h = { "type" => type }.merge(super.transform_keys(&:to_s))
+
+      # Hash form for one viewer. Defaults to the full event.
+      def for_viewer(_viewer) = to_h
+    end
+
+    def self.define(name, *fields, &)
+      klass = Data.define(*fields, &)
+      klass.include(Base)
+      klass.define_singleton_method(:event_type) { name.to_s }
+      REGISTRY[name.to_s] = klass
+      klass
+    end
+
+    def self.from_h(hash)
+      hash = hash.transform_keys(&:to_s)
+      klass = REGISTRY.fetch(hash["type"]) { raise ArgumentError, "unknown event #{hash["type"].inspect}" }
+      klass.new(**klass.members.to_h { |m| [m, hash[m.to_s]] })
+    end
+
+    def self.zone_visible?(zone, owner, viewer)
+      viewer == :observer || PUBLIC_ZONES.include?(zone) || (zone == "hand" && viewer == owner)
+    end
+
+    GameStarted = define(:game_started, :players, :seed)
+    DieRolled = define(:die_rolled, :winner)
+    StartingPlayerChosen = define(:starting_player_chosen, :chooser, :choice, :starting_player)
+    LibraryShuffled = define(:library_shuffled, :player)
+    MulliganDeclared = define(:mulligan_declared, :player, :choice)
+    MulliganTaken = define(:mulligan_taken, :player, :mulligans)
+    HandKept = define(:hand_kept, :player, :mulligans)
+    TurnBegan = define(:turn_began, :turn, :active)
+    StepBegan = define(:step_began, :turn, :step, :phase)
+    PriorityPassed = define(:priority_passed, :player)
+    Tapped = define(:tapped, :object)
+    Untapped = define(:untapped, :object)
+    # CR 702.26: phasing isn't a zone change; `indirectly`: it phased out attached to another permanent.
+    PhasedOut = define(:phased_out, :object, :indirectly)
+    PhasedIn = define(:phased_in, :object)
+    ManaAdded = define(:mana_added, :player, :mana, :source)
+    ManaEmptied = define(:mana_emptied, :player, :mana)
+    PlayerLost = define(:player_lost, :player, :reason)
+    GameEnded = define(:game_ended, :winner, :reason)
+    TargetChosen = define(:target_chosen, :player, :object, :target)
+    XAnnounced = define(:x_announced, :player, :object, :value)
+    ManaPaid = define(:mana_paid, :player, :mana, :object)
+    # `during_resolution`: cast while another spell or ability resolves (CR 608.2g), ignoring timing.
+    SpellCast = define(:spell_cast, :player, :object, :card, :targets, :during_resolution) do
+      def initialize(player:, object:, card:, targets:, during_resolution: false) = super
+    end
+    AbilityActivated = define(:ability_activated, :player, :object, :card, :source, :ability, :targets)
+    CastCancelled = define(:cast_cancelled, :player, :object, :card)
+    Resolved = define(:resolved, :object, :card, :kind)
+    Fizzled = define(:fizzled, :object, :card)
+    # `combat`: dealt as combat damage (CR 510.2); triggers such as "deals combat damage to a player" read it.
+    DamageDealt = define(:damage_dealt, :source, :target, :amount, :combat) do
+      def initialize(source:, target:, amount:, combat: false) = super
+    end
+    # A life total changed. CR 119.9: a gain is a life gain event, a loss a life loss event.
+    LifeChanged = define(:life_changed, :player, :from, :to) do
+      def gain = [to - from, 0].max
+      def loss = [from - to, 0].max
+    end
+    CountersChanged = define(:counters_changed, :object, :counter, :from, :to)
+    PlayerCountersChanged = define(:player_counters_changed, :player, :counter, :from, :to) # poison, rad, ... (CR 122.1)
+    EmblemCreated = define(:emblem_created, :player, :object, :card) # CR 114.2
+    # CR 705: a coin flip; `won` is nil for a flip no one wins or loses (CR 705.2).
+    CoinFlipped = define(:coin_flipped, :player, :heads, :won)
+    # CR 706.2: a die with `sides` sides rolled by an effect, and its natural result.
+    RolledDie = define(:rolled_die, :player, :sides, :result)
+    # CR 707.10: a copy of a spell put on the stack (not cast).
+    SpellCopied = define(:spell_copied, :player, :object, :card, :original, :targets)
+    EffectStarted = define(:effect_started, :kind, :affected, :details)
+    EffectsEnded = define(:effects_ended, :count)
+    AttackerDeclared = define(:attacker_declared, :object, :target)
+    BlockerDeclared = define(:blocker_declared, :object, :attacker)
+    DamageAssigned = define(:damage_assigned, :attacker, :blocker)
+    # `trigger`: the id of the pending triggered ability ("copy that ability", see Engine#stack_object_for).
+    AbilityTriggered = define(:ability_triggered, :player, :source, :card, :ability, :trigger) do
+      def initialize(player:, source:, card:, ability:, trigger: nil) = super
+    end
+    TriggerPutOnStack = define(:trigger_put_on_stack, :player, :object, :source, :card, :ability, :targets)
+    TriggerRemoved = define(:trigger_removed, :player, :source, :card, :reason)
+    TokenCeased = define(:token_ceased, :object, :card, :zone)
+    LibraryReordered = define(:library_reordered, :player, :top, :bottom)
+    Attached = define(:attached, :object, :to) # CR 701.3
+    Unattached = define(:unattached, :object, :from) # CR 701.3d
+    # A card in a hidden zone is shown to every player (CR 701.20a); it doesn't leave its zone (701.20b).
+    CardRevealed = define(:card_revealed, :player, :object, :card)
+    # A player looks at cards in a hidden zone (CR 701.20e): only they (and the cards' owner) see which.
+    LookedAt = define(:looked_at, :player, :owner, :objects, :cards) do
+      def for_viewer(viewer)
+        return to_h if viewer == :observer || viewer == player || viewer == owner
+
+        { "type" => type, "player" => player, "owner" => owner, "count" => objects.size }
+      end
+    end
+    ControlChanged = define(:control_changed, :object, :controller)
+    ExtraTurnAdded = define(:extra_turn_added, :player) # CR 500.7
+    TurnSkipped = define(:turn_skipped, :player) # CR 614.10
+    DilemmaFaced = define(:dilemma_faced, :player, :object, :modes) # CR 700.17
+    # Combat declarations once final (CR 508.3d "whenever [a player] attacks", 509.3c "becomes blocked").
+    AttacksDeclared = define(:attacks_declared, :player, :attackers)
+    BecameBlocked = define(:became_blocked, :object, :blockers)
+    # Crew (CR 702.122): a creature tapped to pay a crew cost crews that Vehicle (702.122b); the Vehicle
+    # becomes crewed as its crew ability resolves (702.122e), by the creatures in `crew`.
+    CrewedVehicle = define(:crewed_vehicle, :object, :vehicle)
+    # A permanent tapped to pay a `cost` (e.g. "teamwork", CR 702.194a) of the spell `spell`, once the spell is cast.
+    TappedForCost = define(:tapped_for_cost, :object, :cost, :spell)
+    BecameCrewed = define(:became_crewed, :object, :crew)
+    # Saddle (CR 702.171): a creature tapped to pay a saddle cost saddles that Mount (702.171c); the Mount
+    # becomes saddled (702.171b), by the creatures in `riders` when its saddle ability did it.
+    SaddledMount = define(:saddled_mount, :object, :mount)
+    BecameSaddled = define(:became_saddled, :object, :riders)
+    # A player's speed changed (CR 702.179); `from` nil: they had no speed.
+    SpeedChanged = define(:speed_changed, :player, :from, :to)
+    # A player got a designation for the rest of the game, e.g. an enduring story (CR 702.195b).
+    DesignationGained = define(:designation_gained, :player, :designation)
+    # A permanent's class level became `level` (CR 717.2a).
+    ClassLevelChanged = define(:class_level_changed, :object, :level)
+    # CR 701.27a: a double-faced permanent turned over; `card` names the face now up (CR 712).
+    Transformed = define(:transformed, :object, :card)
+    # CR 723.3a-c: a permanent gained (`prepared` true) or lost the prepared designation.
+    PreparedChanged = define(:prepared_changed, :object, :prepared)
+    # A keyword action that abilities trigger on, once it's complete: "scry" / "surveil" N (CR 701.22, 701.25);
+    # earthbend, waterbend, airbend and firebend (CR 701.66b, 701.67c, 701.65b, 702.189b).
+    KeywordAction = define(:keyword_action, :player, :action, :amount)
+
+    # A card moved between zones; old_id stops existing and new_id is born (CR 400.7). `lookers`: the card
+    # was exiled face down, and only these players (by name) see which card it is (CR 406.3).
+    ZoneChanged = define(:zone_changed, :card, :old_id, :new_id, :owner, :from, :to, :reason, :lookers) do
+      def initialize(card:, old_id:, new_id:, owner:, from:, to:, reason:, lookers: nil) = super
+
+      def for_viewer(viewer)
+        if lookers && viewer != :observer && !lookers.include?(viewer)
+          { "type" => type, "owner" => owner, "new_id" => new_id, "from" => from, "to" => to, "reason" => reason,
+            "face_down" => true }
+        elsif Events.zone_visible?(from, owner, viewer) || Events.zone_visible?(to, owner, viewer)
+          to_h
+        else
+          { "type" => type, "owner" => owner, "from" => from, "to" => to, "reason" => reason }
+        end
+      end
+    end
+  end
+end

data/lib/enjine/frames.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Enjine
+  # In-progress processes, kept on a serializable stack (state.frames, innermost last).
+  #
+  # Anything that may need to stop and ask a player something in the middle of the
+  # rules (casting, resolving a spell, assigning combat damage, ...) is a frame:
+  # plain JSON data plus a registered frame class. Engine#advance! steps the top
+  # frame until it is done or waiting for a decision, so a game can be exported at
+  # any point, including halfway through resolving an effect list.
+  #
+  # A frame class implements:
+  #   .step(engine, frame) -> :done (pop it), :wait (state.pending is set), or :push (stepped child next)
+  #   .decisions           -> decision kinds that may be pending while it is on top
+  #   .validate(frame, data, errors) -> snapshot consistency checks
+  module Frames
+    KINDS = {} # rubocop:disable Style/MutableConstant -- extension registry
+
+    def self.register(type, klass)
+      KINDS[type] = klass
+    end
+
+    def self.fetch(type) = KINDS.fetch(type) { raise ArgumentError, "unknown frame type #{type.inspect}" }
+
+    # Base frame.
+    class Base
+      def self.decisions = []
+      def self.validate(_frame, _data, _errors) = nil
+    end
+
+    # Casting a spell or activating an ability (CR 601.2, 602.2).
+    class Cast < Base
+      def self.step(engine, _frame) = engine.continue_casting!
+
+      def self.decisions
+        %w[choose_kicker choose_cost_option choose_mode choose_x choose_target_count choose_target distribute choose_cost pay_cost]
+      end
+
+      def self.validate(frame, data, errors)
+        errors << "frames: cast object #{frame["object"]} is not on the stack" unless data["stack"].include?(frame["object"])
+      end
+    end
+    register("cast", Cast)
+
+    # Resolving the top object of the stack, one effect at a time (CR 608).
+    class Resolve < Base
+      def self.step(engine, frame) = engine.step_resolution!(frame)
+      def self.decisions = %w[effect_choice enter_choice]
+
+      def self.validate(frame, data, errors)
+        errors << "frames: resolving object #{frame["object"]} is not on the stack" unless data["stack"].include?(frame["object"])
+      end
+    end
+    register("resolve", Resolve)
+
+    # Assigning and dealing combat damage (CR 510).
+    class CombatDamage < Base
+      def self.step(engine, frame) = engine.step_combat_damage!(frame)
+      def self.decisions = %w[assign_damage]
+    end
+    register("combat_damage", CombatDamage)
+
+    # Putting pending triggered abilities on the stack (CR 603.3), then giving priority.
+    class PutTriggers < Base
+      def self.step(engine, frame) = engine.step_put_triggers!(frame)
+      def self.decisions = %w[order_triggers]
+    end
+    register("put_triggers", PutTriggers)
+
+    # The legend rule's choice (CR 704.5j).
+    class LegendRule < Base
+      def self.step(engine, frame) = engine.step_legend_rule!(frame)
+      def self.decisions = %w[legend_rule]
+    end
+    register("legend_rule", LegendRule)
+
+    # Playing a land that asks an "as this enters" choice first (CR 614.12).
+    class PlayLand < Base
+      def self.step(engine, frame) = Actions::PlayLand.step(engine, frame)
+      def self.decisions = %w[enter_choice]
+    end
+    register("play_land", PlayLand)
+  end
+end