# 🤎 Checkpoint Name Cycler (心臓 v0.3.1)
`Checkpoint Name Cycler` は、本Suiteの「動力を司る心臓」じゃ。
大量の生成ジョブをバックグラウンドで走らせながら、Checkpoint（.safetensors）を指定したルールに基づいて全自動で切り替え、KSamplerへインジェクション（注入）し続ける役割を担っておる。
v0.2.0のアップデートでは、巡回アルゴリズム自体の根本的な破壊変更はない（なぜなら最初から完成されていたからじゃ！）。じゃが、絶対神 `god! (👑)` を含む新ステータスフィルターへの完全追従に加え、**「ブラウザをリロードしたりComfyUIを再起動しても、ノード上でポチポチ設定したフィルター状態や巡回モードがしっかり復元される（Restore-safe Runtime Controls）」**という、地味ながらも長時間のお祭り（運用）には欠かせない極めて強力な安定性向上が図られておるぞ！
---
## 🔌 入出力仕様（Specifications）
### 📥 入力（Inputs）
* **`start_checkpoint` (必須 / COMBO):**
巡回を開始する基準となるCheckpoint（または `fixed` モード時に固定するCheckpoint）を選択する。
* **`mode` (必須 / COMBO):**
Checkpointの巡回アルゴリズムを選択する（詳細は後述）。
* 設定値：`fixed` / `increment` / `randomize` / `shuffle_once`
* **`change_every` (必須 / INT):**
同じCheckpointを「何回のジョブ（Queue）の間維持するか」を設定する（デフォルト: `1`）。
* *※Local Listの割り込み処理中は、この値は無視されて必ず1回ずつ消費されるぞ。*
* **`hps_tab_id` (非表示 / STRING):**
ブラウザのタブを識別し、マルチタブ間での独立した巡回制御（時空隔離）を実現するための固有ID。
### 📤 出力（Outputs）
* **`ckpt_name` (COMBO):**
現在選択（解決）されたCheckpointの名前。
ざっくり言ってしまえば、これを今使っているワークフローの `Load Checkpoint（チェックポイントを読み込む）` の入力に繋いでやるだけで、既存のスパゲッティ配線を1ミリも壊さずに全自動巡回システムを寄生（アドオン）させることができるのじゃ！
* **`ckpt_name_str` (STRING):**
現在選択されたCheckpointのファイルパス文字列（TaggerやPreviewへの動的バインド用）。
* **`ckpt_name_safe` (STRING):**
ファイル名として安全に使用できるよう、記号や拡張子を除去・置換した文字列。`SaveImage` ノードのプリフィックス等に繋ぐことで、出力ファイル名に自動でモデル名が美しく刻まれるぞ！
---
## 🎛 4つの巡回モード（Anatomy of Modes）
### 1. `fixed` (固定モード)
一般的なCheckpoint選択ノードと同じ挙動じゃ。
* `start_checkpoint` で選んだモデルを常に使い続ける。
* ノード上に表示されているステータスフィルター（👑や💛など）のボタンをオンにしても、このモードでは**フィルターは完全に無視**される。一点突破じゃ！
* リフレッシュによって選択中のモデルが物理消滅した場合は、エラーで墜落させず、安全のために自動で「現在存在する有効なモデル」へフォールバックするタフな仕様じゃぞ。
### 2. `increment` (順次巡回モード)
ソートされたモデル一覧を、ジョブごとに1つずつ順番に進めていく王道のモードじゃ。
* フィルターが設定されている場合、フィルター条件に一致するモデルだけを自動で検索し、一致しないモデルはインデックスをマッハでスキップ（飛ばして進む）する。
* 途中でフィルター条件を変更しても、現在の巡回インデックス（どこまで進んだか）がリセットされることはない安心設計じゃ。
### 3. `randomize` (ランダムモード)
現在存在するモデル（またはフィルターに一致したモデル群）の中から、毎回完全にランダムで1つをチョイスする。
* 重複（連続で同じモデルが選ばれること）を許容する。
* 山札から取り除くような概念（スキップやデッキ挙動）はないぞ。ひたすらサイコロを振るのじゃ！
### 4. `shuffle_once` (一期一会モード) ★超推奨★
現在存在するすべてのモデルをシャッフルし、「1枚の特製山札（グローバルデッキ）」を内部で構築するモードじゃ！
* 登録されたモデルを**重複なしで1回ずつすべて引き切るまで**巡回を続ける。
* フィルターは「山札からカードを引いたその瞬間」に動的適用される。もし引いたカードが現在のフィルターに合致しなければ、そのカードは破棄（消費）されて即座に次のカードを引く！
* 山札のカードをすべて引ききって空（Empty）になった瞬間、自動で再び全モデルを含んだ新しい山札がシャッフル生成される仕様じゃ。
---
## 🧠 技術的深淵：【ジョブの実行時遅延解決（Lazy Resolution）】
### なぜ、500件のジョブを走らせたまま、裏でモデルの同期をかけてもワークフローが壊れないのか？
従来の一般的なComfyUIカスタムノードや標準機能では、ユーザーが `Queue Prompt`（ジョブ実行）ボタンを押した「その瞬間」に、どのCheckpointを読み込むかというパス情報が静的に確定し、プロンプトサーバーのキュー（待ち行列）の中にそのままカチコチのデータとして積まれてしまう。
この設計だと、ジョブが実行されている最中にモデルを削除したり、Selector側で「🔄 Refresh All」を押してモデル一覧を動的に同期させた場合、**すでに待ち行列（キュー）の中に積まれてしまっている古いパス情報との間で深刻な不整合（データの矛盾）が発生し、キャッシュが壊れてComfyUIが墜落（クラッシュ）してしまう**のじゃ。
これを美しく粉砕したのが、本Suiteの誇る **「実行時遅延解決（Lazy Resolution）」** アーキテクチャじゃ！
```
【従来の設計】
[ジョブ登録時] ── ❌ 読み込むモデルのパスをカチコチに固定してキューに積む
↓ (この間にモデル構成が変わると……)
[KSampler実行] ── 💥 データが矛盾してクラッシュ！
【HandpickerSuiteの陰の叡智】
[ジョブ登録時] ── 📦 「Cyclerを実行せよ」という空のコンテナだけをキューに積む
↓ (この間に別タブでリフレッシュやタグ打ちを行っても……)
[KSampler実行直前] ── 🎯 その一瞬の「最新の内部状態」を参照して、Checkpoint名を動的に解決・注入！
```
`Checkpoint Name Cycler` は、ジョブが積まれた時点ではCheckpointのパスを固定しない。
待ち行列が消化され、**まさにKSamplerにデータが渡るその直前の瞬間（実行時）になって初めて、「現在の最新のインデックス」や「別タブ側で更新された最新のフィルター状態」を参照し、Checkpointの名前をギリギリで動的に解決（インジェクション）する**のじゃ。
この「決定をギリギリまで引き延ばす」非同期遅延解決プロセスの導入により、
* **ジョブのキューの中身（待ち行列）をわざわざ書き換えたり同期し直したりする必要が一切ない**
* 生成ラインが全力疾走している裏で、別タブから安心して `Refresh All` やタグ打ちを行っても、ワークフローが絶対に壊れない
という、圧倒的な堅牢性と常時稼働（ノンストップ・運用）が実現されておるのじゃよ！
## 宣伝画像
