# Zombie GC: 原子性・Domain 境界・instance maintenance 更新: 2026-09-14 ## 修正した問題 旧実装は全インスタンスの候補を transaction 外で取得し、その UUID の Revision/Object を無条件に削除していた。WAL reader の候補取得後に別 connection が Path/Asset/本文 Revision を追加すると、その変更を無視して削除できた。 また Domain 管理者の HTTP/config 操作が同じ global purge を呼び出していた。 ## 候補の定義 Object の作成時刻が指定した猶予期間より古く、次の全条件を満たすものに限定する。 - **すべての Domain** において Path と Asset 所有者の参照がない。 - Revision がない、または **全 Revision** の本文 bytes と Document hash が空である。 空 Document の SHA-256 は空として扱うが、非空の inline body を上書きしない。 NUL を含む本文も BLOB byte length で保護する。HEAD だけの判定は禁止する。 - `revision_document_refs`、City の明示ページ参照・Street inbox・ページ配置 override、 exact Object capability grant、未期限切れの連携エディタ ticket/session がない。 後半の参照は保守的に保護する。Path だけ消しても、意味的に保持している空ページや 編集中のページを自動削除しない。期限切れ editor session の bookkeeping は削除時に清掃する。 ## 権限境界 | 呼び出し元 | 範囲 | | --- | --- | | `GET /_/api/v1/gc/zombies/list` | current Domain の作成 provenance がある候補のみ | | `POST /_/api/v1/gc/zombies/purge` | current Domain の作成 provenance がある候補のみ | | 設定画面の一覧・`section=zombie-purge` | 同じ Domain 制約 | | ローカルの trusted CLI/store maintenance | インスタンス全体 | | ビルトイン 6 時間周期 GC worker | インスタンス全体 | HTTP 呼び出しは `object_origins(object_uuid, domain_uuid)` が current Domain に一致する ことを必須とする。クエリ・フォームの `domain_uuid` で切り替えない。Campus 管理者でも HTTP から global maintenance に昇格しない。legacy/作成元不明 Object は一覧にも出さず、 HTTP から削除しない。参照がないこと自体を所有権の証拠にはしない。 `CreateObjectInDomain` が記録した provenance を利用する。作成元を記録していない 既存データや旧作成経路を、現在の default Domain に推測で backfill してはならない。 こうしたデータの整理は trusted instance maintenance の範囲とする。 現在 `runEvent` に global GC の event type は登録しない。HTTP から任意の event type を保存・手動起動しても、`gc.purge` 等は worker で unknown type として失敗し、削除しない。 将来 GC を scheduler に統合する場合、サーバー内部だけが設定できる trusted origin と、 Domain provenance を持つ手動 payload の区別を先に設計する必要がある。 ## 書き込み原子性と上限 `BeginTx(ctx)` の直後、`zombie_gc_maintenance` の一行を UPDATE し、SQLite の writer lock を取得してから候補を選ぶ。同じ write transaction 内で UUID ごとに全条件と provenance を 再検証し、関連 bookkeeping/Revision/Object を削除する。候補抽出から commit まで他 connection の書き込みが入らない。失敗・キャンセル時にはバッチ全体を rollback し、成功件数を返さない。 Domain 一覧は indexed `object_origins(domain_uuid, object_uuid)` から検索を開始する。 他 Domain の全 Object を走査しない。候補上限は SQL `LIMIT` に置き、Go の後処理 slice で制限してはならない。各参照検索には Object/Page UUID の lookup index を用意する。 - HTTP/config の既定バッチ: 100 件。 - 最大: 1,000 件。HTTP の `limit=0`・負数・最大値超過は 400。 - trusted store の旧 `limit=0` は無制限にせず既定 100 件とする。 - trusted 一覧も最大 1,000 件。継続する purge はローカルから明示的に繰り返す。 - 検索・削除の context は最長 5 秒。HTTP は request context のキャンセルを継承する。 - SQLite writer の待機も既存 busy timeout の 5 秒内。重い history の走査が期限に 達したときは、不完全な候補判定で削除せず失敗する。 Foreign key enforcement が無効な legacy connection でも整合性を保つよう、 `object_origins` 等は明示的に清掃する。Revision の検索 index は既存の transaction 内 trigger で追従する。CAS 本体のファイル削除はこの GC では行わない。 `BindPathInDomain` と Revision の INSERT も、同じ書き込み SQL に `WHERE EXISTS(SELECT ... FROM objects)` と `RowsAffected` の検証を置く。 GC が先に commit した場合は `ErrPageNotFound` または安全な書き込み競合失敗となり、 orphan Path/Revision を作らない。失敗した bind は既存 Path を置換しない。 `PutAsset` は新規 Object と Asset を同じ transaction で作成しており、別途変更は不要。 ## global worker の猶予期間 既定の **24 時間** と **6 時間ごとの実行** は維持する。今回の変更によって従来より 短い猶予へ移行させない。 起動時に、従来の default Domain の `zombie_grace_hours`、24 時間、永続保持済み値、 operator 環境変数 `PAGESWIKI_ZOMBIE_GC_GRACE_HOURS` の最大値を採用し、 `zombie_gc_maintenance.grace_seconds` に high-water mark として保存する。 Domain の UI 設定がその後短縮されても、再起動しても、この値は小さくならない。 Domain の設定は Domain 内の手動 purge に適用され、稼働中の global worker は変更しない。 より長い operator 環境設定は再起動時に継承できる。短縮のための HTTP/API は提供しない。 従来設定の読み込み失敗・不正な operator 環境設定では global worker を停止しログに残す。 時間から秒への整数 overflow で削除が早まることも防止する。 ## 回帰テスト - WAL の別 connection が Path・Asset・非空 Revision を未 commit のまま追加し、 GC を開始した後で commit しても Object が保持される。 - 作成元が foreign/unknown の Object は管理画面/API から見えず、削除できない。 - 他 Domain の Path/Asset、過去 Revision、NUL bytes、CAS hash、明示参照を保持する。 - 既定/最大/不正 limit、キャンセル、途中 SQL failure の完全 rollback。 - GC の commit 後の bind・Revision 保存は孤立データを作らない。Revision は テスト専用 SQLite view/scalar による制御で、存在確認直後の削除を時刻依存なく再現する。 - 手動 event の偽装 type から global GC を実行できない。 - 長い従来設定、Domain 設定変更、再起動、operator 設定、整数 overflow、設定 read failure。