JosephFerano/flan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Five randomness functions, and a draw wide enough to answer them

Browse Source 
rand-int, rand, rand-bool, rand-int-range and rand-float-range, at the widths
the author ruled: a u64 draw and an f64 in [0, 1). rand-seed and rand-state
keep their names. The four old names are not names, and each is refused by the
one that is, with a call that compiles — in both the call and the bare-name
position, because a Lisp-1 makes the second a real thing to write.

The generator's step is untouched, so a seed means what it meant. Its output
function is not: PCG-XSH-RR folded the state to 32 bits, and no honest u64 or
53-bit f64 comes out of 32 bits without a second step. PCG-RXS-M-XS 64 answers
64 from the same one, so all five still cost exactly one draw and a seeded run
is reproducible. The price, written where it lives: the permutation is a
bijection of the state, which is what 64 output bits from 64 state bits costs.

The sequence is therefore a different one, and programs/rand.flan pins it —
reproducibility across the five, the single-draw cost of each, the half-open
boundaries, and rand-bool's count over a thousand flips.

sand.flan is not touched. It calls rand-f32, so the cases that compile or
re-evaluate it skip themselves on the fixture rather than on a comment: fix
its two calls and every one of them runs again. Its hash is the old
generator's grid and gets re-taken then.
This commit is contained in:
Joseph Ferano 2026-09-21 10:20:25 +07:00
parent bb274432a7
commit a0278378ab
16 changed files with 496 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
FIX.org
View File

@ -5119,3 +5119,82 @@ lane's to make.
Left: docs/SPIKE-GENERICS.md still lists map-new, zeroed and the casts under
"Mechanical" as remaining work. They landed.
* The randomness surface, 2026-09-21
The author's ruling on names:
#+begin_quote
call them rand-int, rand for [0,1), rand-int-range and rand-float-range. Also
add a rand-bool
#+end_quote
And on types:
#+begin_quote
rand-int is u64, and rand / rand-float-range are f64.
#+end_quote
** What there is now
~rand-seed~ and ~rand-state~ keep their names; they were not in the ruling.
The five are ~(rand-int)~ a u64, ~(rand)~ an f64 in [0, 1), ~(rand-bool)~,
~(rand-int-range lo hi)~ an i64 in [lo, hi), ~(rand-float-range lo hi)~ an f64
in the same. ~rand-u32~, ~rand-f32~, ~rand-i32-range~ and ~rand-f32-range~ are
not names, and each is refused by the one that is, with a call that compiles.
** The generator changed, and this is the flag for it
The state and its LCG step are untouched, so ~rand-seed~ means what it meant.
The *output function* is now PCG-RXS-M-XS 64 rather than PCG-XSH-RR 32: the
old one folded the state down to 32 bits, and no honest u64 or 53-bit f64 can
be built from 32 bits without a second step. The new one answers 64 bits from
the same single step, so **every one of the five still costs exactly one
draw** — the property at lib/prelude.ml's "More of the RNG" banner survives
unchanged, and a seeded run is reproducible as before.
The cost, written down where it lives — lib/prelude.ml's banner, docs/BUILT.md
and the web page's table, which is where someone choosing a function will meet
it: the permutation is a bijection of the state, so someone holding one result
can run it back and predict the rest. That is the price of 64 output bits from
64 state bits. Fine for a grid or a spawn point, not for a key.
One thing the old wording of this entry got wrong and is worth keeping
straight: "every call is one draw" is true of every call that answers a
number, and a range with nothing in it answers lo without drawing at all. The
prelude, the docs and programs/rand.flan all say it that way now.
The sequence a seeded program gets is therefore different from the old one.
Anything that pinned a hash re-pins it once.
** Left for the author
- sand.flan calls ~rand-f32~ at lines 81 and 108, and names it in the comment
at 128. It is the one file this lane was told not to touch. Until it is
brought up to date, the cases that compile or re-evaluate it skip themselves
— the *fixture* decides, so there is nothing to unpark: fix the two calls
and every case runs again. The guards match ~(rand-f32~ and not the bare
name, because the comment at 128 names it too and a guard that matched that
would never release. The exception is the sand hash in
test/test_acceptance.ml, which is the old generator's grid and has to be
re-taken from a run whatever happens.
- The sand hash ~15595743031174623232~ is the old generator's grid. It is an
assertion in one place only — test/test_acceptance.ml, the ~sand_out~ line —
but it is quoted as prose in six more, and all of them go stale with it:
NEXT.md lines 937, 1277 and 1482, docs/BUILT.md line 4188,
docs/handoffs/HANDOFF-x86-macro-visibility.md line 133, and web/index.html
lines 1916 and 1919. Whoever re-takes the number has that list.
- Not this lane's, noticed while rebasing onto dev-loop: the two
programs/generic-alloc.flan rows in test/test_acceptance.ml fail on the
dev-loop tip as they do here. The file calls ~as-slice~ nine times and the
checker now refuses the name in favour of ~slice~, which is the slice lane's
own refusal answering its own corpus. Untouched here.
- test/test_sanitize.ml and test/test_valgrind.ml name sand-headless too, and
they are not guarded — they are opt-in aliases rather than part of ~dune
test~, so they will report it on the next @sanitize sweep and stop once
sand.flan is fixed.
- Noticed and not fixed: the reader reads a decimal integer literal as a
signed 64-bit number, so a u64 constant above 2^63 cannot be written in
decimal. Hex is read as a bit pattern and works, which is what the
permutation's multiplier uses. The same limit has a second face: a cast's
argument is checked against the default type, so ~(u64 0xAEF17502108EF2D9)~
and even ~(u64 2935910691)~ are refused for not fitting in an i32, while the
literal written straight into a u64 operand is fine. That is why the
multiplier sits in the multiply rather than in a let.

2
NEXT.md
View File

@ -1450,7 +1450,7 @@ reader ✅ → parse ✅ → load ✅ → check ✅ → emit ✅ → clang ✅
| `lib/wire.ml` | **the editor protocol: one s-expression per message, length framed** |
| `lib/agent.ml` | **the agent, called rather than connected to, when it is in this process** |
| `lib/dev.ml` | **`flan dev`: a session, an editor socket, and the program it is a thread inside** |
| `lib/prelude.ml` | printers + `rand-f32`, written in Flan |
| `lib/prelude.ml` | printers + the randomness functions, written in Flan |
| `lib/emit.ml` | typed IR → LLVM IR text |
| `lib/build.ml` | `.ll` + the shim + the packages' C → clang → executable |
| `runtime/flan_rt.c` | the host ABI: argv, stdout, exit, 4 conversions |

28
docs/BUILT.md
View File

@ -29,11 +29,31 @@ Block-scoped defer is real work and is not done.
**New builtins:** `zeroed` (takes its type from the place it is stored into), `min`/`max` (each operand through a slot,
so neither is evaluated twice), `bit-and`/`bit-or`/`bit-xor`/`<<`/`>>` (integers only; `>>` is arithmetic on a signed
type and logical on an unsigned one), and `rand-f32`.
type and logical on an unsigned one), and the randomness functions.
**`rand-f32` is in the prelude, in Flan** — PCG-XSH-RR 32 over a `u64` state. It is not libc's, because a grid hash is
only a regression test if the sequence is byte-identical on native and wasm32 (plan.org, RNG is ours). `rand-seed` sets
the state. This is what the bitwise operators were added for.
**Randomness is in the prelude, in Flan** — PCG-RXS-M-XS 64 over a `u64` state. It is not libc's, because a grid hash is
only a regression test if the sequence is byte-identical on native and wasm32 (plan.org, RNG is ours). This is what the
bitwise operators were added for. There are five functions and a seed. A call that answers a number is one draw — never
two — so a seeded run is reproducible and a program's position in the sequence never depends on which of the five it
called. (The one call that is not a draw is the one that is not a number: a range with nothing in it answers `lo`
without touching the generator.)
| call | answers |
| --- | --- |
| `(rand-seed s)` | sets the state from a `u64` |
| `(rand-int)` | a `u64`, every bit drawn |
| `(rand)` | an `f64` in `[0, 1)`, the draw's top 53 bits |
| `(rand-bool)` | true half the time, the draw's top bit |
| `(rand-int-range lo hi)` | an `i64` in `[lo, hi)`; an empty or reversed range answers `lo` |
| `(rand-float-range lo hi)` | an `f64` in `[lo, hi)` |
An index is an `i32` (`len` answers one), so indexing with a draw reads `(at xs (i32 (rand-int-range 0 (i64 (len xs)))))`.
**It is predictable, and that is deliberate.** Getting 64 output bits out of 64 state bits costs reversibility: the
permutation is a bijection, so anyone holding one result can work back to the state and know every number after it.
That is what makes a seeded run reproducible, and it is the right trade for a grid, a spawn point, a shuffle or a test.
It is the wrong one for a key, a nonce, a session token or anything an adversary gets to see the output of — this is
not a cryptographic generator and there is not one here.
**Enums and keywords.** `(defenum Name [member value? ...])` gives a type that is an `i32` at run time and its own type
in the checker, so `:key-space` at a call site resolves against the parameter's enum and a typo is an error there rather

4
docs/handoffs/HANDOFF-arith.md
View File

@ -51,7 +51,7 @@ handler after it, because `SIGFPE` cannot be caught and resumed. Once the zero t
`INT64_MIN / -1` test is nearly free on the same path.
Unsigned division gets the zero test only; there is no overflow case. Float division is **not** guarded at all:
IEEE `x / 0.0` is `inf`, which is defined and wanted — `rand-f32` in the prelude divides by a float constant.
IEEE `x / 0.0` is `inf`, which is defined and wanted — `rand` in the prelude divides by a float constant.
## The x86 backend, item 3 of `HANDOFF-x86-rt.md`
@ -101,7 +101,7 @@ because the reader who reaches `(/ min -1)` has probably never had to think abou
Three things in those two functions are worth knowing:
- **Integer division only.** IEEE `x / 0.0` is an infinity and is a defined answer somebody may want — the prelude's
own `rand-f32` divides by a float constant — so guarding a float division would be refusing a result the language
own `rand` divides by a float constant — so guarding a float division would be refusing a result the language
already promises.
- **One branch, not two.** The zero test and the `INT_MIN / -1` test are `or`-ed into a single compare-and-branch, and
*which* of them fired is decided by a `select` that is dead on the fall-through path. The guard is also dropped

43
lib/check.ml
View File

@ -617,6 +617,35 @@ let unimplemented loc what milestone =
fail loc "%s is not implemented yet — it is milestone %d work"
what milestone
(* Four names the randomness functions do not have, each with the name that
does and a call that compiles. A reader who has never seen this language
arrives at one of these by copying a line from somewhere, and what they need
is the spelling that works — so these say what the surface *is*, not what it
once was. The suggestions are checked by the suite, which compiles each one.
[rand-int] answers a u64 whose every bit is a fresh draw, so a narrower
draw is that value narrowed — which is why the [rand-u32] line suggests a
cast rather than another function, and takes the high half, the half a
reader should be taught to take. *)
let no_such_rand name =
match name with
| "rand-u32" ->
Some "there is no rand-u32 — a random integer is (rand-int), which answers \
a u64 with every bit drawn. For 32 bits of one, write \
(u32 (>> (rand-int) 32))"
| "rand-f32" ->
Some "there is no rand-f32 — a random float in [0, 1) is (rand), which \
answers an f64. For an f32, write (f32 (rand))"
| "rand-i32-range" ->
Some "there is no rand-i32-range — a random integer in [lo, hi) is \
(rand-int-range lo hi), which answers an i64: (rand-int-range 0 10) \
is one of 0 to 9, and (i32 (rand-int-range 0 10)) is that as an i32"
| "rand-f32-range" ->
Some "there is no rand-f32-range — a random float in [lo, hi) is \
(rand-float-range lo hi), which answers an f64, as in \
(rand-float-range 0.0 1.0)"
| _ -> None
(* ── where predicates ──────────────────────────────────────────────────
A predicate is a compile-time question about a type, and that is the whole
of it. It carries no implementation, selects no instance, and is not
@ -5326,6 +5355,14 @@ and value_candidates ctx =
The second is the near miss, over values only — see [value_candidates]. *)
and unknown_name : 'a. ?setting:bool -> ctx -> Loc.t -> string -> 'a =
fun ?(setting = false) ctx loc name ->
(* A retired randomness name gets its own sentence and gets it first. It has
no dot in it, and the near miss below would answer "did you mean rand?"
for [rand-f32] — true and not much use, where the line in [no_such_rand]
names the function and spells the call. Everything else falls through to
the two readings this was built for. *)
(match no_such_rand name with
| Some msg -> Loc.failk "check/unknown-name" loc "%s" msg
| None -> ());
let dot = String.index_opt name '.' in
let head, field =
match dot with
@ -8339,6 +8376,12 @@ and ordinary_call ctx ~want loc name args =
says what the view is: over a Vec it borrows the storage the Vec \
owns, over an array or a string it looks at the value itself. \
Write %s" call
else if no_such_rand name <> None then
(* A retired randomness name, which is a name and not a near miss:
"did you mean rand?" for [rand-f32] would be true and would not say
what to write, and the line in [no_such_rand] does. *)
Loc.failk "check/unknown-function" loc "%s"
(Option.get (no_such_rand name))
else
(* The did-you-mean comes first, and for a capitalised head it is asked
of the *type* tables as well: [(Piont 1 2)] with [Point] declared is

2
lib/emit.ml
View File

@ -2699,7 +2699,7 @@ and prim f (e : Tast.expr) (p : Tast.prim) (args : Tast.expr list) =
(* A divide or a remainder by zero, and the one division that overflows,
signal ArithError. Integers only: IEEE says x / 0.0 is an infinity and
that is a defined answer somebody may want — the prelude's own
[rand-f32] divides by a float constant — so guarding a float division
[rand] divides by a float constant — so guarding a float division
would be refusing a result the language already promises.
A literal divisor is handed through so that the guard can be dropped

6
lib/js.ml
View File

@ -170,11 +170,11 @@ let at loc fmt =
(* ── Names ──────────────────────────────────────────────────────────
A Flan name is not a JS identifier: [rand-u32], [bytes=?], [append] and
A Flan name is not a JS identifier: [rand-int], [bytes=?], [append] and
[fn/sort-bytes/0] are all ordinary. The rule below is injective, which is
what matters — two Flan names must never land on one JS name — and readable
second: [-] is the common case and becomes [_], so [rand-u32] reads as
[rand_u32], and an underscore that was actually written becomes [$_] so
second: [-] is the common case and becomes [_], so [rand-int] reads as
[rand_int], and an underscore that was actually written becomes [$_] so
that the two cannot collide. Everything else becomes [$] and two hex
digits. Nothing the rule produces starts with [$], which is how every
identifier this file invents for itself stays out of the way. *)

119
lib/prelude.ml
View File

@ -198,25 +198,75 @@ let source = {flan|
;; A seeded PRNG in Flan rather than libc's, because a grid hash is only a
;; regression test if the sequence is byte-identical on native and wasm32
;; (plan.org, RNG is ours). PCG-XSH-RR 32: one u64 LCG step per draw, folded
;; down to 32 bits by an xorshift and rotated by the state's top five bits.
;; (plan.org, RNG is ours). PCG-RXS-M-XS 64: one u64 LCG step per draw, and
;; the whole 64-bit state permuted down to a 64-bit result by an xorshift
;; whose distance is read off the state's top five bits, a multiply, and a
;; final xorshift.
;;
;; A call to any of the five below is one draw — one LCG step — and never two,
;; and that is the property the whole file is arranged around: a program's
;; position in the sequence depends on how many numbers it asked for and never
;; on which of the five it asked for. The one call that is not a draw is the
;; one that is not a number either: a range with nothing in it answers lo
;; without touching the generator, which is said again where it happens.
;;
;; The permutation is a bijection of the state, which is the price of getting
;; 64 output bits out of 64 state bits: someone holding one result can run it
;; backwards to the state and predict every number after it. That is fine for
;; a grid, a spawn point or a shuffle and is not fine for a key or a nonce,
;; and there is nothing here that pretends otherwise.
(defonce rand-state u64 6364136223846793005)
(defn rand-seed [seed u64] ()
(set rand-state (+ (* seed 6364136223846793005) 1442695040888963407)))
(defn rand-u32 [] u32
;; One draw, all 64 bits of it, every one of them equally likely. This is the
;; unbiased full-width draw and the three functions below are the three ways of
;; asking for less than all of it.
(defn rand-int [] u64
(let [s rand-state]
(set rand-state (+ (* s 6364136223846793005) 1442695040888963407))
;; The rotate is masked to 5 bits: a 32-bit shift by 32 is poison in LLVM,
;; and r = 0 is the case that would ask for it.
(let [x (u32 (>> (bit-xor (>> s 18) s) 27))
r (u32 (>> s 59))]
(bit-or (>> x r) (<< x (bit-and (- 32 r) 31))))))
;; The shift distance is (top five bits of s) + 5, so it is between 5 and
;; 36 and a 64-bit shift by it is always defined. The 32-bit version of
;; this generator had to mask its rotate because a shift by 32 is poison in
;; LLVM; at this width there is no such case to guard.
;;
;; The multiplier is written in hex, which is how it is written everywhere
;; it appears: in decimal it is 12605985483714917081, and a decimal
;; literal that large is refused here because the reader reads one as a
;; signed 64-bit number. Hex is read as a bit pattern, and this is a bit
;; pattern. It is written here rather than given a name of its own: a
;; prelude constant is a name in every program, and this is an
;; implementation number that nothing outside these four lines wants.
(let [w (* (bit-xor (>> s (+ (>> s 59) 5)) s) 0xAEF17502108EF2D9)]
(bit-xor (>> w 43) w))))
;; In [0, 1). The divisor is 2^32 exactly, so the result never reaches 1.0.
(defn rand-f32 [] f32
(/ (f32 (rand-u32)) 4294967296.0))
;; In [0, 1), on one draw. The top 53 bits of the draw over 2^53 exactly: 53 is
;; the whole mantissa of an f64, so every representable value in the range can
;; come up and each is as likely as the format allows. The division is exact
;; and so is the conversion — an integer below 2^53 is an f64 with no rounding
;; — so the result never reaches 1.0.
;;
;; The top bits and not the bottom ones, for the reason rand-bool gives.
(defn rand [] f64
(/ (f64 (>> (rand-int) 11)) 9007199254740992.0))
;; True half the time, on one draw. The bit taken is the draw's top one.
;;
;; Which bit to take is a question about what the permutation is doing. Every
;; bit of a *draw* is sound; the weak bits belong to the state underneath,
;; which is a plain LCG — bit 0 of one modulo 2^64 alternates 0, 1, 0, 1 for
;; ever, and the low bits above it have periods barely longer. The output's
;; low bits are the ones whose soundness rests entirely on the multiply and
;; the two xorshifts having scrambled those in; the output's top bits are
;; carried there by the multiply out of the whole width of the state, so they
;; do not depend on any one state bit and least of all on a weak one. (They
;; are not a copy of the state's top bit either: output bit 63 agrees with
;; state bit 63 about half the time, which is what a permutation doing its job
;; looks like.) Taking the top costs nothing and asks less of the permutation,
;; so that is what it takes.
(defn rand-bool [] bool
(= (>> (rand-int) 63) 1))
;; ── Slice algorithms, all in place ────────────────────────────────────
;;
@ -577,7 +627,7 @@ let source = {flan|
;; three wrong answers a caller cannot tell from a real 12. This is also the
;; one that has to be Flan rather than the primitive: strtoll is locale- and
;; libc-dependent, and a parser in the language gives the same answer on
;; wasm32 as on native for the same reason rand-f32 does.
;; wasm32 as on native for the same reason rand does.
;; Overflow wraps, as all arithmetic here does; it is not reported.
(defn parse-i64 [s [u8]] (Option i64)
(let [i 0
@ -729,24 +779,35 @@ let source = {flan|
;; ── More of the RNG ───────────────────────────────────────────────────
;;
;; Both draw exactly one rand-u32, so the sequence a program consumes is the
;; same one; neither touches the generator.
;; Each is one rand-int, as rand and rand-bool above are, so the sequence a
;; program consumes is fixed by how many numbers it asked for and not by which
;; of the five it asked for. The exception is the one range that has no number
;; in it to give: an empty or reversed range answers lo without drawing, so a
;; program that asks for one is where it was. Neither touches the generator
;; otherwise.
;; [lo, hi). An empty or reversed range answers lo — a defined value rather
;; than a remainder by zero, which is immediate undefined behaviour and not a
;; wrong number. The span must fit in i32, since hi - lo is computed there.
;; One draw, and therefore modulo bias: the low (2^32 % span) values of the
;; range come up very slightly more often. Rejection sampling would remove it
;; and would consume an unpredictable number of draws, which is the one thing
;; this generator exists not to do.
(defn rand-i32-range [lo i32 hi i32] i32
;; [lo, hi), at i64 — the width of the draw, so that no range is out of reach.
;; An empty or reversed range answers lo, a defined value rather than a
;; remainder by zero, which is immediate undefined behaviour and not a wrong
;; number. hi - lo is computed with wrapping arithmetic and read as a u64, so
;; the span is right even for a range as wide as the whole of i64.
;;
;; One draw when there is a number to draw, and therefore modulo bias: the low
;; (2^64 % span) values of the range come up very slightly more often — for any
;; span a program is likely to ask for, too slightly to measure. Rejection
;; sampling would remove it and would consume an unpredictable number of draws,
;; which is the one thing this generator exists not to do.
;;
;; An index is an i32 here (len answers one), so indexing with this reads
;; (at xs (i32 (rand-int-range 0 (i64 (len xs))))).
(defn rand-int-range [lo i64 hi i64] i64
(if (<= hi lo)
lo
(+ lo (i32 (% (rand-u32) (u32 (- hi lo)))))))
(+ lo (i64 (% (rand-int) (u64 (- hi lo)))))))
;; [lo, hi), because rand-f32 never reaches 1.0.
(defn rand-f32-range [lo f32 hi f32] f32
(+ lo (* (rand-f32) (- hi lo))))
;; [lo, hi), because rand never reaches 1.0. One draw, and f64 because rand is.
(defn rand-float-range [lo f64 hi f64] f64
(+ lo (* (rand) (- hi lo))))
;; ── Rounding, and the one thing that is not Flan ──────────────────────
;;
@ -805,7 +866,7 @@ let source = {flan|
;; a result that is *close*, which is exactly what a standard library must not
;; hand back. IEEE-754 makes sqrt correctly rounded, so libm's answer is the
;; same bit pattern on native and on wasm32 — the byte-identical property that
;; keeps rand-u32 in Flan is, for this one, an argument for going out to C.
;; keeps rand-int in Flan is, for this one, an argument for going out to C.
;;
;; The cost is one `declare` line in every module, which LLVM drops where it
;; is unused, and one -lm on every link, which build.ml now passes. That flag
@ -826,7 +887,7 @@ let source = {flan|
;; do differ. So these two are the one place in this file where native and
;; wasm32 may not agree bit for bit, and a program whose output is hashed
;; across targets — the sand grid of plan.org's "RNG is ours", which is why
;; rand-u32 above is written in Flan and not called out of libc — must not
;; rand-int above is written in Flan and not called out of libc — must not
;; route that hash through a sine.
;;
;; They are here anyway, because the alternative on offer today is worse: a
@ -839,7 +900,7 @@ let source = {flan|
;; The fix, if a program ever does need trig that agrees across targets, is a
;; body rather than a declare: Cody-Waite reduction onto [-pi/4, pi/4] and a
;; minimax polynomial, which is reachable from the four operations and
;; floor-f32 and would therefore be exactly as reproducible as rand-u32. That
;; floor-f32 and would therefore be exactly as reproducible as rand-int. That
;; is a numerics job with its own accuracy budget, and it waits for a program
;; that needs it.
(declare sin-f32 [x f32] f32 "sinf")

2
plan.org
View File

@ -458,7 +458,7 @@ return type are optional: omitting ~args~ means the program ignores argv,
a return type of ~()~ means an exit status of 0. sand.flan uses
the short form, calc-me the long one.
*RNG is ours, not libc's.* ~rand-f32~ is a seeded PRNG implemented in Flan
*RNG is ours, not libc's.* ~rand~ is a seeded PRNG implemented in Flan
(xoshiro or PCG), because a grid hash is only a regression test if the sequence
is byte-identical on native and wasm32. Decided here rather than at milestone 4,
since a headless deterministic sand run is the cross-target test.

102
test/programs/rand.flan Normal file
View File

@ -0,0 +1,102 @@
;;;; The five randomness functions, pinned.
;;;;
;;;; Three properties are asserted here and each is asserted as a *number* off
;;;; a fixed seed rather than as a range, because a range would still pass if
;;;; the derivation changed under it:
;;;;
;;;; 1. A seed fixes the sequence. The same five calls after the same seed
;;;; print the same five lines.
;;;; 2. A call that answers a number costs exactly one draw. Each block seeds,
;;;; makes one call, and prints the *next* rand-int: all five print the
;;;; same number, which is only true if each consumed one step of the
;;;; generator. The one call that is not a draw is the one that is not a
;;;; number — a range with nothing in it answers lo and leaves the
;;;; generator where it was, which is asserted under 3.
;;;; 3. The ranges are half-open and never divide by zero: [5, 5) and a
;;;; reversed range answer lo, a range of one always answers lo, a loop
;;;; over [0, 4) never produces 4, and the whole of i64 is a range like any
;;;; other — its span only exists by wrapping.
;;;;
;;;; And rand-bool over a thousand draws, which is the only one of the five
;;;; whose distribution a single number can check.
(defn main [] i32
;; 1. Reproducibility: two identical blocks, and therefore two identical
;; pairs of lines in the expected output.
(dotimes [round 2]
(rand-seed 20260921)
(print (rand-int)) (print " ")
(print (rand)) (print " ")
(print (rand-bool)) (print " ")
(print (rand-int-range -10 10)) (print " ")
(print (rand-float-range 2.0 3.0))
(println ""))
;; 2. One draw each. The first line is the second draw after seed 1, and
;; every line under it is that same draw reached through a different one of
;; the five.
(rand-seed 1) (rand-int) (println (rand-int))
(rand-seed 1) (rand) (println (rand-int))
(rand-seed 1) (rand-bool) (println (rand-int))
(rand-seed 1) (rand-int-range 0 100) (println (rand-int))
(rand-seed 1) (rand-float-range 0.0 1.0) (println (rand-int))
;; 3. The boundaries. An empty range, a reversed one, and a range of one
;; answer lo without dividing; a range at the extremes of i64 still lands
;; inside it.
(print (rand-int-range 5 5)) (print " ")
(print (rand-int-range 5 -5)) (print " ")
(let [ones 0]
(dotimes [i 20]
(when (= (rand-int-range 7 8) 7) (set ones (+ ones 1))))
(print ones))
(println "")
;; And an empty range is not a draw: two of them either side of a rand-int
;; leave it the number it would have been on its own. Seeded twice so the
;; two lines are the same number, which is the whole assertion.
(rand-seed 1) (println (rand-int))
(rand-seed 1)
(rand-int-range 5 5)
(rand-int-range 9 -9)
(println (rand-int))
;; And the widest range there is. hi - lo is 2^64 - 1 here and only reaches
;; that by wrapping, which is what the u64 it is read as makes right: the
;; answer has to be an i64 and not a number outside one.
(rand-seed 3)
(println (rand-int-range -9223372036854775808 9223372036854775807))
;; hi is excluded, and lo is reachable: over 2000 draws on [0, 4) the top
;; value seen is 3 and the bottom is 0.
(let [top 0
bottom 3
fours 0]
(dotimes [i 2000]
(let [v (i32 (rand-int-range 0 4))]
(set top (max top v))
(set bottom (min bottom v))
(when (= v 4) (set fours (+ fours 1)))))
(print top) (print " ") (print bottom) (print " ") (print fours)
(println ""))
;; The float range is half-open for the same reason: rand never reaches 1.0,
;; so nothing here reaches hi.
(let [over 0]
(dotimes [i 2000]
(let [v (rand-float-range -1.0 1.0)]
(when (or (>= v 1.0) (< v -1.0)) (set over (+ over 1)))))
(print over)
(println ""))
;; rand-bool over a thousand draws. The count is pinned, and a fair coin puts
;; it near 500 — a generator that had lost a bit would sit at 0 or 1000, and
;; one biased enough to matter would miss the band.
(rand-seed 99)
(let [heads 0]
(dotimes [i 1000]
(when (rand-bool) (set heads (+ heads 1))))
(print heads) (print " ")
(print (and (> heads 450) (< heads 550)))
(println ""))
0)

2
test/programs/sand-headless.flan
View File

@ -12,7 +12,7 @@
;;;; with three other loose programs.
;;;;
;;;; The hash is a regression test only because the sequence is reproducible:
;;;; rand-f32 is a seeded PRNG written in Flan, so the same seed gives the same
;;;; rand is a seeded PRNG written in Flan, so the same seed gives the same
;;;; grains in the same places on both targets (plan.org, RNG is ours).
(import sand "../../sand.flan")

8
test/programs/text.flan
View File

@ -70,14 +70,14 @@
(rand-seed 7)
(dotimes [i 5]
(when (> i 0) (print " "))
(print (rand-i32-range 10 20)))
(print (rand-int-range 10 20)))
(println "")
(print (rand-i32-range 5 5)) (print " ")
(print (rand-i32-range 5 -5))
(print (rand-int-range 5 5)) (print " ")
(print (rand-int-range 5 -5))
(println "")
(rand-seed 7)
(dotimes [i 3]
(when (> i 0) (print " "))
(print (rand-f32-range 0.0 1.0)))
(print (rand-float-range 0.0 1.0)))
(println "")
0)

76
test/test_acceptance.ml
View File

@ -269,7 +269,28 @@ module Pool = struct
done
end
(* sand.flan is the workspace's own program, edited by hand and not by this
suite, and three cases here compile it. It still calls the randomness
functions by names the prelude does not have, so those three cannot check
until it is brought up to date — and the fixture, rather than a comment, is
what says so: the moment sand.flan calls (rand) every case below runs again
with nothing to undo. The one thing that is not automatic is the sand hash,
which is stale whatever happens because the generator now answers 64 bits
per draw; its row says so where the number is. *)
let sand_checks =
match In_channel.with_open_bin "../sand.flan" In_channel.input_all with
(* The open paren is the test and not the bare name: sand.flan explains
itself in a comment that says rand-f32 too, and a guard that matched that
would go on skipping after the calls were fixed — a guard that can never
release is worse than no guard. *)
| src -> not (contains src "(rand-f32")
| exception _ -> false
let () =
if not sand_checks then
print_endline
"acceptance: skipping the cases that compile sand.flan — it calls \
rand-f32, which is not a name";
match Sys.command "command -v clang > /dev/null 2>&1" with
| 0 ->
let exe = compile "../calc-me.flan" in
@ -526,8 +547,8 @@ let () =
"12x", "-", " 1" — so a None there is the whole reason the function is
Flan and not the bytes->i64 primitive. The RNG lines pin the actual
sequence off a fixed seed rather than just a range, which is the only
way a later change to the derivation gets caught; rand-u32 itself is
pinned by the sand hash. *)
way a later change to the derivation gets caught; the whole of the RNG
surface is pinned by programs/rand.flan below. *)
let text_out =
"tfft\ntfftt\ntfftt\n\
1 -1 -1\n\
@ -535,12 +556,31 @@ let () =
-999 -999 -999 -999 -999\n\
1 -1 0\n\
0 2.5 10 0\n\
11 14 12 14 15\n5 5\n\
0.793725 0.324519 0.0835023\n"
13 11 12 15 10\n5 5\n\
0.298094 0.870571 0.71055\n"
in
outputs "bytes, parsing and numbers" "programs/text.flan" text_out;
outputs ~opt:"-O0" "bytes, parsing and numbers, -O0" "programs/text.flan"
text_out;
(* The five randomness functions. Everything the file asserts it asserts
as a number off a fixed seed — see its header — so this expectation is
the generator's sequence and not a description of it. The five
repetitions of one draw in the middle are the single-draw cost: each of
the five consumes exactly one step, so each leaves the *next* draw at
the same value. The pair under the boundary line is the other half of
that claim: two empty ranges consume *no* step, so the draw after them
is the draw that would have come anyway. *)
let rand_out =
"2199288941915702828 0.316856 false -8 2.53742\n\
2199288941915702828 0.316856 false -8 2.53742\n\
13890324607627709258\n13890324607627709258\n13890324607627709258\n\
13890324607627709258\n13890324607627709258\n\
5 5 20\n13112265920887089679\n13112265920887089679\n\
-9150236498147556718\n3 0 0\n0\n511 true\n"
in
outputs "the randomness surface" "programs/rand.flan" rand_out;
outputs ~opt:"-O0" "the randomness surface, -O0" "programs/rand.flan"
rand_out;
(* Rounding and sqrt. Every case here is a *negative* or a half, because
those are the two places a plausible wrong version differs: a floor
written as the bare cast truncates toward zero and answers -2 for -2.5,
@ -2225,10 +2265,19 @@ let () =
case: N frames from a seeded PRNG, one hash. It imports the sim package
and not raylib, deliberately — a program that imports raylib links
libraylib on every target, and this one is the version meant to run on
wasm32 too. The hash is reproducible only because rand-f32 is ours. *)
wasm32 too. The hash is reproducible only because rand is ours.
The number below is the *old* generator's grid and cannot be right
again: a draw is 64 bits now and every grain lands somewhere else. When
sand.flan is brought up to date and these rows run again, the hash is
re-taken from the run — that is the one manual step, and it is the
normal one for this case. *)
let sand_out = "15595743031174623232\n" in
if sand_checks then begin
outputs "sand, headless" "programs/sand-headless.flan" sand_out;
outputs ~opt:"-O0" "sand, headless, -O0" "programs/sand-headless.flan" sand_out;
outputs ~opt:"-O0" "sand, headless, -O0" "programs/sand-headless.flan"
sand_out
end;
(* The ported raylib example that has a headless half. The other nine of
the ten in examples/ are input read straight into drawing calls, and a
@ -2254,7 +2303,9 @@ let () =
this is the same table asserting the indirection changes nothing before
anything has been redefined — the sand hash especially, since it is the
one result that would notice a call reaching the wrong function. *)
outputs ~dev:true "sand, headless, dev" "programs/sand-headless.flan" sand_out;
if sand_checks then
outputs ~dev:true "sand, headless, dev" "programs/sand-headless.flan"
sand_out;
outputs ~dev:true "value semantics, dev" "programs/values.flan" values_out;
outputs ~dev:true "machine surface, dev" "programs/machine.flan" machine_out;
@ -2614,6 +2665,7 @@ let () =
(* A package may import a package, and one reached along two routes is read
once: pkg-shared imports sand.flan, which imports raylib, and imports
raylib itself. Loading it twice would declare every binding twice. *)
if sand_checks then
outputs "a package reached along two routes" "programs/pkg-shared.flan"
"ok\n";
(* A generic defined in a package and instantiated by the program. The
@ -2921,6 +2973,10 @@ let () =
refuses "and it names the type the call site asked for"
"programs/generic-map-reject.flan" "at $t = f64";
(* This one is refused either way, so the guard is about *which* refusal:
with sand.flan out of date the file stops at the import and the needle
below would pass on the wrong error. *)
if sand_checks then
refuses "a package's main is not visible" "programs/pkg-hidden-main.flan"
"sand/main is not a name";
refuses "one directory under two aliases" "programs/pkg-two-aliases.flan"
@ -3007,7 +3063,7 @@ let () =
The second target, and the reason sand-headless imports no raylib. What
is asserted is not that a wasm module exists — it is that it prints the
*same hash* as the native build, byte for byte. That is only possible
because rand-f32 is written in Flan rather than bound to libc, so the
because rand is written in Flan rather than bound to libc, so the
case is the regression test for that decision as much as for the port.
Four independent things can be absent — clang's wasm target, the
@ -3086,10 +3142,12 @@ let () =
(* The hash, which must equal the native one above. At both levels:
agreement at -O2 alone could be a coincidence of how LLVM folded
the float arithmetic, and -O0 is the cheap way to say it is not. *)
if sand_checks then begin
wasm_case "sand, headless, wasm32" "programs/sand-headless.flan"
sand_out;
wasm_case "sand, headless, wasm32, -O0" ~opt:"-O0"
"programs/sand-headless.flan" sand_out;
"programs/sand-headless.flan" sand_out
end;
(* And the two fixed-output programs, which between them cover the
milestone-2 surface: globals, 2-D arrays, places through a
pointer, casts and match. A 32-bit pointer is the thing most

44
test/test_flan.ml
View File

@ -2362,6 +2362,50 @@ let () =
(defn main [] () (println (pair-fst 1 true)))";
rejects_check "defined twice" "(defn f [] ()) (defn f [] ())"
~needle:"defined twice";
(* ── The randomness surface ────────────────────────────────────────
Four names the prelude does not have, each refused with the name it does
have. A reader who arrives at one of these has copied a line from
somewhere and needs the spelling that works, so the message is checked on
the name it hands back and every call it prints is compiled below. Both
positions, because a bare name and a call take different paths through
the checker and a Lisp-1 makes the bare one a real thing to write. *)
rejects_check "no rand-u32" "(defn f [] u64 (rand-u32))"
~needle:"there is no rand-u32 — a random integer is (rand-int)";
rejects_check "no rand-f32" "(defn f [] f64 (rand-f32))"
~needle:"there is no rand-f32 — a random float in [0, 1) is (rand)";
rejects_check "no rand-i32-range" "(defn f [] i64 (rand-i32-range 0 10))"
~needle:"there is no rand-i32-range";
rejects_check "no rand-f32-range" "(defn f [] f64 (rand-f32-range 0.0 1.0))"
~needle:"there is no rand-f32-range";
(* And the newer machinery is still in front of every name that is not one
of the four: a typo near one of them is a typo, and gets the did-you-mean
the checker has for typos rather than the sentence about a name nobody
wrote. A dotted head keeps the dot-access reading for the same reason. *)
rejects_check "a near miss of a rand name is still a near miss"
"(defn f [] i64 (rand-int-rang 0 10))" ~needle:"did you mean";
rejects_check "and a dotted name is still read as field access"
"(defstruct Point [x i32]) (defn f [p Point] i32 p.x)"
~needle:"accessor";
rejects_check "no rand-f32, named rather than called"
"(defn f [] i32 (let [g rand-f32] 0))" ~needle:"there is no rand-f32";
rejects_check "no rand-i32-range, named rather than called"
"(defn f [] i32 (let [g rand-i32-range] 0))"
~needle:"there is no rand-i32-range";
(* And the five names it does have, at the types it has them at, with every
call the four refusals print. A suggestion that does not compile is worse
than no suggestion, so each is here as well as in the message. *)
infers "rand-int is a u64" "(rand-int)" "u64";
infers "rand is an f64" "(rand)" "f64";
infers "rand-bool is a bool" "(rand-bool)" "bool";
infers "rand-int-range is an i64" "(rand-int-range 0 10)" "i64";
infers "rand-float-range is an f64" "(rand-float-range 0.0 1.0)" "f64";
accepts "the 32 bits a rand-u32 caller wanted"
"(defn f [] u32 (u32 (>> (rand-int) 32)))";
accepts "the f32 a rand-f32 caller wanted" "(defn f [] f32 (f32 (rand)))";
accepts "the i32 a rand-i32-range caller wanted"
"(defn f [] i32 (i32 (rand-int-range 0 10)))";
accepts "main with no parameters and no return" "(defn main [] ())";
accepts "main with argv and a status" "(defn main [args [string]] i32 0)";
rejects_check "main with a wrong parameter" "(defn main [n i32] ())"

27
test/test_session.ml
View File

@ -16,6 +16,21 @@ let () = Watchdog.arm ~seconds:600 "test_session"
let fail fmt = Test_support.fail fmt
let has = Test_support.contains
(* sand.flan is the workspace's own program, edited by hand and not by this
suite, and three cases below read it: it is the file with imports, and it is
the single-file package. While it calls the randomness functions by names
the prelude does not have it does not check at all, and those three would be
reporting that rather than anything about a session. The fixture decides,
so there is nothing to undo once sand.flan is brought up to date. *)
let sand_checks =
match In_channel.with_open_bin "../sand.flan" In_channel.input_all with
(* The open paren and not the bare name — see test_acceptance.ml, which
guards on the same file for the same reason: sand.flan names rand-f32 in
a comment as well, and matching that would leave these skipped for ever.
*)
| src -> not (has src "(rand-f32")
| exception _ -> false
(* Every rejection is asserted on its reason, not just on the failure: the
reason is the part that has to survive a refactor. *)
let checked_program = Test_support.checked
@ -446,6 +461,11 @@ let () =
(* A file with imports, re-evaluated whole — the C-c C-k case. The session
keeps the *expanded* declarations, so the package's names are replaced in
place rather than appended a second time and rejected as duplicates. *)
if not sand_checks then
print_endline
"session: skipping the cases that read sand.flan — it calls rand-f32, \
which is not a name"
else begin
let t, _ = Session.create ~file:"../sand.flan" () in
let src = In_channel.with_open_bin "../sand.flan" In_channel.input_all in
(* [~origin] is the buffer's own path and both editor paths send it
@ -460,7 +480,8 @@ let () =
if not (List.mem "game-draw" c.Session.fns) then
fail "reloading sand.flan did not include its own functions"
| exception Loc.Error { Loc.dmsg = m; _ } ->
fail "reloading a file with imports failed: %s" m);
fail "reloading a file with imports failed: %s" m)
end;
(* A macro that came in with an import is still there on the *second*
evaluation, which is the C-c C-c case and the one that can quietly break.
@ -950,6 +971,7 @@ let () =
importer and written nowhere in the file, so the path is the only thing
that can decide it — which is why it is derived here and not sent by the
editor. *)
if sand_checks then begin
let t, _ = Session.create ~file:"../sand.flan" () in
(match
Session.eval ~origin:"../vendor/agent/agent.flan" t
@ -979,7 +1001,8 @@ let () =
if c.Session.fns <> [ "game-draw" ] then
fail "a form from the program's own file reported %s"
(String.concat " " c.Session.fns)
| exception Loc.Error { Loc.dmsg = m; _ } -> fail "redefining game-draw: %s" m);
| exception Loc.Error { Loc.dmsg = m; _ } -> fail "redefining game-draw: %s" m)
end;
(* An expression's thunk leaves nothing behind, and the module says so, which
is what lets the agent unload it: nothing may point into its text

2
web/index.html
View File

@ -1068,7 +1068,7 @@ over.</p>
<tr><td>time</td><td><code>monotonic-ns</code>, <code>monotonic-seconds</code>, <code>unix-ns</code>, <code>unix-seconds</code>, <code>sleep-ns</code>, <code>sleep-seconds</code>, and <code>ns-per-second</code> and its two smaller siblings</td></tr>
<tr><td>files</td><td><code>file-exists?</code> and <code>file-size</code>, which answer a value; <code>slurp</code>, <code>barf</code>, <code>delete-file</code>, <code>rename-file</code> and <code>make-directory</code>, which signal <code>FileError</code> under <code>retry</code> and <code>use-value</code></td></tr>
<tr><td>the operating system</td><td><code>getenv</code>, which answers an <code>(Option [u8])</code> viewing the process environment</td></tr>
<tr><td>random</td><td><code>rand-seed</code>, <code>rand-u32</code>, <code>rand-f32</code>, <code>rand-i32-range</code>, <code>rand-f32-range</code></td></tr>
<tr><td>random</td><td><code>rand-seed</code>, <code>rand-int</code> (a <code>u64</code>), <code>rand</code> (an <code>f64</code> in [0, 1)), <code>rand-bool</code>, <code>rand-int-range</code> (an <code>i64</code>), <code>rand-float-range</code>. A seeded PRNG written in Flan, one draw per call, so the same seed gives the same numbers on every target. Reproducible and predictable are the same property: a holder of one result can work back to the state and know the rest. Right for a grid or a shuffle, wrong for a key</td></tr>
<tr><td>forms, for macros</td><td><code>form-nil</code>, <code>form-cons</code>, <code>form-append</code>, <code>form-rest</code>, <code>form-items</code>, <code>form-pair</code>, <code>form-sym?</code>, <code>form-is-sym?</code>, <code>gensym</code>, and <code>unless</code> and <code>into</code>, which are macros written here rather than special forms</td></tr>
<tr><td>the rest</td><td><code>pause</code>, which signals the <code>Pause</code> condition the break loop stops on, and <code>embed-find</code></td></tr>
</table>