enjine 0.1.0

data/lib/enjine/deck_builder.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+require "enjine"
+
+module Enjine
+  # Builds random, legal, *plausibly shaped* constructed decks from a card pool it keeps in
+  # memory (require "enjine/deck_builder"). It knows nothing of sets: the pool is whatever cards
+  # you give it. No synergy: just the proportions every 60-card deck shares, drawn as ranges
+  # with occasional outliers.
+  #
+  #   builder = Enjine::DeckBuilder.new(cards)        # card data blocks and/or CardDefinitions
+  #   builder.build(colors: %w[W U], seed: 7)         # explicit colors
+  #   builder.build(colors: 2, seed: 8)               # two random colors
+  #   builder.build(seed: 9, size: 80)                # :any: a random number of colors (profile :random_colors)
+  #   builder.build(colors: "G", seed: 3, including: ["Giant Growth"])   # these cards, then random ones
+  #
+  # A pool entry may also be {"card" => card, "count" => n}: a collection you own, so a deck
+  # never holds more than n copies (and never more than CR 100.2a allows). Basic lands are always
+  # available: the pool's own, else built-in ones.
+  #
+  # #build returns a deck document ({"name", "description", "cards", "main"}) that
+  # Enjine::Player.new(name:, deck:) accepts. Same pool, arguments and seed, same deck: randomness
+  # comes only from Enjine::Rng, and the pool is sorted by card id, so its order doesn't matter.
+  class DeckBuilder
+    # The pool and colors don't have enough playable cards. #details says what was missing.
+    class NotEnoughCards < Error
+      attr_reader :details
+
+      def initialize(message, details)
+        @details = details.freeze
+        super(message)
+      end
+    end
+
+    # Default deck shape. Every count is for 60 cards and scales linearly with `size:`.
+    # Counts are drawn from `range` with a triangular weight peaking at `center`; with
+    # probability `outlier_chance` (percent) a count is instead drawn uniformly from
+    # the wider `outliers` range, so the odd 20-land aggro or 27-land control deck appears.
+    DEFAULT_PROFILE = {
+      # 60-card constructed decks overwhelmingly play 22-26 lands (24 is the classic
+      # "40%" baseline); very low curves dip to ~20, heavy control reaches ~27.
+      lands: { range: 22..26, center: 24, outliers: 20..27 },
+      # Creature counts vary the most between archetypes: ~14 for midrange/control
+      # shells, up to ~24 for creature aggro; spell-heavy or creature-only extremes are rarer.
+      creatures: { range: 14..24, center: 18, outliers: 10..28 },
+      # Non-creature spells (instants, sorceries, artifacts, enchantments,
+      # planeswalkers) take the remaining slots.
+      outlier_chance: 10,
+      # Relative weight of each mana value when choosing the next distinct card
+      # (0 counts as 1, 6 means 6+): most cards cost 1-3, fewer 4, few 5+.
+      curve: { 1 => 16, 2 => 28, 3 => 24, 4 => 16, 5 => 9, 6 => 7 },
+      # Copies of each distinct non-basic card: constructed decks are mostly
+      # 4-ofs, with some 2-3-ofs and a few singletons.
+      copies: { 4 => 50, 3 => 20, 2 => 20, 1 => 10 },
+      # Non-basic land copies (when the pool has lands that fit the colors):
+      # a mono-color deck plays a few utility lands, a multicolor deck several duals.
+      nonbasic_lands: { mono: 0..4, multi: 2..8 },
+      # Number of colors when `colors: :any`: two-color decks are the most common.
+      random_colors: { 1 => 30, 2 => 50, 3 => 20 },
+      # In multicolor decks, the % chance that the next card is drawn from the least
+      # represented chosen color (by colored mana symbols), so no chosen color ends up a
+      # token splash. 0 disables balancing; 100 forces strict balance.
+      color_balance: 75
+    }.freeze
+
+    BASIC_LAND_NAMES = { W: "Plains", U: "Island", B: "Swamp", R: "Mountain", G: "Forest" }.freeze
+    # Used when the pool has no basic land of a color (CR 305.6: the land type grants the mana ability).
+    BASIC_LANDS = BASIC_LAND_NAMES.transform_values do |name|
+      { "name" => name, "types" => ["land"], "supertypes" => ["basic"], "subtypes" => [name.downcase] }.freeze
+    end.freeze
+    BASE_SIZE = 60
+
+    # The colors of a card: the colored and hybrid symbols in its mana cost (CR 105.2, 202.2, 202.2d),
+    # in WUBRG order. A hybrid card needs both of its colors in the deck.
+    def self.colors_of(definition) = definition.mana_cost&.colors || []
+
+    # The colors a deck must be able to produce to use a card: its colors plus the colored
+    # symbols in its activation costs, so an off-color activated ability never sneaks in.
+    def self.required_colors(definition)
+      costs = definition.abilities.flat_map { it.respond_to?(:costs) ? it.costs : [] }.select { it.respond_to?(:mana_cost) }
+      symbols = costs.flat_map { it.mana_cost.colored.keys }
+      Mana::COLORS.select { colors_of(definition).include?(it) || symbols.include?(it) }
+    end
+
+    # The colors of mana a permanent's mana abilities produce, in WUBRG order ({C} excluded).
+    def self.produced_colors(definition)
+      produced = definition.mana_abilities.flat_map { it.produce || it.colors.map(&:to_sym) }
+      Mana::COLORS.select { produced.include?(it) }
+    end
+
+    # One of the five basic lands every deck draws its basics from (Wastes is not: no deck color makes it).
+    def self.basic?(definition) = BASIC_LAND_NAMES.value?(definition.name) && definition.supertype?(:basic)
+
+    # Colorless cards fit every deck (CR 105.2c); others fit when all their colors are deck colors.
+    def self.fits?(definition, colors)
+      required_colors(definition).all? { colors.include?(it) }
+    end
+
+    # Normalizes "WU", %w[w u] or [:W, :U] to [:W, :U] in WUBRG order.
+    def self.parse_colors(value)
+      letters = value.is_a?(Array) ? value.map(&:to_s) : value.to_s.delete(", ").chars
+      symbols = letters.map { it.strip.upcase.to_sym }
+      bad = symbols - Mana::COLORS
+      raise ArgumentError, "unknown color #{bad.join(", ")} (use W U B R G)" unless bad.empty?
+      raise ArgumentError, "choose at least one color" if symbols.empty?
+
+      Mana::COLORS.select { symbols.include?(it) }
+    end
+
+    # The pool's cards, one CardDefinition per card, sorted by id.
+    attr_reader :cards
+
+    # pool: card data blocks, CardDefinitions, or {"card" => either, "count" => copies owned}.
+    # Entries for the same card add up; a card listed once without a count has no cap.
+    def initialize(pool)
+      definitions = {}
+      owned = Hash.new(0)
+      uncapped = []
+      Array(pool).each do |entry|
+        card, count = pool_entry(entry)
+        defn = CardDefinition.from_h(card)
+        held = definitions[defn.id] ||= defn
+        raise CatalogConflict, "two different definitions for #{defn.name.inspect} (#{defn.id})" unless held == defn
+
+        count ? owned[defn.id] += count : uncapped << defn.id
+      end
+      @cards = definitions.values.sort_by(&:id).freeze
+      @by_id = definitions.freeze
+      @owned = owned.except(*uncapped).freeze
+    end
+
+    # seed:    seed for Enjine::Rng
+    # colors:  %w[W U], "WU", an Integer 1-5 (that many random colors), or :any (random count, see random_colors)
+    # size:    deck size, at least 60; every profile count scales with it
+    # profile: overrides for DEFAULT_PROFILE, merged key by key
+    # including: pool cards (names or ids) the deck must hold, as many copies as allowed up to 4; they must fit
+    #            the colors (a land: produce only deck colors). They define the deck, so a chosen color then
+    #            needs no card of its own: it may only bring basics.
+    def build(seed:, colors: :any, size: BASE_SIZE, profile: {}, including: [])
+      Draft.new(self, seed: seed, colors: colors, size: size, profile: profile, including: including).deck
+    end
+
+    # Copies of a card the pool holds: nil when uncapped, 0 when it isn't in the pool.
+    def count(card)
+      id = CardDefinition.slug(card)
+      @by_id.key?(id) ? @owned[id] : 0
+    end
+
+    def definition(id) = @by_id.fetch(id)
+
+    private
+
+    def pool_entry(entry)
+      return [entry, nil] unless entry.is_a?(Hash) && (entry.key?("card") || entry.key?(:card))
+
+      entry = entry.transform_keys(&:to_s)
+      count = entry["count"]
+      unless count.is_a?(Integer) && count.positive?
+        raise ArgumentError,
+              "pool entry count must be a positive Integer, got #{count.inspect}"
+      end
+
+      [entry["card"], count]
+    end
+
+    # One #build call: the seed-dependent choices for one deck.
+    class Draft
+      def initialize(builder, seed:, colors:, size:, profile:, including:)
+        raise ArgumentError, "size must be an Integer of at least #{Deck::MIN_SIZE}" unless size.is_a?(Integer) && size >= Deck::MIN_SIZE
+
+        @builder = builder
+        @pool = builder.cards
+        @rng = Rng.from_seed(seed)
+        @seed = seed
+        @size = size
+        @profile = merge_profile(profile)
+        @colors = resolve_colors(colors)
+        @creatures = {}
+        @others = {}
+        @lands = {}
+        include_cards(including)
+      end
+
+      def deck
+        check_colors! if @creatures.empty? && @others.empty? && @lands.empty?
+        lands = [scaled(sample(@profile[:lands])), @lands.values.sum].max
+        creatures = scaled(sample(@profile[:creatures])).clamp(0, @size - lands)
+        lands += fill_spells(lands, creatures)
+        document(lands)
+      end
+
+      private
+
+      # --- inputs -------------------------------------------------------------------------------------
+
+      def merge_profile(overrides)
+        unknown = overrides.keys.map(&:to_sym) - DEFAULT_PROFILE.keys
+        raise ArgumentError, "unknown profile keys: #{unknown.join(", ")}" unless unknown.empty?
+
+        DEFAULT_PROFILE.to_h do |key, default|
+          value = overrides.fetch(key, overrides.fetch(key.to_s, default))
+          [key, default.is_a?(Hash) ? default.merge(value) : value]
+        end
+      end
+
+      def resolve_colors(value)
+        case value
+        when :any, "any", nil then random_colors(weighted(@profile[:random_colors]))
+        when Integer then random_colors(value)
+        when /\A\d\z/ then random_colors(value.to_i)
+        else DeckBuilder.parse_colors(value)
+        end
+      end
+
+      # A uniformly random color combination among those the pool can actually fill.
+      def random_colors(count)
+        raise ArgumentError, "a deck has 1 to 5 colors, not #{count}" unless (1..5).cover?(count)
+
+        combos = Mana::COLORS.combination(count).to_a
+        viable = combos.select { viable?(it) }
+        return viable[@rng.rand(viable.size)] unless viable.empty?
+
+        combos.max_by { capacity(spells_for(it)) } # nothing fits: the closest one, which then explains what's missing
+      end
+
+      def viable?(colors)
+        spells = spells_for(colors)
+        colors.all? { |c| spells.any? { DeckBuilder.colors_of(it).include?(c) } } &&
+          capacity(spells) >= @size - scaled(@profile[:lands][:outliers].max)
+      end
+
+      def spells_for(colors) = @pool.select { it.castable? && DeckBuilder.fits?(it, colors) }
+      def capacity(definitions) = definitions.sum { limit(it) }
+
+      # Most copies of a card the deck may hold: 4 (CR 100.2a) or any number if exempt, and never
+      # more than the pool holds.
+      def limit(definition) = [definition.deck_limit || @size, @builder.count(definition.id) || @size].min
+
+      # Puts each required card in the deck with as many copies as it may hold, up to 4 (basics come anyway).
+      def include_cards(cards)
+        cards.each do |card|
+          id = CardDefinition.slug(card)
+          raise ArgumentError, "#{card.inspect} is not in the pool" if @builder.count(id)&.zero?
+
+          defn = @builder.definition(id)
+          fits = defn.land? ? DeckBuilder.produced_colors(defn).all? { @colors.include?(it) } : DeckBuilder.fits?(defn, @colors)
+          raise ArgumentError, "#{defn.name} does not fit a #{@colors.join} deck" unless fits
+          next if DeckBuilder.basic?(defn) # every deck has its basics
+
+          group = if defn.land? then @lands
+                  else defn.creature? ? @creatures : @others
+                  end
+          group[id] = [limit(defn), Deck::MAX_COPIES].min
+        end
+      end
+
+      # --- spells -------------------------------------------------------------------------------------
+
+      # Fills the non-land slots. Scarcity, in order: more copies of chosen cards (up to 4),
+      # then the creature/other split moves, then up to the outlier land maximum. Returns extra lands.
+      def fill_spells(lands, creature_target)
+        creature_pool, other_pool = spells_for(@colors).partition(&:creature?)
+        others_target = @size - lands - creature_target
+        creatures = pick(creature_pool, creature_target, @creatures)
+        others = pick(other_pool, others_target + (creature_target - creatures), @others)
+        missing = @size - lands - creatures - others
+        missing -= pick(creature_pool, creatures + missing, @creatures) - creatures if missing.positive?
+        extra = missing.clamp(0, [scaled(@profile[:lands][:outliers].max) - lands, 0].max)
+        not_enough!(creature_pool, other_pool, lands + extra, missing - extra) if missing > extra
+        extra
+      end
+
+      # Adds distinct cards (by curve weight) to `chosen` until it holds `target` cards, then
+      # tops up copies. Returns the number of cards in `chosen`.
+      def pick(pool, target, chosen)
+        candidates = pool.reject { chosen.key?(it.id) }
+        filled = chosen.values.sum
+        missing_colors.each do |color|
+          colored = candidates.select { DeckBuilder.colors_of(it).include?(color) }
+          filled = take(colored.empty? ? nil : by_curve(colored), candidates, chosen, filled, target)
+        end
+        filled = take(by_curve(balanced(candidates)), candidates, chosen, filled, target) while filled < target && !candidates.empty?
+        top_up(chosen, filled, target)
+      end
+
+      def take(definition, candidates, chosen, filled, target)
+        return filled if definition.nil? || filled >= target
+
+        candidates.delete(definition)
+        copies = [weighted(@profile[:copies]), target - filled, limit(definition)].min
+        chosen[definition.id] = [copies, 1].max
+        filled + chosen[definition.id]
+      end
+
+      def top_up(chosen, filled, target)
+        while filled < target
+          open = chosen.keys.select { chosen[it] < limit(@builder.definition(it)) }
+          break if open.empty?
+
+          open.each do |id|
+            break if filled >= target
+
+            chosen[id] += 1
+            filled += 1
+          end
+        end
+        filled
+      end
+
+      # Candidates restricted to the least represented chosen color (see profile :color_balance).
+      def balanced(candidates)
+        return candidates if @colors.size < 2 || @rng.rand(100) >= @profile[:color_balance]
+
+        symbols = Hash.new(0)
+        (@creatures.to_a + @others.to_a).each do |id, n|
+          @builder.definition(id).mana_cost&.colored&.each { |color, k| symbols[color] += k * n }
+        end
+        weakest = @colors.min_by { [symbols[it], it] }
+        preferred = candidates.select { DeckBuilder.colors_of(it).include?(weakest) }
+        preferred.empty? ? candidates : preferred
+      end
+
+      # Multicolor decks start with one card of each color not yet represented.
+      def missing_colors
+        have = (@creatures.keys + @others.keys).flat_map { DeckBuilder.colors_of(@builder.definition(it)) }
+        @colors.size > 1 ? @colors - have : []
+      end
+
+      def by_curve(candidates)
+        buckets = candidates.group_by { it.mana_cost.mana_value.clamp(1, 6) }
+        weights = @profile[:curve].select { |mv, w| buckets.key?(mv) && w.positive? }
+        bucket = weights.empty? ? buckets.keys.min : weighted(weights)
+        cards = buckets.fetch(bucket)
+        cards[@rng.rand(cards.size)]
+      end
+
+      def not_enough!(creature_pool, other_pool, lands, missing)
+        details = base_details.merge(lands: lands, creatures_available: creature_pool.size, others_available: other_pool.size,
+                                     max_spell_copies: capacity(creature_pool + other_pool), missing: missing)
+        raise NotEnoughCards.new(
+          "cannot build a #{@size}-card #{@colors.join} deck from #{@pool.size} cards: only #{creature_pool.size} creature and " \
+          "#{other_pool.size} other non-land cards are playable in those colors (at most #{details[:max_spell_copies]} copies), " \
+          "#{missing} short of the #{@size - lands} non-land cards needed even with #{lands} lands. " \
+          "Add cards or colors, or lower the profile's ranges.", details
+        )
+      end
+
+      # Every deck color needs at least one playable card (a "WU" deck with no blue cards isn't one).
+      def check_colors!
+        lacking = colors_without_cards
+        return if lacking.empty?
+
+        raise NotEnoughCards.new(
+          "cannot build a #{@colors.join} deck from #{@pool.size} cards: none of them is a playable #{lacking.join(", ")} card",
+          base_details
+        )
+      end
+
+      def colors_without_cards
+        spells = spells_for(@colors)
+        @colors.reject { |c| spells.any? { DeckBuilder.colors_of(it).include?(c) } }
+      end
+
+      def base_details = { pool: @pool.size, colors: @colors.join, size: @size, colors_without_cards: colors_without_cards.join }
+
+      # --- lands --------------------------------------------------------------------------------------
+
+      def pick_nonbasic_lands(total)
+        pool = @pool.select { nonbasic_land?(it) }
+        range = @profile[:nonbasic_lands][@colors.size == 1 ? :mono : :multi]
+        want = [scaled(uniform(range)), total / 2].min.clamp(@lands.values.sum..)
+        chosen = @lands.dup
+        pool.reject! { chosen.key?(it.id) }
+        take(by_land_weight(pool), pool, chosen, chosen.values.sum, want) while chosen.values.sum < want && !pool.empty?
+        chosen
+      end
+
+      def nonbasic_land?(definition)
+        definition.land? && !definition.supertype?(:basic) && !definition.mana_abilities.empty? &&
+          DeckBuilder.produced_colors(definition).all? { @colors.include?(it) }
+      end
+
+      # Weight 4 for lands that produce two or more deck colors (duals), 2 for one color, 1 for colorless-only.
+      def by_land_weight(pool)
+        weights = pool.map { [1, 2, 4][DeckBuilder.produced_colors(it).size.clamp(0, 2)] }
+        roll = @rng.rand(weights.sum)
+        pool.each_with_index { |defn, i| (roll -= weights[i]).negative? && (return defn) }
+      end
+
+      # Basic lands split by the deck's colored mana symbols: every color that has symbols
+      # gets at least one, the rest is proportional (largest remainder, ties in WUBRG order).
+      def split_basics(count)
+        pips = @colors.to_h { |c| [c, spell_entries.sum { |defn, n| (defn.mana_cost&.colored || {}).fetch(c, 0) * n }] }
+        pips = @colors.to_h { [it, 1] } if pips.values.sum.zero?
+        split = pips.to_h { |c, n| [c, n.positive? && count >= pips.count { it[1].positive? } ? 1 : 0] }
+        rest = count - split.values.sum
+        total = pips.values.sum
+        shares = pips.to_h { |c, n| [c, Rational(rest * n, total)] }
+        shares.each { |c, share| split[c] += share.floor }
+        leftover = count - split.values.sum
+        shares.sort_by { |c, share| [-(share - share.floor), @colors.index(c)] }.first(leftover).each { split[it[0]] += 1 }
+        split.reject { |_, n| n.zero? }
+      end
+
+      # --- output -------------------------------------------------------------------------------------
+
+      def document(lands)
+        nonbasic = pick_nonbasic_lands(lands)
+        basics = split_basics(lands - nonbasic.values.sum)
+        main = basics.map { |color, n| [basic_land(color), n] } + sorted(nonbasic) + spell_entries
+        { "name" => "Random #{@colors.join} deck",
+          "description" => "random deck: colors=#{@colors.join} seed=#{@seed} — #{lands} lands, " \
+                           "#{@creatures.values.sum} creatures, #{@others.values.sum} other spells, #{main.size} distinct cards",
+          "cards" => main.map { it[0].to_h },
+          "main" => main.map { |defn, n| { "card" => defn.name, "count" => n } } }
+      end
+
+      def sorted(chosen)
+        chosen.map { |id, n| [@builder.definition(id), n] }.sort_by { |defn, _| [defn.mana_cost&.mana_value || 0, defn.name] }
+      end
+
+      def spell_entries = sorted(@creatures) + sorted(@others)
+
+      def basic_land(color)
+        name = BASIC_LAND_NAMES.fetch(color)
+        @pool.find { it.id == CardDefinition.slug(name) && it.supertype?(:basic) } || CardDefinition.from_h(BASIC_LANDS[color])
+      end
+
+      # --- randomness ---------------------------------------------------------------------------------
+
+      def sample(spec)
+        return uniform(spec[:outliers]) if @rng.rand(100) < @profile[:outlier_chance]
+
+        range = spec[:range]
+        center = spec.fetch(:center) { (range.min + range.max) / 2 }
+        spread = [center - range.min, range.max - center].max + 1
+        weighted(range.to_h { [it, spread - (it - center).abs] })
+      end
+
+      def uniform(range) = range.min + @rng.rand(range.max - range.min + 1)
+      def scaled(count) = Rational(count * @size, BASE_SIZE).round
+
+      # A key of `weights` ({key => Integer weight}), chosen proportionally; keys are tried in order.
+      def weighted(weights)
+        weights = weights.select { |_, w| w.positive? }
+        raise ArgumentError, "profile weights must include a positive weight" if weights.empty?
+
+        roll = @rng.rand(weights.values.sum)
+        weights.each { |key, w| (roll -= w).negative? && (return key) }
+      end
+    end
+    private_constant :Draft
+  end
+end

data/lib/enjine/docs.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Enjine
+  # Generates the reference docs and support matrix from Enjine.registry, so the
+  # documentation always matches the code. `rake docs` writes them; a spec fails
+  # when the committed files drift.
+  module Docs
+    CATEGORY_TITLES = {
+      type: "Card types", supertype: "Supertypes", subtype: "Subtypes with rules", keyword: "Keyword abilities",
+      ability: "Abilities", trigger: "Trigger conditions", cost: "Costs", effect: "Effects", filter: "Target filters and selectors",
+      counter: "Counters with rules"
+    }.freeze
+    ROOT = File.expand_path("../..", __dir__)
+
+    module_function
+
+    # {relative path => content}
+    def generate
+      files = { "SUPPORTED.md" => supported }
+      Primitive::CATEGORIES.each { |c| files["docs/reference/#{file_for(c)}.md"] = reference(c) }
+      files["docs/reference/decisions.md"] = decisions
+      files
+    end
+
+    def write(root = ROOT)
+      generate.each do |path, content|
+        full = File.join(root, path)
+        FileUtils.mkdir_p(File.dirname(full))
+        File.write(full, content)
+      end
+    end
+
+    def supported
+      lines = ["# Supported mechanics", "", generated_note, "",
+               "Rules version: Comprehensive Rules effective #{RULES_VERSION}.", ""]
+      Primitive::CATEGORIES.each do |category|
+        lines << "## #{CATEGORY_TITLES.fetch(category)}" << ""
+        entries = Enjine.registry.each(category).to_a
+        if entries.empty?
+          lines << "_None yet._" << ""
+          next
+        end
+        lines << "| Name | Rules | Description |" << "| --- | --- | --- |"
+        entries.each do |klass|
+          lines << "| [`#{klass.primitive_name}`](docs/reference/#{file_for(category)}.md##{klass.primitive_name}) | " \
+                   "#{klass.rules.join(", ")} | #{klass.description} |"
+        end
+        lines << ""
+      end
+      lines << "## Decisions" << "" << "See [docs/reference/decisions.md](docs/reference/decisions.md)." << ""
+      lines.join("\n")
+    end
+
+    def reference(category)
+      lines = ["# #{CATEGORY_TITLES.fetch(category)}", "", generated_note, ""]
+      entries = Enjine.registry.each(category).to_a
+      lines << "_None yet._" << "" if entries.empty?
+      entries.each do |klass|
+        lines << "## #{klass.primitive_name}" << "" << klass.description << ""
+        lines << "Rules: #{klass.rules.map { "CR #{it}" }.join(", ")}" << "" unless klass.rules.empty?
+        unless klass.params.empty?
+          lines << "| Parameter | Description |" << "| --- | --- |"
+          klass.params.each { |k, v| lines << "| `#{k}` | #{v} |" }
+          lines << ""
+        end
+        lines << "```json" << JSON.pretty_generate(klass.example) << "```" << "" if klass.example
+      end
+      lines.join("\n")
+    end
+
+    def decisions
+      lines = ["# Decisions", "", generated_note, "",
+               "`game.pending_decision` returns the decision below; submit one of its `options`.", ""]
+      Decisions::KINDS.sort.each do |kind, klass|
+        lines << "## #{kind}" << "" << (klass.respond_to?(:doc) ? klass.doc : "") << ""
+      end
+      lines << "## Priority actions" << ""
+      Actions::BY_TYPE.sort.each { |type, klass| lines << "- `#{type}` — #{klass.doc}" }
+      lines << ""
+      lines.join("\n")
+    end
+
+    def file_for(category) = category == :ability ? "abilities" : "#{category}s"
+
+    def generated_note = "<!-- Generated by `rake docs` from the primitive registry. Do not edit. -->"
+  end
+end

data/lib/enjine/engine/ability_layers.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Layers 5 and 6 of the layer pass (Engine::Characteristics#apply_layers): colors, and abilities gained
+    # and lost in timestamp order (CR 613.1e-f, 613.7).
+    module AbilityLayers
+      # Layer 5 (CR 613.1e): effects that set colors, in timestamp order. Layer 6 (CR 613.1f): keyword counters
+      # (CR 122.1b), keywords and abilities from static abilities and resolved effects, and "loses all
+      # abilities", applied in timestamp order (CR 613.7): a removal takes away what the object had then, and
+      # what is granted later stays. A static ability's timestamp is its source's (CR 613.7a), an effect's is
+      # its own (613.7b) and a keyword counter's is when it was put on (613.7c, see #counter_timestamp). A
+      # granted ability is referenced "granted:<card>:<ref>" (the granting card's data holds it, see
+      # #granted_origin); one a static ability grants ends with "@<granting permanent>", so it can refer to that
+      # permanent ("Return Trusty Boomerang to its owner's hand", CR 607.1a, Selector "granter").
+      def ability_layers(obj, base, statics, effects)
+        base = color_layer(obj, base, statics, effects)
+        changes = Mechanics::Counters.keywords(obj.counters).map { |kw| [counter_timestamp(obj, kw.to_s), 0, [:keywords, [kw]]] }
+        # A creature cast with suspend has haste while its caster controls it (CR 702.62a); since it was cast.
+        changes << [0, 0, [:keywords, [:haste]]] if obj.memory["haste_while_controlled_by"] == obj.controller
+        statics.each do |source, ability|
+          next unless ability.ability_changes? && ability.affects?(obj, source, facts(obj, base))
+
+          changes << [timestamp_of(source), 1, [:lose]] if ability.loses_abilities?
+          changes << [timestamp_of(source), 1, [:keywords, ability.keywords, granted_instances(source, ability)]]
+        end
+        effects.each do |effect|
+          next unless effect["affected"].include?(obj.id)
+
+          change = case effect["kind"]
+                   when "lose_abilities" then [:lose]
+                   when "grant" then [:keywords, effect["keywords"].map(&:to_sym)]
+                   when "abilities" then [:keywords, [], effect_granted_instances(effect)] # e.g. Effects::Become
+                   end
+          changes << [effect["timestamp"], 1, change] if change
+        end
+        return base if changes.empty?
+
+        apply_ability_changes(base, changes.each_with_index.sort_by { |(ts, rank, _), i| [ts, rank, i] }.map { it[0][2] })
+      end
+
+      # Folds layer 6 changes in order. Keywords stand for their abilities (prowess is a triggered ability),
+      # so a keyword gained, or kept after a removal, brings its instances (CR 613.1f).
+      def apply_ability_changes(base, changes)
+        keywords = base.keywords
+        abilities = base.abilities
+        lost = false
+        changes.each do |kind, added, granted|
+          if kind == :lose
+            lost = true
+            keywords = []
+            abilities = []
+          else
+            keywords |= added
+            abilities += granted unless granted.nil? || granted.empty?
+          end
+        end
+        return base if keywords == base.keywords && abilities.equal?(base.abilities)
+
+        abilities += (lost ? keywords : keywords - base.keywords).flat_map { CardDefinition.keyword_instances(it) }
+        base.with(keywords: keywords.freeze, abilities: abilities.freeze)
+      end
+
+      # Layer 5: statics (by their source's timestamp) and resolved effects that set colors, the latest last.
+      def color_layer(obj, base, statics, effects)
+        sets = statics.filter_map do |source, ability|
+          [timestamp_of(source), ability.colors] if ability.colors && ability.affects?(obj, source, facts(obj, base))
+        end
+        effects.each { sets << [it["timestamp"], it["colors"]] if it["kind"] == "colors" && it["affected"].include?(obj.id) }
+        return base if sets.empty?
+
+        base.with(colors: Mana::COLORS & sets.max_by(&:first)[1].map(&:to_sym))
+      end
+
+      # CR 613.7a, 613.7d: a permanent's timestamp is when it entered the battlefield; its id carries the
+      # counter it was created with, which is the timestamp sequence (#next_timestamp!). An Aura or Equipment gets
+      # a new one each time it becomes attached (CR 613.7e) and a permanent each time it transforms (CR 613.7g).
+      def timestamp_of(obj) = [obj.id[/\d+\z/].to_i, obj.memory["attached_at"].to_i, obj.memory["transformed_at"].to_i].max
+
+      # CR 613.7c: a keyword counter's timestamp is when it was last put on (Engine#add_counters! records it);
+      # one it had as it entered (or from a test board) counts as earliest.
+      def counter_timestamp(obj, kind) = obj.memory.dig("counter_timestamps", kind) || 0
+
+      # Whether the permanent loses all abilities this layer pass (an effect or a static ability, CR 613.1f).
+      def losing_abilities?(obj, statics, effects)
+        effects.any? { it["kind"] == "lose_abilities" && it["affected"].include?(obj.id) } ||
+          statics.any? { |source, ability| ability.loses_abilities? && ability.affects?(obj, source, facts(obj, @layering[obj.id])) }
+      end
+
+      def granted_instances(source, ability)
+        defn = definition(source)
+        ref = own_ability_instances(source).find { it.ability.equal?(ability) }&.ref or return []
+        defn.nested_instances(ref).map { AbilityInstance.new(ref: "granted:#{defn.id}:#{it.ref}@#{source.id}", ability: it.ability) }
+      end
+
+      # Abilities a resolved effect grants (layer 6, CR 613.1f): the effect's card holds them under its ref.
+      def effect_granted_instances(effect)
+        catalog.fetch(effect["card"]).effect_granted(effect["ref"]).map do |inst|
+          AbilityInstance.new(ref: "granted:#{effect["card"]}:#{inst.ref}", ability: inst.ability)
+        end
+      end
+
+      # For a granted ability's reference: [granting card id, its ref in that card], else nil.
+      def granted_origin(ref) = AbilityLayers.granted_parts(ref)&.first(2)
+
+      # [granting card id, its ref in that card, granting permanent id or nil] of a granted ability's reference.
+      def self.granted_parts(ref)
+        return nil unless ref.start_with?("granted:")
+
+        card, inner = ref.delete_prefix("granted:").split(":", 2)
+        inner, granter = inner.split("@", 2)
+        [card, inner, granter]
+      end
+    end
+
+    include AbilityLayers
+  end
+end