enjine 0.1.0

data/lib/enjine/snapshot.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require_relative "snapshot/turn_checks"
+require_relative "snapshot/player_checks"
+
+module Enjine
+  # Converts State to and from plain data, with complete consistency validation.
+  #
+  # The validation doubles as the engine's invariant check: the fuzzer runs it
+  # after every decision of every random game.
+  module Snapshot
+    VERSION = 2
+    PLAYER_KEYS = %w[name life poison library hand graveyard mana_pool lands_played drew_from_empty lost
+                     mulligans kept mulligan_choice].freeze
+
+    module_function
+
+    def validate(data, catalog)
+      errors = []
+      return ["snapshot must be an object"] unless data.is_a?(Hash)
+      return ["version: expected #{VERSION}, got #{data["version"].inspect}"] unless data["version"] == VERSION
+
+      validate_header(data, errors)
+      validate_players(data, errors)
+      validate_objects(data, catalog, errors)
+      validate_combat(data, errors) if errors.empty?
+      validate_turn(data, errors) if errors.empty?
+      validate_delayed_triggers(data, catalog, errors) if errors.empty?
+      validate_extra_turns(data, errors)
+      validate_extra_phases(data, errors)
+      validate_outside(data, catalog, errors)
+      errors
+    end
+
+    def load(data, catalog)
+      data = deep_stringify(data)
+      errors = validate(data, catalog)
+      raise InvalidSnapshot, errors unless errors.empty?
+
+      build(data)
+    end
+
+    def build(data)
+      state = State.new
+      state.seed = data["seed"]
+      state.rng = Rng.new(data["rng"])
+      state.decklists = data["decklists"].map { |l| l.dup.freeze }.freeze
+      state.players = data["players"].map { |p| build_player(p) }
+      state.objects = data["objects"].to_h do |o|
+        [o["id"], build_object(o)]
+      end
+      State::SHARED_ZONES.each { |z| state.public_send("#{z}=", data.fetch(z.to_s, []).dup) }
+      state.attackers = deep_copy(data.fetch("attackers", {}))
+      state.blockers = deep_copy(data.fetch("blockers", {}))
+      state.effects = deep_copy(data.fetch("effects", []))
+      state.frames = deep_copy(data.fetch("frames", []))
+      state.pending_triggers = deep_copy(data.fetch("pending_triggers", []))
+      state.delayed_triggers = deep_copy(data.fetch("delayed_triggers", []))
+      state.extra_turns = deep_copy(data.fetch("extra_turns", { "queue" => [], "begun" => [] }))
+      state.extra_phases = deep_copy(data.fetch("extra_phases", State.no_extra_phases))
+      state.outside_lists = data.fetch("outside_lists", [[], []]).map { |l| l.dup.freeze }.freeze
+      state.repeat_cleanup = data.fetch("repeat_cleanup", false)
+      state.combat_damage_pass = data["combat_damage_pass"]
+      state.attacks_declared = data.fetch("attacks_declared", 0)
+      %w[turn active step_state priority passes next_id starting_player].each do |k|
+        state.public_send("#{k}=", data[k])
+      end
+      state.step = data["step"]&.to_sym
+      state.pending = data["pending"]&.dup
+      state.result = data["result"]&.dup
+      state
+    end
+
+    def build_object(hash)
+      GameObject.new(id: hash["id"], card: hash["card"], owner: hash["owner"], controller: hash["controller"],
+                     zone: hash["zone"].to_sym, tapped: hash["tapped"], controlled_since: hash["controlled_since"],
+                     kind: hash.fetch("kind", "card"), counters: deep_copy(hash.fetch("counters", {})),
+                     damage: hash.fetch("damage", 0), source: hash["source"], ability: hash["ability"],
+                     targets: deep_copy(hash["targets"]), loyalty_turn: hash["loyalty_turn"],
+                     deathtouched: hash.fetch("deathtouched", false), modes: hash["modes"]&.dup,
+                     memory: deep_copy(hash.fetch("memory", {})), x: hash["x"], mana_spent: hash["mana_spent"]&.dup,
+                     attached_to: hash["attached_to"], paid: hash["paid"] && deep_copy(hash["paid"]),
+                     phased_out: hash["phased_out"]&.dup)
+    end
+
+    def deep_copy(value) = Marshal.load(Marshal.dump(value))
+
+    def build_player(hash)
+      PlayerState.new(**PLAYER_KEYS.to_h { |k| [k.to_sym, hash[k]] }).tap do |pl|
+        pl.library = pl.library.dup
+        pl.hand = pl.hand.dup
+        pl.graveyard = pl.graveyard.dup
+        pl.mana_pool = Mana::TYPES.to_h { |t| [t, hash["mana_pool"].fetch(t.to_s, 0)] }
+        pl.turn_log = deep_copy(hash.fetch("turn_log", {}))
+        pl.game_log = deep_copy(hash.fetch("game_log", {}))
+        pl.last_turn_log = deep_copy(hash.fetch("last_turn_log", {}))
+        pl.restricted_mana = deep_copy(hash.fetch("restricted_mana", []))
+        pl.outside = hash.fetch("outside", []).dup
+        pl.speed = hash["speed"] # CR 702.179; absent: no speed
+        pl.designations = hash.fetch("designations", []).dup # CR 702.195b (Engine::Designations)
+        pl.counters = hash.fetch("counters", {}).dup # CR 122.1: counters other than poison
+        pl.pool_sources = deep_copy(hash.fetch("pool_sources", [])) # Engine::ManaSources#add_mana!
+      end
+    end
+
+    def validate_header(data, errors)
+      errors << "rng: must be a non-negative integer" unless non_negative?(data["rng"])
+      errors << "next_id: must be a positive integer" unless data["next_id"].is_a?(Integer) && data["next_id"].positive?
+      errors << "decklists: must be a list of card id lists" unless data["decklists"].is_a?(Array) && data["decklists"].all?(Array)
+      %w[battlefield stack exile].each { |z| errors << "#{z}: must be a list" unless data[z].is_a?(Array) }
+      errors << "phased_out: must be a list" unless data.fetch("phased_out", []).is_a?(Array)
+    end
+
+    def validate_players(data, errors)
+      players = data["players"]
+      return errors << "players: must be a list of 2 players" unless players.is_a?(Array) && players.size == 2
+
+      players.each_with_index do |pl, i|
+        path = "players[#{i}]"
+        next errors << "#{path}: must be an object" unless pl.is_a?(Hash)
+
+        (PLAYER_KEYS - pl.keys).each { |k| errors << "#{path}.#{k}: missing" }
+        %w[life poison lands_played mulligans].each do |k|
+          errors << "#{path}.#{k}: must be an integer" unless pl[k].is_a?(Integer)
+        end
+        %w[library hand graveyard].each { |z| errors << "#{path}.#{z}: must be a list" unless pl[z].is_a?(Array) }
+        pool = pl["mana_pool"]
+        unless pool.is_a?(Hash) && pool.all? { |t, n| Mana::TYPES.include?(t.to_sym) && non_negative?(n) }
+          errors << "#{path}.mana_pool: must map W/U/B/R/G/C to non-negative integers"
+        end
+        validate_restricted_mana(pl.fetch("restricted_mana", []), errors, "#{path}.restricted_mana")
+        validate_pool_sources(pl, errors, "#{path}.pool_sources")
+        errors << "#{path}.speed: must be 1, 2, 3 or 4 (or absent)" unless [nil, 1, 2, 3, 4].include?(pl["speed"]) # CR 702.179
+        validate_designations(pl.fetch("designations", []), errors, "#{path}.designations")
+      end
+      validate_logs(players, errors)
+      names = players.map { it.is_a?(Hash) ? it["name"] : nil }
+      errors << "players: names must be distinct non-empty strings" unless names.all?(String) && names.uniq.size == 2
+    end
+
+    # What happened this turn and this game (Engine::TurnHistory) and counters on the players; absent in older
+    # snapshots.
+    def validate_logs(players, errors)
+      players.each_with_index.select { |pl, _| pl.is_a?(Hash) }.each do |pl, i|
+        %w[turn_log game_log last_turn_log].each do |k|
+          errors << "players[#{i}].#{k}: must be an object" unless pl.fetch(k, {}).is_a?(Hash)
+        end
+        counters = pl.fetch("counters", {}) # CR 122.1: counters other than poison; absent in older snapshots
+        next if counters.is_a?(Hash) && counters.all? { |k, n| Mechanics::Counters.valid?(k) && k != "poison" && non_negative?(n) }
+
+        errors << "players[#{i}].counters: must map counter kinds other than poison to non-negative integers"
+      end
+    end
+
+    def validate_objects(data, catalog, errors)
+      objects = data["objects"]
+      return errors << "objects: must be a list" unless objects.is_a?(Array)
+      return unless errors.empty?
+
+      seen = {}
+      objects.each_with_index do |o, i|
+        path = "objects[#{i}]"
+        next errors << "#{path}: must be an object" unless o.is_a?(Hash)
+
+        id = o["id"]
+        errors << "#{path}: duplicate id #{id.inspect}" if seen.key?(id)
+        seen[id] = o
+        validate_object(o, path, catalog, data["next_id"], errors)
+      end
+      validate_zone_membership(data, seen, errors)
+    end
+
+    def validate_object(obj, path, catalog, next_id, errors)
+      validate_object_id(obj, path, catalog, next_id, errors)
+      %w[owner controller].each { |k| errors << "#{path}.#{k}: must be 0 or 1" unless [0, 1].include?(obj[k]) }
+      zone = obj["zone"].to_s
+      errors << "#{path}.zone: unknown zone #{zone.inspect}" unless State::ZONES.map(&:to_s).include?(zone)
+      errors << "#{path}.tapped: must be true or false" unless [true, false].include?(obj["tapped"])
+      validate_object_state(obj, path, zone, errors)
+      validate_phasing(obj, path, zone, errors)
+      return if %w[battlefield stack phased_out].include?(zone)
+
+      errors << "#{path}: only permanents on the battlefield can be tapped" if obj["tapped"]
+      errors << "#{path}: controller must equal owner outside the battlefield and stack" if obj["controller"] != obj["owner"]
+    end
+
+    def validate_object_state(obj, path, zone, errors)
+      kind = obj.fetch("kind", "card")
+      errors << "#{path}.kind: must be \"card\", \"ability\" or \"emblem\"" unless %w[card ability emblem].include?(kind)
+      home = { "ability" => "stack", "emblem" => "command" }[kind]
+      if home
+        errors << "#{path}: #{kind}s can only exist in the #{home} zone" unless zone == home
+        errors << "#{path}.ability: must be an ability reference" unless obj["ability"].is_a?(String)
+      end
+      errors << "#{path}: only emblems are in the command zone (CR 114.1)" if zone == "command" && kind != "emblem"
+      counters = obj.fetch("counters", {})
+      unless counters.is_a?(Hash) && counters.all? { |k, v| Mechanics::Counters.valid?(k) && non_negative?(v) }
+        errors << "#{path}.counters: must map counter kinds to non-negative integers"
+      end
+      errors << "#{path}.damage: must be a non-negative integer" unless non_negative?(obj.fetch("damage", 0))
+      errors << "#{path}.memory: must be an object" unless obj.fetch("memory", {}).is_a?(Hash)
+      validate_cast_info(obj, path, errors)
+      validate_attachment(obj, path, zone, errors)
+      return if ON_BATTLEFIELD.include?(zone)
+
+      # Cards in exile may have counters (time counters of suspend, CR 702.62a); only permanents have damage.
+      return unless (zone != "exile" && counters.values.any?(&:positive?)) || obj["damage"].to_i.positive?
+
+      errors << "#{path}: only permanents have counters or damage"
+    end
+
+    # The X announced for a spell or ability and the mana spent on it (CR 107.3a, 702.44a).
+    def validate_cast_info(obj, path, errors)
+      errors << "#{path}.x: must be a non-negative integer" unless obj["x"].nil? || non_negative?(obj["x"])
+      spent = obj["mana_spent"]
+      return if spent.nil? || (spent.is_a?(Array) && spent.all? { Mana::TYPES.map(&:to_s).include?(it) })
+
+      errors << "#{path}.mana_spent: must be a list of mana types"
+    end
+
+    # CR 701.3: only a permanent is attached, never to itself. The object it names may already
+    # be gone: state-based actions (704.5m/n) clean that up before the next priority.
+    def validate_attachment(obj, path, zone, errors)
+      to = obj["attached_to"]
+      return if to.nil?
+
+      errors << "#{path}.attached_to: must be another object's id" unless to.is_a?(String) && to != obj["id"]
+      errors << "#{path}: only permanents on the battlefield can be attached" unless ON_BATTLEFIELD.include?(zone)
+    end
+
+    # Phased out (CR 702.26): still a permanent on the battlefield, kept in the `phased_out` list with who
+    # controlled it as it phased out and whether it phased out indirectly.
+    ON_BATTLEFIELD = %w[battlefield phased_out].freeze
+
+    def validate_phasing(obj, path, zone, errors)
+      info = obj["phased_out"]
+      return errors << "#{path}.phased_out: only phased-out permanents have it" if info && zone != "phased_out"
+      return if zone != "phased_out"
+      return if info.is_a?(Hash) && [0, 1].include?(info["by"]) && [true, false].include?(info["indirectly"])
+
+      errors << "#{path}.phased_out: must be {\"by\": 0 or 1, \"indirectly\": true or false}"
+    end
+
+    def validate_combat(data, errors)
+      battlefield = data["battlefield"]
+      attackers = data.fetch("attackers", {})
+      blockers = data.fetch("blockers", {})
+      return errors << "attackers/blockers: must be objects" unless attackers.is_a?(Hash) && blockers.is_a?(Hash)
+
+      attackers.each_key { |id| errors << "attackers: #{id} is not on the battlefield" unless battlefield.include?(id) }
+      blockers.each do |id, attacker|
+        errors << "blockers: #{id} is not on the battlefield" unless battlefield.include?(id)
+        errors << "blockers: #{id} blocks #{attacker}, which is not attacking" unless attackers.key?(attacker)
+      end
+      errors << "effects: must be a list" unless data.fetch("effects", []).is_a?(Array)
+      validate_frames(data, errors)
+    end
+
+    def validate_frames(data, errors)
+      frames = data.fetch("frames", [])
+      return errors << "frames: must be a list" unless frames.is_a?(Array)
+
+      frames.each_with_index do |frame, i|
+        klass = frame.is_a?(Hash) && Frames::KINDS[frame["type"]]
+        next errors << "frames[#{i}]: unknown frame #{frame.inspect[0, 60]}" unless klass
+
+        klass.validate(frame, data, errors)
+      end
+      top = frames.last
+      kind = data.dig("pending", "kind")
+      return unless top && kind && !Frames.fetch(top["type"]).decisions.include?(kind)
+
+      errors << "pending: #{kind} can't be pending while a #{top["type"]} frame is in progress"
+    end
+
+    def validate_zone_membership(data, objects, errors)
+      placed = Hash.new(0)
+      lists = State::SHARED_ZONES.map { |z| [z.to_s, nil, data.fetch(z.to_s, [])] }
+      data["players"].each_with_index do |pl, i|
+        State::PLAYER_ZONES.each { |z| lists << [z.to_s, i, pl[z.to_s]] }
+      end
+      lists.each do |zone, owner, ids|
+        ids.each do |id|
+          placed[id] += 1
+          obj = objects[id]
+          next errors << "#{zone}: unknown object #{id.inspect}" unless obj
+          next errors << "#{id}: listed in #{zone} but its zone is #{obj["zone"]}" unless obj["zone"].to_s == zone
+          next unless owner && obj["owner"] != owner
+
+          errors << "#{id}: in #{data["players"][owner]["name"]}'s #{zone} but owned by player #{obj["owner"]}"
+        end
+      end
+      objects.each_key { |id| errors << "#{id}: in #{placed[id]} zones, expected exactly 1" if placed[id] != 1 }
+    end
+
+    def non_negative?(value) = value.is_a?(Integer) && !value.negative?
+
+    def deep_stringify(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s, deep_stringify(v)] }
+      when Array then value.map { deep_stringify(it) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+  end
+end

data/lib/enjine/state.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Enjine
+  # A card or token in a zone (CR 109). Refers to its definition by id only.
+  # A new GameObject (with a new id) is created on every zone change (CR 400.7).
+  GameObject = Struct.new(:id, :card, :owner, :controller, :zone, :tapped, :controlled_since, :kind, :counters,
+                          :damage, :source, :ability, :targets, :loyalty_turn, :deathtouched, :modes, :memory,
+                          :x, :mana_spent, :attached_to,
+                          :paid, # paid: choices made paying costs, e.g. the creature tapped (CR 702.184a)
+                          :phased_out) do # {"by" => controller, "indirectly" => bool} while phased out (CR 702.26)
+    def ability? = kind == "ability"
+
+    def to_h
+      { "id" => id, "card" => card, "owner" => owner, "controller" => controller, "zone" => zone.to_s,
+        "tapped" => tapped, "controlled_since" => controlled_since, "kind" => kind, "counters" => counters.dup,
+        "damage" => damage, "source" => source, "ability" => ability, "targets" => targets&.dup,
+        "loyalty_turn" => loyalty_turn, "deathtouched" => deathtouched,
+        "modes" => modes&.dup, "memory" => Marshal.load(Marshal.dump(memory || {})), "x" => x,
+        "mana_spent" => mana_spent&.dup, "attached_to" => attached_to, "paid" => paid&.map(&:dup),
+        "phased_out" => phased_out&.dup }
+    end
+  end
+
+  # Per-player game state.
+  PlayerState = Struct.new(:name, :life, :poison, :library, :hand, :graveyard, :mana_pool, :lands_played,
+                           :drew_from_empty, :lost, :mulligans, :kept, :mulligan_choice,
+                           :turn_log, :game_log, # what happened this turn / this game (see Engine::History)
+                           :last_turn_log, # what happened during the previous turn (CR 500.1)
+                           :restricted_mana, # mana with a spending restriction (CR 106.6), see Engine#add_mana!
+                           :outside, # definition ids of the cards they own outside the game (CR 400.11a)
+                           :speed, # nil (no speed) or 1-4 (CR 702.179), see Engine::Speed
+                           :designations, # player designations, e.g. "enduring_story" (CR 702.195b), see Engine::Designations
+                           :counters, # nil or {kind => n}: counters other than poison (CR 122.1), see Engine#add_player_counters!
+                           :pool_sources) do # nil or [{"mana", "from"}]: sources of pool mana made by artifacts (Engine#add_mana!)
+    def zone(name)
+      case name
+      when :library then library
+      when :hand then hand
+      when :graveyard then graveyard
+      end
+    end
+
+    def to_h
+      { "name" => name, "life" => life, "poison" => poison, "library" => library.dup, "hand" => hand.dup,
+        "graveyard" => graveyard.dup, "mana_pool" => mana_pool.transform_keys(&:to_s),
+        "lands_played" => lands_played, "drew_from_empty" => drew_from_empty, "lost" => lost,
+        "mulligans" => mulligans, "kept" => kept, "mulligan_choice" => mulligan_choice,
+        "turn_log" => deep(turn_log || {}), "game_log" => deep(game_log || {}), "last_turn_log" => deep(last_turn_log || {}),
+        "restricted_mana" => deep(restricted_mana || []), "outside" => (outside || []).dup }.merge(optional_h)
+    end
+
+    private
+
+    def deep(value) = Marshal.load(Marshal.dump(value))
+
+    # Fields left out while empty.
+    def optional_h
+      { "speed" => speed, "designations" => designations.to_a.empty? ? nil : designations.dup,
+        "counters" => counters.nil? || counters.empty? ? nil : counters.dup,
+        "pool_sources" => pool_sources.nil? || pool_sources.empty? ? nil : deep(pool_sources) }.compact
+    end
+  end
+
+  # The complete, mutable state of one game. Plain data only: everything here
+  # round-trips through #to_h / Snapshot.load, and Marshal copies it cheaply.
+  class State
+    STARTING_LIFE = 20
+    PLAYER_ZONES = %i[library hand graveyard].freeze
+    # `phased_out` is not a zone of the rules: phased-out permanents are on the battlefield but treated as
+    # though they don't exist (CR 702.26b, 702.26d), so they are kept apart from `battlefield`. The command
+    # zone holds emblems (CR 114, 408).
+    SHARED_ZONES = %i[battlefield stack exile phased_out command].freeze
+    ZONES = (PLAYER_ZONES + SHARED_ZONES).freeze
+    STEP_STATES = %w[begin active done].freeze
+
+    attr_accessor :seed, :rng, :decklists, :players, :objects, :battlefield, :stack, :exile, :phased_out, :command, :turn,
+                  :active,
+                  :step, :step_state, :priority, :passes, :next_id, :starting_player, :pending, :result,
+                  :attackers, :blockers, :effects, :frames, :attacks_declared,
+                  :pending_triggers, :repeat_cleanup, :combat_damage_pass, :delayed_triggers,
+                  :extra_turns, :extra_phases
+    # The definition ids each player started the game with outside it (CR 400.11a, 100.4), like
+    # `decklists`: a restart begins from these again. What is still outside is PlayerState#outside.
+    attr_accessor :outside_lists
+
+    def self.initial(names:, decklists:, seed:, outside: nil)
+      state = new
+      state.seed = seed
+      state.rng = Rng.from_seed(seed)
+      state.decklists = decklists.map { |l| l.dup.freeze }.freeze
+      state.outside_lists = (outside || names.map { [] }).map { |l| l.dup.freeze }.freeze
+      state.players = names.each_with_index.map { |name, i| new_player(name, state.outside_lists[i]) }
+      state.objects = {}
+      state.battlefield = []
+      state.stack = []
+      state.exile = []
+      state.phased_out = []
+      state.command = []
+      state.attackers = {}
+      state.blockers = {}
+      state.effects = []
+      state.frames = []
+      state.pending_triggers = []
+      state.delayed_triggers = []
+      state.extra_turns = { "queue" => [], "begun" => [] } # CR 500.7
+      state.extra_phases = no_extra_phases # CR 500.8
+      state.repeat_cleanup = false
+      state.combat_damage_pass = nil
+      state.attacks_declared = 0
+      state.turn = 0
+      state.passes = 0
+      state.next_id = 1
+      state.step_state = "begin"
+      state
+    end
+
+    # Phases added this turn (CR 500.8): "pending" [{"after": phase, "phases": ["combat", "main"]}] wait for
+    # their phase to end, "queue" lists added phases still to come and "resume" the step the turn goes on
+    # with after them (Engine::TurnStructure); "combats" counts combat phases begun this turn.
+    def self.no_extra_phases = { "pending" => [], "queue" => [], "combats" => 0 }
+
+    def self.new_player(name, outside = [])
+      PlayerState.new(name: name, life: STARTING_LIFE, poison: 0, library: [], hand: [], graveyard: [],
+                      mana_pool: Mana.empty_pool, lands_played: 0, drew_from_empty: false, lost: nil,
+                      mulligans: 0, kept: false, mulligan_choice: nil, turn_log: {}, game_log: {}, last_turn_log: {}, restricted_mana: [],
+                      outside: outside.dup)
+    end
+
+    def zone_list(zone, owner)
+      SHARED_ZONES.include?(zone) ? public_send(zone) : players[owner].zone(zone)
+    end
+
+    def object(id) = objects.fetch(id)
+    def opponent(index) = 1 - index
+    def over? = !result.nil?
+
+    def to_h
+      { "version" => Snapshot::VERSION, "rules" => RULES_VERSION, "seed" => seed, "rng" => rng.state,
+        "decklists" => decklists.map(&:dup), "turn" => turn, "active" => active, "step" => step&.to_s,
+        "step_state" => step_state, "priority" => priority, "passes" => passes, "next_id" => next_id,
+        "starting_player" => starting_player, "pending" => pending&.dup, "result" => result&.dup,
+        "players" => players.map(&:to_h), "objects" => objects.values.map(&:to_h),
+        "battlefield" => battlefield.dup, "stack" => stack.dup, "exile" => exile.dup, "phased_out" => phased_out.dup,
+        "command" => (command || []).dup,
+        "attackers" => attackers.dup, "blockers" => blockers.dup, "effects" => effects.map { deep_dup(it) },
+        **DEEP_FIELDS.to_h { [it, deep_dup(public_send(it))] },
+        "repeat_cleanup" => repeat_cleanup, "combat_damage_pass" => combat_damage_pass,
+        "attacks_declared" => attacks_declared }.merge("outside_lists" => (outside_lists || []).map(&:dup))
+    end
+
+    # Nested fields #to_h deep-copies as they are.
+    DEEP_FIELDS = %w[frames pending_triggers delayed_triggers extra_turns extra_phases].freeze
+
+    # An independent deep copy, about 10x faster than a Marshal round trip. It walks every
+    # instance variable, so fields added later are copied automatically. Strings, symbols,
+    # numbers and frozen values are shared: state never mutates them in place.
+    def fork
+      copy = State.allocate
+      instance_variables.each { |ivar| copy.instance_variable_set(ivar, deep_dup(instance_variable_get(ivar))) }
+      copy
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash then value.frozen? ? value : value.to_h { |k, v| [k, deep_dup(v)] }
+      when Array then value.frozen? ? value : value.map { deep_dup(it) }
+      when Struct then value.dup.tap { |copy| copy.each_pair { |k, v| copy[k] = deep_dup(v) } }
+      when Rng then Rng.new(value.state)
+      else value
+      end
+    end
+  end
+end

data/lib/enjine/steps.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Enjine
+  # The twelve steps of a turn (CR 500.1). Each step object owns its turn-based
+  # actions and whether players receive priority during it.
+  module Steps
+    # Base step: turn-based actions are a no-op and players get priority.
+    class Step
+      attr_reader :name, :phase
+
+      def initialize(name, phase)
+        @name = name
+        @phase = phase
+        freeze
+      end
+
+      def priority? = true
+      def skip?(_engine) = false
+      def finish(_engine) = nil
+
+      # Performs the step's turn-based actions. May set a pending decision; in that
+      # case the decision calls engine.turn_based_actions_done! when finished.
+      def begin(engine)
+        engine.turn_based_actions_done!
+      end
+    end
+
+    # CR 502: phasing (502.1), then the active player's permanents untap (502.3), some by their choice
+    # (Engine::TurnStructure); no priority (502.4).
+    class Untap < Step
+      def priority? = false
+      def begin(engine) = engine.begin_untap_step!
+    end
+
+    # CR 504: the active player draws. In a two-player game the starting player skips the whole
+    # draw step of their first turn (CR 103.8a): no draw, no priority, no "draw step" triggers.
+    class Draw < Step
+      def skip?(engine) = engine.state.then { it.turn == 1 && it.active == it.starting_player }
+
+      def begin(engine)
+        engine.draw!(engine.state.active)
+        engine.turn_based_actions_done!
+      end
+    end
+
+    # CR 505.4 / 715.3c: as the precombat main phase begins, the active player puts a
+    # lore counter on each Saga they control with one or more chapter abilities.
+    class PrecombatMain < Step
+      def begin(engine)
+        engine.add_lore_counters!(engine.state.active)
+        engine.turn_based_actions_done!
+      end
+    end
+
+    # CR 508.8: if no creatures were declared as attackers, declare blockers and combat damage are skipped.
+    class CombatStepAfterAttackers < Step
+      def skip?(engine) = engine.state.attacks_declared.zero?
+    end
+
+    # CR 508.1: the active player declares attackers (a turn-based action).
+    class DeclareAttackers < Step
+      def begin(engine) = engine.begin_declare_attackers!
+    end
+
+    # CR 509.1: the defending player declares blockers.
+    class DeclareBlockers < CombatStepAfterAttackers
+      def begin(engine) = engine.begin_declare_blockers!
+    end
+
+    # CR 510: combat damage is assigned and dealt simultaneously.
+    class CombatDamage < CombatStepAfterAttackers
+      def begin(engine) = engine.begin_combat_damage!
+    end
+
+    # CR 514: discard to maximum hand size, then end "until end of turn" effects; no priority.
+    class Cleanup < Step
+      def priority? = false
+
+      # CR 514.2: remove marked damage and end "until end of turn" effects (control returns first).
+      def finish(engine)
+        engine.revert_temporary_control!
+        engine.cleanup_turn!
+      end
+
+      # CR 514.1 / 402.2: discard down to the maximum hand size, if the player has one.
+      def begin(engine)
+        max = engine.max_hand_size(engine.state.active)
+        excess = max ? engine.active_player.hand.size - max : 0
+        if excess.positive?
+          engine.ask!("kind" => "discard", "player" => engine.state.active, "count" => excess)
+        else
+          engine.turn_based_actions_done!
+        end
+      end
+    end
+
+    ORDER = [
+      Untap.new(:untap, :beginning),
+      Step.new(:upkeep, :beginning),
+      Draw.new(:draw, :beginning),
+      PrecombatMain.new(:precombat_main, :precombat_main),
+      Step.new(:beginning_of_combat, :combat),
+      DeclareAttackers.new(:declare_attackers, :combat),
+      DeclareBlockers.new(:declare_blockers, :combat),
+      CombatDamage.new(:combat_damage, :combat),
+      Step.new(:end_of_combat, :combat),
+      Step.new(:postcombat_main, :postcombat_main),
+      Step.new(:end, :ending),
+      Cleanup.new(:cleanup, :ending)
+    ].freeze
+    BY_NAME = ORDER.to_h { [it.name, it] }.freeze
+    MAIN_PHASE_STEPS = %i[precombat_main postcombat_main].freeze
+
+    def self.fetch(name) = BY_NAME.fetch(name.to_sym)
+    def self.index(name) = ORDER.index(fetch(name))
+  end
+end

data/lib/enjine/tokens.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Enjine
+  # Predefined tokens (CR 111.10): referenced by name from card data, e.g.
+  # {"create_token": {"token": "Treasure"}}. Other tokens are defined inline.
+  module Tokens
+    ANY_COLOR = %w[{W} {U} {B} {R} {G}].freeze
+
+    LIBRARY = {
+      # CR 111.10a: "{T}, Sacrifice this token: Add one mana of any color."
+      "Treasure" => { "name" => "Treasure", "types" => ["artifact"], "subtypes" => ["treasure"],
+                      "abilities" => ANY_COLOR.map { { "mana" => { "cost" => %w[tap sacrifice], "produce" => it } } } },
+      # CR 111.10f: "{2}, Sacrifice this token: Draw a card."
+      "Clue" => { "name" => "Clue", "types" => ["artifact"], "subtypes" => ["clue"],
+                  "abilities" => [{ "activated" => { "cost" => [{ "mana" => "{2}" }, "sacrifice"],
+                                                     "effects" => [{ "draw" => { "amount" => 1 } }] } }] },
+      # CR 111.10b: "{2}, {T}, Sacrifice this token: You gain 3 life."
+      "Food" => { "name" => "Food", "types" => ["artifact"], "subtypes" => ["food"],
+                  "abilities" => [{ "activated" => { "cost" => [{ "mana" => "{2}" }, "tap", "sacrifice"],
+                                                     "effects" => [{ "gain_life" => { "amount" => 3 } }] } }] }
+    }.freeze
+
+    def self.fetch(name) = LIBRARY[name]
+  end
+end