h8io.stages.cycles

A decorator that drives a whole cycle of the inner stage per outer run — like Repeat and Reduce, on the same outer input — folding every output the inner stage produces into an accumulator R via the binary operation stage op.

Unlike Reduce, the accumulator is never empty: apply receives the seed R alongside the input, so every output the inner stage produces — including the first — is folded via op((accumulator, output)); there is no seedless first output to special-case. Because the accumulator always has a value to yield, Fold mixes in h8io.stages.base.Fruitful: apply is statically guaranteed to return h8io.stages.Yield.Some.

That guarantee shapes what happens when op itself produces no output for a given fold (e.g. it filters some outputs out): the accumulator is left unchanged rather than discarded. Reduce can thread an unfolded value onward as None, since its accumulator is optional to begin with; Fold cannot — a Fruitful stage has no None to fall back to — so keeping the previous accumulator is the only option that preserves the guarantee. op's status is still combined into the iteration's status in this case, since op was applied (not skipped) for that output. When the inner stage itself produces no output, op is skipped instead — as in Reduce — and only the inner stage's status carries the iteration, so each iteration still performs exactly one of apply/skip on both inner stages, as the lifecycle contract requires. An iteration that leaves the accumulator unchanged keeps the cycle spinning as long as the combined status is h8io.stages.Status.Success, like Repeat. The cycle is @tailrec and does not grow the stack.

The cycle stops when the status of an iteration is h8io.stages.Status.Complete: an error-free Complete is reported to the enclosing pipeline as Success, a Complete with errors is preserved. The accumulator as it stands at that point is yielded. The accumulator is local to one outer run: the next generation of Fold starts fresh from whatever seed the next outer input supplies.

==The inner pipeline==

alterand and op together form the inner pipeline of Fold, with op downstream of alterand. An iteration's status is therefore the combination of their statuses in pipeline order (alterand first), and both continuations are selected by that combined status — exactly as h8io.stages.Evolution.AndThen evolves both sides of a composed pipeline with the status of the whole run, never with the stages' individual statuses.

As in Loop and Repeat, the continuations are never selected by the status Fold reports to the enclosing pipeline — the two differ, since an error-free Complete is absorbed into a Success — and for the same reason the returned evolution is a h8io.stages.base.ConstEvolution. Its dispose releases both inner evolutions via h8io.stages.Evolution.dispose (op first, then alterand), which per the h8io.stages.Evolution contract stay the terminal cleanup handles of the generation just constructed. Symmetrically a skipped Fold skips both inner stages and selects their continuations on the neutral Status.Success.

A decorator that feeds the output of each successful step back as the input of the next, effectively looping the inner endomorphic stage until it stops.

The tail-recursive loop works as follows:

• h8io.stages.Status.Success + h8io.stages.Yield.Some: the output becomes the new input and the loop continues with the stage selected by yld.evolve().
• h8io.stages.Status.Success + h8io.stages.Yield.None: no output was produced; the loop stops and emits a Yield.None with Success status whose continuation is the stage selected by yld.evolve(), wrapped back in Loop.
• h8io.stages.Status.Complete with no errors: the loop stops, converts the status back to Success, and wraps the stage selected by yld.evolve() in Loop for the next outer invocation.
• h8io.stages.Status.Complete with errors: the loop stops, preserves the errors, and selects the continuation the same way.

In every branch the continuation of the inner stage is selected by the status the inner stage itself produced, and never by the status Loop reports to the enclosing pipeline — the two differ, since an error-free Complete is absorbed into a Success. For the same reason the returned evolution is a h8io.stages.base.ConstEvolution: the status the enclosing pipeline evolves Loop with belongs to that pipeline, not to the inner stage, and must not be passed inwards. Symmetrically, a skipped Loop skips its inner stage and selects the inner continuation on the neutral Status.Success. The returned ConstEvolution keeps the inner evolution's dispose as its own: per the h8io.stages.Evolution contract, the inner evolution stays the terminal cleanup handle for the generation constructed here until that generation runs.

This makes Loop suitable for in-process iterative computations (e.g., fixed-point iterations) where the result of one step seeds the next.

A decorator that drives a whole cycle of the inner stage per outer run — like Repeat, on the same outer input — folding every output the inner stage produces into an accumulator with the binary operation stage op.

The first output becomes the accumulator without invoking op (the classic seedless reduce); each subsequent output is folded via op((accumulator, output)). In an iteration with nothing to fold — the inner stage produced no output, or the output is the first one — op is skipped, so each iteration performs exactly one of apply/skip on both inner stages, as the lifecycle contract requires. An iteration yielding no output with h8io.stages.Status.Success keeps the cycle spinning, like Repeat. The cycle is @tailrec and does not grow the stack.

When op is applied but itself yields no output for a given fold — e.g. it filters some outputs out — the accumulator is left unchanged rather than discarded, exactly as in Fold. op's status is still combined into the iteration's status in this case, since op was applied, not skipped, for that output.

The cycle stops when the status of an iteration is h8io.stages.Status.Complete: an error-free Complete is reported to the enclosing pipeline as Success, a Complete with errors is preserved. The value accumulated so far, if any, is yielded. The accumulator is local to one outer run: the next generation of Reduce starts empty.

==The inner pipeline==

alterand and op together form the inner pipeline of Reduce, with op downstream of alterand. An iteration's status is therefore the combination of their statuses in pipeline order (alterand first), and both continuations are selected by that combined status — exactly as h8io.stages.Evolution.AndThen evolves both sides of a composed pipeline with the status of the whole run, never with the stages' individual statuses.

As in Loop and Repeat, the continuations are never selected by the status Reduce reports to the enclosing pipeline — the two differ, since an error-free Complete is absorbed into a Success — and for the same reason the returned evolution is a h8io.stages.base.ConstEvolution. Its dispose releases both inner evolutions via h8io.stages.Evolution.dispose (op first, then alterand), which per the h8io.stages.Evolution contract stay the terminal cleanup handles of the generation just constructed. Symmetrically a skipped Reduce skips both inner stages and selects their continuations on the neutral Status.Success.

A decorator that keeps re-applying the inner stage (following the continuations its h8io.stages.Evolution selects for h8io.stages.Status.Success) until the stage signals completion or an error.

The loop is implemented with @tailrec so it does not grow the stack. The loop continues as long as the inner stage yields h8io.stages.Status.Success. It stops on h8io.stages.Status.Complete: if there are no errors the status is converted back to Success; if there are errors, the Complete status is preserved.

In every branch the continuation of the inner stage is selected by the status the inner stage itself produced, and never by the status Repeat reports to the enclosing pipeline — the two differ, since an error-free Complete is absorbed into a Success. For the same reason the returned evolution is a h8io.stages.base.ConstEvolution: the status the enclosing pipeline evolves Repeat with belongs to that pipeline, not to the inner stage, and must not be passed inwards. Symmetrically, a skipped Repeat skips its inner stage and selects the inner continuation on the neutral Status.Success. The returned ConstEvolution keeps the inner evolution's dispose as its own: per the h8io.stages.Evolution contract, the inner evolution stays the terminal cleanup handle for the generation constructed here until that generation runs.

Repeat is useful for driving stages like h8io.stages.std.Countdown that signal "batch complete" via Status.Complete and should be repeated as a whole unit.