ignis 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 87196fca0ddbb82a81e1cda44c85ac4ff527da783743a0cce600e92f2ea34929
+  data.tar.gz: a8ffe2c3d578b76bd0e663582b3153ac24e8d09aa54706ad718cea3d70b0f58b
+SHA512:
+  metadata.gz: bc828b7eb0284e8377699e7d147dad2da4cb63e129b88d6be05d5bf87cfd19508f054b3c8bb4e306fb58241a110298e4525475de148c37b3a7aabc301ba34a1a
+  data.tar.gz: 02cc7a1dd7d5b51f9718de9ba91513ba50835dc3b5bca0a2cc6bb1651a9738ab1cf12e3495867608b7bc87243536e08fb40af822fb0440fa389ddcd1f892246f

data/README.md

@@ -0,0 +1,15 @@
+# ignis
+
+GPU compute foundation for Ruby on native Windows — the base of the [Ignis](https://github.com/tigel-agm/Ignis) ecosystem.
+
+Provides a GPU n-dimensional array (`Ignis::NDArray`), CUDA device/memory management, a runtime kernel compiler (NVRTC) with a batteries-included kernel library, fp16/bf16 conversion (`Ignis::Half`), and cuBLAS GEMM. **No C extensions** — libraries bind via FFI and kernels compile at runtime, so `gem install` needs no compiler or devkit.
+
+```ruby
+require "ignis"
+a = Ignis::NDArray.new(shape: [2, 3], dtype: :float32, device_id: 0)
+a.from_host([1, 2, 3, 4, 5, 6].map(&:to_f))
+# custom CUDA kernels via NVRTC:
+k = Ignis.compile_kernel(src, "my_kernel"); k.launch(grid: [..], block: [..], args: [a, ...])
+```
+
+Requires an NVIDIA GPU + CUDA runtime. Ruby ≥ 3.1. MIT.

data/lib/ignis.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Ignis — GPU compute foundation for Ruby on native Windows.
+#
+# Provides a GPU n-dimensional array (Ignis::NDArray), CUDA device/memory
+# management, a runtime kernel compiler (NVRTC) with a batteries-included kernel
+# library, fp16/bf16 conversion, and cuBLAS GEMM. Libraries bind via FFI and
+# kernels compile at runtime — there are no C extensions, so installation needs
+# no compiler/devkit. Requires an NVIDIA GPU + CUDA toolkit/runtime.
+
+# --- Platform + shared foundation (Windows CUDA discovery, the GPU array) ---
+require_relative "nnw/platform"
+require_relative "nnw/shared/ffi_loader"
+require_relative "nnw/shared/nv_array"
+require_relative "nnw/shared/event_bus"
+require_relative "nnw/shared/memory_contract"
+require_relative "nnw/shared/recovery_protocol"
+
+# --- Core types ---
+require_relative "nvruby/version"
+require_relative "nvruby/errors"
+require_relative "nvruby/configuration"
+require_relative "nvruby/dtype"
+require_relative "nvruby/half"
+
+# --- CUDA runtime/driver ---
+require_relative "nvruby/cuda/library_loader"
+require_relative "nvruby/cuda/runtime_api"
+require_relative "nvruby/cuda/device_props"
+require_relative "nvruby/cuda/device"
+require_relative "nvruby/cuda/memory"
+require_relative "nvruby/cuda/stream"
+require_relative "nvruby/cuda/graph"
+require_relative "nvruby/memory"
+
+# --- cuBLAS GEMM ---
+require_relative "nvruby/linalg/cublas_bindings"
+require_relative "nvruby/linalg/epilog"
+require_relative "nvruby/linalg/matmul"
+require_relative "nvruby/linalg/matmul_plan"
+
+# --- JIT (NVRTC) machinery + kernel library ---
+require_relative "nvruby/jit/nvrtc_bindings"
+require_relative "nvruby/jit/driver_api_bindings"
+require_relative "nvruby/jit/compiled_kernel"
+require_relative "nvruby/jit/kernel_module"
+require_relative "nvruby/jit/kernel"
+require_relative "nvruby/jit/compiler"
+require_relative "nvruby/jit/kernels/activations"
+require_relative "nvruby/jit/kernels/elementwise"
+require_relative "nvruby/jit/kernels/attention"
+require_relative "nvruby/jit/kernels/normalization"
+require_relative "nvruby/jit/kernels/loss"
+require_relative "nvruby/jit/kernels/optimizer"
+
+module Ignis
+  class << self
+    # cuBLAS matrix multiply: C = A @ B (optionally transposed).
+    def matmul(a, b, transpose_a: false, transpose_b: false)
+      LinAlg::Matmul.call(a, b, transpose_a: transpose_a, transpose_b: transpose_b)
+    end
+
+    # General GEMM: D = alpha*op(A)@op(B) + beta*C.
+    def gemm(a, b, c: nil, alpha: 1.0, beta: 0.0, transpose_a: false, transpose_b: false, stream: nil)
+      LinAlg::Matmul.call(a, b, c: c, alpha: alpha, beta: beta,
+                          transpose_a: transpose_a, transpose_b: transpose_b, stream: stream)
+    end
+
+    # --- Device management ---
+    def devices;        CUDA::Device.list;    end
+    def current_device; CUDA::Device.current; end
+    def set_device(i);  CUDA::Device.new(i).set_current!; end
+    def synchronize;    CUDA::Device.current.synchronize; end
+    def cuda_available?; CUDA::Device.available?; rescue StandardError; false; end
+    def cuda_version;   CUDA::LibraryLoader.cuda_version; rescue StandardError; nil; end
+
+    # --- JIT kernel compilation (NVRTC) ---
+    def compile_kernel(source, name, device_id: 0, options: [])
+      JIT::Compiler.compile(source, name, device_id: device_id, options: options)
+    end
+
+    def compile_kernel_only(source, name, compute_capability:, options: [])
+      JIT::Compiler.compile_only(source, name, compute_capability: compute_capability, options: options)
+    end
+
+    def jit_cache_stats; JIT::Compiler.cache_stats; end
+    def clear_jit_cache!; JIT::Compiler.clear_cache!; end
+
+    # --- Shared foundation accessors ---
+    def event_bus;         Shared::EventBus;        end
+    def memory_contract;   Shared::MemoryContract;  end
+    def recovery_protocol; Shared::RecoveryProtocol; end
+  end
+end

data/lib/nnw/platform.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module Ignis
+  # Cross-platform detection and path resolution for Ignis.
+  #
+  # Windows is the primary target (the whole point — Ruby HPC without
+  # Python's 20-30% overhead). Linux support exists for multi-GPU bare-metal
+  # testing on Lambda / RunPod / Azure instances.
+  #
+  # Usage:
+  #   Ignis::Platform.windows?          # => true on dev box
+  #   Ignis::Platform.cuda_lib('cudart') # => 'cudart64_130.dll' or 'libcudart.so.13'
+  #   Ignis::Platform.cuda_bin_path      # => 'C:/Program Files/.../bin' or '/usr/local/cuda/lib64'
+  module Platform
+    # ----------------------------------------------------------------
+    # OS Detection
+    # ----------------------------------------------------------------
+
+    # @return [Boolean] true if running on Windows
+    def self.windows?
+      RUBY_PLATFORM.match?(/mswin|mingw|cygwin/i) || (defined?(FFI) && FFI::Platform::IS_WINDOWS)
+    end
+
+    # @return [Boolean] true if running on Linux
+    def self.linux?
+      RUBY_PLATFORM.match?(/linux/i)
+    end
+
+    # @return [Boolean] true if running on macOS (unlikely for GPU work)
+    def self.macos?
+      RUBY_PLATFORM.match?(/darwin/i)
+    end
+
+    # @return [Symbol] :windows, :linux, or :macos
+    def self.os
+      if windows?
+        :windows
+      elsif linux?
+        :linux
+      elsif macos?
+        :macos
+      else
+        :unknown
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # CUDA Paths
+    # ----------------------------------------------------------------
+
+    CUDA_VERSION_MAJOR = 13
+    CUDA_VERSION_MINOR = 0
+
+    # Windows CUDA root
+    WIN_CUDA_ROOT = File.join('C:', 'Program Files', 'NVIDIA GPU Computing Toolkit', 'CUDA', "v#{CUDA_VERSION_MAJOR}.#{CUDA_VERSION_MINOR}").freeze
+    WIN_CUDA_BIN  = File.join(WIN_CUDA_ROOT, 'bin').freeze
+
+    # Linux CUDA root (standard install or Lambda Stack)
+    LINUX_CUDA_ROOT = "/usr/local/cuda-#{CUDA_VERSION_MAJOR}.#{CUDA_VERSION_MINOR}".freeze
+    LINUX_CUDA_LIB  = File.join(LINUX_CUDA_ROOT, 'lib64').freeze
+    LINUX_CUDA_ALT   = '/usr/local/cuda'.freeze
+    LINUX_CUDA_ALT_LIB = File.join(LINUX_CUDA_ALT, 'lib64').freeze
+
+    # Candidate sub-directories that hold the CUDA redistributable DLLs under a
+    # toolkit root. CUDA 13 on Windows moved them from bin\ to bin\x64\, so both
+    # must be probed.
+    WIN_DLL_SUBDIRS = [File.join('bin', 'x64'), 'bin'].freeze
+
+    # Discover the installed Windows CUDA toolkit root.
+    #
+    # The compiled-in v#{MAJOR}.#{MINOR} default is only a last resort: real
+    # installs vary (v13.0 / v13.1 / v13.2 / ...). We prefer the CUDA_PATH env
+    # var set by the NVIDIA installer, then the highest-versioned vX.Y directory
+    # that actually contains a CUDA runtime DLL. Memoized.
+    # @return [String]
+    def self.win_cuda_root
+      @win_cuda_root ||= begin
+        candidates = []
+        env_root = ENV['CUDA_PATH']
+        candidates << env_root if env_root && !env_root.empty?
+
+        base = File.join('C:', 'Program Files', 'NVIDIA GPU Computing Toolkit', 'CUDA')
+        versioned = Dir.glob(File.join(base, 'v*')).select { |d| File.directory?(d) }
+        versioned = versioned.sort_by do |d|
+          (m = d.match(/v(\d+)\.(\d+)/)) ? [m[1].to_i, m[2].to_i] : [0, 0]
+        end.reverse # highest version first (v13.2 before v13.0)
+        candidates.concat(versioned)
+
+        chosen = candidates.find do |root|
+          WIN_DLL_SUBDIRS.any? { |sub| Dir.glob(File.join(root, sub, 'cudart64_*.dll')).any? }
+        end
+        chosen || WIN_CUDA_ROOT
+      end
+    end
+
+    # Resolve the directory that actually contains the CUDA redistributable DLLs
+    # (bin\x64 on CUDA 13, bin on older layouts). Memoized.
+    # @return [String]
+    def self.win_cuda_bin
+      @win_cuda_bin ||= begin
+        root = win_cuda_root
+        sub = WIN_DLL_SUBDIRS.find { |s| Dir.glob(File.join(root, s, 'cudart64_*.dll')).any? }
+        File.join(root, sub || 'bin')
+      end
+    end
+
+    # @return [String] CUDA binary/library directory for the current OS
+    def self.cuda_bin_path
+      if windows?
+        win_cuda_bin
+      else
+        # Prefer versioned path, fall back to symlinked /usr/local/cuda
+        if Dir.exist?(LINUX_CUDA_LIB)
+          LINUX_CUDA_LIB
+        elsif Dir.exist?(LINUX_CUDA_ALT_LIB)
+          LINUX_CUDA_ALT_LIB
+        else
+          # Lambda Stack / system CUDA — libraries on LD_LIBRARY_PATH
+          '/usr/lib/x86_64-linux-gnu'
+        end
+      end
+    end
+
+    # @return [String] CUDA root directory
+    def self.cuda_root
+      if windows?
+        win_cuda_root
+      else
+        Dir.exist?(LINUX_CUDA_ROOT) ? LINUX_CUDA_ROOT : LINUX_CUDA_ALT
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Library Name Resolution
+    # ----------------------------------------------------------------
+
+    # Maps library keys to their platform-specific filenames.
+    # Windows uses DLLs, Linux uses shared objects.
+    #
+    # @param key [Symbol] library key
+    # @return [String] platform-specific glob pattern
+    def self.cuda_lib_pattern(key)
+      if windows?
+        WIN_LIB_PATTERNS[key] || raise(ArgumentError, "Unknown CUDA library: #{key}")
+      else
+        LINUX_LIB_PATTERNS[key] || raise(ArgumentError, "Unknown CUDA library: #{key}")
+      end
+    end
+
+    # Resolve the full path to a specific CUDA library.
+    # @param key [Symbol] library key (e.g. :cuda_runtime, :cublas)
+    # @return [String, nil] full path or nil
+    def self.find_cuda_lib(key)
+      pattern = cuda_lib_pattern(key)
+      search_paths = cuda_search_paths(key)
+
+      search_paths.each do |dir|
+        matches = Dir.glob(File.join(dir, pattern))
+        return matches.max if matches.any?
+      end
+
+      nil
+    end
+
+    # Resolve the CUDA runtime library path directly.
+    # @return [String] path to cudart
+    def self.cudart_path
+      if windows?
+        found = find_cuda_lib(:cuda_runtime)
+        found || File.join(WIN_CUDA_BIN, "cudart64_#{CUDA_VERSION_MAJOR}0.dll")
+      else
+        found = find_cuda_lib(:cuda_runtime)
+        found || "libcudart.so.#{CUDA_VERSION_MAJOR}"
+      end
+    end
+
+    # @return [String] path separator for the OS
+    def self.path_separator
+      windows? ? ';' : ':'
+    end
+
+    # @return [String] shared library extension
+    def self.shared_lib_ext
+      windows? ? '.dll' : '.so'
+    end
+
+    # ----------------------------------------------------------------
+    # Custom Library Paths (cuTENSOR, cuDSS, etc.)
+    # ----------------------------------------------------------------
+
+    # @return [Hash{Symbol => String}] custom search paths per library
+    def self.custom_lib_paths
+      if windows?
+        {
+          cutensor: 'C:/Program Files/NVIDIA cuTENSOR/v2.4/bin/13',
+          cudss:    'C:/Program Files/NVIDIA cuDSS/v0.7/bin/13'
+        }
+      else
+        {
+          cutensor: '/usr/local/cutensor/lib',
+          cudss:    '/usr/local/cudss/lib'
+        }
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Kernel32 / System Library Support
+    # ----------------------------------------------------------------
+
+    # @return [Boolean] true if Kernel32 (Windows DLL path management) is available
+    def self.kernel32_available?
+      windows?
+    end
+
+    # ----------------------------------------------------------------
+    # .NET AOT Path (WNAIS)
+    # ----------------------------------------------------------------
+
+    # @return [String] expected path to WNAIS native AOT binary
+    def self.wnais_native_lib
+      if windows?
+        'Wnais.Core.dll'
+      else
+        'Wnais.Core.so'
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Diagnostics
+    # ----------------------------------------------------------------
+
+    # @return [Hash] platform summary for debugging
+    def self.info
+      {
+        os: os,
+        ruby_platform: RUBY_PLATFORM,
+        cuda_version: "#{CUDA_VERSION_MAJOR}.#{CUDA_VERSION_MINOR}",
+        cuda_root: cuda_root,
+        cuda_bin: cuda_bin_path,
+        cudart: cudart_path,
+        kernel32: kernel32_available?,
+        shared_lib_ext: shared_lib_ext
+      }
+    end
+
+    private_class_method def self.cuda_search_paths(key)
+      paths = []
+
+      # Custom paths first
+      custom = custom_lib_paths[key]
+      paths << custom if custom && Dir.exist?(custom.to_s)
+
+      # Primary CUDA lib path
+      paths << cuda_bin_path
+
+      unless windows?
+        # Linux: also check standard system paths
+        paths << LINUX_CUDA_ALT_LIB if Dir.exist?(LINUX_CUDA_ALT_LIB)
+        paths << '/usr/lib/x86_64-linux-gnu'
+        paths << '/usr/lib64'
+      end
+
+      # System PATH
+      env_paths = ENV['PATH']&.split(path_separator) || []
+      paths.concat(env_paths)
+
+      paths.uniq
+    end
+
+    # Windows DLL patterns
+    WIN_LIB_PATTERNS = {
+      cuda_runtime: 'cudart64_*.dll',
+      cublas:       'cublas64_*.dll',
+      cublaslt:     'cublasLt64_*.dll',
+      cufft:        'cufft64_*.dll',
+      curand:       'curand64_*.dll',
+      cusparse:     'cusparse64_*.dll',
+      cusolver:     'cusolver64_*.dll',
+      cudnn:        'cudnn64_*.dll',
+      nvrtc:        'nvrtc64_*.dll',
+      cutensor:     'cutensor.dll',
+      cudss:        'cudss64_*.dll',
+      mathdx:       'mathdx64_0.dll',
+      cuda_driver:  'nvcuda.dll'
+    }.freeze
+
+    # Linux .so patterns
+    LINUX_LIB_PATTERNS = {
+      cuda_runtime: 'libcudart.so*',
+      cublas:       'libcublas.so*',
+      cublaslt:     'libcublasLt.so*',
+      cufft:        'libcufft.so*',
+      curand:       'libcurand.so*',
+      cusparse:     'libcusparse.so*',
+      cusolver:     'libcusolver.so*',
+      cudnn:        'libcudnn.so*',
+      nvrtc:        'libnvrtc.so*',
+      cutensor:     'libcutensor.so*',
+      cudss:        'libcudss.so*',
+      mathdx:       'libmathdx.so*',
+      cuda_driver:  'libcuda.so*'
+    }.freeze
+  end
+end

data/lib/nnw/shared/event_bus.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Ignis
+  module Shared
+    # EventBus — Typed, bounded, synchronous-first pub/sub bus.
+    #
+    # All cross-layer communication goes through EventBus.
+    # Zero global state except the singleton instance.
+    #
+    # Event types are frozen constants — do not add more at runtime.
+    # All operations are thread-safe via Monitor (reentrant mutex).
+    class EventBus
+      # Maximum history entries per event type (ring buffer).
+      MAX_HISTORY = 100
+
+      # Frozen set of valid event types.
+      VALID_EVENT_TYPES = %i[
+        data_ready
+        compute_done
+        all_reduce_done
+        checkpoint_ready
+        gpu_failed
+        gpu_recovered
+        backpressure_on
+        backpressure_off
+        topology_changed
+        nova_flush_done
+        health_alert
+      ].freeze
+
+      # @return [EventBus] singleton instance
+      def self.instance
+        @instance ||= new
+      end
+
+      # Reset the singleton instance (for testing only).
+      # @return [void]
+      def self.reset!
+        @instance = new
+      end
+
+      # Subscribe a handler to an event type.
+      #
+      # @param event_type [Symbol] one of VALID_EVENT_TYPES
+      # @param handler_id [String, Symbol] unique identifier for this handler
+      # @yield [Hash] block called with event payload when event is published
+      # @return [void]
+      # @raise [ArgumentError] if event_type is invalid or no block given
+      def self.subscribe(event_type, handler_id:, &block)
+        instance.subscribe(event_type, handler_id: handler_id, &block)
+      end
+
+      # Unsubscribe a handler from an event type.
+      #
+      # @param event_type [Symbol] one of VALID_EVENT_TYPES
+      # @param handler_id [String, Symbol] the handler identifier to remove
+      # @return [Boolean] true if handler was found and removed
+      def self.unsubscribe(event_type, handler_id:)
+        instance.unsubscribe(event_type, handler_id: handler_id)
+      end
+
+      # Publish an event to all subscribers.
+      #
+      # Calls all subscribers synchronously in subscription order.
+      # Catches and logs subscriber exceptions (never raises to caller).
+      # Records publish timestamp in metrics.
+      #
+      # @param event_type [Symbol] one of VALID_EVENT_TYPES
+      # @param payload [Hash] event payload
+      # @return [Integer] number of subscribers notified
+      def self.publish(event_type, payload: {})
+        instance.publish(event_type, payload: payload)
+      end
+
+      # Get recent event history for an event type.
+      #
+      # @param event_type [Symbol] one of VALID_EVENT_TYPES
+      # @param last_n [Integer] maximum number of entries to return
+      # @return [Array<Hash>] array of {event_type:, payload:, timestamp:, subscriber_count:}
+      def self.history(event_type, last_n: 10)
+        instance.history(event_type, last_n: last_n)
+      end
+
+      # Get all registered handler IDs for an event type.
+      #
+      # @param event_type [Symbol] one of VALID_EVENT_TYPES
+      # @return [Array<String, Symbol>]
+      def self.handlers_for(event_type)
+        instance.handlers_for(event_type)
+      end
+
+      # Get metrics summary.
+      #
+      # @return [Hash] metrics per event type
+      def self.metrics
+        instance.metrics
+      end
+
+      # Instance methods
+
+      def initialize
+        @monitor = Monitor.new
+        @subscribers = {}
+        @history = {}
+        @metrics = {}
+        @errors = []
+
+        VALID_EVENT_TYPES.each do |et|
+          @subscribers[et] = []
+          @history[et] = []
+          @metrics[et] = { publish_count: 0, last_publish_at: nil, error_count: 0 }
+        end
+      end
+
+      # @see EventBus.subscribe
+      def subscribe(event_type, handler_id:, &block)
+        validate_event_type!(event_type)
+        raise ArgumentError, 'Block required for subscribe' unless block_given?
+
+        @monitor.synchronize do
+          # Remove existing handler with same ID to prevent duplicates
+          @subscribers[event_type].reject! { |h| h[:handler_id] == handler_id }
+          @subscribers[event_type] << { handler_id: handler_id, block: block }
+        end
+      end
+
+      # @see EventBus.unsubscribe
+      def unsubscribe(event_type, handler_id:)
+        validate_event_type!(event_type)
+
+        @monitor.synchronize do
+          initial_size = @subscribers[event_type].size
+          @subscribers[event_type].reject! { |h| h[:handler_id] == handler_id }
+          @subscribers[event_type].size < initial_size
+        end
+      end
+
+      # @see EventBus.publish
+      def publish(event_type, payload: {})
+        validate_event_type!(event_type)
+
+        timestamp = Time.now
+        handlers_snapshot = nil
+        
+        @monitor.synchronize do
+          handlers_snapshot = @subscribers[event_type].dup
+        end
+
+        notified = 0
+        errors_in_publish = []
+
+        handlers_snapshot.each do |handler|
+          begin
+            handler[:block].call(payload)
+            notified += 1
+          rescue => e
+            notified += 1
+            errors_in_publish << {
+              handler_id: handler[:handler_id],
+              error: e,
+              timestamp: timestamp
+            }
+          end
+        end
+
+        # Record history and metrics under lock
+        @monitor.synchronize do
+          entry = {
+            event_type: event_type,
+            payload: payload,
+            timestamp: timestamp,
+            subscriber_count: notified,
+            errors: errors_in_publish.map { |err| { handler_id: err[:handler_id], message: err[:error].message } }
+          }
+
+          ring = @history[event_type]
+          ring << entry
+          ring.shift while ring.size > MAX_HISTORY
+
+          @metrics[event_type][:publish_count] += 1
+          @metrics[event_type][:last_publish_at] = timestamp
+          @metrics[event_type][:error_count] += errors_in_publish.size
+
+          @errors.concat(errors_in_publish)
+          @errors.shift while @errors.size > MAX_HISTORY
+        end
+
+        notified
+      end
+
+      # @see EventBus.history
+      def history(event_type, last_n: 10)
+        validate_event_type!(event_type)
+
+        @monitor.synchronize do
+          ring = @history[event_type]
+          n = [last_n, ring.size].min
+          ring.last(n)
+        end
+      end
+
+      # @see EventBus.handlers_for
+      def handlers_for(event_type)
+        validate_event_type!(event_type)
+
+        @monitor.synchronize do
+          @subscribers[event_type].map { |h| h[:handler_id] }
+        end
+      end
+
+      # @see EventBus.metrics
+      def metrics
+        @monitor.synchronize do
+          @metrics.transform_values(&:dup)
+        end
+      end
+
+      # Get recent errors across all event types.
+      # @param last_n [Integer] max entries
+      # @return [Array<Hash>]
+      def recent_errors(last_n: 20)
+        @monitor.synchronize do
+          @errors.last([last_n, @errors.size].min)
+        end
+      end
+
+      private
+
+      # Validate that event_type is one of the allowed types.
+      # @param event_type [Symbol]
+      # @raise [ArgumentError]
+      def validate_event_type!(event_type)
+        unless VALID_EVENT_TYPES.include?(event_type)
+          raise ArgumentError,
+                "Invalid event type #{event_type.inspect}. Valid: #{VALID_EVENT_TYPES}"
+        end
+      end
+    end
+  end
+end