SingleRunOrchestrator

Thin facade over Runner for the single-model GUI use case.

Low-level API note: application and UI code should prefer KSLAppSession, which owns scope lifecycle, validation, warning emission, and dispatch across all supported run modes. This orchestrator remains public so lower-level tests and advanced integrations can exercise the single-run path directly.

Accepts a RunConfiguration, builds the model via RunConfiguration.buildModel, and delegates to Runner.submit. Returns the RunHandle directly so the caller can observe lifecycle events and await the terminal ksl.app.session.RunResult.Completed.

val handle = SingleRunOrchestrator.submit(config, provider)
launch { handle.events.collect { event -> updateUi(event) } }
when (val r = handle.result.await()) {
    is RunResult.Completed -> showResults(r.snapshot)
    is RunResult.Failed    -> showError(r.error)
    is RunResult.Cancelled -> showCancelled(r.reason)
    else -> {}
}

Pre-flight validation should be performed with ksl.app.validation.RunConfigurationValidator.validateForRun before calling submit. If RunConfiguration.modelReference is ksl.app.config.ModelReference.ByProviderId and provider is null, RunConfiguration.buildModel throws IllegalStateException synchronously — before the coroutine is launched.