# 機能設計書 151-SecureRandom\float

## 概要

本ドキュメントは、Hack Standard Library (HSL) における `SecureRandom\float` 関数の機能設計を記載する。この関数は暗号学的に安全なランダム浮動小数点数を生成する機能を提供する。

### 本機能の処理概要

`SecureRandom\float` は、暗号学的に安全な方法で [0.0, 1.0) の範囲内のランダムな浮動小数点数を生成する関数である。内部的には `SecureRandom\int` を使用して 0 から `Math\INT53_MAX - 1` の範囲のセキュアな乱数を生成し、それを `Math\INT53_MAX` で除算することで浮動小数点数に変換する。

**業務上の目的・背景**：暗号学的に安全な乱数は、セキュリティが重要なアプリケーション（トークン生成、暗号化キー生成、セキュアなセッション管理など）において不可欠である。通常の擬似乱数生成器は予測可能性があり、攻撃者によって推測される可能性があるため、セキュリティクリティカルな場面では暗号学的に安全な乱数生成が必要となる。浮動小数点数形式での提供は、確率計算やサンプリング処理など、0から1の範囲での乱数が必要な場面で利用される。

**機能の利用シーン**：
- モンテカルロシミュレーションにおけるセキュアな確率生成
- 重み付きランダム選択のセキュアな実装
- 暗号学的に安全な確率的アルゴリズムの実装
- セキュリティが重要な A/B テストの割り当て

**主要な処理内容**：
1. `SecureRandom\int` を呼び出して 0 から `Math\INT53_MAX - 1` の範囲のセキュアな整数乱数を取得
2. 取得した整数を `Math\INT53_MAX` (9007199254740992) で除算
3. 結果を `float` 型にキャストして返却

**関連システム・外部連携**：本機能は Hack ランタイムの `_Private\Native\random_int` を間接的に使用し、オペレーティングシステムが提供する暗号学的に安全なランダムソース（Linux では `/dev/urandom`、Windows では `CryptGenRandom`）からエントロピーを取得する。

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

## 関連画面

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

## 機能種別

計算処理（乱数生成）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | この関数は引数を取らない | - |

### 入力データソース

オペレーティングシステムの暗号学的に安全なランダムソース

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | float | [0.0, 1.0) の範囲内の暗号学的に安全なランダム浮動小数点数。0.0以上1.0未満の値を返す |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. SecureRandom\int を呼び出し
   └─ 引数として $min=0, $max=Math\INT53_MAX-1 を指定
2. 取得した整数値を Math\INT53_MAX で除算
   └─ 整数 / INT53_MAX により [0.0, 1.0) の範囲にスケーリング
3. 結果を float 型にキャストして返却
   └─ 明示的な (float) キャストを適用
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SecureRandom\int 0, INT53_MAX-1 呼び出し]
    B --> C[整数乱数取得]
    C --> D[INT53_MAX で除算]
    D --> E[float にキャスト]
    E --> F[結果を返却]
    F --> G[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-151-01 | 範囲制約 | 戻り値は必ず [0.0, 1.0) の範囲内となる | 常時 |
| BR-151-02 | 暗号学的安全性 | 生成される値は暗号学的に安全でなければならない | 常時 |
| BR-151-03 | 精度保証 | IEEE 754 倍精度浮動小数点の精度範囲内で一様分布を近似する | 常時 |

### 計算ロジック

```
result = (float)(SecureRandom\int(0, INT53_MAX - 1) / INT53_MAX)
```

INT53_MAX (9007199254740992) を使用する理由：
- IEEE 754 倍精度浮動小数点数で正確に表現できる最大の整数
- この範囲内であれば、整数から浮動小数点数への変換で精度が失われない
- 結果として、高い精度での一様分布を実現できる

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | この関数は例外を投げない | - |

### リトライ仕様

リトライ処理は不要。OSレベルのランダムソースへのアクセスは常に成功することが期待される。

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

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

## パフォーマンス要件

- 単一呼び出しのレイテンシ：マイクロ秒オーダー
- スループット：システムのランダムソースに依存するが、一般的に高スループット

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

- 生成される値は暗号学的に安全なランダムソースから導出される
- 予測不可能性が保証されている
- `[leak_safe]` コンテキストで実行可能であり、副作用がない
- セキュリティクリティカルな用途（トークン生成など）に使用可能

## 備考

- 非暗号用途（ゲームのランダム要素など）では、パフォーマンスの観点から `PseudoRandom\float` の使用を検討すること
- INT53_MAX を使用することで、JavaScript との相互運用性も考慮されている（JavaScript の安全な整数範囲と一致）

---

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

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

### 推奨読解順序

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

本機能は単純な数値型のみを扱うため、特別なデータ構造は存在しない。ただし、使用される定数を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | constants.php | `src/math/constants.php` | INT53_MAX 定数の定義（19行目）を確認。値は 9007199254740992 |

**読解のコツ**: INT53_MAX は IEEE 754 倍精度浮動小数点で正確に表現できる最大の整数値であることを理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | secure.php | `src/random/secure.php` | SecureRandom\float 関数の実装（21-23行目） |

**主要処理フロー**:
1. **21行目**: 関数宣言。`[leak_safe]` コンテキストで float を返す
2. **22行目**: `SecureRandom\int(0, Math\INT53_MAX - 1)` でセキュアな整数乱数を生成
3. **22行目**: 生成した整数を `Math\INT53_MAX` で除算して [0.0, 1.0) にスケーリング

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | secure.php | `src/random/secure.php` | SecureRandom\int 関数の実装（31-42行目）。$min/$max のバリデーションと native 関数呼び出し |

**主要処理フロー**:
- **35-40行目**: invariant による入力検証（$min <= $max）
- **41行目**: `_Private\Native\random_int` を呼び出してセキュアな整数を生成

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

```
SecureRandom\float()
    │
    └─ SecureRandom\int(0, INT53_MAX - 1)
           │
           └─ _Private\Native\random_int($min, $max)
                  │
                  └─ [OS暗号化ランダムソース]
```

### データフロー図

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

なし ───────────▶ SecureRandom\int() ─────▶ 整数乱数 (0 ~ INT53_MAX-1)
                         │
                         ▼
                  INT53_MAX で除算
                         │
                         ▼
                  float キャスト ─────────▶ float [0.0, 1.0)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| secure.php | `src/random/secure.php` | ソース | SecureRandom 名前空間の公開関数を定義 |
| constants.php | `src/math/constants.php` | ソース | INT53_MAX などの数学定数を定義 |
| SecureRandomTest.php | `tests/random/SecureRandomTest.php` | テスト | SecureRandom 関数群のユニットテスト |
| RandomTestTrait.php | `tests/random/RandomTestTrait.php` | テスト | ランダム関数の共通テストトレイト |
