Module fanout 

Fan-out stage handling as ECS systems.

A fan_out stage (see leviath_core::blueprint::StageMode::FanOut) runs its single inference as a split - its prompt (with the config’s split_prompt folded in by crate::pipeline) asks the model for a JSON array of work items. fan_out_split intercepts that response (before the normal process_response routing), parses the items, and parks the parent in FanOutWaiting. fan_out_collect then starts one worker per item - bounded by max_workers concurrent workers - via the daemon-installed FanOutSpawner, tracks them as the parent’s SubAgentChildren, and once every worker is terminal applies the failure policy, injects a consolidated report into the parent’s conversation, and transitions to the merge_stage (or falls through to the stage’s normal transition).

The runtime only starts and tracks workers; resolving which blueprint a worker runs (self-at-worker-stage, a named agent, or a capability query) is the CLI’s job, encapsulated behind the FanOutSpawner it installs.

Structs

FanOutSpawnerRes

The installed FanOutSpawner, as a world resource. Absent in a pure-runtime world (then every fan-out item fails with “no fan-out spawner installed”).

FanOutState

The serializable form of FanOutWaiting, written to <run_dir>/fanout.json so a parent interrupted mid-split resumes its merge after a restart. active carries worker run-ids (not entities); recovery maps them back to the reloaded worker entities.

FanOutWaiting

A parent parked while its fan-out workers run. Holds the not-yet-started pending items, the currently-active workers, and the accumulated results.

WorkItem

One unit of work produced by a fan-out split.

Traits

FanOutSpawner

Starts one worker for a fan-out work item. The implementor resolves the worker’s blueprint (per config’s worker_stage / worker_agent / worker_query), spawns it into world seeded with the work item, and returns the child entity. Parent/child linking is done by fan_out_collect, not the spawner.

Functions

fan_out_collect

Fan-out collect system (exclusive): drive each FanOutWaiting parent - reap finished workers, start pending ones up to max_workers, and once none remain running apply the failure policy, inject the consolidated report, and transition to the merge stage (or resolve the stage’s own transition).

fan_out_split

Fan-out split system (exclusive): for each ProcessResponse agent whose current stage is a fan-out stage, consume its response as the split output - parse the work items and park the agent in FanOutWaiting (or mark it Error if the split output isn’t a JSON array). Removing ProcessResponse here keeps the normal process_response routing from touching these agents.

parse_work_items

Parse a split response into work items. Tolerates markdown fences and prose by extracting the outermost [ … ]. (Ported from the deleted imperative engine.)

restore_fan_out_waiting

Rebuild a parent’s FanOutWaiting from a persisted FanOutState and insert it, mapping each active worker’s run-id back to its reloaded entity via resolve. Workers whose entity didn’t reload are treated as failures so the merge still completes rather than waiting forever. Used by restart recovery to resume an interrupted fan-out.