feat(lang): add times and fold-while

[singaraiona]

Follow-up to #590 (now merged), which added while and the backward branch (emit_jump_back/write_jump_offset) that the times compiler case reuses.

These are the two remaining forms requested in #588. Neither is an unblock — while already covers the reporter's case, and he said "any one of them solves it" — but they complete the vocabulary he asked for.

times

(times n body...) runs the body exactly n times, returns null.

do is already progn here, so the bounded loop could not reuse that name. Overloading do on an integer head was considered and rejected as genuinely ambiguous: (do 5) would have to mean either "loop five times over nothing" or "return 5", and a computed first expression that happened to be an integer would silently change meaning.

The count is evaluated once on entry, so a body mutating whatever produced it cannot change how many passes remain:

(set k 3)
(times k (set k (+ k 10)))      ; runs 3 times, not forever

Zero or less runs zero times rather than trapping — a bound that computes to empty is a no-op, not an error. A non-integer count is a type error.

How it compiles

A counted loop over a hidden local slot:

     LOADCONST(norm) <n> CALL1  STOREENV c
top: LOADENV c  JMPF -> end
     <body...> POP each
     LOADCONST(dec) LOADENV c CALL1 STOREENV c
     JMP -> top
end: LOADCONST(null)

Three things worth a reviewer's eye:

• ray_times_norm_fn type-checks and clamps a negative bound to zero on entry. That is what lets the per-pass test be a bare truthiness check on the counter — is_truthy makes 0 falsy — so there is no comparison call per pass and a negative bound cannot run away.
• norm and dec are pushed as constant-pool objects, not resolved by name. The loop's own arithmetic is therefore unnamable from source and cannot be swapped out by a (set - ...) or (set > ...) override. They are built fresh per compile site rather than held as singletons, so their lifetime is the code object's constant pool — no pointer survives a runtime teardown.
• The counter's slot is addressed by index and its sym carries a space, so no source token can collide with it and nested times counters stay apart. There's a three-deep nesting test.

As with while, the body compiles inline, so return unwinds the enclosing lambda from inside the loop.

fold-while

(fold-while pred f init xs) offers the accumulator to pred before each step and stops on a falsy answer, yielding the accumulator as it stands. The test precedes the first element, so a predicate false at the start returns init untouched.

The predicate takes the accumulator, not the element — that is the form expressing "iterate until the running result says stop", which is the early termination actually being asked for. (The issue's own wording was ambiguous between the two readings.)

(fold-while (fn [acc] (< acc 100)) + 0 (til 1000))   ; => 105

One deliberate divergence from fold. ray_fold_fn routes its collection through unbox_vec_arg → to_boxed_list, boxing every element up front. For a primitive whose entire purpose is stopping early, paying for the tail it never reaches is the cost being removed, so elements are pulled one at a time via collection_elem. A plain variadic builtin — no compiler work, since it dispatches through the normal call path.

Performance

Release builds:

	per iteration / call	vs baseline
while + manual counter, 1e6 passes	180 ns	1×
times, 1e6 passes	100 ns	1.8×
fold-left stopping after 3 of 1e6	369 ms	1×
fold-while same	3.9 µs	~95 000×

The second pair is the pathological early-stop case, where the old form had to box and walk all million elements to discover it was done after three.

Testing

test/rfl/lang/times.rfl and test/rfl/collection/fold_while.rfl, each behaviour asserted on both evaluator paths where applicable.

Worth noting one gap I caught in my own coverage: the count's type check and negative clamp run through completely different code on the two paths (the tree walker's own check vs ray_times_norm_fn from bytecode), so both are now asserted separately. Also covered: count-evaluated-once, hidden-counter non-collision, return from inside a body, error propagation from count and body with the pass count pinned, three-deep nesting, fold-while touching exactly as many elements as the predicate allows, and both callbacks raising.

Full suite 3903/3903, ASan+UBSan output clean.

Not in scope

Converge/adverb forms, scan-while, TCE.

[github-actions]

Rayforce targeted audit passed

The required Rayforce audit gate passed on the latest run.

Workflow run: https://github.com/RayforceDB/rayforce/actions/runs/35467574130