0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

手動cron再開なしで復旧するRecovery Dispatcher設計

0
Posted at

手動cron再開なしで公開処理を復旧するDispatcher

公開照合、再試行、後続再計画、自動復帰のRecovery Loop

はじめに

自動投稿の失敗時にexit 1で止め、Discordへ通知するだけでは復旧ではありません。担当者が認証を直してもcronはdisableのまま、未公開原稿は古くなり、次の時間帯の処理も巻き込まれます。翌朝、誰かが手動実行して初めて戻る仕組みは自動化の途中です。

復旧ループには、公開済み照合、重複防止、安全な再試行、後続処理の継続または繰下げ、復旧通知が必要です。認証失効のようにその場で直せない原因でも、該当writeだけを待機させ、read-only probeを続ければ、有効な認証へ戻った時に自動復帰できます。

ここではRecovery Dispatcherを通常cronから分離せず、同じ状態機械の一部として実装します。Python例、Receipt schema、dry-run、テストを順に見ます。

停止ではなく状態遷移を記録する

復旧対象を単なる失敗ログにせず、次に何をすべきかを持つrecordへ変換します。

from dataclasses import dataclass
from typing import Literal

RecoveryState = Literal[
    "needs_reconcile", "waiting_probe", "ready_retry",
    "verifying", "recovered", "manual_action"
]

@dataclass(frozen=True)
class RecoveryItem:
    recovery_id: str
    route_id: str
    payload_hash: str
    planned_at: str
    state: RecoveryState
    attempt: int
    next_check_at: str
    external_id: str | None
    reason: str

payload_hashは再試行時に本文が差し替わっていないことを確認する鍵です。external_idがなくても、外部write開始後ならneeds_reconcileから始めます。timeoutを未実行と決めつけて新規writeすると、外部側だけ成功していた場合に二重投稿になります。

RecoveryItemにはsecret本文を含めません。route_idから承認済みのcredential referenceを解決し、実行直前にaccount identityを確認します。

公開済み照合を最初に行う

再試行より先に、予定時刻、author、本文hash、親子関係などで公開済みeffectを探します。見つかれば新しいwriteは不要です。

def reconcile(item, adapter):
    candidates = adapter.list_recent(
        route_id=item.route_id,
        since=item.planned_at,
        read_only=True,
    )
    matches = [x for x in candidates if x.payload_hash == item.payload_hash]
    if len(matches) == 1:
        return transition(item, "verifying", external_id=matches[0].id,
                          reason="existing_effect_found")
    if len(matches) > 1:
        return transition(item, "manual_action", reason="duplicate_effects_found")
    return transition(item, "waiting_probe", reason="effect_not_found")

照合対象が多すぎる場合は、route/account、狭い時刻窓、payload hashで絞ります。単に本文先頭20文字が同じという一致は危険です。外部サービスが本文を正規化する場合は、公開前とreadback後で同じcanonicalize関数を使ってhashを計算します。

既存effectが見つかった時も即recoveredにせず、公開URL、author、本文、画像、親IDをverifyします。必要条件が一つでも欠ければ、成功Receiptを作りません。

probeとwriteを分ける

認証失効中に毎分writeを繰り返すと、account lockやRate Limitを悪化させます。軽量なread-only probeで回復を観測し、writeは状態がready_retryになった時だけ許可します。

def dispatch(item, adapter, now):
    if now < parse_time(item.next_check_at):
        return item
    if item.state == "needs_reconcile":
        return reconcile(item, adapter)
    if item.state == "waiting_probe":
        probe = adapter.probe_identity(item.route_id, read_only=True)
        if not probe.ok:
            return reschedule(item, backoff(item.attempt), probe.reason)
        if probe.account != expected_account(item.route_id):
            return transition(item, "manual_action", reason="account_mismatch")
        return transition(item, "ready_retry", reason="probe_recovered")
    if item.state == "ready_retry":
        return execute_retry(item, adapter)
    if item.state == "verifying":
        return verify_effect(item, adapter)
    return item

probeの成功は「アクセスできた」だけでなく、期待accountと必要権限の一致まで含めます。別accountでログインできた状態は回復ではありません。unknownなprobe結果はfail-closedし、writeへ進めません。

再試行に期限とbudgetを持たせる

すべてのpayloadを後日公開すればよいわけではありません。速報、朝の挨拶、キャンペーン期限など、鮮度を失ったpayloadがあります。Recovery Dispatcherはexpires_atとattempt budgetを検査します。

function retryDecision(item: RecoveryItem, now: Date): RetryDecision {
  if (now >= new Date(item.expiresAt)) {
    return { action: "drop", reason: "payload_expired" };
  }
  if (item.attempt >= item.maxAttempts) {
    return { action: "manual", reason: "retry_budget_exhausted" };
  }
  if (!item.approvalValid || item.currentHash !== item.approvedHash) {
    return { action: "hold", reason: "approval_or_hash_changed" };
  }
  return { action: "retry", reason: "within_budget" };
}

再試行前には公開台帳をもう一度照合し、分散lockを取ります。最初の実行と復旧実行が同時に走っても、同一route_id + payload_hashのwriteは一件に収束させます。attempt数はwriteを始める直前にatomicに確保し、プロセス終了で巻き戻しません。

後続枠を再計画する

失敗分を今すぐ出すと、次の予約投稿と衝突する場合があります。後続処理を全停止するのではなく、cadenceを守って再配置します。

def replan(queue, recovered_item, now):
    next_slot = cadence.next_available_after(now)
    if recovered_item.expires_at <= next_slot:
        return mark_dropped(recovered_item, "no_fresh_slot")
    queue.reserve(next_slot, recovered_item.id)
    for item in queue.after(next_slot):
        if cadence.distance(item.slot, previous_slot(item, queue)) < cadence.minimum:
            queue.move(item.id, cadence.next_available_after(item.slot))
    return queue

公開頻度が一日一件なら、復旧した二件を連続放出しません。期限切れをdropし、次に鮮度があるものを一枠だけ予約します。後続のブログ生成やread-only分析は、write障害と独立していれば継続します。

再計画結果もReceiptへ残し、recovered_now、rescheduled、dropped_expiredを区別します。「復旧したので全部成功」という雑な集約を避けます。

atomic Receiptと通知を組み合わせる

各遷移をJSONLのeventとしてappendし、latest stateは一時ファイルからrenameします。通知が失敗しても状態を失わないよう、保存を先に行います。

{
  "schema": "recovery-event/v1",
  "recovery_id": "rcv_20260722_001",
  "route_id": "agent_memories_x",
  "from": "waiting_probe",
  "to": "ready_retry",
  "reason": "identity_and_permission_restored",
  "payload_hash": "sha256:...",
  "external_effect_count": 0,
  "recorded_at": "2026-07-22T02:00:00Z"
}

通知はwaiting_probeが続くたびに送らず、初回障害、manual action化、recoveredの遷移に限定します。復旧通知には公開URLとreadback項目、繰り下げた後続枠を含めます。

失敗を注入して自動復帰をテストする

テストでは、人がcronをenableし直さなくても回復することを確認します。

def test_auth_recovers_without_manual_cron_restart(fake_adapter, clock):
    item = recovery_item(state="waiting_probe", attempt=1)
    fake_adapter.probe_results = [AuthError(), Probe(ok=True, account="agentmemories")]

    first = dispatch(item, fake_adapter, clock.now())
    assert first.state == "waiting_probe"
    assert fake_adapter.write_count == 0

    clock.advance(minutes=30)
    second = dispatch(first, fake_adapter, clock.now())
    assert second.state == "ready_retry"

    third = dispatch(second, fake_adapter, clock.now())
    assert third.state == "verifying"
    assert fake_adapter.write_count == 1

さらに「timeoutだが外部側は成功」「同一payloadを二つのworkerが処理」「probeが別accountを返す」「approval hashが変わる」「期限切れ」「readback不一致」を負試験にします。dry-runでは状態遷移と再計画だけを出し、external write countが0であることをassertします。

最終的な完了条件は、公開済み照合、write最大1回、readback一致、後続cadence維持、recovered Receipt、通知遷移の6点です。

まとめ

Recovery Dispatcherは失敗を再実行するだけのretry workerではありません。外部effectの照合、read-only probe、hashと承認の再確認、期限とbudget、後続枠の再計画、readback、復旧通知を一つの状態機械にします。

これにより、自動解消できない認証切れでも対象writeだけを待機させ、正常な処理を続けられます。そして認証が戻れば手動cron再開なしで安全に復帰します。AIエージェントの記憶には、障害の説明だけでなく、現在state、次のprobe、再試行条件、完了証拠を残すことが重要です。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?