Goal
Refactor the Helix Job Monitor into a modular, reviewable, regression-resistant distributed-state reconciler while preserving its current observable behavior unless an individual child issue explicitly changes that behavior.
Motivation
The monitor has strong behavioral coverage and a valuable pipeline-emulating test harness, but key domain concepts and state transitions are spread across JobMonitorRunner, MonitorState, upload coordination, service adapters, and smart fakes. This makes requirements cross-cutting and difficult for both humans and coding models to modify safely.
Principles
- Preserve and strengthen the end-to-end scenario harness.
- Keep behavioral changes separate from behavior-preserving refactors.
- Each PR must identify the behavioral invariants it preserves or changes.
- Prefer pure reconciliation logic and typed domain concepts over implicit strings, booleans, nulls, and mutable collection membership.
- Keep each PR independently reviewable and revertible.
Planned work
Child issues will cover:
- specification alignment and invariant traceability;
- upload lifecycle correctness;
- typed identity and lineage extraction;
- retry reconciliation planning;
- polling/completion planning and state reduction;
- service-boundary and test-harness improvements.
Completion criteria
- The behavioral specification, implementation, and tests agree.
- Retry, attempt scoping, upload durability, cancellation, and outcome precedence are represented by explicit domain concepts.
- Core reconciliation decisions are deterministic and testable without external services.
- External adapters have focused contracts and protocol-level tests.
- The pipeline-emulating harness remains the final end-to-end regression layer.
Sub-items
Implementation order follows the list above. Behavioral changes, when required, should remain isolated from behavior-preserving extraction PRs.
Goal
Refactor the Helix Job Monitor into a modular, reviewable, regression-resistant distributed-state reconciler while preserving its current observable behavior unless an individual child issue explicitly changes that behavior.
Motivation
The monitor has strong behavioral coverage and a valuable pipeline-emulating test harness, but key domain concepts and state transitions are spread across
JobMonitorRunner,MonitorState, upload coordination, service adapters, and smart fakes. This makes requirements cross-cutting and difficult for both humans and coding models to modify safely.Principles
Planned work
Child issues will cover:
Completion criteria
Sub-items
Implementation order follows the list above. Behavioral changes, when required, should remain isolated from behavior-preserving extraction PRs.