ruminar-ComfyUI-PromptRandomChoice/.spec/runtime-behavior.md

Runtime behavior specification

目的

Queue投入済みで未実行のジョブが、ノード実行時点でサーバーに受理済みの 最新候補集合を参照できるようにする。実行開始済みのジョブは変更しない。

Queue時とRuntime時の分離

Queue時に確定するもの:

• グラフと接続
• change_every
• サーバー状態がない場合のフォールバック候補テキスト
• 永続化されたstate_key

Runtime同期するもの:

• 候補入力テキスト
• 入力状態
• 受理済み候補revision

change_everyはRuntime同期しない。

選択寿命

Runtimeで更新されるのは候補集合であり、現在選択中の完成文字列ではない。

change_every = 3
実行1: revision 1からAを選択
編集: revision 2を受理
実行2: A
実行3: A
実行4: revision 2から再選択

• 候補編集でrepeat countをリセットしない。
• 選択中候補の削除、#化、内容変更でも保持期間中は完成文字列を維持する。
• !の追加・削除も次回再選択時に反映する。
• change_every入力値自体がQueue間で変わった場合は、新周期として選択し直す。
• selected_revisionは現在の完成文字列を決めたrevisionを表す。

サーバー状態

状態は少なくとも次を保持する。

state_key
node_kind
input_text
input_status
error
accepted_text
revision
client_id
client_sequence

• accepted_text=None と受理済み空文字 accepted_text="" を区別する。
• revisionは正常な候補テキストが変わった場合だけ増加する。
• incomplete/hard errorだけではrevisionを増加させない。
• クライアントごとの連番で古い更新と連番再利用を拒否する。
• 状態はメモリ内にあり、ComfyUI再起動で消える。
• 状態がなければQueueへ保存された候補テキストを使用する。

エラー分類

Soft incomplete

例: 波括弧の閉じ忘れ、余分な閉じ括弧。

• 新しい正常revisionとして受理しない。
• 直前のaccepted_textとrevisionを維持する。
• Hard Error状態は解除する。
• 実行は最後の正常候補集合で継続する。
• 正常候補が一度もなく、Queueフォールバックも不正なら実行エラー。
• UIは EDITING / SYNTAX INCOMPLETE と使用中revisionを表示する。

Hard error

例: 隣接する複数の直接子グループ、単独の !、上限超過。

• サーバーはHard Error状態を保存する。
• 最後の正常候補を黙って使用しない。
• 現在のchange_every保持期間中でも、次回実行をValueErrorで停止する。
• 正常な入力が受理されたらHard Errorを解除する。
• UIは HARD ERROR と理由を表示する。

フロントエンド同期

• 120ms debounce。
• 日本語IME変換中は送信しない。
• 1ノード内の送信は順番に処理する。
• UTF-8で512KiBを上限とする。
• Workflow複製で重複したstate_keyは再発行する。
• 入力内容は通常どおりWorkflowへ保存する。
• EDITING / SYNCING / LIVE / SYNC ERRORを表示する。
• サーバーに状態があれば、そのinput_textを初期表示へ復元する。
• Runtime textareaはDOMウィジェットの可変領域を使用し、ノードの高さ変更へ追従する。
• textareaは可変領域、同期状態フッターは固定領域として配置する。