The ambient nondeterminism a test needs to control.
The guarantee is the product: the same seed produces the same sequence, on every platform, forever.
Scoped precisely, because half of it is provable and half is not:
| Guarantee | Basis | |
|---|---|---|
SplitMix64, Xoshiro256StarStar |
identical output on any platform | provable — pure UInt64 arithmetic with Swift-defined overflow. These import nothing, not even Foundation |
WallClock, IdentifierSource, StableOrdering |
identical behaviour | value semantics and integer arithmetic |
FormattingEnvironment |
identical strings | verified on Darwin only. It routes through ICU, which differs between Darwin Foundation and swift-corelibs-foundation |
import SwiftDeterminism
var rng = SplitMix64(seed: 42)
let value = Double.random(in: 0...1, using: &rng) // identical on every runSwift's standard library ships no seeded random number generator.
SystemRandomNumberGenerator is the only concrete RandomNumberGenerator it offers, and it
is deliberately unseedable — unpredictability is its contract. Foundation adds nothing, and
GameplayKit's Mersenne Twister is Apple-only.
So every project writes its own. This portfolio had done it four times, in four places, with four names — and all four were arithmetically identical.
A test drawing from the system generator that fails once in CI carries no reproduction. It gets triaged as flakiness and retried until it passes, which is indistinguishable from fixing it, and is how a real defect survives.
An implementation change that alters an output sequence is a breaking change here in a way
it is not in most libraries, because downstream tests encode expected values. Known-answer
tests pin it against Vigna's published reference: seed 0 yields 0xE220A8397B1DCDAF first.
An implementation checked only against its own output agrees with itself perfectly and may still be wrong.
SplitMix64's mixing function is invertible — two outputs are enough to recover the state and
predict the rest. Never use it for keys, tokens, session identifiers, salts, or PKCE
verifiers. SystemRandomNumberGenerator is the standard library's CSPRNG and is correct there.
Two of the four implementations this consolidates are product code — Monte Carlo simulation and game state. This ships as an ordinary library with no test-framework dependency.
SplitMix64 and its known-answer tests. See project/master_plan.md
for the migration roadmap and what is deliberately excluded.
Proprietary.