Module engine 

Evolution engine: the glue that turns primitives into a working A/B loop.

Called from cmd_record (after each session is inserted) and from cmd_roll (manual challenger generation).

Structs

DeploymentState

What was deployed at the start of the most recent session.

Functions

collect_scores_for_config

Load all signals tied to sessions that ran under config_id, group by session, and collapse each session’s signals into a single 0..=1 score.

evaluate_promotion

Evaluate the running experiment (if any) against the promotion threshold. Returns the experiment + decision, or None if no experiment is running.

generate_challenger

Convenience wrapper around generate_challenger_with_picker that uses the default LLM-aware picker. Callers that may not have an LLM should call generate_challenger_with_picker with picker_for_environment(false).

generate_challenger_with_picker

Generate a challenger from the current champion using one mutator, persist it as an AgentConfig row with role=Challenger, start a new Experiment with traffic_share=0.5 (proper A/B — half of new sessions go to each variant, decided by the SessionStart hook), and apply the challenger config to disk via the adapter as the initial deployment for the next session.

handle_session_start

Decide which variant to deploy for a fresh session, apply that variant’s config to disk via the adapter, and persist the choice in the project’s deployment-state file.

picker_for_environment

Build the mutator picker, omitting LLM-dependent mutators if no LLM is reachable. Without this, the default 50%-LLM-rewrite weight means roughly half of all challenger generations would silently fail to mutate anything when the user has no Anthropic key and no local Ollama.

promote_challenger

Promote the challenger: mark experiment as Promoted, swap project’s champion pointer, and re-apply the new champion to disk via the adapter.

read_deployment_state

Read deployment state for a project, if any.

resolve_active_deployment

Figure out which variant + config_id a new session should be tagged with.

should_evolve

Default scheduler: trigger challenger generation when enough sessions have accumulated since the last champion change. Skips if an experiment is already running.

write_deployment_state

Write deployment state for a project.