hierarchical_status.json の意味論
hierarchical_status.json は CLI / API / rerun 判定の接点にある status file である。PR #840(2026-05-21 merge)以降は、CLI(kouchou-analyze / python -m analysis_core)も API も run_default() → run_workflow() だけを通るので、この file を書くのは workflow path である。API はレポート生成・config からの生成・集計だけの再実行の 3 経路とも、python -m analysis_core を subprocess で起動する。legacy の PipelineOrchestrator.run() は DeprecationWarning を出す形で残っているが、通常の経路からは呼ばれない。source-codeより
本ページはもともと、この PR の review で論点だった「workflow default 化の blocker は status semantics に残るか」を判定するため、merge 直前の branch tip 04516af で legacy .run()(core/orchestration.py が書く)と workflow path の差分を棚卸ししたものである。下の「項目別の比較」はその時点の記録として残し、今の main での性質は次の「結論」にまとめる。pr-840-workflow-defaultization-observation-2026-05-20より
結論(2026-10-21 の main b71e0b79 で確認)
- API が日常的に読む
status,current_job, token usage,provider,model,errorは workflow path が書く。予期しない例外で止まった時はerror_stack_traceも書く - rerun 判定に使う
completed_jobs/previously_completed_jobsも carry-forward される completed_jobs[].durationは常に0.0で、実測値ではないestimated_costは、成功時には status file に書かれない。error で終わった時はestimated_cost: nullとtoken_usage_complete: falseが書かれる。費用は API が token 数から計算して自分のレポート状態に持つので、admin の/status/step-jsonが status file から返すestimated_costはNoneになるcurrent_jobは終了後も最後の step 名が残る。API はstatusを優先して読むので、実害は小さい- analysis-core が書く
errorの文面は 3 通りある。workflow の step が失敗した時は"Step '<step>' failed: ..."(入力検証で止まった時は"Step '<step>' validation failed: ...")、予期しない例外の時はstr(e)、中断された時は"Interrupted: <例外の型名>"。analysis-core のプロセスが異常終了した時や、起動・storage への同期に失敗した時は、API がstatus: errorとerror_log_path/error_log_excerpt(ログの末尾)を書き足す - analysis-core の
update_status()は、一時ファイルに書いてから置き換える atomic な書き方をする(PR #1033、2026-10-19 merge)。admin の/status/step-jsonは JSON を読めなかった時も失敗扱いにせず、loading/runningとして次のポーリングに任せる - 別の出力から中間成果物を再利用して作った時(config の
reuse_from、CLI の--reuse-from)は、再利用元を示すreused_fromが入る - progress 系 key(
current_job_progress/current_jop_tasks)は、workflow engine の正式な callback としては扱われていない(Open Questions)
項目別の比較(2026-05-21 時点、merge 直前の記録)
以下は branch tip 04516af を基準にした当時の記録で、「workflow path」は当時 branch 上にあった実装を指す。今の main での性質は上の「結論」を見る。
status
- legacy
.run():running→completed/errorをtermination()で確定する。source-codeより - workflow path: 同じく
runningで開始し、WorkflowResult.successに応じてcompleted/errorを書く。予期しない exception でもerrorを書く。source-codeより - 評価: ほぼ同等
plan
- legacy
.run():initialization()がdecide_what_to_run()の結果を status file にも保存する。source-codeより - workflow path:
from_dict()/from_config()から得た plan を開始時に保存する。explicit plan を渡した場合はそれを尊重するよう branch 上で修正済み。source-codeより - 評価: 同等
start_time / end_time
- legacy
.run(): 開始・終了で保存する。source-codeより - workflow path: 同様に開始・終了で保存する。source-codeより
- 評価: 同等
current_job
- legacy
.run():run_step()開始時に step 名を入れる。終了時に明示的に消す処理は無く、最終 status がcompleted/errorに変わる。source-codeより - workflow path:
mark_step_started()で step 名を入れ、終了後も消さない。failure 時は失敗した step 名を残す。source-codeより - API reader:
/status/step-jsonはstatus=completedならcurrent_jobの値に関わらずcompletedを返し、status=errorならcurrent_jobを current step として返す。source-codeより - 評価: 実運用上はほぼ同等だが、file 単体の意味としては差分あり
current_job_started
- legacy
.run(): step 開始時に保存する。source-codeより - workflow path: 同様に保存する。source-codeより
- 評価: 同等
current_job_progress / current_jop_tasks
- legacy
.run(): 長い step の進捗 callback から更新されうる。source-codeより - workflow path: step 完了時に空へ戻すが、engine 自体は進捗更新をまだ積極利用していない。source-codeより
- 評価: 差分あり
completed_jobs
- legacy
.run(): 各 step 完了時にstep,completed,duration,params,token_usageを append する。durationは実測秒数。source-codeより - workflow path: 同じ shape の entry を append するが、
durationは0.0固定で、実測時間ではない。source-codeより - 評価: shape は同等、意味は差分あり
previously_completed_jobs
- legacy
.run(): rerun 時に prior status から carry-forward する。source-codeより - workflow path: branch 上で同様に carry-forward する。source-codeより
- 評価: 同等
total_token_usage / token_usage_input / token_usage_output
- legacy
.run(): step 実行のたびに加算し、status file に保存する。source-codeより - workflow path: step 完了時に加算し、最終結果と status file の両方へ保存する。exception path でも branch tip
04516afで 0 に戻さず保持するよう直った。source-codeより - API reader:
report_launcherと/status/step-jsonの両方がここを読む。source-codeより - 評価: branch 上では実用上同等
provider / model
- legacy
.run(): 初期化時に status file へ保存する。source-codeより - workflow path: 同様に保存する。source-codeより
- API reader:
/status/step-jsonは status file から返すが、report_launcherの完了処理は config 側も参照する。source-codeより - 評価: 同等
estimated_cost
- legacy
.run():run_step()が各 step の後に key を書くが、run()はrun_step()にpricing_calculatorを渡さないので、値は placeholder(当時は0.0)で計算値ではなかった。source-codeより - workflow path: branch 上でも明示保存していない。source-codeより
- API reader:
/status/step-jsonは値があれば返すが、無ければNoneになる。source-codeより - 評価: key の有無は違うが、どちらの経路でも status file に計算した費用は入っていなかった
error
- legacy
.run():termination()は原則"{ExceptionType}: {message}"形式で保存する。source-codeより - workflow path: workflow result failure では
"Step '<name>' failed: ..."のような step 文脈付き文面になる。予期しない exception ではstr(e)をそのまま保存する。source-codeより - 評価: 差分あり。ただし API / rerun に必要な情報量は branch 上の方がむしろ多い
error_stack_trace
- legacy
.run(): error 時に保存する。source-codeより - workflow path: 予期しない exception 時に保存し、failure semantics を legacy に寄せる修正が branch 上で入った。source-codeより
- 評価: ほぼ同等
lock_until
- legacy
.run():update_status()が毎回更新し、stale running detection に使う。source-codeより - workflow path: 同じ
update_status()を通るので更新される。source-codeより - 評価: 同等
API / 運用から見て重要な性質
以下は 2026-05-21 時点で legacy との差分として挙げたもので、今の main では workflow path の性質としてそのまま残っている。
1. current_job を終端時に消さない
file 単体だけ読むと「completed なのに current_job=embedding が残っている」状態がありうる。もっとも API router は status=completed を優先して "completed" を返すため、利用者には大きな破綻はない。source-codeより
2. completed_jobs[].duration が実測値でない
status file を進捗 UI や perf 分析の材料に再利用したくなると、この性質は無視できない。逆に rerun 判定や API の ready/error 表示にはほぼ効かない。source-codeより
3. estimated_cost は status file に入らない
成功時は key が無く、error 時は null になる。費用は API が token 数から計算するので、status file の estimated_cost を費用の出どころとして読むと外れる。source-codeより
4. error 文字列の形式は統一されていない
機械処理向けに parse するなら危険だが、現状の API は表示用途が中心で、step 名を含む文面の方が診断しやすい。source-codeより
含意
- PR #840 の merge で workflow path が canonical になり、Phase 3b は完了扱いになった(refactoring-status / phase3b-exit-criteria)。上の性質は merge の blocker ではなく、許容した差分として残っている
- status file を「legacy と byte-for-byte 同じ意味」と見なさない
- 残課題は status file の存在そのものではなく、progress / duration / cost のような周辺意味論を、どこまで正式な契約にするか である
Open Questions
- workflow path でも
completed_jobs[].durationを実測値にするべきか estimated_costを status file の正式契約に戻すべきか、API 側の計算に一本化して key をやめるべきかerrorをExceptionType: ...に寄せるべきか、step 文脈付き文面を canonical にするべきかcurrent_jobを終了時に消すべきかcurrent_job_progress/current_jop_tasksを workflow engine の正式な callback にするべきか
Updates
- 2026-05-21: 初回作成。branch tip
04516afを基準に、legacy.run()と workflow path のhierarchical_status.jsonsemantics を比較 - 2026-10-21: main
b71e0b79と照合し、PR #840(2026-05-21 merge)後の現状(workflow path だけが書く、durationは 0.0 固定、estimated_costは成功時に無い、PR #1033 で atomic な書き込み)を冒頭と「結論」に書き直し、項目別の比較を merge 直前の記録として位置づけ直した。legacy.run()のestimated_costが計算値ではなかったことも訂正