babylon.engine.headless_runner.runner

Core headless simulation runner — orchestrates Postgres + tick loop + artifacts.

Spec: 064-headless-sim-runner (T028-T035).

The runner is intentionally thin: it composes pre-existing pieces from babylon.persistence (PostgresRuntime, initialize_session, persist_tick_atomic) and emits the contracted artifact bundle. The simulation math itself is whatever the configured engine step performs on the persisted state — this MVP carries hex state forward unchanged so the pipeline (hex hydration → tick loop → trace view → CSV) ships as a single executable e2e contract. Future specs can plug richer per-tick advancement in via the step_function seam (currently private; exposed when needed).

Exit code semantics live in contracts/cli_contract.yaml. Stderr formatting on non-zero exits follows the ERROR <NAME>: <message> | partial_artifacts=<path-or-NONE> template.

Functions

main_from_argv(args)	Build config + dispatch + map exit code (T032).
run(config)	Execute the headless simulation per config and emit artifacts.

Exceptions

ConfigError
LivenessGateFailure	Spec-105: runtime liveness gate assertion failure.
PostgresUnreachableError
ReferenceDataMissingError
RunnerError	Base class for runner-side preflight errors.
TerminalAggregateResolutionError	Spec-102 STEP 0: hex rows exist but county resolution yielded zero.

exception babylon.engine.headless_runner.runner.ConfigError

Bases: RunnerError

exit_code: int = 2

exit_name: str = 'CONFIG_ERROR'

exception babylon.engine.headless_runner.runner.PostgresUnreachableError

Bases: RunnerError

exit_code: int = 4

exit_name: str = 'POSTGRES_UNREACHABLE'

exception babylon.engine.headless_runner.runner.ReferenceDataMissingError

Bases: RunnerError

exit_code: int = 3

exit_name: str = 'REFERENCE_DATA_MISSING'

exception babylon.engine.headless_runner.runner.RunnerError

Bases: Exception

Base class for runner-side preflight errors.

exit_code: int = 1

exit_name: str = 'ENGINE_FAILURE'

babylon.engine.headless_runner.runner.build_parser()

Construct the argparse parser for the headless runner CLI.

Return type:

ArgumentParser

Returns:

Fully configured parser mirroring contracts/cli_contract.yaml.

babylon.engine.headless_runner.runner.main_from_argv(args)

Build config + dispatch + map exit code (T032).

Reads CLI args, dispatches to run(), prints the artifact directory path on stdout for exit-0 runs, and emits the canonical error format on stderr for non-zero exits.

Return type:

int

Parameters:

args (Namespace)

babylon.engine.headless_runner.runner.run(config)

Execute the headless simulation per config and emit artifacts.

Return type:

SimulationRunResult

Returns:

SimulationRunResult describing the run outcome.

Parameters:

config (SimulationRunConfig)