Add enclose for the stages of nested loops

[SimonHeybrock]

Stacked on #245. Adds enclose, which builds the stages of nested loops, such as detector banks within runs, from the inside out.

Why

#245 handles nested loops with one stage per loop, the forwarded values derived from Stage.frontier by hand (ADR 0003, "Nested loops"). That leaves a silent pitfall: a key that depends on the run but not on the bank, declared as an output of the bank stage, is pushed once per bank and counted several times without an error. It also takes a few lines of stage building per level, repeated by every nested driver (esssans runs times banks, Bifrost triplets times runs, the StreamProcessor context).

enclose(pipeline, stages, inputs=...) puts stages inside a loop over inputs. It returns an outer stage that computes, once per iteration, the values the given stages held and that depend on inputs, followed by the given stages rebuilt to take those values as inputs. Nesting is the order of the calls. It rejects an output declared on a stage that does not vary in it.

enclose went through three designs (Aggregation, split with one Part per loop, enclose), which is why it was moved out of #245: the decision to replace map/reduce does not depend on it.

Content

• sciline.enclose, with tests in tests/enclose_test.py.
• Stage.compute ignores values for keys the stage does not use, so a driver passes each stage everything the stages of the enclosing loops returned. It still rejects a value for a key the stage holds or computes itself.
• The nested-loops part of the user guide on stages.
• loki_banks_validation.py: the esssans LoKI reduction over two runs times nine banks against with_banks(with_sample_runs(...)), with identical results.

Status

Draft. The first commit restores the state before the split, so the enclose text is back in ADR 0003 and the design document. It moves to its own ADR 0004 once #245 has had a review round, since the nested-loops section of ADR 0003 decides what 0004 has to add.

Test plan

• tests/enclose_test.py and the full suite pass, also with the dask environment.
• loki_banks_validation.py run locally against the reference: identical results.

🤖 Generated with Claude Code