fable-loop

Fable Loop

繰り返しによって新しい状態が判明する場合に限り、明確な終了条件、バックオフ、エラー分類を設け、ループが停止した理由を曖昧さなく示してチェックを繰り返します。

ミッション

ポーリングとは、「成功するまで同じコマンドを実行し続ける」ことではありません。適切なループでは、変化する外部条件をモデル化し、保留中と失敗を区別し、レートやコストの予算を守り、成功、終端失敗、キャンセル、または予算の超過時に終了します。

繰り返し実行しても新しい情報が得られない場合、そのタスクに必要なのはループではなく診断です。

次の場合に有効化

• CI／デプロイ／ビルド／バッチジョブの状態変化を待つ場合。
• 範囲が限定された非同期処理を監視する場合。
• 結果整合性のある外部状態をチェックする場合。
• 既知のプロセスが進行している間、安全な測定を繰り返す場合。
• 繰り返し自体が測定となる、有限の安定性サンプリングを実行する場合。

次の場合は有効化しない

• コマンド／プローブを 1 回実行すれば十分な場合（fable-run／fable-verify）。
• 外部状態が変化していないのに、同じ決定論的な失敗が繰り返されている場合（fable-recover）。
• ユーザーが、セッション内の範囲が限定されたループではなく、将来の通知やスケジュール済みタスクを期待している場合。
• ポーリングによって、冪等でない副作用が繰り返し発生する場合。
• 終了条件や予算を定義できない場合。

ループの分類

ループの種類	成功／終端の意味
CI／ビルド	保留中 → 成功または終端失敗／キャンセル
デプロイ	進行中 → 正常／ロールバック済み／失敗
バッチジョブ	キュー待ち／実行中 → 完了／失敗
結果整合性	古い状態 → 期限内に期待される状態
レート制限付き API	保留中／再試行可能 → 成功または終端の認証／スキーマエラー
安定性サンプリング	範囲が限定された N 回の観測 → 分布／分散の判定

プロトコル

ステージ 1 — 状態機械を定義する

反復を始める前に、次を列挙します。

• 成功状態。
• 保留中／再試行可能な状態。
• 終端失敗状態。
• 不正な状態／不明な状態。
• キャンセル条件。

成功以外のすべてを「再試行」と扱うループは安全ではありません。

ステージ 2 — 予算を設定する

少なくとも次を定義します。

• 経過時間の上限／期限。
• 該当する場合は、反復回数またはリクエスト数の上限。
• 初期間隔／バックオフ方針。
• 最大間隔。
• API／コスト／レートの制約。

複数の上限が適用される場合は、より厳しい方を適用します。

ステージ 3 — 冪等性と副作用を確認する

ポーリング操作は読み取り専用または冪等である必要があります。エンドポイント／コマンドが処理を開始する場合は、処理の開始と状態の観測を分離し、再試行によって処理が重複しないようにしてください。

ステージ 4 — 反復を 1 回実行し、結果を分類する

次を記録します。

• 反復回数／時刻。
• 観測した状態／値。
• トランスポート／コマンドの結果。
• 分類：成功／保留中／再試行可能なエラー／終端失敗／不明。
• 次の待機時間／理由。

ステージ 5 — 状況に応じてバックオフを適用する

予想される更新間隔が既知で、コストも低い場合は固定間隔を使います。レート制限や一時的なサービスエラーが問題となる場合は、指数バックオフとジッターを使います。

該当する場合は、明示された Retry-After／プロバイダーの指示に従います。ツールで実行できるからといって、応答の遅い外部ジョブに対して 1 秒未満の間隔で過度に呼び出さないでください。

ステージ 6 — 終端情報が得られたら早期に停止する

次の場合は直ちに終了します。

• 成功。
• 明示的な失敗／キャンセル状態。
• 再試行できない認証／スキーマ／権限エラー。
• ユーザーによるキャンセル。
• 予算／期限の超過。

結果がすでに判明している場合、残りの反復を消費しないでください。

ステージ 7 — 進展がない状態を検出する

状態に進捗／バージョン／タイムスタンプが含まれる場合は、反復ごとに比較します。SLA の想定時間の前後に状態が長時間変わらない場合、それは予算を自動的に延長する理由ではなく、診断の手がかりとなる可能性があります。

ステージ 8 — 正確な実行記録を提示する

最終的な実行記録には、停止理由、経過時間、反復回数、最後の状態、一時的なエラー、条件が実際に満たされたかどうかを含めます。

タイムアウトは成功ではありません。「まだ実行中」であることは、仕様や期限で失敗と定められていない限り、失敗ではありません。

判断ルール

• 外部状態が変化しないまま同じ失敗が確定的に繰り返される場合は、ループを停止して復旧します。
• 再試行可能な通信エラーの場合は予算内で続行できますが、認証／権限／スキーマエラーは通常、設定が変更されるまで終了します。
• 該当する場合、プロバイダーの Retry-After またはジョブが推奨するポーリング間隔を下限として扱います。
• ステータスポーリングとして、べき等でないトリガーを繰り返してはいけません。
• 各反復で無視できない費用やクォータが発生する場合は、時間だけでなく費用／リクエストの予算も設定します。
• 完了予定が現在のセッション／タスクの実行モデルを超える場合、セッション内のループが無期限に実行できるかのように扱わず、利用可能であればスケジュールまたは条件監視の仕組みを作成します。
• ループは INCOMPLETE/TIMEOUT で終了する場合があります。成功を得るために、上限を黙って延長してはいけません。
• 進捗に変化がなく、期限までまだ時間がある場合は、ポリシーに従って続行し、ユーザーへの不要な更新は控えます。長時間の対話型実行では、意味のある状態変化のみを伝えます。

不変条件

• ループを開始する前に、終了条件と予算を明示します。
• 各反復は安全かつべき等であるか、副作用のセマンティクスが明示的に制御されている必要があります。
• 終端エラーが発生したら、直ちに停止します。
• 保留状態と失敗状態は区別します。
• バックオフ／レート制限を遵守します。
• 結果記録には実際の停止理由を記録し、タイムアウトを成功に変換しません。

障害の分類

無限／暗黙のループ

強制可能な予算がありません。拒否して上限を定義します。

すべてのエラーを再試行

認証／スキーマ／権限エラーや終端ジョブエラーを一時的なものとして扱っています。適切に分類して停止します。

副作用の重複

ポーリング呼び出しが作業を再トリガーします。ステータス用エンドポイント／冪等性キーを分けるか、停止します。

ポーリング集中

間隔がサービス／ジョブの処理間隔に対して短すぎます。バックオフし、プロバイダーの指示を尊重します。

タイムアウトの誤診

ジョブは想定 SLA 内で保留中なのに、ループが異常と判断します。タイムアウト／未完了は製品の失敗とは分けて報告します。

進捗の停滞

進捗があるべき状況で状態が変化しません。無期限に延長するのではなく、復旧／運用の診断に引き継ぎます。

セッションの不整合

要求された監視が利用可能な実行時間を超えています。対応している場合は、スケジュール／条件監視機能を使用します。

アンチパターン

• 裸の while true／上限のないスリープループ。
• すべてのエラークラスを再試行する。
• ジョブを繰り返し再送信してポーリングする。
• 失敗するたびに、成功するまでタイムアウトを延長する。
• 10 分のデプロイに対して 1 秒間隔でポーリングする。
• ステータスが保留中というだけで失敗と宣言する。
• ループが正常に終了したというだけで成功と宣言する。
• 最終結果記録で一時的なエラーを隠す。
• 確定的に繰り返される失敗の診断を避けるためにループを使用する。

ループ結果記録

Condition/state machine:
Success / terminal failure states:
Time + iteration/request budgets:
Interval/backoff policy:
Idempotency/side-effect check:
Iterations: time → observed state → classification
Transient errors:
Stop reason:
Condition satisfied? yes/no
Final state:
Next action if incomplete/failed:

完了条件

ループは、次の条件を満たすと完了します。

• ステートマシン、成功／失敗のセマンティクス、予算が明示されている。
• ポーリングがべき等性／レート／費用の制約を遵守している。
• 終端情報が得られた時点でループを早期停止している。
• タイムアウト／停滞状態を正確に表している。
• 最終結果記録に、ループが終了した理由と次に行うべきことが正確に示されている。

段階的なリソース

• 詳細ガイド：references/polling-state-machines-and-backoff.md
• 既存のガイドライン：references/loop-control-guidelines.md
• 例：examples/poll-build-job.md