pseudo_random 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 90e087be024b1baf1841f93924e3d1303ed1b131f8ed63a676115db7d6317f02
+  data.tar.gz: b305efbe151f6675b163f04eb7671264c865f6fe9f283f73afcd3416862e24c3
+SHA512:
+  metadata.gz: d3a8678024b1ad7be9e5af9e85fcceffa7a3517fed4c64d50275fe16973892f7b414cd84b1007c0f87ecf3fcda33d1fd953a87128c879643ef1ce3818a44c278
+  data.tar.gz: 95d0bba372eabb184cf433dddd6f38ef3d987b48d265cf18501b577e9971b84180aa34bc2755309d64a574ded98730e475b5416d3d6a7ddcfce91caf3ff547e2

data/.rubocop.yml

@@ -0,0 +1,50 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  Exclude:
+    - 'pseudo_random.gemspec'
+
+##################### Layout ##################################
+Layout/LineLength:
+  Max: 120
+
+Layout/EndOfLine:
+  EnforcedStyle: lf
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+##################### Style ###################################
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/NumericPredicate:
+  Enabled: false
+
+##################### Naming #################################
+Naming/VariableNumber:
+  Enabled: false
+
+##################### Metrics #################################
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/MethodLength:
+  Max: 80
+
+Metrics/AbcSize:
+  Max: 70
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Metrics/PerceivedComplexity:
+  Max: 15

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+Versioning policy (summary):
+
+- MAJOR: Backward-incompatible changes (breaking API changes, method signature changes, or any change that alters the deterministic output sequence for an identical seed / call order without being an explicitly documented bug fix).
+- MINOR: Backward-compatible feature additions (new methods, new optional parameters, etc.). Existing deterministic sequences for existing seeds remain stable (except when corrected by a PATCH-level bug fix).
+- PATCH: Backward-compatible bug fixes, internal improvements, or documentation-only changes. Public API and existing deterministic output sequences are not modified (unless prior behavior was incorrect per documentation—in such cases the CHANGELOG will call it out explicitly as a fix).
+- Pre-release (e.g., 1.1.0-alpha.1): Experimental; output sequence stability is not guaranteed until the final release.
+
+Deterministic output compatibility: the mapping (seed, invocation order) -> value is part of the public API. Changing the underlying algorithm is treated as a MAJOR change unless clearly marked and justified as a bug fix.
+
+Deprecations: A deprecated feature will remain for at least one MINOR release after the deprecation notice before removal in the next MAJOR release.
+
+## [Unreleased]
+
+### 追加
+
+- ここに未リリースの変更を追記してください。
+
+## [1.0.0] - 2025-08-14
+
+### 追加
+
+- 初回リリース: 決定的な擬似乱数ジェネレータ (数値 / hex / alphabetic / alphanumeric 文字列生成)
+- 任意オブジェクトシード対応
+
+[Unreleased]: https://github.com/aYosukeMakita/pseudo_random/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/aYosukeMakita/pseudo_random/releases/tag/v1.0.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 aYosukeMakita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,290 @@
+# PseudoRandom
+
+PseudoRandom is a Ruby library that generates deterministic, reproducible pseudo-random numbers from a seed. Given the same seed, it always produces the same sequence, making it ideal for tests, simulations, and any scenario where repeatability matters.
+
+## Features
+
+- Deterministic & reproducible sequences from identical seeds
+- Flexible seeding: numbers, strings, arrays, hashes, Time objects, and more
+- Floating point values in [0.0, 1.0) and integers within given ranges
+- Hexadecimal string generation of arbitrary length
+- API surface broadly compatible with Ruby's built-in `Random`
+
+## String generation methods (alphabetic / alphanumeric / hex)
+
+This section documents the specs, boundary conditions, and determinism guarantees for the string helpers.
+
+### Common rules
+
+- Covered methods: `generator.hex(length)`, `generator.alphabetic(length)`, `generator.alphanumeric(length)`
+- Argument `length` MUST be an Integer >= 0.
+  - Negative or non-integer (e.g. Float) raises: `ArgumentError: "Length must be a non-negative integer"`.
+- When `length == 0` an empty string (`""`) is returned.
+- The returned string length always equals `length`.
+- Output is deterministic w.r.t. the seed AND the exact call order of all generator methods.
+  - Same seed + identical sequence of method calls + identical `length` values => identical sequence of outputs.
+  - Different seeds produce statistically different outputs.
+- Implementation wraps Ruby's `Random`. Characters are produced in fixed-size chunks by drawing a uniformly distributed integer and converting it to a mixed‑radix representation. Chunk sizing is part of the public deterministic algorithm; changing it is a breaking (MAJOR) change (see Determinism Policy below).
+
+### Per-method specifics
+
+| Method                 | Character set                             | Notes                                                                                                                                                  |
+| ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `hex(length)`          | `0-9a-f` (16 chars, lowercase)            | Uses 32‑bit integers -> 8 hex chars at a time; remainder (1–7) from another 32‑bit block prefix. Uniform over all hex strings of the requested length. |
+| `alphabetic(length)`   | `A-Z` (26) + `a-z` (26) = 52              | 3-char chunks (since 52^3 < 2^32) plus remainder (1–2 chars). Uniform.                                                                                 |
+| `alphanumeric(length)` | `A-Z` (26) + `a-z` (26) + `0-9` (10) = 62 | 5-char chunks (62^5 < 2^32) plus remainder (1–4 chars). Uniform.                                                                                       |
+
+### Uniformity
+
+Each chunk uses `Random#rand(base^k)` for an integer in `0...(base^k)` which is then expanded via repeated mod/div to `k` characters. This yields a uniform distribution over all `base^k` length-`k` strings. Remainder segments use the same approach. Thus (subject to the statistical quality of Ruby's underlying PRNG) each character position is unbiased and independent across chunks.
+
+### Performance / limits
+
+- Time complexity: O(length). Memory: O(length) for the resulting string.
+- Very large values (millions of characters) imply higher allocation cost; consider generating in smaller segments if required.
+
+### Determinism Policy
+
+As stated in Versioning: the mapping `(seed, call order) -> output sequence` is a public contract.
+
+- PATCH / MINOR: Existing deterministic sequences are preserved (unless fixing clearly incorrect behavior as per docs).
+- MAJOR: We may alter internal chunk sizing / conversion strategy. Any such change will be called out in the CHANGELOG.
+- The seed normalization algorithm (FNV‑1a based canonicalization) is also part of the deterministic surface; modifying it (outside critical bug fixes) is MAJOR.
+
+### Exceptions (current)
+
+| Condition               | Exception       |
+| ----------------------- | --------------- |
+| `length < 0`            | `ArgumentError` |
+| `length` not an Integer | `ArgumentError` |
+
+### Examples
+
+```ruby
+g = PseudoRandom.new("seed")
+g.hex(10)         # => 10 hex chars (0-9a-f)
+g.alphabetic(12)  # => 12 alphabetic chars (A-Za-z)
+g.alphanumeric(8) # => 8 alphanumeric chars (A-Za-z0-9)
+```
+
+See `CHANGELOG.md` for detailed release notes.
+
+## ⚠️ Security / Cryptographic Use Disclaimer
+
+The random values produced by this library prioritize determinism and reproducibility. They are NOT cryptographically secure. Do NOT use this library for any of the following:
+
+- Password or passphrase generation
+- API keys, access tokens, session IDs, CSRF tokens
+- Cryptographic keys, IVs, nonces, salts
+- Lotteries, drawings, or any fairness-critical public process exposed to adversaries
+
+For those purposes use Ruby's standard `SecureRandom`, or a cryptographically secure source via OpenSSL / libsodium. Always use a CSPRNG for any security-sensitive or fairness‑critical context (passwords, keys, tokens, lotteries, audits, public selections, etc.).
+
+Example (when you need secure randomness):
+
+```ruby
+require 'securerandom'
+token = SecureRandom.hex(32) # 64 hex characters
+```
+
+Use PseudoRandom only in contexts where determinism is valuable: tests, simulations, reproducible data generation, behavior snapshots with fixed seeds, etc.
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem 'pseudo_random'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install pseudo_random
+```
+
+## Usage
+
+### Basic usage
+
+```ruby
+require 'pseudo_random'
+
+# Create a generator with seed 42
+generator = PseudoRandom.new(42)
+
+# Float in [0.0, 1.0)
+random_float = generator.rand
+puts random_float  # => 0.6394267984578837
+
+# Integer in [0, 9]
+random_int = generator.rand(10)
+puts random_int  # => 6
+
+# Float in [0.0, 10.0)
+random_float_range = generator.rand(10.0)
+puts random_float_range  # => 9.66814512009282
+
+# Integer in [1, 100]
+random_range = generator.rand(1..100)
+puts random_range  # => 64
+```
+
+### Convenience one-off method
+
+```ruby
+# One-off random number (legacy convenience)
+result = PseudoRandom.rand(42)
+puts result  # => 0.6394267984578837
+
+# Create a new generator explicitly
+generator = PseudoRandom.new(42)
+```
+
+### Diverse seed types
+
+```ruby
+# String seed
+generator1 = PseudoRandom.new("hello")
+puts generator1.rand  # => 0.1915194503788923
+
+# Array seed
+generator2 = PseudoRandom.new([1, 2, 3])
+puts generator2.rand  # => 0.04548605918364251
+
+# Hash seed
+generator3 = PseudoRandom.new({ name: "John", age: 30 })
+puts generator3.rand  # => 0.7550896311312906
+
+# Time seed
+generator4 = PseudoRandom.new(Time.new(2023, 1, 1))
+puts generator4.rand  # => 0.4320558086698993
+
+# Omitted seed (uses hash of nil)
+generator5 = PseudoRandom.new
+puts generator5.rand  # => 0.8501480898450888
+```
+
+### Hex string generation
+
+```ruby
+generator = PseudoRandom.new("secret")
+
+# 8 hex characters
+hex_string = generator.hex(8)
+puts hex_string  # => "a1b2c3d4"
+
+# 10 hex characters
+hex_string_10 = generator.hex(10)
+puts hex_string_10  # => "a50ee918e5"
+
+# 16 hex characters
+long_hex = generator.hex(16)
+puts long_hex  # => "a1b2c3d4e5f67890"
+
+# Empty string (length 0)
+empty_hex = generator.hex(0)
+puts empty_hex  # => ""
+```
+
+### Reproducibility demonstration
+
+```ruby
+# Two generators with the same seed
+gen1 = PseudoRandom.new("test")
+gen2 = PseudoRandom.new("test")
+
+# Produces identical sequences
+5.times do
+  puts "gen1: #{gen1.rand}, gen2: #{gen2.rand}"
+end
+
+# Example output:
+# gen1: 0.5985762380674765, gen2: 0.5985762380674765
+# gen1: 0.8325673044064309, gen2: 0.8325673044064309
+# gen1: 0.24136065771243595, gen2: 0.24136065771243595
+# gen1: 0.7392418174919607, gen2: 0.7392418174919607
+# gen1: 0.9853406830436152, gen2: 0.9853406830436152
+```
+
+### Practical examples
+
+#### Generating test data
+
+```ruby
+# Consistent user test data
+def generate_test_user(seed)
+  generator = PseudoRandom.new(seed)
+
+  {
+    id: generator.rand(1_000_000),
+    name: "User#{generator.hex(6)}",
+    score: generator.rand(100),
+    active: generator.rand(2) == 1
+  }
+end
+
+user1 = generate_test_user("user1")
+user2 = generate_test_user("user1")  # Same data
+puts user1 == user2  # => true
+```
+
+#### Simulation
+
+```ruby
+# Dice roll simulation
+def simulate_dice_rolls(seed, count)
+  generator = PseudoRandom.new(seed)
+  results = Array.new(6, 0)
+
+  count.times do
+    roll = generator.rand(1..6)
+    results[roll - 1] += 1
+  end
+
+  results
+end
+
+# Identical results with identical seed
+results1 = simulate_dice_rolls("dice_sim", 1000)
+results2 = simulate_dice_rolls("dice_sim", 1000)
+puts results1 == results2  # => true
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run `rake test` to run the test suite. You can also run `bin/console` for an interactive prompt to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version: update the version in `version.rb`, then run `bundle exec rake release` (this creates a git tag, pushes commits and the tag, and publishes the `.gem` to [rubygems.org](https://rubygems.org)).
+
+## Versioning
+
+This project follows [Semantic Versioning 2.0.0](https://semver.org/).
+
+Version numbers use the format MAJOR.MINOR.PATCH (e.g. `1.2.3`).
+
+- MAJOR: Incremented for any backward-incompatible change to the public API. A change is considered breaking if it alters method names, argument semantics, return types, raises new errors in previously valid use, or changes the deterministic output sequence for the same seed in a way not explicitly documented as a bug fix.
+- MINOR: Backward-compatible feature additions or expansions. May introduce new methods or optional arguments. Deterministic sequences for existing seeds remain unchanged (except where a PATCH-level bug fix applies).
+- PATCH: Backward-compatible bug fixes and internal improvements that do not modify the documented behavior or output streams for existing seeds, unless the prior output was clearly incorrect per documentation (in which case the CHANGELOG will call it out explicitly).
+
+Deprecations: A feature marked as deprecated will remain available for at least one MINOR release before removal in the next MAJOR. Deprecations are announced in the CHANGELOG under an "Deprecated" heading.
+
+Deterministic Output Contract: The algorithm's mapping from (seed, call order) to values is part of the observable API. Altering it counts as a breaking change unless correcting a documented bug.
+
+Pre-release tags (e.g. `1.1.0-alpha.1`) may be used for experimentation; they do not guarantee output stability until the final release.
+
+The current version is defined in `lib/pseudo_random/version.rb` (`PseudoRandom::VERSION`).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/aYosukeMakita/pseudo_random.
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/pseudo_random/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PseudoRandom
+  VERSION = '1.0.0'
+end

data/lib/pseudo_random.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require_relative 'pseudo_random/version'
+
+module PseudoRandom
+  class Error < StandardError; end
+
+  # Internal seed canonicalization & hashing (FNV-1a 64-bit, pure Ruby)
+  module Seed
+    FNV_OFFSET = 0xcbf29ce484222325
+    FNV_PRIME  = 0x100000001b3
+    MASK64     = 0xffff_ffff_ffff_ffff
+
+    module_function
+
+    # Public: Convert arbitrary Ruby object to a deterministic 31-bit Integer for Random.new
+    def to_seed_int(obj)
+      h = FNV_OFFSET
+      canonical_each_byte(obj) do |byte|
+        h ^= byte
+        h = (h * FNV_PRIME) & MASK64
+      end
+      s = h ^ (h >> 32)
+      s & 0x7fff_ffff
+    end
+
+    # Depth-first canonical serialization streamed as bytes
+    def canonical_each_byte(obj, &blk)
+      case obj
+      when NilClass
+        yield 'n'.ord
+      when TrueClass
+        yield 't'.ord
+      when FalseClass
+        yield 'f'.ord
+      when Integer
+        yield 'i'.ord
+        encode_varint(zigzag(obj), &blk)
+      when Float
+        yield 'd'.ord
+        [obj].pack('G').each_byte(&blk) # big-endian IEEE 754
+      when String
+        str = obj.encode(Encoding::UTF_8)
+        yield 's'.ord
+        encode_varint(str.bytesize, &blk)
+        str.each_byte(&blk)
+      when Symbol
+        str = obj.to_s.encode(Encoding::UTF_8)
+        yield 'y'.ord
+        encode_varint(str.bytesize, &blk)
+        str.each_byte(&blk)
+      when Array
+        yield 'a'.ord
+        encode_varint(obj.length, &blk)
+        obj.each { |e| canonical_each_byte(e, &blk) }
+      when Hash
+        yield 'h'.ord
+        encode_varint(obj.length, &blk)
+        # Canonical order by key string representation to avoid insertion order dependence
+        obj.keys.map(&:to_s).sort.each do |ks|
+          canonical_each_byte(ks, &blk)
+          original_key = if obj.key?(ks)
+                           ks
+                         elsif obj.key?(ks.to_sym)
+                           ks.to_sym
+                         else
+                           # Fallback (should not usually happen)
+                           obj.keys.find { |k| k.to_s == ks }
+                         end
+          canonical_each_byte(obj[original_key], &blk)
+        end
+      when Time
+        yield 'T'.ord
+        encode_varint(obj.to_i, &blk)
+        encode_varint(obj.nsec, &blk)
+      else
+        # Fallback: class name + ':' + to_s (could cause collisions if to_s not stable)
+        rep = "#{obj.class.name}:#{obj}"
+        rep = rep.encode(Encoding::UTF_8)
+        yield 'o'.ord
+        encode_varint(rep.bytesize, &blk)
+        rep.each_byte(&blk)
+      end
+    end
+
+    # ZigZag encode signed -> unsigned integer
+    def zigzag(num)
+      num >= 0 ? (num << 1) : ((-num << 1) - 1)
+    end
+
+    # Varint (7-bit continuation) encoding
+    def encode_varint(num)
+      raise ArgumentError, 'negative varint' if num < 0
+
+      loop do
+        byte = num & 0x7f
+        num >>= 7
+        if num.zero?
+          yield byte
+          break
+        else
+          yield(byte | 0x80)
+        end
+      end
+    end
+  end
+
+  class Generator
+    # Character set for alphabetic generation: A-Z (26) + a-z (26) = 52 characters
+    ALPHABETIC_CHARS = ('A'..'Z').to_a + ('a'..'z').to_a
+    # Character set for alphanumeric generation: A-Z (26) + a-z (26) + 0-9 (10) = 62 characters
+    ALPHANUMERIC_CHARS = ('A'..'Z').to_a + ('a'..'z').to_a + ('0'..'9').to_a
+
+    def initialize(seed = nil)
+      @random = Random.new(normalize_seed(seed))
+    end
+
+    # Generates the next pseudo-random number in the sequence
+    # If max is provided, returns a value between 0 and max-1 (or 0.0 to max for floats)
+    # If a Range is provided, returns a value within that range
+    # If no arguments, returns a float between 0.0 and 1.0 (like Ruby's Kernel.#rand)
+    def rand(max = nil)
+      if max.nil?
+        @random.rand # Returns float between 0.0 and 1.0
+      else
+        @random.rand(max)
+      end
+    end
+
+    # Generates a hexadecimal string with the specified number of characters
+    # @param length [Integer] the number of hexadecimal characters to generate (must be >= 0)
+    # @return [String] a hexadecimal string with lowercase a-f
+    def hex(length)
+      raise ArgumentError, 'Length must be a non-negative integer' unless length.is_a?(Integer) && length >= 0
+
+      return '' if length == 0
+
+      result = ''
+      remaining = length
+
+      # Process 8 characters at a time for efficiency (32-bit random number = 8 hex chars)
+      while remaining >= 8
+        # Generate a 32-bit random number and convert to 8-character hex string
+        random_value = @random.rand(2**32)
+        hex_chunk = format('%08x', random_value)
+        result += hex_chunk
+        remaining -= 8
+      end
+
+      # Process remaining characters (1-7) by generating 8 chars and taking what we need
+      if remaining > 0
+        random_value = @random.rand(2**32)
+        hex_chunk = format('%08x', random_value)
+        result += hex_chunk[0, remaining] # Take only the first 'remaining' characters
+      end
+
+      result
+    end
+
+    # Generates an alphabetic string with the specified number of characters
+    # @param length [Integer] the number of alphabetic characters to generate (must be >= 0)
+    # @return [String] a string containing uppercase letters (A-Z) and lowercase letters (a-z)
+    def alphabetic(length)
+      raise ArgumentError, 'Length must be a non-negative integer' unless length.is_a?(Integer) && length >= 0
+
+      return '' if length == 0
+
+      result = ''
+      remaining = length
+
+      # Process multiple characters at once for efficiency
+      # We can generate about 3 characters from a 32-bit random number (52^3 = 140,608 < 2^32)
+      chunk_size = 3
+
+      while remaining >= chunk_size
+        # Generate a random number and convert to base-52 representation
+        random_value = @random.rand(52**chunk_size)
+        chunk = ''
+
+        chunk_size.times do
+          chunk = ALPHABETIC_CHARS[random_value % 52] + chunk
+          random_value /= 52
+        end
+
+        result += chunk
+        remaining -= chunk_size
+      end
+
+      # Process remaining characters (1-2)
+      if remaining > 0
+        random_value = @random.rand(52**remaining)
+        chunk = ''
+
+        remaining.times do
+          chunk = ALPHABETIC_CHARS[random_value % 52] + chunk
+          random_value /= 52
+        end
+
+        result += chunk
+      end
+
+      result
+    end
+
+    # Generates an alphanumeric string with the specified number of characters
+    # @param length [Integer] the number of alphanumeric characters to generate (must be >= 0)
+    # @return [String] a string containing uppercase letters (A-Z), lowercase letters (a-z), and digits (0-9)
+    def alphanumeric(length)
+      raise ArgumentError, 'Length must be a non-negative integer' unless length.is_a?(Integer) && length >= 0
+
+      return '' if length == 0
+
+      result = ''
+      remaining = length
+
+      # Process multiple characters at once for efficiency
+      # We can generate about 5 characters from a 32-bit random number (62^5 = 916,132,832 < 2^32)
+      chunk_size = 5
+
+      while remaining >= chunk_size
+        # Generate a random number and convert to base-62 representation
+        random_value = @random.rand(62**chunk_size)
+        chunk = ''
+
+        chunk_size.times do
+          chunk = ALPHANUMERIC_CHARS[random_value % 62] + chunk
+          random_value /= 62
+        end
+
+        result += chunk
+        remaining -= chunk_size
+      end
+
+      # Process remaining characters (1-4)
+      if remaining > 0
+        random_value = @random.rand(62**remaining)
+        chunk = ''
+
+        remaining.times do
+          chunk = ALPHANUMERIC_CHARS[random_value % 62] + chunk
+          random_value /= 62
+        end
+
+        result += chunk
+      end
+
+      result
+    end
+
+    private
+
+    # Deterministic, process-independent reduction of arbitrary object to Integer seed.
+    def normalize_seed(seed)
+      Seed.to_seed_int(seed)
+    end
+  end
+
+  # Creates a new generator with the given seed
+  def self.new(seed = nil)
+    Generator.new(seed)
+  end
+
+  # Generates a single pseudo-random number based on the given seed (backward compatibility)
+  def self.rand(seed)
+    generator = new(seed)
+    generator.rand
+  end
+end

data/sig/pseudo_random.rbs

@@ -0,0 +1,24 @@
+module PseudoRandom
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Generator
+    ALPHABETIC_CHARS: Array[String]
+    ALPHANUMERIC_CHARS: Array[String]
+
+    def initialize: (?untyped seed) -> void
+
+    def rand: () -> Float
+             | (Integer max) -> Integer
+             | (Float max) -> Float
+             | (Range[Integer, Integer] range) -> Integer
+             | (Range[Float, Float] range) -> Float
+
+    def hex: (Integer length) -> String
+    def alphabetic: (Integer length) -> String
+    def alphanumeric: (Integer length) -> String
+  end
+
+  def self.new: (?untyped seed) -> Generator
+  def self.rand: (untyped seed) -> Float
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: pseudo_random
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- aYosukeMakita
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Generates reproducible (deterministic) pseudo-random numbers and strings
+  (hex/alphabetic/alphanumeric) from arbitrary Ruby object seeds. Not cryptographically
+  secure.
+email:
+- yosuke.makita@access-company.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/pseudo_random.rb
+- lib/pseudo_random/version.rb
+- sig/pseudo_random.rbs
+homepage: https://github.com/aYosukeMakita/pseudo_random
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aYosukeMakita/pseudo_random
+  source_code_uri: https://github.com/aYosukeMakita/pseudo_random
+  changelog_uri: https://github.com/aYosukeMakita/pseudo_random/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  issue_tracker_uri: https://github.com/aYosukeMakita/pseudo_random/issues
+  documentation_uri: https://www.rubydoc.info/gems/pseudo_random
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Deterministic pseudo-random generator for numbers and strings.
+test_files: []