random

设计契约

XRT 把伪随机数分成两个可独立裁剪的层次：

• XRT_FEATURE_RANDOM_SECURE：直接使用操作系统安全随机源，不依赖 PCG、密码算法或线程运行时。
• XRT_FEATURE_RANDOM_SECURE_TEXT：在系统安全随机源上生成无偏 ASCII 令牌，只依赖 random_secure。
• XRT_FEATURE_RANDOM：调用方持有的 PCG32 显式状态，不分配内存，不依赖线程、任务、时间或密码模块。
• XRT_FEATURE_RANDOM_DEFAULT：当前线程便捷状态，依赖 XRT_FEATURE_RANDOM，首次使用时自动播种，也允许显式播种以复现结果。
• XRT_FEATURE_RANDOM_TEXT：在显式状态上生成可复现 ASCII 文本，依赖 random。
• XRT_FEATURE_RANDOM_TEXT_DEFAULT：在当前线程状态上生成便捷随机文本，依赖 random_text 与 random_default。

显式状态是算法原语，也是测试、模拟、游戏、随机采样和可复现构建应优先使用的路径。便捷层只转发到同一套原语，不维护第二种随机算法。

这里的 PCG 是统计用途伪随机数，不是密码随机源。TLS、WebSocket、令牌、密码、密钥、nonce、UUID v4、临时资源名称和其他安全边界必须使用 xrtSecureRandom 或建立在其上的 Helper；不能使用 xrtRng* 或 xrtRand*。

系统安全随机

Windows 使用系统 CNG BCryptGenRandom，通过线程安全的一次性运行时解析保持单头文件无需额外导入库；成功后缓存系统入口。Linux 优先使用 getrandom，仅在旧内核不支持时回退 /dev/urandom，其他 POSIX 平台使用 /dev/urandom。旧版中已经压实的短读、EINTR、旧内核回退、并发初始化和整缓冲清零边界全部保留。

函数只有在完整填满缓冲后才返回 true。系统源失败时返回 false、清零整个输出，并设置 xrt.random / XRANDOM_ERROR_SYSTEM 结构化错误；绝不退化为 PCG、时间或进程号。空区间直接成功并允许空指针。

random_secure 是独立基础模块。密码密钥生成、TLS、临时文件、原子写和目录树暂存共同依赖它，不会让文件体系反向拉入 crypto_core。

数组洗牌

使用无偏有界采样执行原地 Fisher-Yates 洗牌，支持任意固定大小元素且不分配内存。函数先验证状态、空指针、元素大小、总字节数溢出和数组/状态重叠，再推进随机状态；失败时数组和状态都不变。空数组允许空指针并直接成功。

这个原语承接旧文档中反复手写的洗牌与随机采样底座。抽取前 N 项可以先复制数据、调用 xrtRngShuffle，再读取前 N 项；权重采样和特定概率分布仍由上层按业务规则组合。

随机文本

xrtRngText 是零分配基础 API，把固定长度文本写入调用方缓冲区并补零；容量必须至少为 length + 1。xrtRngStringFrom 创建使用自定义字母表的独立字符串，xrtRngString 使用 0-9A-Za-z-_ 组成的 URL-safe 64 字符默认字母表。对应的 xrtRandText、xrtRandStringFrom、xrtRandString 使用当前线程状态。

自定义字母表必须包含 1 至 94 个互不重复的可见 ASCII 字符。该约束保证输出始终是有效、无嵌入零的 UTF-8 文本，并防止重复字符无意改变概率权重。每个字符都通过拒绝采样选择，不产生 random % alphabet_size 的模偏差。

参数、容量、字母表和重叠会在推进 RNG 前完整检查；失败不改变输出或随机状态。调用方缓冲区不能与字母表或 xrng 状态重叠。长度为零的分配便捷函数仍返回可释放的独立空字符串。

这些 API 继承 PCG 的“可复现但可预测”属性，只适用于测试数据、模拟、游戏、明确不承担安全边界的名称和随机采样。令牌、Cookie 密钥、WebSocket nonce、密码、UUID v4、会话标识和临时资源必须使用 xrtSecureRandom、xrtSecureText 或 xrtSecureString。

旧 API 决策

• xrand 改为 xrng，显式状态统一使用 xrtRng*，当前线程便捷层统一使用 xrtRand*。
• 删除 Ex、Obj 和线程专用版本族。栈上 xrng 已覆盖独立对象，不需要堆分配、ptr 强转和专用销毁函数。
• 64 位输出只消费一个状态，不再要求 low/high 两个生成器。
• 原来的区间函数同时承担“自动交换边界”和“闭区间”两种隐藏规则；现在半开与闭区间分名表达，反向边界明确失败。
• 修复完整 32 位闭区间宽度转换为零后执行除零的问题，并把范围扩展到完整 int64。
• 删除普通伪随机数可生成安全 UUID/GUID 的旧文档建议。

完整示例

• examples/math/random/main.c：显式状态、闭区间和单位实数。
• examples/math/random_secure/main.c：操作系统安全随机源和敏感缓冲清理。
• examples/math/random_secure_text/main.c：URL-safe 密码安全随机令牌。
• examples/math/thread_random/main.c：当前线程便捷状态。
• examples/math/random_text/main.c：显式状态可复现随机文本。
• examples/math/thread_random_text/main.c：当前线程便捷随机文本。

PCG 来源与许可证见 docs/THIRD_PARTY.md。