# 共通outbox:購読・移行・復旧契約 更新日:2026-09-25。単一インスタンスのSQLiteと既存イベントキューでの初期実装です。タスクの期限日/計画日通知は[正本と同時に作る予約](task-reminders.md)から配信します。outbox購読による汎用変更通知、分散配送、outboxの自動削除は未実装です。 ## 責務を分ける | 要素 | 役割 | | --- | --- | | `activity_outbox` | 正本変更と同時に保存する小さなイベント。Domain-local sequence、UUID、型、actor、対象、一意キー | | `activity_outbox_heads` | Domain・イベント型ごとの最新sequence。INSERT triggerで同じtransaction内に更新 | | `activity_outbox_checkpoints` | consumer・Domainごとの完了位置。成功後にのみ単調に進める | | `event_jobs` | 実際の実行・再試行・優先度・ログ・キャンセル。outboxの記録とは別 | `status`、`attempts`、`next_attempt_ms` 等のoutbox旧列は互換のため残しますが、consumer配信の完了や再試行判定には使いません。旧 `processed` 行も、新規consumerにとっては未処理になり得ます。`CompleteActivityOutboxThrough` は指定したconsumerのcheckpointのみ更新します。 ## 購読と負荷 `ActivitySubscription` のconsumer IDとevent type集合は信頼するworkerコードで定義します。HTTP入力から任意の購読を生成しません。現在のCity購読は `page.created`、`revision.created`、`path.renamed`、`path.unlinked`、`object.deleted` です。タスク変更や無関係の拡張イベントだけではCityジョブを作りません。 未処理Domainの発見はheadsとcheckpointの比較で行い、全イベント履歴を毎回検索しません。1回最大100 Domain。イベント取得は型ごとにsequence索引から上限件数を取り、その結果をマージします。1回の最終結果は最大500件、型は最大16種類です。無関係のイベントが大量に入っても、対象イベントの手前を何ページも読み飛ばしません。 同じconsumer IDのまま購読型を増やすと、checkpointより古い新購読型のイベントを取り逃がします。**購読集合の変更時は新しいconsumer IDを使う**ことを契約とします(例:`notifications.tasks.v2`)。再生の開始位置・過去通知の抑止を別途指定します。 Cityは取得した対象イベントの最終sequenceまで、再構成成功後にcheckpointを進めます。並行して追加された後続イベントは次回に残ります。再構成後・checkpoint保存前の停止は再実行になりますが、既存の冪等な再構成で回復します。途中で失敗したbatchの一部だけを成功扱いにしてはいけません。 ## タスクの直接接続と既存データ タスクhead・版・専用ジャーナル・共通outbox・headsを同じtransactionで保存します。どこか一つが失敗したらDBの変更は全体をrollbackします。CASファイルの孤立可能性は従来どおりで、未commitのheadには現れません。 タスクの一意キーはDomainにスコープされた `organizer:{kind}:{uuid}:{version}`。payloadは版番号と変更時刻のみです。作成の再送、旧記録の再生、ジョブ再試行で二重記録しません。 `organizer_activity_bridge` は専用ジャーナルの移行位置です。`task.activity.publish` は1回100件、3秒timeout、既定60秒間隔・priority -5。処理したイベントと移行位置を同時commitします。失敗時は位置を進めません。対象が欠損して種類を判定できない場合はエラー停止し、黙ってスキップしません。タスクの物理削除導入時にはtombstoneを追加する必要があります。 この移行ジョブは拡張のユーザー操作を実行するものではなく、保存済み変更記録の内部保全です。拡張の無効化とは別に、イベント定義のenabledをOFFにできます。既存enabled・intervalの設定は起動時に保持します。`/_/api/v1/event/run` からも既存の管理権限で手動実行できます。ログは件数のみで、個人タスクのタイトルや本文は出しません。 ## アップグレードと保全 初回のみ旧outboxを集計してheadsを作成します。この移行と完了マーカーはtransaction内で行い、途中失敗は再実行できます。次回以降の起動で履歴全件を再集計しません。既存checkpointと旧processed行は保持します。 新しいsequenceの採番は保持されたheadsの最大値から行います。将来の履歴整理でsequenceが巻き戻らないための対策ですが、**outboxの自動削除機能を提供するものではありません**。削除可能範囲には全必須consumerの完了確認に加えて、一意キーの再送抑止用tombstoneが必要です。heads・checkpoint・移行位置・正本DBをまとめてバックアップします。 ## 残タスク - [x] タスクの期限日/計画日通知:正本transactionで予約を更新し、配信時に現在権限・版を再検査。旧outboxイベントから予約を復活させない。 - [ ] 汎用の変更通知consumerと購読設定。 - [ ] consumer別の未処理/失敗表示、再生操作、購読変更時のbootstrap。 - [ ] 多数の失敗Domainがある場合の公平なdispatch、consumer別backoff/dead-letter。 - [ ] Outbox保持ポリシー:必須購読者の進捗、sequenceと一意キーの保全、consumer廃止手続き。 - [ ] 分散lease/fencing。現時点でHA時のexactly-onceを保証しない。 ## テスト 購読者間の独立、型での絞り込み、ページング、旧processed行の取得、初回移行/再起動、transaction rollback、無関係イベント1200件の中の対象取得、sequence巻き戻り防止を検証します。サーバー側では、タスク変更でCityジョブが作られないこと、ページ変更では作られること、タスク保存全体のrollback、移行の再開/重複抑止、管理者の停止・間隔設定保持を検証します。運用DB・外部カレンダーは使用しません。