Expose bounded operating-system cryptographic random bytes

Summary

Expose cryptographically secure bytes from the operating system:

bytes = Random.bytes!(32)?

Illustrative API:

bytes! : U64 => Try(
    List(U8),
    [
        EntropyUnavailable(IOErr),
        TooManyBytes({ requested : U64, max : U64 }),
    ],
)

Exact names can be settled during implementation.

Why this belongs in the platform

Secure randomness is necessary for session identifiers, CSRF tokens, password-reset tokens, webhook secrets, and other conventional web application capabilities. Applications cannot implement it safely in pure Roc, and the platform is the only supported boundary through which they can access the operating system.

OWASP recommends a CSPRNG and at least 128 bits when an application creates session identifiers. A byte API avoids encouraging applications to concatenate or reinterpret a small integer seed.

This is a small, app-independent OS primitive with identical semantics on every target, so it meets the platform subsystem criteria in design.md.

Required contract

• Use the operating system's preferred cryptographic random source on Linux, macOS, and Windows.
• Return exactly the requested number of bytes or a typed failure; never return partial success.
• bytes!(0) returns Ok([]).
• Enforce a documented hard allocation bound before allocating. A proposed initial maximum is 64 KiB.
• Calls are safe under concurrent request handling.
• Do not expose a mutable global PRNG or require application-provided seeding.
• Do not log, inspect, or otherwise expose generated bytes on an error path.
• Coordinate naming with basic-cli's Random module, while keeping this repository independently usable.

Tests

• Zero length, exact maximum, and over-maximum.
• Exact output length over representative sizes.
• Concurrent calls.
• Injected host success and failure paths.
• Native smoke coverage on Linux, macOS, and Windows.
• No statistical randomness tests: those do not validate the security of the OS source.

Non-goals

• Deterministic seeded random-number generation
• Probability distributions or random collection helpers
• UUIDs, tokens, Base64, or hexadecimal encoding
• Key derivation, hashing, signing, or encryption
• Arbitrarily large random buffers

Acceptance criteria

• pf.Random.bytes! returns exact-length OS cryptographic randomness.
• Allocation has a finite documented maximum and typed over-limit error.
• The operation has one cross-platform semantic contract.
• The implementation has no mutable process-global PRNG state.
• Failure and concurrency paths are covered.

References

• OWASP Cryptographic Storage Cheat Sheet
• OWASP Session Management Cheat Sheet
• getrandom::fill semantics

Start by reading design.md and coordinating the naming with basic-cli's Random module. Use the pf.Random.bytes! entry point and the listed zero-length, maximum-bound, concurrency, host success/failure, and native platform checks as the validation map. Done means the acceptance criteria are met across Linux, macOS, and Windows without exposing partial bytes or mutable global PRNG state.