# Split runtime/launch.rs (https://jackin.tailrocks.com/roadmap/split-runtime-launch/)



**Status**: Partially implemented — the old monolithic `runtime/launch.rs` was split into a root module and child launch modules, but three large launch orchestration functions still carry the remaining reviewability risk. The next work is internal phase extraction inside those functions, not another top-level file move.

## Current Shape [#current-shape]

The launch area now uses Rust 2024 self-named module layout:

* <RepoFile path="crates/jackin-runtime/src/runtime/launch.rs">crates/jackin-runtime/src/runtime/launch.rs</RepoFile> — 269 lines; public launch API, module declarations, and tests.
* <RepoFile path="crates/jackin-runtime/src/runtime/launch/launch_runtime.rs">crates/jackin-runtime/src/runtime/launch/launch\_runtime.rs</RepoFile> — 1,155 lines; `LaunchContext`, prewarm helpers, and `launch_role_runtime`.
* <RepoFile path="crates/jackin-runtime/src/runtime/launch/launch_pipeline.rs">crates/jackin-runtime/src/runtime/launch/launch\_pipeline.rs</RepoFile> — 1,184 lines; `load_role_with` and launch-input/pipeline coordination.
* <RepoFile path="crates/jackin-runtime/src/runtime/launch/launch_pipeline/launch_core.rs">crates/jackin-runtime/src/runtime/launch/launch\_pipeline/launch\_core.rs</RepoFile> — 1,223 lines; `run_launch_core` and the `LaunchCore` context.

The split moved dedicated concerns such as DinD setup, slot claim, restore resolution, auth-error rendering, progress helpers, trust helpers, and launch-core execution out of the former root file. The remaining issue is that the largest orchestration functions still combine several behavioral phases behind broad context structs.

## Remaining Split [#remaining-split]

Three production functions still need internal splitting:

* `launch_role_runtime` in <RepoFile path="crates/jackin-runtime/src/runtime/launch/launch_runtime.rs">crates/jackin-runtime/src/runtime/launch/launch\_runtime.rs</RepoFile>.
* `load_role_with` in <RepoFile path="crates/jackin-runtime/src/runtime/launch/launch_pipeline.rs">crates/jackin-runtime/src/runtime/launch/launch\_pipeline.rs</RepoFile>.
* `run_launch_core` in <RepoFile path="crates/jackin-runtime/src/runtime/launch/launch_pipeline/launch_core.rs">crates/jackin-runtime/src/runtime/launch/launch\_pipeline/launch\_core.rs</RepoFile>.

Keep the current module layout. Do not split tests simply to reduce line counts; a growing `tests.rs` remains a signal that the production module may still own too much behavior, not an independent target.

## Candidate Boundaries [#candidate-boundaries]

`launch_role_runtime`:

* launch-profile and cgroup/AppArmor validation;
* sibling-auth prewarm;
* Docker run-argument construction;
* socket-directory preparation;
* hardline handoff and session-finalization reporting.

`load_role_with`:

* launch-input preparation;
* workspace and role materialization;
* trust and role-source checks;
* image materialization and diagnostics;
* environment/auth resolution;
* `run_launch_core` invocation;
* post-launch cleanup.

`run_launch_core`:

* preflight state assembly;
* Docker run execution;
* wait-for-state handling;
* teardown and error tagging.

## Remaining Work [#remaining-work]

1. Extract one cohesive phase at a time and keep existing launch behavior covered by the runtime launch tests.
2. Avoid circular dependencies around trust confirmation and launch diagnostics.
3. Move repeated Docker naming and launch-plan helpers behind shared runtime helpers only where duplication remains after phase extraction.
4. Add or update links to [Behavioral spec for runtime launch](/roadmap/behavioral-spec-runtime-launch/) after each extracted phase has stable invariants.

## Related Work [#related-work]

* [Codebase health: structure & reviewability](/roadmap/codebase-health-enforcement/) — umbrella item that tracks cross-surface follow-up after the PR #664 merge-readiness audit.
* [Behavioral spec for runtime launch](/roadmap/behavioral-spec-runtime-launch/) — spec item covering the same pipeline; extracted phases should land documented invariants there.