games_dice 0.5.0 → 0.6.0

data/lib/games_dice/probability_budget.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module GamesDice
+  # Raised when a probability query cannot meet its accuracy or work limits.
+  class ProbabilityLimitError < RuntimeError; end
+
+  # @api private
+  # Tracks a conservative upper bound on omitted mass, separately from floating-point roundoff.
+  class ProbabilityBudget
+    # Strictly below the decimal aggregate truncation budget.
+    LIMIT = 1e-10.prev_float
+    # Maximum evaluated faces per component calculation.
+    MAX_FACES = 100_000
+    # Maximum reroll and mapping predicate calls per component calculation.
+    MAX_PREDICATES = 1_000_000
+    # Maximum number of face draws along one enumerated history.
+    MAX_DEPTH = 64
+
+    # @return [Float] Upward-rounded omitted probability mass.
+    attr_reader :omitted
+
+    def initialize(limit, sides)
+      @limit = limit
+      @sides = sides
+      @omitted = 0.0
+      @upper = [1.0]
+      @faces = @predicates = 0
+    end
+
+    # Counts one evaluated face, refusing work above the cap.
+    def face
+      @faces += 1
+      work_limit if @faces > MAX_FACES
+    end
+
+    # Counts one rule invocation, including shortcut and map predicates.
+    def predicate
+      @predicates += 1
+      work_limit if @predicates > MAX_PREDICATES
+    end
+
+    def omit?(depth, probability)
+      return false if depth < 20 && probability >= 1e-16
+
+      @upper << (@upper.last / @sides).next_float while @upper.length <= depth
+      total = (@omitted + @upper[depth]).next_float
+      if total <= @limit
+        @omitted = total
+        return true
+      end
+      return false if depth < MAX_DEPTH
+
+      raise ProbabilityLimitError,
+            'Probability calculation cannot meet truncation error bound within calculation limits'
+    end
+
+    # Allocates a downward-rounded share of an aggregate error budget.
+    def self.share(limit, count)
+      (limit / count).prev_float
+    end
+
+    # Bounds a union of repeated independent component errors.
+    def self.scale(error, count)
+      error.zero? ? 0.0 : (error * count).next_float
+    end
+
+    # Adds achieved error bounds with outward rounding and exact zero handling.
+    def self.add(left, right)
+      return left if right.zero?
+      return right if left.zero?
+
+      (left + right).next_float
+    end
+
+    # Validates a complete aggregate certificate before its distribution is cached.
+    def self.check(error, limit)
+      if error > limit
+        raise ProbabilityLimitError,
+              'Probability calculation cannot meet truncation error bound within calculation limits'
+      end
+      error
+    end
+
+    private
+
+    def work_limit
+      raise ProbabilityLimitError, 'Probability calculation exceeds work limit'
+    end
+  end
+end

data/lib/games_dice/probability_calculation.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'games_dice/probability_shortcuts'
+
+module GamesDice
+  # @api private
+  # A bounded enumeration of completed rolls, with exact shortcuts for simple recipes.
+  class ProbabilityCalculation
+    include ProbabilityShortcuts
+
+    State = Struct.new(:depth, :reason, :subtracting, :probability, :total, :remaining)
+    private_constant :State
+
+    # @return [Float] Certified omitted-mass bound after successful calculation.
+    attr_reader :error
+
+    def initialize(die, limit)
+      @die = die
+      @sides = die.sides
+      @rerolls = die.rerolls&.dup || []
+      @maps = die.maps&.dup
+      @budget = ProbabilityBudget.new(limit, @sides)
+      @probabilities = Hash.new(0.0)
+    end
+
+    # @return [Probabilities] Normalized distribution of completed outcomes.
+    def calculate
+      exact = shortcut
+      enumerate(State.new(0, :basic, false, 1.0, nil, @rerolls.map(&:limit))) unless exact
+      @probabilities = exact if exact
+      @error = @budget.omitted
+      normalize
+      @probabilities = mapped_probabilities if @maps
+      Probabilities.from_h(@probabilities)
+    end
+
+    private
+
+    def enumerate(state)
+      probability = state.probability / @sides
+      depth = state.depth + 1
+      (1..@sides).each do |face|
+        @budget.face
+        visit_face(state, face, depth, probability)
+      end
+    end
+
+    def visit_face(state, face, depth, probability)
+      total = next_total(state, face)
+      index = @die.__send__(:find_matching_reroll_rule, face, depth, state.remaining, @budget, @rerolls)
+      if index.nil?
+        @probabilities[total] += probability
+      elsif !@budget.omit?(depth, probability)
+        continue_branch(state, total, index, depth, probability)
+      end
+    end
+
+    def next_total(state, face)
+      case state.reason
+      when :reroll_add then state.total + face
+      when :reroll_subtract then state.total - face
+      when :reroll_use_best then [state.total, face].max
+      when :reroll_use_worst then [state.total, face].min
+      else face
+      end
+    end
+
+    def continue_branch(state, total, index, depth, probability)
+      rule = @rerolls[index]
+      remaining = state.remaining.dup
+      remaining[index] -= 1
+      subtracting = state.subtracting || rule.type == :reroll_subtract
+      reason = state.subtracting && rule.type == :reroll_add ? :reroll_subtract : rule.type
+      enumerate(State.new(depth, reason, subtracting, probability, total, remaining))
+    end
+
+    def normalize
+      mass = @probabilities.values.sum
+      unless mass.finite? && mass.positive? && (mass + @error - 1.0).abs <= 1e-8
+        raise ProbabilityLimitError,
+              'Probability calculation cannot meet truncation error bound within calculation limits'
+      end
+      return if @error.zero?
+
+      @probabilities.transform_values! { |probability| probability / mass }
+    end
+
+    def mapped_probabilities
+      @probabilities.each_with_object(Hash.new(0.0)) do |(value, probability), mapped|
+        result, = @die.__send__(:calc_maps, value, @budget, @maps)
+        mapped[result] += probability
+      end
+    end
+  end
+end

data/lib/games_dice/probability_shortcuts.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module GamesDice
+  # @!visibility private
+  # Exact distributions for inexpensive ordinary reroll recipes.
+  module ProbabilityShortcuts
+    def self.boolean_rule?(rule)
+      value = rule.trigger_value
+      operator = rule.trigger_op
+      return false unless value.method(operator).source_location.nil?
+      return %i[== != < <= > >=].include?(operator) if value.instance_of?(Integer)
+
+      value.instance_of?(Range) && value.begin.is_a?(Integer) && value.end.is_a?(Integer) &&
+        %i[include? cover?].include?(operator)
+    end
+
+    private
+
+    def shortcut
+      return @die.basic_die.probabilities.to_h if @rerolls.empty?
+
+      rule = shortcut_rule
+      return unless rule
+      return deterministic_add(rule) if @sides == 1 && rule.type == :reroll_add
+      return replacement(rule) if rule.type == :reroll_replace
+
+      nil
+    end
+
+    def shortcut_rule
+      return unless @rerolls.one?
+
+      rule = @rerolls.first
+      rule if rule.instance_of?(RerollRule) && ProbabilityShortcuts.boolean_rule?(rule)
+    end
+
+    def deterministic_add(rule)
+      @budget.predicate
+      count = rule.applies?(1) ? [rule.limit, 0].max : 0
+      { 1 + count => 1.0 }
+    end
+
+    def replacement(rule)
+      triggers = triggering_faces(rule)
+      count = triggers.count(true)
+      return @die.basic_die.probabilities.to_h if count.zero? || count == @sides || rule.limit <= 0
+
+      replacement_weights(triggers, count, rule.limit)
+    end
+
+    def replacement_weights(triggers, count, limit)
+      repeated = ((count.to_f / @sides)**limit) / @sides
+      terminal = (1.0 - (count * repeated)) / (@sides - count)
+      triggers.each_with_index.to_h { |trigger, index| [index + 1, trigger ? repeated : terminal] }
+    end
+
+    def triggering_faces(rule)
+      Array.new(@sides) do |index|
+        @budget.face
+        @budget.predicate
+        rule.applies?(index + 1)
+      end
+    end
+  end
+end

data/lib/games_dice/recipe_cache.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module GamesDice
+  # @api private
+  # A structural snapshot of exposed recipe arrays. Stable reads allocate nothing.
+  class RecipeCache
+    def initialize(sources, labels)
+      @sources = sources
+      @labels = labels
+      @format = 1
+      capture
+    end
+
+    # @return [Boolean] Whether this is a recognized snapshot format.
+    def valid?
+      @format == 1
+    end
+
+    def changed?
+      index = 0
+      while index < @sources.length
+        array, = @sources[index]
+        return true if source_changed?(array, @snapshots[index])
+
+        index += 1
+      end
+      @labels != @label_copies
+    end
+
+    # Records entry references, component versions, and copies of mutable labels.
+    def capture
+      @snapshots = @sources.map do |array, klass|
+        array&.map do |entry|
+          validate(entry, klass)
+          [entry, child_version(entry), label_copy(entry)]
+        end
+      end
+      @label_copies = @labels.map(&:dup)
+    end
+
+    private
+
+    def source_changed?(array, snapshot)
+      return false unless array
+      return true unless snapshot && array.length == snapshot.length
+
+      index = 0
+      while index < array.length
+        return true if entry_changed?(array[index], snapshot[index])
+
+        index += 1
+      end
+      false
+    end
+
+    def entry_changed?(entry, snapshot)
+      saved, version, label = snapshot
+      return true unless entry.equal?(saved)
+      return true if version && entry.__send__(:recipe_version) != version
+
+      label && entry.mapped_name != label
+    end
+
+    def validate(entry, klass)
+      raise TypeError, "Expected #{klass}, got #{entry.class}" unless entry.is_a?(klass)
+    end
+
+    def child_version(entry)
+      entry.__send__(:recipe_version) if entry.is_a?(Bunch) || entry.is_a?(ComplexDie)
+    end
+
+    def label_copy(entry)
+      entry.mapped_name.dup if entry.is_a?(MapRule)
+    end
+  end
+
+  # @api private
+  # Shared invalidation and transaction boundary for recipe-dependent operations.
+  module RecipeQueries
+    private
+
+    def initialize_copy(original)
+      super
+      @recipe_cache = nil
+      refresh_recipe
+    end
+
+    def initialize_recipe
+      @recipe_cache = RecipeCache.new(recipe_sources, recipe_labels)
+      @recipe_version = 0
+    end
+
+    def recipe_labels
+      []
+    end
+
+    def recipe_version
+      refresh_recipe
+      @recipe_version
+    end
+
+    def refresh_recipe
+      validate_recipe
+      restore_recipe_cache unless @recipe_cache.is_a?(RecipeCache) && @recipe_cache.valid?
+      return unless @recipe_cache.changed?
+
+      clear_derived_state
+      @recipe_version += 1
+      @recipe_cache.capture
+    rescue TypeError, ArgumentError
+      clear_derived_state
+      @recipe_version = (@recipe_version || 0) + 1
+      raise
+    end
+
+    def restore_recipe_cache
+      previous_version = @recipe_version || 0
+      initialize_recipe
+      @recipe_version = previous_version + 1
+      clear_derived_state
+    end
+
+    def validate_recipe; end
+
+    def clear_derived_state
+      @probabilities = @probability_error = @probabilities_complete = nil
+      @min = @max = @min_result = @max_result = nil
+      @result = @raw_result_details = @used_result_details = nil
+    end
+
+    def valid_probability_cache?(limit)
+      @probabilities && @probability_error.is_a?(Float) && @probability_error >= 0.0 && @probability_error <= limit
+    end
+
+    def with_recipe
+      version = recipe_version
+      result = yield
+      completed = true
+      result
+    ensure
+      verify_recipe(version, completed) if version
+    end
+
+    def verify_recipe(version, completed)
+      discard_changed_recipe(completed) if recipe_version != version
+    rescue TypeError, ArgumentError
+      discard_changed_recipe(completed)
+    end
+
+    def discard_changed_recipe(completed)
+      clear_derived_state
+      raise 'Dice recipe changed during calculation' if completed
+    end
+  end
+end

data/lib/games_dice/version.rb

@@ -2,5 +2,5 @@
 
 module GamesDice
   # Current version of the gem.
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/games_dice.rb

@@ -6,6 +6,8 @@ require 'games_dice/die'
 require 'games_dice/die_result'
 require 'games_dice/reroll_rule'
 require 'games_dice/map_rule'
+require 'games_dice/recipe_cache'
+require 'games_dice/probability_budget'
 require 'games_dice/complex_die'
 require 'games_dice/bunch'
 require 'games_dice/dice'
@@ -26,6 +28,8 @@ module GamesDice
     GamesDice::Dice.new(parsed[:bunches], parsed[:offset])
   end
 
+  # Returns the shared parser used by {.create}.
+  # @return [GamesDice::Parser] Lazily constructed dice-notation parser.
   def self.parser
     @parser ||= GamesDice::Parser.new
   end

data/script/check_documentation.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'yard'
+
+# Match the Ruby source and visibility boundary used by the documentation task.
+# Stats reports omissions but does not fail on them, so check the parsed objects too.
+stats = YARD::CLI::Stats.new
+stats.run('--list-undoc', '--fail-on-warning', '--no-cache', '--no-save', 'lib/**/*.rb')
+abort 'Documentation check found no objects' if stats.all_objects.empty?
+abort 'Documentation check found undocumented objects' if stats.all_objects.any? { |object| object.docstring.blank? }

data/spec/games_dice/bunch_regressions_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'helpers'
+
+describe GamesDice::Bunch, :aggregate_failures do
+  let(:prng) { Random.new(1) }
+
+  invalid_counts = [0, -1]
+  valid_counts = [1, 3, 4]
+  %i[keep_best keep_worst].each do |mode|
+    invalid_counts.each do |count|
+      it "rejects #{count} keepers in #{mode}" do
+        expect { described_class.new(ndice: 3, sides: 6, keep_mode: mode, keep_number: count) }
+          .to raise_error(ArgumentError, /:keep_number must be 1 or more/)
+      end
+    end
+    valid_counts.each do |count|
+      it "keeps at most the whole bunch for #{count} keepers in #{mode}" do
+        bunch = described_class.new(ndice: 3, sides: 1, keep_mode: mode, keep_number: count)
+        expect(bunch.roll).to eq([count, 3].min)
+        expect(bunch.probabilities.to_h).to eq({ [count, 3].min => 1.0 })
+        expect(bunch.explain_result).to be_a(String)
+      end
+    end
+  end
+
+  { keep_best: [10, '1 Jackpot'], keep_worst: [1, '6 Low'] }.each do |mode, (total, kept)|
+    it "explains the actual mapped keeper for #{mode}" do
+      allow(prng).to receive(:rand).and_return(0, 5)
+      bunch = mapped_bunch(mode)
+      expect(bunch.roll).to eq(total)
+      expect(bunch.explain_result).to include("Keep: #{kept}. Successes: #{total}")
+    end
+  end
+
+  it 'shares its truncation budget across all rolled dice even when only one is kept' do
+    bunch = described_class.new(ndice: 20, sides: 2, rerolls: [[2, :==, :reroll_add]], keep_mode: :keep_best)
+    expect(bunch.probabilities.to_h).to be_valid_distribution
+    expect(bunch.instance_variable_get(:@probability_error)).to be <= 1e-10
+  end
+
+  def mapped_bunch(mode)
+    described_class.new(ndice: 2, sides: 6, prng: prng, keep_mode: mode,
+                        maps: [[1, :==, 10, 'Jackpot'], [2, :<=, 1, 'Low']])
+  end
+end