Is there an existing issue for the same feature?
Is your feature request related to a problem?
As a contributor trying to understand or modify the runtime, several core modules are too large to review safely and make ownership boundaries difficult to see.
On current main (374320e), examples include approximately:
crates/services/src/runs.rs: 37k lines;crates/runtime/src/server/server_loop_host.rs: 31k lines;crates/runtime/src/server/run/lifecycle/mod.rs: 22k lines;crates/runtime/src/turn/agentic_loop/execution_phase.rs: 20k lines;crates/astra-cli/src/tui/event_loop.rs: 15k lines.
The repository correctly emphasizes one canonical source of truth, but very large canonical modules create a different failure mode: unrelated state transitions, persistence code, protocol adaptation, policy checks, and test helpers accumulate in the same compilation unit. This raises review cost, increases merge conflicts, and makes it hard for a new contributor to prove that a change preserves cross-surface semantics.
Describe the feature you'd like
Introduce an incremental decomposition plan for oversized runtime modules based on ownership, not arbitrary file length. Candidate boundaries include:
- durable state transitions versus SQL persistence;
- admission/lease/fencing versus status projection;
- model-loop orchestration versus provider transport;
- event persistence versus streaming projection;
- production implementation versus test fixtures/builders.
Add lightweight architecture checks that prevent already-large modules from growing without an explicit exemption. The goal should not be a blanket line-count rule; it should be reviewable ownership with one canonical implementation per behavior.
Acceptance criteria
Implementation / design notes
A useful first step could be dependency-direction tests or module-level architecture tests before moving code. That would make the refactor measurable and reduce the chance of replacing one large file with circular internal packages.
Is there an existing issue for the same feature?
Is your feature request related to a problem?
As a contributor trying to understand or modify the runtime, several core modules are too large to review safely and make ownership boundaries difficult to see.
On current
main(374320e), examples include approximately:crates/services/src/runs.rs: 37k lines;crates/runtime/src/server/server_loop_host.rs: 31k lines;crates/runtime/src/server/run/lifecycle/mod.rs: 22k lines;crates/runtime/src/turn/agentic_loop/execution_phase.rs: 20k lines;crates/astra-cli/src/tui/event_loop.rs: 15k lines.The repository correctly emphasizes one canonical source of truth, but very large canonical modules create a different failure mode: unrelated state transitions, persistence code, protocol adaptation, policy checks, and test helpers accumulate in the same compilation unit. This raises review cost, increases merge conflicts, and makes it hard for a new contributor to prove that a change preserves cross-surface semantics.
Describe the feature you'd like
Introduce an incremental decomposition plan for oversized runtime modules based on ownership, not arbitrary file length. Candidate boundaries include:
Add lightweight architecture checks that prevent already-large modules from growing without an explicit exemption. The goal should not be a blanket line-count rule; it should be reviewable ownership with one canonical implementation per behavior.
Acceptance criteria
Implementation / design notes
A useful first step could be dependency-direction tests or module-level architecture tests before moving code. That would make the refactor measurable and reduce the chance of replacing one large file with circular internal packages.