enjine 0.1.0

data/lib/enjine/verify.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "enjine/deck_builder"
+
+module Enjine
+  # Checks a folder of card data (require "enjine/verify"): every JSON file below `dir`, each a card or an
+  # array of cards. It validates every card, builds random decks from the valid ones (one per color and color
+  # pair the pool supports, plus decks that each include a handful of cards, so every card is in some deck),
+  # plays rules-monitored games between them (Agents::Busy and Agents::Random seats, export/import round
+  # trips), and records which cards were used: cast, played, activated, or had an ability trigger or resolve.
+  # Cards still unused get decks of their own, each seated twice, for up to ROUNDS rounds in all.
+  #
+  #   report = Enjine::Verify.new("cards/", games: 20, seed: 1).run
+  #   report["ok"]                   # => false if a card is invalid, a rules finding occurred or the engine raised
+  #   puts Enjine::Verify.text(report)
+  #
+  # Same folder, games and seed: same report.
+  class Verify
+    TYPES = %w[creature instant sorcery artifact enchantment land planeswalker battle kindred].freeze
+    SPELLS_PER_DECK = 6
+    LANDS_PER_DECK = 3
+    ROUNDS = 4
+    ROUNDTRIP_EVERY = 97
+    # Tiny pools still make decks: no outlier land counts, but basics may fill every slot the cards can't.
+    PROFILE = { outlier_chance: 0, lands: { outliers: 20..Deck::MIN_SIZE } }.freeze
+    PAIRINGS = [%i[busy busy], %i[busy random], %i[random busy]].freeze
+
+    # One distinct card: where it was first seen, its type names, its definition (nil if invalid).
+    Card = Data.define(:name, :file, :index, :types, :definition, :errors)
+
+    def initialize(dir, games: 10, seed: 0, max_decisions: 20_000)
+      raise ArgumentError, "#{dir}: not a directory" unless File.directory?(dir)
+
+      @dir = dir
+      @games = games
+      @seed = seed
+      @max_decisions = max_decisions
+    end
+
+    def run
+      @cards = {}
+      @invalid = []
+      @used = Hash.new(0)
+      @results = { findings: [], errors: [], unfinished: [], games: 0, decisions: 0 }
+      Dir.glob("**/*.json", base: @dir).sort.each { load_file(it) }
+      play_rounds unless valid.empty?
+      report
+    end
+
+    # A readable report.
+    def self.text(report)
+      out = ["Enjine #{report["engine_version"]} (Comprehensive Rules #{report["rules_version"]}) — seed #{report["seed"]}",
+             "#{report["cards"]} valid cards, #{report["games"]} games, #{report["decisions"]} decisions", "",
+             "type            total  valid  exercised"]
+      report["types"].each { |type, n| out << format("%-14s %6d %6d %10d", type, n["total"], n["valid"], n["exercised"]) }
+      section(out, "Invalid cards", report["invalid"]) do
+        "#{it["file"]}#{"[#{it["index"]}]" if it["index"]} #{it["name"]}: #{it["errors"].join("; ")}"
+      end
+      section(out, "Never exercised", report["unexercised"]) { "#{it["name"]} (#{it["file"]})" }
+      section(out, "Rules monitor findings", report["findings"]) { "seed #{it["seed"]}: #{it["message"]} — #{it["decks"].join(" vs ")}" }
+      section(out, "Engine errors", report["errors"]) { "seed #{it["seed"]}: #{it["message"]}" }
+      section(out, "Unfinished games (decision cap)", report["unfinished"]) { "seed #{it["seed"]}" }
+      out << "" << (report["ok"] ? "OK" : "FAILED")
+      out.join("\n")
+    end
+
+    def self.section(out, title, rows, &)
+      return if rows.empty?
+
+      out << "" << "#{title} (#{rows.size}):"
+      rows.each { out << "  #{yield it}" }
+    end
+    private_class_method :section
+
+    private
+
+    def valid = @cards.values.select(&:definition)
+
+    # --- loading --------------------------------------------------------------------------------------
+
+    def load_file(file)
+      data = JSON.parse(File.read(File.join(@dir, file)))
+      data.is_a?(Array) ? data.each_with_index { |card, i| add(file, i, card) } : add(file, nil, data)
+    rescue JSON::ParserError => e
+      @invalid << invalid(file, nil, nil, [], ["not valid JSON: #{e.message.lines.first.strip}"])
+    end
+
+    def add(file, index, data)
+      return @invalid << invalid(file, index, nil, [], ["a card must be a JSON object"]) unless data.is_a?(Hash)
+
+      defn = CardDefinition.from_h(data)
+      held = @cards[defn.id]
+      return @cards[defn.id] = Card.new(defn.name, file, index, type_names(data), defn, []) if held.nil?
+      return if held.definition == defn # a reprint: the same card
+
+      @invalid << invalid(file, index, defn.name, type_names(data), ["differs from #{defn.name} in #{held.file}"])
+    rescue InvalidCardDefinition => e
+      @invalid << invalid(file, index, data["name"], type_names(data), e.errors)
+    end
+
+    def invalid(file, index, name, types, errors) = Card.new(name, file, index, types, nil, errors)
+
+    # Type names from the raw data, so an invalid card still counts: its own, or all its faces'.
+    def type_names(data)
+      types = [data, *(data["faces"].is_a?(Array) ? data["faces"] : [])].flat_map { it.is_a?(Hash) ? Array(it["types"]) : [] }
+      types.grep(String).map(&:downcase).uniq
+    end
+
+    # --- decks and games ------------------------------------------------------------------------------
+
+    def play_rounds
+      @rng = Rng.from_seed(@seed)
+      @builder = DeckBuilder.new(valid.map(&:definition))
+      decks = coverage_decks(valid) + variety_decks
+      ROUNDS.times do |round|
+        play(decks, round.zero? ? @games : decks.size)
+        rest = valid.reject { @used.key?(it.definition.id) }
+        break if rest.empty?
+
+        decks = coverage_decks(rest)
+      end
+    end
+
+    # One deck per color and color pair the pool can fill.
+    def variety_decks
+      combos = Mana::COLORS.combination(1).to_a + Mana::COLORS.combination(2).to_a
+      combos.filter_map do |colors|
+        @builder.build(colors: colors, seed: @rng.rand(2**31), profile: PROFILE)
+      rescue DeckBuilder::NotEnoughCards
+        nil
+      end
+    end
+
+    # Decks that together include every card in `cards`: grouped by the colors each needs (a land: the colors it
+    # makes), a few spells and lands per deck. Colorless groups get random colors.
+    def coverage_decks(cards)
+      defns = cards.map(&:definition).reject { DeckBuilder.basic?(it) } # every deck has them
+      groups = defns.group_by { it.land? ? DeckBuilder.produced_colors(it) : DeckBuilder.required_colors(it) }
+      groups.sort_by { |colors, _| colors.join }.flat_map do |colors, defns|
+        lands, spells = defns.partition(&:land?)
+        spell_chunks = spells.each_slice(SPELLS_PER_DECK).to_a
+        land_chunks = lands.each_slice(LANDS_PER_DECK).to_a
+        Array.new([spell_chunks.size, land_chunks.size].max) do |i|
+          including = (spell_chunks[i] || []) + (land_chunks[i] || [])
+          coverage_deck(colors.empty? ? :any : colors, including.map(&:id))
+        end
+      end.compact
+    end
+
+    def coverage_deck(colors, including)
+      @builder.build(colors: colors, seed: @rng.rand(2**31), profile: PROFILE, including: including)
+    rescue Error, ArgumentError => e
+      @results[:errors] << { "seed" => nil, "message" => "building a deck with #{including.join(", ")}: #{e.message}" }
+      nil
+    end
+
+    # Seats every deck at least once, and plays at least `minimum` games.
+    def play(decks, minimum)
+      return if decks.empty?
+
+      [minimum, (decks.size + 1) / 2].max.times do |i|
+        game_seed = @seed + @results[:games]
+        @results[:games] += 1
+        play_game([decks[(2 * i) % decks.size], decks[((2 * i) + 1) % decks.size]], game_seed)
+      end
+    end
+
+    # The rules monitor checks every decision; Snapshot invariants are the fuzz task's (they nearly halve the speed).
+    def play_game(decks, seed)
+      players = decks.each_with_index.map { |deck, i| Player.new(name: "p#{i + 1}", deck: deck) }
+      game = Setup.new(*players).new_game(seed: seed)
+      game.subscribe { use(it) }
+      @results[:decisions] += Fuzz.play(game, seats(game, seed), seed, @max_decisions, ROUNDTRIP_EVERY, false, RulesMonitor.new(game))
+    rescue Fuzz::Failure => e
+      @results[:decisions] += e.decisions
+      failure(e, decks)
+    rescue StandardError => e # setting the game up, before Fuzz.play wraps errors
+      @results[:errors] << { "seed" => seed, "message" => "#{e.class}: #{e.message}" }
+    end
+
+    def failure(error, decks)
+      row = { "seed" => error.seed, "decisions" => error.decisions, "message" => error.message,
+              "decks" => decks.map { it["description"] } }
+      case error.kind
+      when :finding then @results[:findings] << row
+      when :stall then @results[:unfinished] << row
+      else @results[:errors] << row
+      end
+    end
+
+    # An agent for each seat, by the game's place in PAIRINGS.
+    def seats(game, seed)
+      agents = game.names.zip(PAIRINGS[seed % PAIRINGS.size]).to_h do |name, kind|
+        [name, (kind == :busy ? Agents::Busy : Agents::Random).new(seed: seed + name.sum)]
+      end
+      Seats.new(agents)
+    end
+
+    Seats = Data.define(:agents) do
+      def choose(decision) = agents.fetch(decision.player).choose(decision)
+    end
+
+    def use(event)
+      card = case event
+             when Events::SpellCast, Events::AbilityActivated, Events::AbilityTriggered, Events::Resolved then event.card
+             when Events::ZoneChanged then event.card if event.reason == "play_land"
+             end
+      @used[card] += 1 if card
+    end
+
+    # --- report ---------------------------------------------------------------------------------------
+
+    def report
+      unused = valid.reject { @used.key?(it.definition.id) }
+      { "engine_version" => VERSION, "rules_version" => RULES_VERSION, "seed" => @seed, "cards" => valid.size,
+        "games" => @results[:games], "decisions" => @results[:decisions], "types" => type_counts,
+        "invalid" => @invalid.map { { "file" => it.file, "index" => it.index, "name" => it.name, "errors" => it.errors } },
+        "unexercised" => unused.sort_by(&:name).map { { "name" => it.name, "file" => it.file } },
+        "findings" => @results[:findings], "errors" => @results[:errors], "unfinished" => @results[:unfinished],
+        "ok" => @invalid.empty? && @results[:findings].empty? && @results[:errors].empty? }
+    end
+
+    def type_counts
+      all = @cards.values + @invalid
+      types = (TYPES & all.flat_map(&:types)) + (all.flat_map(&:types).uniq - TYPES).sort
+      types.to_h do |type|
+        cards = all.select { it.types.include?(type) }
+        exercised = cards.count { it.definition && @used.key?(it.definition.id) }
+        [type, { "total" => cards.size, "valid" => cards.count(&:definition), "exercised" => exercised }]
+      end
+    end
+  end
+end

data/lib/enjine/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Enjine
+  VERSION = "0.1.0"
+  # Comprehensive Rules document this engine follows.
+  RULES_VERSION = "2026-11-06"
+end

data/lib/enjine/view.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Enjine
+  # Builds what a viewer may see of a game. A viewer is a player name or :observer.
+  #
+  # A player sees public zones, their own hand, and counts of hidden zones.
+  # The observer sees everything, including both hands and library order.
+  module View
+    module_function
+
+    def build(engine, viewer)
+      state = engine.state
+      observer = viewer == :observer
+      {
+        "viewer" => observer ? "observer" : viewer,
+        "turn" => state.turn,
+        "active" => state.active && engine.name(state.active),
+        "step" => state.step&.to_s,
+        "phase" => state.step && Steps.fetch(state.step).phase.to_s,
+        "priority" => state.priority && engine.name(state.priority),
+        "players" => state.players.map { |pl| player_view(engine, pl, observer || pl.name == viewer, observer) },
+        "battlefield" => state.battlefield.map { object_view(engine, it) },
+        "stack" => state.stack.map { object_view(engine, it) },
+        "exile" => state.exile.map { exiled_view(engine, it, viewer) },
+        "phased_out" => state.phased_out.map { object_view(engine, it) },
+        "command" => engine.emblems.map { emblem_view(engine, it) },
+        "pending" => pending_view(engine, viewer),
+        "result" => state.result&.dup,
+        "effects" => state.effects.map { it.except("controller").merge("controller" => engine.name(it["controller"])) },
+        "delayed_triggers" => state.delayed_triggers.map { delayed_view(engine, it) }
+      }
+    end
+
+    # An emblem in the command zone (CR 114): public, with its owner and abilities.
+    def emblem_view(engine, obj)
+      { "id" => obj.id, "kind" => "emblem", "owner" => engine.name(obj.owner),
+        "abilities" => engine.chars(obj).abilities.map { it.ability.to_s } }
+    end
+
+    # A delayed triggered ability waiting for its event (CR 603.7): public, like the spell that made it.
+    def delayed_view(engine, entry)
+      defn = engine.catalog.fetch(entry["card"])
+      { "controller" => engine.name(entry["controller"]), "card" => defn.name, "ability" => defn.ability(entry["ability"]).to_s }
+    end
+
+    # How a mana kept apart in the pool may be spent and how long it stays (CR 106.6, 702.189a).
+    def pool_entry_text(entry)
+      parts = [entry["spend_only"] && Mechanics::SpendOnly.from_data(entry["spend_only"]).to_s,
+               entry["until"] && "you don't lose this mana until end of combat"]
+      parts.compact.join("; ")
+    end
+
+    def player_view(engine, player, sees_hand, sees_library)
+      view = {
+        "name" => player.name, "life" => player.life, "poison" => player.poison,
+        "mana_pool" => player.mana_pool.reject { |_, n| n.zero? }.transform_keys(&:to_s),
+        "restricted_mana" => player.restricted_mana.map { it.merge("text" => View.pool_entry_text(it)) },
+        "lands_played" => player.lands_played, "mulligans" => player.mulligans,
+        "hand_count" => player.hand.size, "library_count" => player.library.size, "outside_count" => player.outside.size,
+        "graveyard" => player.graveyard.map { object_view(engine, it) }
+      }
+      view.merge!(public_extras(player))
+      view["hand"] = player.hand.map { object_view(engine, it) } if sees_hand
+      view["outside"] = outside_view(engine, player) if sees_hand # CR 400.11a: only its owner knows their sideboard
+      view["library"] = player.library.map { object_view(engine, it) } if sees_library
+      view["library_top"] = object_view(engine, player.library.first) if sees_hand && looks_at_top?(engine, player)
+      view
+    end
+
+    # Public player state present only when there is some: speed (CR 702.179), designations (CR 702.195b), player
+    # counters other than poison (CR 122.1) and the artifact sources of pool mana (Engine::ManaSources#add_mana!).
+    def public_extras(player)
+      { "speed" => player.speed, "designations" => player.designations&.dup, "counters" => player.counters&.dup,
+        "pool_sources" => Snapshot.deep_copy(player.pool_sources) }.reject { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
+    end
+
+    # The cards a player owns outside the game (CR 400.11a): not objects, so no ids (CR 400.11).
+    def outside_view(engine, player)
+      player.outside.map do |card|
+        defn = engine.catalog.fetch(card)
+        { "card" => card, "name" => defn.name, "type_line" => defn.type_line, "mana_cost" => defn.mana_cost&.to_s }.compact
+      end
+    end
+
+    # CR 401.5: an effect letting a player look at the top card of their library shows it to that player only.
+    def looks_at_top?(engine, player)
+      !player.library.empty? && engine.may_look_at_top?(engine.state.players.index(player))
+    end
+
+    # CR 406.3: a card exiled face down shows only that it's face down, except to an observer and to the
+    # players who may look at it.
+    def exiled_view(engine, id, viewer)
+      obj = engine.object(id)
+      return object_view(engine, id) unless engine.face_down?(obj)
+
+      hidden = { "id" => id, "face_down" => true, "owner" => engine.name(obj.owner) }
+      looks = viewer == :observer || obj.memory.fetch("may_look", []).map { engine.name(it) }.include?(viewer)
+      looks ? object_view(engine, id).merge(hidden) : hidden
+    end
+
+    def object_view(engine, id)
+      obj = engine.object(id)
+      defn = engine.definition(obj)
+      return ability_view(engine, obj, defn) if obj.ability?
+
+      view = { "id" => id, "card" => obj.card, "name" => defn.name, "type_line" => defn.type_line,
+               "owner" => engine.name(obj.owner) }
+      view["mana_cost"] = defn.mana_cost.to_s if defn.mana_cost
+      view["keywords"] = defn.keywords.map(&:to_s) unless defn.keywords.empty?
+      view["rules_text"] = defn.rules_text if defn.rules_text
+      case obj.zone
+      when :battlefield then permanent_view(engine, obj, defn, view)
+      when :stack then view.merge!("controller" => engine.name(obj.controller), "targets" => (obj.targets || []).flatten)
+      when :phased_out # public: still on the battlefield, treated as though it doesn't exist (CR 702.26b)
+        view.merge!("controller" => engine.name(obj.controller), "tapped" => obj.tapped, "phased_out" => true)
+        view["attached_to"] = obj.attached_to if obj.attached_to
+      end
+      view
+    end
+
+    def permanent_view(engine, obj, defn, view)
+      view["controller"] = engine.name(obj.controller)
+      view["tapped"] = obj.tapped
+      view["name"] = engine.chars(obj).name # "named Humble Merchant" (CR 612.8)
+      keywords = engine.chars(obj).keywords # printed plus granted (CR 613.1f), minus removed
+      keywords.empty? ? view.delete("keywords") : view["keywords"] = keywords.map(&:to_s)
+      if engine.chars(obj).creature? # e.g. a Spacecraft with enough charge counters (CR 722.2b)
+        power, toughness = engine.power_toughness(obj)
+        view.merge!("power" => power, "toughness" => toughness, "damage" => obj.damage,
+                    "summoning_sick" => engine.summoning_sick_for_tap?(obj))
+      end
+      view["loyalty"] = engine.loyalty(obj) if defn.planeswalker?
+      view["counters"] = obj.counters.reject { |_, n| n.zero? } unless obj.counters.values.all?(&:zero?)
+      view["attached_to"] = obj.attached_to if obj.attached_to
+      view["transformed"] = true if engine.transformed?(obj) # CR 701.27h
+      view["prepared"] = true if engine.prepared?(obj) # CR 723.3a
+      if (attack = engine.attackers[obj.id])
+        view["attacking"] = attack["target"]
+      end
+      view["blocking"] = engine.state.blockers[obj.id] if engine.state.blockers.key?(obj.id)
+    end
+
+    def ability_view(engine, obj, defn)
+      ability = defn.ability(obj.ability)
+      { "id" => obj.id, "card" => obj.card, "name" => "#{defn.name} ability", "kind" => "ability",
+        "ability" => obj.ability, "loyalty_cost" => ability.loyalty_cost, "source" => obj.source,
+        "controller" => engine.name(obj.controller), "targets" => (obj.targets || []).flatten }.compact
+    end
+
+    def pending_view(engine, viewer)
+      pending = engine.state.pending
+      return nil unless pending
+
+      decider = engine.name(pending["player"])
+      view = pending.merge("player" => decider)
+      return view.except("choices") unless viewer == :observer || viewer == decider # e.g. the cards a search sees
+
+      view["options"] = engine.options.map { it.transform_keys(&:to_s) }
+      view
+    end
+  end
+end

data/lib/enjine.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "enjine/version"
+require_relative "enjine/errors"
+require_relative "enjine/rng"
+require_relative "enjine/mana"
+require_relative "enjine/primitive"
+require_relative "enjine/mechanics"
+# The shared bases load first; a mechanic file requires any other mechanic it builds on.
+%w[selector values effects/base triggers/base filters/base costs/base abilities/stack_abilities].each do |f|
+  require_relative "enjine/mechanics/#{f}"
+end
+Dir[File.join(__dir__, "enjine/mechanics/**/*.rb")].each { |f| require f }
+require_relative "enjine/characteristics"
+require "json"
+require "digest"
+require_relative "enjine/tokens"
+require_relative "enjine/card_definition"
+require_relative "enjine/catalog"
+require_relative "enjine/deck"
+require_relative "enjine/player"
+require_relative "enjine/state"
+require_relative "enjine/events"
+require_relative "enjine/steps"
+require_relative "enjine/frames"
+require_relative "enjine/decisions"
+Dir[File.join(__dir__, "enjine/decisions/*.rb")].each { |f| require f }
+require_relative "enjine/actions"
+%w[pass play_land activate_mana_ability cast special_action].each { |f| require_relative "enjine/actions/#{f}" }
+require_relative "enjine/replacements"
+require_relative "enjine/engine"
+Dir[File.join(__dir__, "enjine/engine/**/*.rb")].each { |f| require f }
+require_relative "enjine/snapshot"
+require_relative "enjine/history"
+require_relative "enjine/view"
+require_relative "enjine/game"
+require_relative "enjine/setup"
+
+# Enjine: a deterministic, rules-accurate Magic: The Gathering engine.
+# It knows no cards: every card arrives as data, in a deck or a DeckBuilder pool.
+module Enjine
+end
+require_relative "enjine/agents/random"
+require_relative "enjine/agents/busy"
+require_relative "enjine/fuzz"
+require_relative "enjine/rules_monitor"