### 11. 番号の種類と書き方（2026-11-01）

記録とデータには、意味の違う番号が何種類もある。見た目が同じ番号を別の意味で使うと、記事とデータを取り違える（例：`lab/Log07` は研究室の7回目、`vision/captured/Log07` は画像認識の7回目で、別物）。番号は付け替えず、種類ごとの意味と書き方を決める。

#### 11-1. 番号の種類

| 種類 | 形 | 意味 |
|---|---|---|
| 記事番号 | `DAY{NNN}` → `LOG{NNN}` | 記事の通し番号。初期は DAY、記事を毎日出さなくなってから LOG に名前を変えた。DAY と LOG は同じ通し番号（LOG は DAY の続き） |
| シリーズ内の番号 | `Log{NN}` | そのシリーズの何回目か。シリーズ名と組でなければ意味を持たない |
| 試行の番号 | `run_stem` の全体（例 `run_0001_20261019_191257`） | 1回の試行。`run_0001` だけでは別の日の試行と重なるので、日付まで含めた全体で1回を指す |
| 学習・推論の回 | `pi05_{YYYYMMDD}_{HHMMSS}` など | 1回の学習・推論の実行 |
| データの版 | `_v1`・`_v2`・`_trim2`・`_corr_v3` など | そのデータセット・モデルの版。記事番号ではない |
| 学習の段数 | checkpoint の step（`1499`・`3999` など） | 学習の何段目のモデルか。記事番号ではない |

記事番号とシリーズ内の番号の正は、公開記事（pixelstomotors.com）とする（MASTER「シリーズの正は公開記事」に従う）。

#### 11-2. 書き方の決まり

- 既存のフォルダ名・ファイル名・台帳の値は付け替えない（記録の改変を始めないため）
- 文章・README・これから出力する meta には、番号を種類つきで書く。例：`記事LOG352`、`研究室Log09`、`画像認識Log07`、`run_0001_20261019_191257`
- これから出力する meta（各回の JSON・`recording_meta.json` など）には、シリーズ名とシリーズ内の番号を組で入れる。分かっていれば記事番号も入れる。記事が後から決まる場合は空のままでよい（対応は11-3で足す）
- 番号どうしの対応（記事番号 ↔ シリーズ内の番号 ↔ 試行・学習の回・データ・checkpoint）は、番号に詰め込まず、索引の関係表に置く（置き場所は MASTER の保存先テーブルに従う）

#### 11-3. 関係表への載せ方

- 載せる根拠は、記事本文・README・meta に書かれた明示の参照を優先する。名前や日付が近いだけのものは「候補」とし、確定と分ける
- 1つの記事が複数のデータを使い、1つのデータが複数の記事で使われることがある（多対多）。関係には種類（作った・使った・比べた など）を付ける
- 仮の番号（例：README に「番号は仮」と書かれたフォルダ）は「仮」として載せ、確定したら確定の行を1行足す（既存の行は書き換えない）

---

### 12. 出力に付ける由来（provenance）（2026-11-01）

データ・モデルが「どのコード・どの入力・どの設定で、どう終わったか」を、作った時点で機械が読める形で残す。主指標の「再現可能」の条件2（依存関係とバージョンが記載されている）を、手書きの README に頼らず満たすため。

#### 12-1. 対象

- **これから作る出力だけ**。既存のデータ・JSON・checkpoint には書き足さない（過去の由来は索引の関係表と README でたどる）
- 段階的に入れる：①学習と checkpoint → ②データセットを作るスクリプト → ③実機の試行（`run_pick_place.py`・recorder など）。③は関節の制御に触れないが、実機の流れの中なので codex のレビューと dry-run を通してから使う

#### 12-2. 置き方

- 既存の出力 JSON（各回の JSON・`recording_meta.json`・データセットの `index.json`・lab の記録など）に、キー `provenance` を1つ足して中に入れる。由来のためだけの JSON を別に増やさない
- 例外：checkpoint は中に書ける JSON がない（`_CHECKPOINT_METADATA` は openpi の形式）。新しく置く checkpoint の各ステップのフォルダ（`checkpoints/<モデル名>/<ステップ>/`）に `train_provenance.json` を1つ置き、同じものをその回の `lab/Log{NN}/` にも写す。Hugging Face に上げるときも同じファイルを入れる
- **台帳の列は増やさない**（8-A の手順を踏まずに済ませるため）。台帳から各回の JSON へは、今までどおり `run_stem` でたどる

#### 12-3. 項目（`schema_version` = `provenance/1`）

| 項目 | 中身 |
|---|---|
| `schema_version` | `provenance/1`。項目を変えるときは版を上げる |
| `created_at` | 作った時刻（ISO8601・タイムゾーンつき） |
| `producer` | スクリプトのパス（r2r2r-scripts からの相対）・実行したコマンドの引数（秘密の値は除く）・実行した機械（Mac / Pod など） |
| `code` | `repo`（r2r2r-scripts）・`commit`・`dirty`（未コミットの変更があるか）・`dirty_files`（変更のあるファイル名）・`diff_sha256`（変更の中身の指紋） |
| `external_code` | 使った外部のコードごとに `name`・`commit`・`dirty`（例 openpi） |
| `inputs` | 入力ごとに `kind`（dataset / checkpoint / run / recording / config）・`id`（フォルダ名やモデル名）・`path`（r2r2r-data からの相対）・`fingerprint` |
| `config` | 設定の名前と主な値（学習なら設定名・ステップ数・初期の重み・学習率など） |
| `compute` | 学習・推論でクラウドを借りたとき：借り先・GPU の型番・始めと終わりの時刻・時間・費用（MASTER「買う前に借りて測る」の記録） |
| `numbering` | `series`・`series_log`・`article_no`（11節。分からなければ空） |
| `status` | `process`（completed / interrupted / failed：処理が最後まで動いたか）と `task`（success / failure / unknown / not_applicable：タスクが成功したか）を分けて書く |

#### 12-4. 指紋（fingerprint）の作り方

- `files-v1:` ＋ sha256。中身は、フォルダ内のファイルを相対パスの順に並べた「相対パス・バイト数」の一覧と、1MB 未満の JSON（`index.json` など）の中身
- 大きなファイル（画像・動画・重み）は中身を読まない。数GBのものを毎回読むと出力が遅くなるため
- `._` で始まるファイル（exFAT の印）・`.cache`・一時フォルダ（`.incoming_*`）は数えない

#### 12-5. 守ること

- 未コミットの変更があっても止めない。`dirty: true` と変更のファイル名・指紋を残して進める（研究を止めないため）
- 鍵・トークン・パスワードは書かない。コマンドの引数に秘密が入る場合は値を伏せる
- 由来を書く処理が失敗しても、本来の出力（学習・データ・試行）は止めない。そのときは `provenance` に `error` を書く
- 書き方は共通の部品（r2r2r-scripts の `provenance.py`）にまとめ、各スクリプトはそれを呼ぶ