docs: WHEEL_DEBUG_METADATA_{JSON,XML} overwrite behavior

documentMD/design/configuration.md

@@ -103,6 +103,13 @@ WHEELの設定は **c12** ライブラリを使用してロードされ、複数
 | `WHEEL_ANONYMOUS_LOGIN` | `YES` に設定すると匿名ログインユーザーを作成し認証を有効化 |
 | `WHEEL_ANONYMOUS_PASSWORD` | 匿名ユーザーのパスワード（省略時はランダム生成） |
 
+### デバッグ変数（環境変数専用・`server.json` にマッピングされない）
+
+| 環境変数 | 説明 |
+|---------|------|
+| `WHEEL_DEBUG_METADATA_JSON` | HPCI-SS メタデータJSONを指定パスに書き出す。固定パスへ毎回上書き（詳細・上書き挙動は `gfarm.md` の「デバッグ用メタデータ書き出し」節を参照） |
+| `WHEEL_DEBUG_METADATA_XML` | 同上のXML版 |
+
 ## 5. 型の自動変換（coerce）
 
 環境変数はすべて文字列として渡されるため、以下のルールで自動変換される。

documentMD/design/gfarm.md

@@ -244,6 +244,24 @@ gfarm:///path/to/project/output  # プロジェクト配下
 WHEEL_DEBUG_METADATA_XML=/tmp/debug_metadata.xml npm start -w server
 ```
 
+#### 上書き挙動
+
+書き出し先は環境変数で指定した**固定パス**で、コンポーネント名や連番は付与されない。
+`writeFile`（`node:fs/promises`、フラグ `w` = truncate）で書き込むため、既存内容は毎回上書きされる。
+
+- **1つの HPCI-SS / HPCISS-tar コンポーネント内に `inputFiles` が複数ある場合** — 書き出しは
+  **1回だけ**。`gatherComponentMetadata` / `componentMetadataToXml` は `_hpcissHandler`
+  （`dispatcher.js`）内で1回のみ呼ばれ、複数の `inputFiles` は Gfarm 拡張属性
+  `wheel.workflow` の付与先が増えるだけで、生成される JSON/XML は共通。
+- **プロジェクト内に HPCI-SS / HPCISS-tar コンポーネントが2つ以上ある場合、または同一コンポーネントが
+  loop 内・再実行で複数回実行される場合** — 実行のたびに同じパスへ書き出すため上書きされ、
+  **最後の実行分だけが残る**。
+- 各書き出しはその時点の**プロジェクト全体のスナップショット**（対象コンポーネントだけではない）。
+  実行タイミングが異なれば各コンポーネントの `state` 等が変わり、内容も異なり得る。
+
+複数コンポーネント分をすべて残したい場合は、パスへ連番／コンポーネントID／タイムスタンプを
+付与する改修が必要（現状の実装では非対応）。
+
 ## 9. タイムアウト設定
 
 各GFarm操作関数はデフォルトのタイムアウト（秒）が設定されている。

server/app/db/version.json

@@ -1 +1 @@
-{"version": "2026-0902-123259-beta" }
+{"version": "2026-0903-113554-beta" }