refactor: simplify re-estimation entrypoint [code:qws] [system:MiyabiG]

Author: yoshifuminakamura

.gitlab-ci.yml

@@ -28,9 +28,7 @@ variables:
   benchpark: "false"
   park_only: "false"
   park_send: "false"
-  estimate_uuid: ""
   estimate_result_uuid: ""
-  result_uuid: ""
   reestimation_reason: ""
   reestimation_trigger: ""
 
@@ -78,7 +76,7 @@ generate_matrix:
       - .gitlab-ci.generated.yml
     expire_in: 1 hour
   rules:
-    - if: '$estimate_uuid != "" || $estimate_result_uuid != "" || $result_uuid != ""'
+    - if: '$estimate_result_uuid != ""'
       when: never  # 推定モードでは通常パイプラインを無効化
     - if: '$park_only == "true"'
       when: never  # park_onlyモードでは無効
@@ -115,7 +113,7 @@ trigger_child_pipeline:
     - job: generate_matrix
       optional: true
   rules:
-    - if: '$estimate_uuid != "" || $estimate_result_uuid != "" || $result_uuid != ""'
+    - if: '$estimate_result_uuid != ""'
       when: never  # 推定モードでは通常パイプラインを無効化
     - if: '$park_only == "true"'
       when: never  # park_onlyモードでは無効
@@ -152,7 +150,7 @@ generate_benchpark_matrix:
       - .gitlab-ci.benchpark.yml
     expire_in: 1 hour
   rules:
-    - if: '$estimate_uuid != "" || $estimate_result_uuid != "" || $result_uuid != ""'
+    - if: '$estimate_result_uuid != ""'
       when: never  # 推定モードではBenchParkパイプラインも無効化
     - if: '$code != "" && $benchpark != "true" && $park_only != "true" && $park_send != "true"'
       when: never  # BenchKit専用のcode指定時はBenchParkを実行しない
@@ -186,7 +184,7 @@ trigger_benchpark_pipeline:
     - job: generate_benchpark_matrix
       optional: true
   rules:
-    - if: '$estimate_uuid != "" || $estimate_result_uuid != "" || $result_uuid != ""'
+    - if: '$estimate_result_uuid != ""'
       when: never  # 推定モードではBenchParkパイプラインも無効化
     - if: '$code != "" && $benchpark != "true" && $park_only != "true" && $park_send != "true"'
       when: never  # BenchKit専用のcode指定時はBenchParkを実行しない
@@ -219,7 +217,7 @@ generate_estimate_matrix:
       - .gitlab-ci.estimate.yml
     expire_in: 1 hour
   rules:
-    - if: '$estimate_uuid != "" || $estimate_result_uuid != "" || $result_uuid != ""'
+    - if: '$estimate_result_uuid != ""'
       when: always
     - when: never
 
@@ -238,6 +236,6 @@ trigger_estimate_pipeline:
     - job: generate_estimate_matrix
       optional: true
   rules:
-    - if: '$estimate_uuid != "" || $estimate_result_uuid != "" || $result_uuid != ""'
+    - if: '$estimate_result_uuid != ""'
       when: always
     - when: never

README.md

@@ -247,7 +247,7 @@ python -m pytest tests/ -v
 - UUID指定による再推定もサポート
   - `estimate_result_uuid` を指定すると、その estimate から `source_result_uuid` を引いて再推定
   - docs 上の正式な入口は `estimate_result_uuid` に統一する
-  - `result_uuid` は内部処理や互換のために残りうるが、利用者向け入口としては扱わない
+  - 入口を 1 本に絞ることで、比較・履歴・UI の意味付けを単純に保つ
 
 ### 5. BenchPark統合パイプライン
 - `benchpark-bridge/config/apps.csv` で監視対象を定義

docs/cx/BENCHKIT_GAP_ANALYSIS.md

@@ -193,7 +193,7 @@ Once the estimation specification is clarified, many other design decisions beco
 | 詳細推定 package | `instrumented_app_sections` など取得方式別 package を持てること | `instrumented_app_sections_dummy` を `qws` 向け参照実装として実装済み | 実測区間時間や外部ツール区間時間を使う本格 package は未実装 | 最優先 |
 | 複合推定 | section ごとに異なる方式を合成できること | `qws` と `instrumented_app_sections_dummy` で section ごとの package 指定、artifact 参照、section package dispatch、section-level fallback を実装済み | 複数実アプリへの適用、本格 package 実装、より一般的な合成規則は未着手 | 高 |
 | 推定 provenance | 推定元 result と推定結果自体の出自情報を保持すること | 推定元 result の UUID / timestamp、requested/applied package、推定結果自体の UUID / timestamp を Estimate JSON に保持できる。result JSON 側にも server UUID / timestamp を保持できる | compare UI や再推定導線での活用は未整理 | 中 |
-| 再推定 | UUID 起点で再推定し比較可能にすること | shell フローはある | UUID 取得 API 仕様と比較表示の整理が未完 | 高 |
+| 再推定 | `estimate_result_uuid` 起点で再推定し比較可能にすること | 再推定専用 trigger、child pipeline、result / estimate / estimation input の再取得、`reestimation` ブロック付与、CI 上での保存完了まで動作する | compare UI、portal からの起動導線、表示上の差分把握が未完 | 高 |
 | 推定結果表示 | model / assumptions / applicability を表示できること | estimated 画面で requested/applied package、applicability、estimate UUID などの基本表示は可能 | section / overlap 単位の詳細表示、比較表示、`not_applicable` の説明補助は未整備 | 中 |
 
 この表から、現在の最小核は以下と整理できる。
@@ -205,8 +205,8 @@ Once the estimation specification is clarified, many other design decisions beco
 
 逆に、まだ核ではないが後で効くものは以下である。
 
-- UUID 比較 UI
-- 再推定要求フロー
+- 再推定比較 UI
+- portal からの再推定要求フロー
 - 複合推定の本格化
 - counter / trace / overlap の本格活用
 - section / overlap 単位の詳細 UI 表示
@@ -218,7 +218,7 @@ Once the estimation specification is clarified, many other design decisions beco
 1. `qws` 以外の app へ推定方式を横展開する
 2. section / overlap 単位の package applicability と `not_applicable` 詳細を portal で見やすくする
 3. 複数 detailed package 間の fallback と discovery を整理する
-4. その後に UUID 再推定と比較表示へ進む
+4. その後に再推定比較 UI と portal 起動導線へ進む
 
 ここでいう区間時間ダミー package は、すでに最初の参照実装として導入済みである。
 今後は、少なくとも以下を満たす方向へ育てる必要がある。

docs/cx/REESTIMATION_SPEC.md

@@ -54,11 +54,11 @@ Typical use cases include:
 
 再推定では、入力となる benchmark result を明示的に固定しなければならない。
 この識別には、少なくとも result の UUID を用いることを基本とする。
-ただし、実運用では estimate result UUID を入口にし、その estimate が保持する `source_result_uuid` から元 result を辿れることが望ましい。
+再推定の利用者向け入口は `estimate_result_uuid` に統一する。BenchKit はその estimate が保持する `source_result_uuid` を内部的に解決し、元 result を辿る。
 
 In re-estimation, the input benchmark result must be explicitly fixed.
-At minimum, the UUID of the result should be used as the primary identifier.
-In practical workflows, however, it is desirable to allow an estimate-result UUID as the entry point and resolve the original result through `source_result_uuid`.
+The documented user-facing entrypoint is `estimate_result_uuid`.
+BenchKit internally resolves the original benchmark result through the `source_result_uuid` stored in that estimate.
 
 ### 3.2 比較可能性 / Comparability
 
@@ -100,17 +100,17 @@ It must not silently ignore missing inputs and still report a successful estimat
 
 BenchKit における再推定の典型フローは以下である。
 
-1. 利用者またはワークフローが `estimate_result_uuid` または `result_uuid` を指定する
-2. `estimate_result_uuid` の場合、BenchKit は estimate JSON を取得し、そこから `source_result_uuid` を解決する
+1. 利用者またはワークフローが `estimate_result_uuid` を指定する
+2. BenchKit は estimate JSON を取得し、そこから `source_result_uuid` を解決する
 3. BenchKit が対応する Result JSON を取得する
 4. 対象 app の `estimate.sh` を起動する
 5. `Estimate JSON` を生成する
 6. 生成結果を保存し、ポータルで参照可能にする
 
 The typical re-estimation flow in BenchKit is:
 
-1. a user or workflow specifies either an `estimate_result_uuid` or a `result_uuid`
-2. if an `estimate_result_uuid` is given, BenchKit fetches the estimate JSON and resolves `source_result_uuid`
+1. a user or workflow specifies an `estimate_result_uuid`
+2. BenchKit fetches the estimate JSON and resolves `source_result_uuid`
 3. BenchKit fetches the corresponding Result JSON
 4. the app-specific `estimate.sh` is invoked
 5. an `Estimate JSON` is generated
@@ -120,7 +120,7 @@ The typical re-estimation flow in BenchKit is:
 
 再推定では少なくとも以下を入力として扱う。
 
-- `estimate_result_uuid` または `result_uuid`
+- `estimate_result_uuid`
 - `code`
 
 必要に応じて以下を追加で与えてよい。
@@ -133,7 +133,7 @@ The typical re-estimation flow in BenchKit is:
 
 At minimum, re-estimation uses the following inputs:
 
-- `estimate_result_uuid` or `result_uuid`
+- `estimate_result_uuid`
 - `code`
 
 Optionally, the following may also be supplied:
@@ -164,29 +164,39 @@ In the current implementation, the following already exist:
 - a distinction between `requested_estimation_package` and the actually applied `estimation_package`
 - final-state applicability recording through `applicable`, `partially_applicable`, `fallback`, and `not_applicable`
 
-現時点では、re-estimation で再取得できるのは source result JSON までであり、
-server 側に保存された detailed estimation-input artifact の復元はまだ未実装である。
-そのため現状では、
+現時点では、re-estimation で
+- source result JSON の再取得
+- server 側に保存された detailed estimation-input artifact の復元
+- 復元 artifact を用いた detailed 再推定
+まで実装済みである。
 
+ただし、artifact が server 側に存在しない場合は、
 - artifact 不要な lightweight 再推定は成立しうる
 - artifact を要求する detailed 再推定は `not_applicable` で終わりうる
 
-At present, re-estimation can re-fetch the source result JSON itself, but restoration of stored detailed estimation-input artifacts is not yet implemented.
-Therefore:
+At present, re-estimation can:
+
+- re-fetch the source result JSON
+- restore stored detailed estimation-input artifacts
+- execute detailed re-estimation using the restored artifacts
+
+However, when those artifacts do not exist on the server:
 
 - lightweight or artifact-free re-estimation may succeed
 - detailed re-estimation that depends on missing artifacts may terminate as `not_applicable`
 
 ## 7. 現行実装と仕様のギャップ / Gaps Between Current Implementation and the Intended Specification
 
-### 7.1 UUID 取得 API の仕様 / UUID-Based Result Retrieval API
+### 7.1 再推定取得口の仕様 / Re-Estimation Retrieval Interfaces
 
-再推定を UUID 起点で運用するには、少なくとも次の取得口が必要である。
+再推定を `estimate_result_uuid` 起点で運用するには、少なくとも次の取得口が必要である。
 
 - estimate result UUID で estimate JSON を返す取得 API
-- result UUID で Result JSON を返す取得 API
+- estimate JSON に記録された `source_result_uuid` に基づいて Result JSON を返す取得 API
+- `source_result_uuid` に対応する estimation input artifact を返す取得 API
 
-現時点では、再推定の shell フロー自体は存在しても、その取得口の公開仕様や認証条件は文書としてまだ十分に固定されていない。
+現時点では、再推定の shell フローと取得口自体は実装済みである。
+一方で、取得 API の公開方針、認証条件、portal や compare UI からの見せ方は文書としてまだ十分に整理されていない。
 
 したがって、以下を明確化する必要がある。
 
@@ -195,13 +205,17 @@ Therefore:
 - confidential 結果の扱い
 - 取得失敗時の振る舞い
 
-UUID-based re-estimation requires an API or equivalent retrieval path that can fetch Result JSON by UUID.
-At present, the shell-side re-estimation flow exists, but the retrieval endpoint, exposure rules, and authentication conditions are not yet fixed clearly enough in the documents.
+Re-estimation from `estimate_result_uuid` requires retrieval paths for:
+
+- Estimate JSON by estimate-result UUID
+- Result JSON through the resolved `source_result_uuid`
+- estimation-input artifacts associated with that source result
+
+At present, the shell-side re-estimation flow and these retrieval endpoints exist, but the exposure rules, authentication conditions, and portal-facing documentation are not yet fixed clearly enough in the documents.
 
 The following therefore need to be clarified:
 
-- a retrieval API that returns Estimate JSON by estimate-result UUID
-- a retrieval API that returns Result JSON by result UUID
+- the exposure policy of the retrieval APIs
 - whether authentication is required
 - how confidential results are handled
 - behavior on retrieval failure
@@ -260,7 +274,7 @@ At least the following need to be clarified:
 
 BenchKit における再推定は、少なくとも以下を満たすことが望ましい。
 
-1. `estimate_result_uuid` または `result_uuid` 指定で benchmark result を再取得できること
+1. `estimate_result_uuid` 指定で benchmark result を再取得できること
 2. app ごとの `estimate.sh` を同じ入力に対して繰り返し実行できること
 3. 再推定結果に、元 benchmark result UUID を残せること
 4. 異なる推定方式を同じ benchmark result に対して併存させられること
@@ -269,7 +283,7 @@ BenchKit における再推定は、少なくとも以下を満たすことが
 
 Re-estimation in BenchKit should preferably satisfy at least:
 
-1. the benchmark result can be re-fetched from either `estimate_result_uuid` or `result_uuid`
+1. the benchmark result can be re-fetched from `estimate_result_uuid`
 2. app-specific `estimate.sh` can be run repeatedly for the same input
 3. the re-estimation result can retain the original benchmark-result UUID
 4. different estimation methods can coexist for the same benchmark result
@@ -281,8 +295,8 @@ Re-estimation in BenchKit should preferably satisfy at least:
 
 当面の再推定では、artifact 復元を次の流れで扱う。
 
-1. `estimate_result_uuid` から開始する場合は、estimate JSON から `source_result_uuid` を解決する
-2. `result_uuid` から開始する場合は、そのまま source result JSON を取得する
+1. `estimate_result_uuid` から開始し、estimate JSON から `source_result_uuid` を解決する
+2. source result JSON を取得する
 3. `received_estimation_inputs/<result-stem>/` が存在する場合は、その内容を `results/estimation_inputs/` に復元する
 4. server 側に estimation input artifact が無い場合は、artifact 不要な推定のみを許可し、必要な推定は `not_applicable` とする
 
@@ -297,18 +311,17 @@ Current restoration should follow this flow:
 
 次に候補となる実装は以下である。
 
-1. estimate/result の UUID 指定取得 API の仕様化と実装確認
-2. 再推定向けに UUID 指定取得口と認証条件を文書化する
-3. 同一 `source_result_uuid` を軸にした比較表示仕様を定義する
+1. 再推定向け取得 API の公開方針と認証条件を文書化する
+2. 同一 `source_result_uuid` を軸にした比較表示仕様を定義する
+3. `reestimation` ブロックを portal / compare UI で活かす
 4. portal から再推定を起動する要求フローを定義する
 
 Candidate next steps include:
 
-1. specify and verify the UUID-based estimate/result retrieval APIs
-2. document the retrieval endpoint and authentication conditions for re-estimation
-3. persist estimation-input artifacts under `received_estimation_inputs/` and restore them during re-estimation fetch
-4. define a display specification for comparing re-estimation results using `source_result_uuid`
-5. define a portal-driven request flow for starting re-estimation
+1. document the exposure policy and authentication conditions of the re-estimation retrieval APIs
+2. define a display specification for comparing re-estimation results using `source_result_uuid`
+3. surface the `reestimation` block in portal / compare UI
+4. define a portal-driven request flow for starting re-estimation
 
 ## 10. 現在の実装状態の補遺 / Addendum on Current Status
 
@@ -330,8 +343,7 @@ Candidate next steps include:
 - compare UI や portal からの起動とも整合しやすい
 - どの estimate を起点にした再推定かを明示しやすい
 
-`result_uuid` は内部処理や正規化のために使うことがあっても、利用者向けの正式入口としては扱わない。
-また、`estimate_uuid` は文書上の正式入口とはしない。
+再推定の入口として文書化するのは `estimate_result_uuid` のみとする。
 
 ## 12. 再推定トリガ例 / Re-Estimation Trigger Example
 

scripts/estimation/generate_reestimate_pipeline.sh

@@ -5,10 +5,8 @@
 # of a specific benchmark result identified by UUID.
 #
 # Required CI variables:
-#   result_uuid          - UUID of the benchmark result to re-estimate directly
 #   estimate_result_uuid - UUID of the estimate result to re-estimate from
-#   estimate_uuid        - legacy alias for result_uuid
-#   code           - Program code name (e.g., "qws")
+#   code                 - Program code name (e.g., "qws")
 # Optional CI variables:
 #   reestimation_reason  - e.g. package-update, model-tuning, manual-rerun
 #   reestimation_trigger - e.g. ci-reestimation, portal, local-test
@@ -18,8 +16,8 @@
 set -euo pipefail
 
 # Validate required variables
-if [[ -z "${result_uuid:-}" && -z "${estimate_result_uuid:-}" && -z "${estimate_uuid:-}" ]]; then
-  echo "ERROR: result_uuid or estimate_result_uuid must be specified" >&2
+if [[ -z "${estimate_result_uuid:-}" ]]; then
+  echo "ERROR: estimate_result_uuid must be specified" >&2
   exit 1
 fi
 

scripts/estimation/test_reestimate.sh

@@ -1,22 +1,18 @@
 #!/bin/bash
 set -euo pipefail
 
-if [[ $# -lt 2 || $# -gt 3 ]]; then
-  echo "Usage: $0 <code> <result_uuid|estimate_result_uuid> [kind]"
+if [[ $# -ne 2 ]]; then
+  echo "Usage: $0 <code> <estimate_result_uuid>"
   echo "  <code>: program name (directory under programs/)"
-  echo "  <result_uuid|estimate_result_uuid>: UUID to use as the re-estimation entry point"
-  echo "  [kind]: result | estimate (default: estimate)"
+  echo "  <estimate_result_uuid>: UUID to use as the re-estimation entry point"
   echo ""
   echo "Examples:"
   echo "  $0 qws 11111111-2222-3333-4444-555555555555"
-  echo "  $0 qws 11111111-2222-3333-4444-555555555555 estimate"
-  echo "  $0 qws 11111111-2222-3333-4444-555555555555 result"
   exit 1
 fi
 
 code="$1"
 input_uuid="$2"
-kind="${3:-estimate}"
 
 if [[ ! "$input_uuid" =~ ^[0-9a-fA-F-]{36}$ ]]; then
   echo "ERROR: UUID format looks invalid: $input_uuid" >&2
@@ -36,28 +32,12 @@ fi
 rm -f results/result*.json results/estimate*.json results/source_estimate.json
 mkdir -p results
 
-case "$kind" in
-  estimate)
-    export estimate_result_uuid="$input_uuid"
-    unset result_uuid 2>/dev/null || true
-    unset estimate_uuid 2>/dev/null || true
-    ;;
-  result)
-    export result_uuid="$input_uuid"
-    unset estimate_result_uuid 2>/dev/null || true
-    unset estimate_uuid 2>/dev/null || true
-    ;;
-  *)
-    echo "ERROR: kind must be one of: estimate, result" >&2
-    exit 1
-    ;;
-esac
+export estimate_result_uuid="$input_uuid"
 
 export code
 
 echo "Re-estimation test"
 echo "  code: $code"
-echo "  kind: $kind"
 echo "  uuid: $input_uuid"
 echo ""