Module settle 

SRD-86 §“Settling via the cadence pulse” — the per-pulse settle interpreter and its PulseEvaluator adapter.

For a volatile optimizer objective (one defined over a windowed run-produced metric such as metric_window("...","errors") or a metricsql_* reader), the objective value chases the live cadence window and at phase completion the trailing window is empty. The objective therefore cannot be read by a one-shot post-execution pull; it must be settled across the run and held in a register the executor reads at completion.

SettleInterpreter is the settle-signal engine. It owns one persistent settle-kernel — typically the phase’s objective bindings plus (stable_value, stable) := is_stable(<objective>, …) — and is driven once per cadence pulse:

1. set_input on the kernel’s poke input advances the generation, which dirties every non-deterministic node (engine rule, see kernel::engines::set_input): the embedded volatile objective reader re-reads the latest published window and is_stable re-evaluates — exactly one new sample on its ring.
2. Pull stable then stable_value; both land on that single evaluation (generation cache), so the multi-output node contributes one sample per pulse, not two.
3. Publish stable_value into the shared register (an ArcSwap, lock-free for the executor’s completion read).

The interpreter does not decide phase stop — that is the SettleEvaluator’s job (settled ⇒ interrupted; timed out ⇒ failed), driven through the general super::phase_pulse::PhaseStopEvaluator callback registered on the metrics cadence feed.

Structs

SettleEvaluator

The settle detector as a PulseEvaluator. It holds the phase’s objective kernel (a clone of node X’s kernel — already bound to this evaluation’s coordinate, the same kernel read_objective_at_completion pulls) and a fixed is_stable engine. Each cadence pulse:

SettleHandle

What the executor holds while a settle detector runs: the cadence subscription to tear down, the settled-value register, and the terminal-disposition cell.

SettleInterpreter

Per-pulse interpreter of objective settling. See the module docs.

SettleReading

The latest reading a SettleInterpreter publishes.

Enums

SettleSkip

Why start_settle started no detector.

Functions

program_reads_live_metrics

True if program contains a metrics-reader node — the signal that the phase’s objective may be a volatile windowed metric that the one-shot post-completion read cannot capture.

start_settle

Start a cadence-fed settle detector for objective on the running phase iff the objective reads live metrics. Builds the objective kernel as node X’s program rebound to parent (carrying the coordinate — mirrors read_objective_at_completion), wraps it in a PhaseStopEvaluator, and subscribes it to the smallest cadence. Starts nothing for a non-volatile objective (the one-shot read path is correct there) or when the metrics cadence is disabled, and says which; a detector that cannot be built is SettleSkip::Failed.