feat(worker): unprocessed-event retention via DO alarm sweep + document retention in READMEs #236

purpose / 目的

未処理 webhook イベントの保持上限を導入し, DO ストレージ肥大の唯一残った無限増加経路を塞ぐ. あわせて retention 仕様 (処理済み 7 日 / 未処理 90 日) をユーザー向け README (root + NPM 公開パッケージ) に明記する.

premise / 前提

• feat(worker): auto-purge processed events on mark_processed in WebhookStore DO #235 (merged) で処理済みイベントの auto-purge を導入済み: mark_processed 時, processed=1 かつ received_at が PURGE_AFTER_DAYS 日 (既定 7) より古いものを削除.
• 未処理イベント (processed=0) は age に関わらず一切削除されない (feat: purge processed events from events.json #29 の安全側設計: 未読 = ユーザー未確認, 黙って捨てない).
• fix(worker): windowed per-tenant quota + restore #230 (end webhook 429 lockout) #233 で quota は「1 時間あたりのスループット制限」に変更された (tenant.ts: window 1h で events_stored リセット). quota は保存量を縛らず流入レートのみ縛る.
• 結論: 未処理イベントが現状で唯一の無制限ストレージ増加経路. アプリ側の上限が無く, Cloudflare の 1GB/DO ハード壁 (到達で書き込み失敗 = 新規イベント取りこぼし) まで素通り.

design / 設計方針

• 未処理 purge: processed=0 かつ received_at が UNPROCESSED_PURGE_AFTER_DAYS 日 (既定 90) より古いイベントを削除. 既定を長く取るのは未読データ消失の安全域だから (処理済み 7 日との非対称は意図的).
• トリガ: mark_processed のみに依存しないこと. 「消費されない = 未処理が溜まる」放置テナントでは mark_processed が呼ばれず, 掃除が一番要る相手に手が届かない. DO Alarms (ctx.storage.setAlarm + alarm() ハンドラ) で消費ゼロでも走る時間駆動 sweep を実装する. sweep は期限超過の処理済み (>7 日) と未処理 (>90 日) の両方をまとめて掃除し, alarm() 内で次回を再スケジュールして周期実行する (例: 日次).
• 既存の mark_processed 時 purge は即時性のため残してよいが, 本質的な保証は Alarms sweep が担う.
• 既知の限界 (スコープ外): 時間窓は「古さ」を縛るが「量」は縛らない. 高頻度 x 無消費テナントは 90 日窓があっても 1GB 壁に先に到達しうる. 量ベースの hard cap (最新 N 件 / 最大 M バイト) は別 issue 候補として記録のみ.
• DO Alarms が現プランで制約/不可の場合: それを surface した上で mark_processed トリガにフォールバックし, 放置テナントの限界を docs に明記する (ブロックしない).

constraints / 制約

• 新規 env UNPROCESSED_PURGE_AFTER_DAYS (既定 90) を worker/wrangler.toml [vars] に追加. 既存 PURGE_AFTER_DAYS (処理済み, 7) は just-shipped のため改名せずそのまま.
• docs/0-requirements.md と docs/0-requirements.ja.md に未処理 retention と Alarms sweep を反映 (同一 PR, docs 分割禁止).
• README 二枚に retention 仕様を明記:
  • README.md (リポジトリ root)
  • mcp-server/README.md (NPM 公開パッケージ github-webhook-mcp の README)
  • 内容: 処理済み 7 日 (PURGE_AFTER_DAYS) / 未処理 90 日 (UNPROCESSED_PURGE_AFTER_DAYS) / Alarms による自動 sweep / 既定値と env 可変であること.
  • NOTE: local-mcp/ は private (未公開) のため README 更新対象外.
• テスト: 未処理 >90 日が sweep で削除 / 未処理 <90 日は残る / 処理済み >7 日が sweep で削除 / alarm が再スケジュールされる, を検証.

scope out / スコープ外

• 量ベースの hard cap (最新 N 件 / 最大 M バイト). 別 issue 候補.
• TenantRegistry quota の decrement 連動 (feat(worker): re-port auto-purge of processed events to WebhookStore DO #234 から継続して別軸).

target files / 対象ファイル

• worker/src/store.ts
• worker/wrangler.toml
• worker/test/workers/store.test.ts
• docs/0-requirements.md, docs/0-requirements.ja.md
• README.md
• mcp-server/README.md

completion conditions / 完了条件

• 未処理イベントは received_at が UNPROCESSED_PURGE_AFTER_DAYS 日 (既定 90) を超えると削除される
• DO Alarms による sweep が消費ゼロでも周期実行される (処理済み >7 日 + 未処理 >90 日 をまとめて掃除)
• 90 日以内の未処理は残る (テストで検証)
• env UNPROCESSED_PURGE_AFTER_DAYS で可変 (既定 90)
• docs/0-requirements.md (.ja 含む) に反映
• root README.md と mcp-server/README.md に retention 仕様 (処理済み 7 日 / 未処理 90 日 / Alarms sweep / env) が明記される
• 全テスト green

Refs #234 #235 #233 #29