# 機能設計書 155-PseudoRandom\int

## 概要

本ドキュメントは、Hack Standard Library (HSL) における `PseudoRandom\int` 関数の機能設計を記載する。この関数は擬似ランダムな整数を生成する機能を提供する。

### 本機能の処理概要

`PseudoRandom\int` は、指定された範囲内の擬似ランダムな整数を生成する関数である。内部的には `_Private\Native\pseudorandom_int` ネイティブ関数を呼び出し、高速な擬似乱数生成器（PRNG）を使用する。**重要：この関数は暗号用途には適さない。**

**業務上の目的・背景**：多くのアプリケーションでは、暗号学的な安全性は不要だが、高速で統計的に良好な乱数が必要な場面がある。ゲーム開発、シミュレーション、テストデータ生成、統計処理、機械学習のデータシャッフルなどでは、暗号学的乱数の重いオーバーヘッドは不要であり、擬似乱数で十分である。

**機能の利用シーン**：
- ゲームにおけるダイスロールやランダムイベント
- テストデータのランダム生成
- 配列要素のランダム選択（インデックス生成）
- シャッフルアルゴリズムの実装
- シミュレーションにおける確率的処理

**主要な処理内容**：
1. 入力パラメータ `$min` と `$max` の検証（$min <= $max）
2. `_Private\Native\pseudorandom_int` ネイティブ関数の呼び出し
3. 擬似乱数生成器から指定範囲内の整数を取得
4. 結果を返却

**関連システム・外部連携**：Hack ランタイムの `_Private\Native\pseudorandom_int` を使用する。これは内部的に高速な PRNG アルゴリズム（通常は Mersenne Twister や xorshift 系）を使用する。

**権限による制御**：本機能は純粋関数として実装されており、特別な権限は必要としない。`[leak_safe]` コンテキストで実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはUIを持たないライブラリのため画面なし |

## 機能種別

計算処理（乱数生成）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $min | int | No | 生成する乱数の最小値。デフォルトは PHP_INT_MIN | $min <= $max でなければならない |
| $max | int | No | 生成する乱数の最大値。デフォルトは PHP_INT_MAX | $min <= $max でなければならない |

### 入力データソース

擬似乱数生成器（PRNG）の内部状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | [$min, $max] の範囲内の擬似ランダム整数。$min 以上 $max 以下の値を返す（両端を含む） |

### 出力先

関数の戻り値として呼び出し元に返却

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの検証
   └─ invariant() で $min <= $max をチェック
   └─ 違反時は InvariantException をスロー
2. ネイティブ関数の呼び出し
   └─ _Private\Native\pseudorandom_int($min, $max) を呼び出し
3. 結果の返却
   └─ PRNG から取得した乱数を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{$min <= $max?}
    B -->|No| C[InvariantException をスロー]
    B -->|Yes| D[_Private\Native\pseudorandom_int 呼び出し]
    D --> E[PRNG から乱数取得]
    E --> F[結果を返却]
    F --> G[終了]
    C --> H[異常終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-155-01 | 範囲制約 | 戻り値は必ず [$min, $max] の範囲内となる（両端を含む） | 常時 |
| BR-155-02 | 入力検証 | $min は $max 以下でなければならない | 常時 |
| BR-155-03 | 非暗号用途 | 暗号用途には使用してはならない | 常時 |
| BR-155-04 | 一様分布 | 範囲内の全ての整数が等確率で選択される | 常時 |

### 計算ロジック

```
// 入力検証
invariant($min <= $max, 'Expected $min (%d) to be less than or equal to $max (%d).', $min, $max);

// ネイティブ関数呼び出し
result = _Private\Native\pseudorandom_int($min, $max)
```

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本機能はデータベース操作を行わない |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | $min > $max の場合 | 呼び出し側で適切な $min, $max を指定する |

### リトライ仕様

リトライ処理は不要。

## トランザクション仕様

本機能はトランザクションを使用しない純粋関数である。

## パフォーマンス要件

- 単一呼び出しのレイテンシ：ナノ秒〜マイクロ秒オーダー
- `SecureRandom\int` より高速（システムコールを伴わない）
- スループット：非常に高い
- 範囲のサイズによるパフォーマンス影響：実質的になし

## セキュリティ考慮事項

- **警告**：この関数は暗号用途に適さない
- 生成される値は予測可能な可能性がある
- PRNG の内部状態が判明した場合、将来の出力を予測される可能性がある
- シード値が同じであれば同じシーケンスが生成される（再現性）
- トークン生成、パスワード、暗号鍵などには絶対に使用しないこと
- セキュリティが必要な場面では `SecureRandom\int` を使用すること

## 備考

- 暗号用途が必要な場合は `SecureRandom\int` を使用すること
- パフォーマンスが重要で、セキュリティが不要な場合に本関数を使用
- デフォルト引数により、PHP_INT_MIN から PHP_INT_MAX の全範囲での乱数生成が可能
- `PseudoRandom\float` は本関数を内部で使用している

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

本機能は単純な整数型のみを扱うため、特別なデータ構造は存在しない。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| - | - | - | 特別なデータ構造なし |

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | pseudo.php | `src/random/pseudo.php` | PseudoRandom\int 関数の実装（31-42行目） |

**主要処理フロー**:
1. **31-34行目**: 関数宣言。$min と $max のデフォルト値は PHP_INT_MIN と PHP_INT_MAX
2. **35-40行目**: invariant による入力検証。$min が $max より大きい場合は例外をスロー
3. **41行目**: `_Private\Native\pseudorandom_int($min, $max)` を呼び出して結果を返却

```hack
function int(
  int $min = \PHP_INT_MIN,
  int $max = \PHP_INT_MAX,
)[leak_safe]: int {
  invariant(
    $min <= $max,
    'Expected $min (%d) to be less than or equal to $max (%d).',
    $min,
    $max,
  );
  return _Private\Native\pseudorandom_int($min, $max);
}
```

#### Step 3: ネイティブ実装への接続を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | - | Hack Runtime | `_Private\Native\pseudorandom_int` はHackランタイムのネイティブ関数。高速なPRNGを使用 |

**読解のコツ**: `_Private\Native\pseudorandom_int` は Hack ランタイムに組み込まれたネイティブ関数であり、Hack コード内では定義されていない。`SecureRandom\int` で使用される `random_int` とは異なり、暗号学的な安全性は保証されないが高速である。

### プログラム呼び出し階層図

```
PseudoRandom\int($min, $max)
    │
    ├─ invariant() [入力検証]
    │
    └─ _Private\Native\pseudorandom_int($min, $max)
           │
           └─ [PRNG 内部状態]
```

### データフロー図

```
[入力]                         [処理]                           [出力]

$min (int) ─────────▶┐
                     ├──▶ invariant() ──▶ 検証OK ──▶ pseudorandom_int()
$max (int) ─────────▶┘                                      │
                                                            ▼
                                                 [$min, $max] 範囲の整数 ──▶ int
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| pseudo.php | `src/random/pseudo.php` | ソース | PseudoRandom 名前空間の公開関数を定義 |
| PseudoRandomTest.php | `tests/random/PseudoRandomTest.php` | テスト | PseudoRandom 関数群のユニットテスト |
| RandomTestTrait.php | `tests/random/RandomTestTrait.php` | テスト | ランダム関数の共通テストトレイト。testIntRange() と testIntException() を含む |
