<a id="failure-and-recovery"></a>

# 障害とリカバリ

<!-- i18n: source=docs/architecture/failure-and-recovery.md blob=40f8e4b57e275dada1e2090b1f563fcdaafd8095 model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/failure-and-recovery.md)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/failure-and-recovery.md), which is authoritative.


プライマリへの書き込みとすべてのアクセス判定は、フェイルクローズで動作します。派生データとテレメトリはフェイルオープンで動作し、後から修復されます。成功を返したリクエストは、約束した内容を永続的に保存済みです。それと並んで投影されるデータは、ワーカーが追いつかせます。最後のセクション [容量](#capacity) では、何がどのようにスケールするか、そして限界がどこにあるかを説明します。症状別のランブックは [トラブルシューティング](/ja/operations/troubleshooting) にあります。

<a id="errors-retries-and-idempotency"></a>

## エラー、リトライ、冪等性

| 境界                 | 動作                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ClickHouse クライアント | 冪等なステートメントで一時的なネットワーク障害が起きた場合は、新しい接続で 1 回だけリトライします。レプリカに起因するサーバーエラー（コード 10、242、999）は、新しい接続で最大 2 回リトライします。それ以外は例外を送出します。                                                                                                                                                                                                                                                      |
| ステートメントのデッドライン | クラスごとのデッドライン（`LOOM_CH_TIMEOUT_READ_S`、`_WRITE_S`、`_DDL_S`）を超えると、リクエストは 504 `BACKEND_TIMEOUT` で失敗し、リトライされません。                                                                                                                                                                                                                                                                   |
| プールへの受け入れ   | `LOOM_CH_POOL_WAIT_MS` 以内に空きスロットがない場合は、`Retry-After: 1` を付けた 503 `OVERLOADED` を返します。                                                                                                                                                                                                                                                                                                 |
| INSERT               | リトライされる INSERT は同じ `insert_deduplication_token` を持つため、コミット済みのバッチが二重に書き込まれることはありません。トークンがない INSERT はリトライされません。バッチ INSERT は、同じテーブルへの同時 INSERT と ClickHouse のフラッシュを共有します。フラッシュ全体が失敗すると、それに含まれるすべての INSERT が失敗し、各リトライはそれぞれ独自のトークンで 1 回だけ書き込まれます（[バッチ INSERT](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#batched-inserts)）。 |
| 未対応の設定         | 量子化コード読み取りの設定を拒否するレプリカがあると、クライアントはそのプロセスの間その設定を外してリトライします。                                                                                                                                                                                                                                                                                         |
| ポイント読み取り     | 呼び出し元自身の書き込み後の読み取りは逐次一貫性を使います。書き込み直後に見つからなかった場合は 1 回だけ再読み取りします（`LOOM_CH_READ_YOUR_WRITES`）。20 秒以内に書き込まれた名前空間に対する検索は、逐次一貫性で読み取ります。                                                                                                                                                                                               |
| スキーマの不整合     | 保留中のマイグレーションが作成するテーブルを指すステートメントは、503 `SCHEMA_PENDING` で拒否されます（後述）。                                                                                                                                                                                                                                                                                           |
| op の冪等性          | `idempotent` と宣言された op は `Idempotency-Key`（HTTP）または `_idempotency_key`（MCP）を受け付けます。応答は組織、サブジェクト、op、キーをキーとして `loom.idempotency` に 24 時間保持されます。最初のリクエストの実行中に重複が来た場合は 409 を返します。                                                                                                                                                                       |
| プライマリ書き込み   | ファクト行とそのベクトル行は、コミットを待つ INSERT です。失敗した場合はリクエストが失敗します。                                                                                                                                                                                                                                                                                                         |
| Postgres オーソリティ | `LOOM_STORAGE_AUTHORITY=postgres` の場合、書き込みとは Postgres のコミットを指します。対応する ClickHouse の行はそこから発行され、`pg_delivery` ワーカーが修復します。Postgres が停止すると、書き込みとポイント読み取りは拒否されます（503 `POSTGRES_UNAVAILABLE`）（[ストレージオーソリティ](/ja/architecture/storage-authority#failure)）。                                                                                                   |
| プロジェクション     | グラフ、チャンク、エビデンス、置き換え（supersession）のサイドテーブルは、失敗しても処理を継続し（fail open）、ワーカーが修復します。                                                                                                                                                                                                                                                                         |
| テレメトリ           | `agent_events` とイベントストリームはプロセス内でキューイングされます。`agent_events` のフラッシュはバッチ INSERT、イベントストリームのフラッシュはコミット済み INSERT です。どちらもリクエストを失敗させませんが、クラッシュするとフラッシュ前のキューが失われる可能性があります。                                                                                                                                                                                     |
| ワーカー             | 失敗したパスはバックオフを伴ってリトライされます。作業は絶対値または新しいバージョンとして書き込まれるため、パスを繰り返しても同じ結果に収束します。                                                                                                                                                                                                                                                                           |
| 消去                 | `erasure.request` はチェックポイント付きのサーガです。`erasure_recovery` がこれを再開し、全テーブルに対する残存データの調査で成否を判定します。                                                                                                                                                                                                                                                                     |

**リトライ可能な応答。** `OVERLOADED`、`AUTH_UNAVAILABLE`、`RATE_LIMITED` には `Retry-After`（および `retry_after_s`）が付きます。ヒントに従ってリトライしてください。`SCHEMA_PENDING` は、オペレーターが指定されたマイグレーションを適用すると解消されます。`EMBED_TIMEOUT` については、生の HTTP または MCP の呼び出し元は 1 回リトライします。SDK の呼び出し元は（冪等な op では）すでにリトライ済みのため、バックオフしてください。`BACKEND_TIMEOUT` がリトライ可能なのは `idempotent` な op の場合のみで、書き込みでは冪等性キーを付けます。完全な一覧は[エラーリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/errors.md)を参照してください。

**冪等性キャッシュがベストエフォートである理由：** クラスター全体で一貫したキャッシュには、リクエストごとのロックが必要になります。このキャッシュを使う op は、重複実行時に同じ内容を `ReplacingMergeTree` に書き込むため、競合が起きてもハンドラーが 2 回実行されるだけで、効果が 2 回生じることはありません。繰り返すと効果が倍になる op（`memory.set_from_messages`）は非冪等であり、このキャッシュを使いません。

<a id="consistency-boundaries"></a>

## 整合性の境界

テーブルをまたぐ書き込みはトランザクションではありません。ファクトとそのベクトルは一緒に書き込まれ、派生データは後から追いつきます。

| 派生データ | 追いつくタイミング |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BM25 統計 | リフレッシュ可能ビューが 1 分ごとに更新します。検索はライブテールを読み取るため、ランキングは正確なままです（`LOOM_MEMORY_SEARCH_BM25_LIVE_TAIL`）。 |
| 使用回数カウンタ、強化 | 1 回の `usage_fold` パス（300 秒ごと）。 |
| エンティティグラフ射影 | レスポンスの直後。レスポンスの後に開始された同じ名前空間の `facts.traverse` は、デプロイメントのすべてのプロセスで、その射影を（最大 3 秒）待ちます。実行中の各射影は `loom.graph_projections` に記録され（サーバーに Keeper がある場合は Keeper のキー）、射影の終了時には、サーバーのクロックで、その記録を消す前に名前空間のグラフ書き込みを記録します。射影の途中で終了したプロセスの記録は最大 15 秒残ります。各プロセスはそれを一度だけ待ち（3 秒）、記録が古くなるまで、その名前空間のウォークは常に最新の状態を読み取り、メモからの提供もメモへの保存も行いません。1 つの名前空間で同時に 32 を超える射影がある場合、超過分は待たれません。それぞれが、`memory.set` が応答する前と射影の終了時に、グラフ書き込みとして数えられます。 |

**トランザクションを使わない理由：** ClickHouse にはテーブルをまたぐトランザクションがなく、それをエミュレートすると、すべての書き込みにラウンドトリップと障害モードが 1 つずつ加わります。永続的なプライマリのペアと冪等な修復により、書き込みは 1 回のラウンドトリップで済みます。

<a id="backpressure"></a>

## バックプレッシャー

共有リソースを無期限に待つリクエストはありません。

- **ClickHouse プール：** 待機時間に上限があり、超えると `OVERLOADED` を返します（[ClickHouse クライアント](#clickhouse-client)）。
- **ドキュメントバケット：** プロセスごとに転送 8 件とストリーム 4 件までで、それぞれ待機時間に上限があり（`LOOM_CH_POOL_WAIT_MS`）、超えると `OVERLOADED` を返します。一覧取得と削除（消去、スイープ）は、専用の 4 スロットのいずれかが空くまで待ちます。
- **レート制限：** `Retry-After` 付きの 429 `RATE_LIMITED` を返します。MCP では、トランスポートが短いヒント分（`LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S`）だけ一度待ち、再確認します。
- **クエリの埋め込み：** 1 回の試行につき `LOOM_MEMORY_SEARCH_EMBED_BOUND_S`（2.5 秒）で打ち切り、`LOOM_MEMORY_SEARCH_EMBED_BOUND_RETRIES` 回（1）再試行した後、503 `EMBED_TIMEOUT` を返します。
- **テレメトリキュー：** `agent_events` エミッタ（10,000 行）とイベントストリーム（20,000 行）は、満杯になると行を破棄してカウントします（`dropped_queue_full`、`dropped_flush_failed`）。最初の破棄と、その後 1000 回ごとにログを出力します。配信は最大 1 回です。
- **ワーカー：** `usage_fold` は、ClickHouse の未処理ミューテーションが多すぎる間はパスをスキップします。各パスはバッチサイズと期限で制限されます。
- **バジェット：** `budget_p99_ms` を超えた op も応答を返し、`budget.violated` 行を残します（op ごとに `LOOM_BUDGET_VIOLATION_AUDIT_INTERVAL_S`（60 秒）あたり最大 1 行）。

<a id="schema_pending"></a>

## `SCHEMA_PENDING`

スキーマより新しいコミットからビルドされたサーバー（`LOOM_BOOT_MIGRATE=false` のブランチサーバー、またはマイグレーションの適用前に起動したカラー）は、まだ存在しないテーブルを参照することがあります。`server/core/ch_schema_guard.py`（`guard_pending_schema`）は、そのようなステートメントをテーブル名とマイグレーション名を示した 503 `SCHEMA_PENDING` で拒否します。失敗した読み取りを任意として扱う検索レッグは、その読み取りなしで処理を続行し、台帳の行にはそのテーブルが記録されます。DDL が拒否されることはありません。

保留中のセットはマイグレーション台帳（`server/core/schema/status.py`）から取得され、プロセスごとに 60 秒間キャッシュされます。台帳が適用済みのファイルなしと報告した場合、または保留中のファイルが 25 を超える場合、ガードは警告を 1 回出力して待機状態になります。`/v1/health` は `schema.pending` を報告し、blue/green の切り替えはこれが空になるまで待機します。

<a id="worker-supervision"></a>

## ワーカーの監視

`server/workers/supervisor.py` は、有効な各ワーカーを個別の asyncio タスクとして実行します。

- **Stagger（スタガー）。** 最初のパスは `crc32(name) % interval` だけ待機します。ただし、出力テーブルが空のワーカーはただちに実行され、前回のパスが interval より古いワーカーは起動から 300 s 以内に開始されます。
- **Deadline（デッドライン）。** `min(4 × interval, 900 s)` を超えたパスは、60 s を下限として（ワーカーが独自に宣言する場合を除く）キャンセルされ、失敗として数えられます。
- **Backoff（バックオフ）。** 失敗したパスは `min(60 s, 2^(n-1) s)` だけ待機します。デッドラインで打ち切られたパス、および interval がデッドラインより長いワーカーの失敗したパスは、interval の間待機します。
- **Degraded（劣化）。** 3 回連続で失敗すると `DEGRADED` をログに出力します。連続失敗の回数は `loom.worker.consecutive_failures{worker}` で、一部のレッグが失敗したパスは `loom.worker.partial_failures` に計上されます。
- **Status（ステータス）。** 各パスは `loom.worker_status` の行を書き込みます（`GET /v1/admin/workers.status`）。再開カーソルにより、新しいデプロイメントインスタンスが長時間のスキャンを引き継げます。
- **Shutdown（シャットダウン）。** `stop_all` はタスクをキャンセルし、最大 10 s 待機してから、ステータス行をフラッシュします。

ワーカーの例外はそのタスク内にとどまります。ワーカーは絶対値または新しいバージョンを書き込むため、2 回実行されたパスも同じ結果に収束します。

<a id="repair-workers"></a>

## 修復ワーカー

| ワーカー                  | 修復対象                                                                                                                                                      | 保証                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `projection_repair`       | `loom.memory_projection_failures` に記録された、失敗したプロジェクション（エビデンスリンク、チャンク、グラフのサイドテーブル、有効期限スイープの検索ミラー）を再実行します。 | 未対応のエントリは調査用に残ります。                                                 |
| `entity_extractor`        | エンティティを持たない行にエンティティを抽出します。`entities` が `memory` と食い違う `memory_embeddings` 行を再出力します。                                    | 検索可能なすべての行が、最終的にそのエンティティを持ちます。                         |
| `orphan_vector_reconcile` | 対応するメモリが廃棄済みまたは存在しない埋め込み行とエンティティベクトル行を、猶予期間の後に廃棄します。                                                      | ファクトより長く残るベクトルはありません。                                           |
| `embedding_worker`        | `embedding_dim = 0` のスタブを新しいものから順に埋め込み、埋め込み行を持たないメモリも埋め込みます。古いモデルのスタブは再埋め込みします。                    | 5 回失敗した行には `embed_failed_at` が付き、スキップされます。                      |
| `erasure_recovery`        | `in_progress` または `failed` で止まっているサガを `steps_completed` から再開します。                                                                          | `max_attempts`（5）を超えると、終端の `failed` となり、`erasure.abandoned` の監査行が記録されます。 |
| `task_lease_sweep`        | 期限切れのリースを `todo` に戻します。試行回数を使い切った場合は `blocked` にします。保留中のタスクを再開します。                                             | クラッシュしたエージェントのタスクは失われません。                                   |
| `audit_verifier`          | 監査ハッシュを再計算し、チェックポイントチェーンを検証します。                                                                                                | 改ざんは報告されますが、修復はされません。                                           |

<a id="fail-closed-choices"></a>

## フェイルクローズの選択

以下は、機能を縮退させるとアクセスが広がったり、削除について誤った結果を返したりするため、縮退せずに拒否する処理です。

- **失効（Revocation）。** プロセスが失効トークンのセットを一度読み込むまでは、すべてのトークンに対して 503 `AUTH_UNAVAILABLE` を返します。読み込み後に ClickHouse が停止した場合は、最後のスナップショットを保持します。
- **認可（Authorization）。** 対象主体の権限マップの読み取りに失敗した場合は 503 を返します。ただし、`LOOM_JWT_REVOCATION_MAX_STALE_SECONDS`（600 秒）より新しく、その後の権限変更で置き換えられていないキャッシュエントリをプロセスが保持している場合は、それを返します（[トークン](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#tokens)）。単一の権限参照（`authz.grant_role_for`）は、読み取りの失敗を権限なしとして扱います。分類を読み取れない制限付き名前空間は拒否されます。
- **起動時マイグレーション。** マイグレーションに失敗すると、ワーカーが起動する前にプロセスが停止します。
- **消去（Erasure）。** 削除を確認できないフェデレーテッドバックエンドは、そのステップを失敗させます。対象範囲のどこかに残存データがあれば、saga は失敗します。
- **開発用署名シークレット。** 認証を必須とするデプロイは、リポジトリにコミット済みのシークレットでは起動を拒否します。

以下は、拒否するとサービスが停止してしまい、可用性のための制御として本末転倒になるため、フェイルオープンとし、カウントまたはログ記録を行います。トラフィック分類、レートリミッター、冪等性キャッシュの読み取り、監査ログの挿入（[データ損失の境界](#data-loss-boundaries)にある 2 つの復元処理を除く）、起動時のキャリブレーション、埋め込みキャッシュ、およびすべてのテレメトリ書き込みが該当します。詳細は[セキュリティ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md)を参照してください。

<a id="when-a-dependency-is-down"></a>

## 依存先が停止したとき

| 停止対象              | 挙動                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ClickHouse            | `/v1/health` と `/v1/health/ready` は 503 を返し、`/v1/health/live` は 200 のままです。リクエストは `OVERLOADED`、`BACKEND_TIMEOUT`、またはリクエスト ID を含む 500 で失敗します。トークンは直近の失効スナップショットで検証されます。ワーカーはパスに失敗し、バックオフします。                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 埋め込みプロバイダ    | `memory.set` と `memory.bulk_set` は失敗します。ベクトルを持たないファクトは保存されません。待機できる経路（`memory.promote`、チャンクの埋め込み）は `embedding_worker` 用のスタブを保存します。会話ターンは埋め込みエラーを記録した状態で保存され、未埋め込みのままになります（再試行されません）。`conversation.compact` は要約を書き込まず、ターンも廃棄しません（`embed-failed`）。クエリのベクトルが埋め込みキャッシュにない場合、`memory.search` は 503 `EMBED_TIMEOUT` で失敗します。プロバイダがハングしてもヘルスフラグは設定されません（ログに `query embed exceeded` が出ます）。エラーを返すプロバイダは `/v1/health` に `provider_failing:<name>` として表示されます。 |
| 埋め込みキーが未設定  | プロセスは偽の埋め込み器を使い、エラーログと `problems` エントリを出力します。検索は偽のモデルで書き込まれた行にのみ一致します。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| LLM プロバイダ        | 各呼び出しは再試行します（4 回）。フェイルオープンのステージ（HyDE、リランク、抽出の検証、タイトル）はスキップされます。抽出と `memory.ask` の合成には代替手段がありません。`LOOM_LLM_FALLBACK_MODEL` を設定すると、障害時に 2 つ目のモデルへ切り替えます。                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ドキュメントバケット  | バケットに保管された原本のアップロードとダウンロードは 503 `BACKEND_UNAVAILABLE` を返し、存在しなくなった原本のダウンロードは 410 を返します。バケットに到達する消去ステップはフェイルクローズし、`erasure_recovery` が再試行します。原本のスイープはそのパスの失敗を記録し、バケットの走査は次のパスでカーソルから再開します。                                                                                                                                                                                                                                                                                                                                                                                       |
| Langfuse、ClickStack  | トレースとエクスポートは破棄されますが、リクエストには影響しません。設定済みの消去バックエンドが停止している場合は、その saga ステップが失敗し、リカバリが再試行します。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

**`memory.set` がスタブを保存せず失敗する理由：** スタブは埋め込まれるまですべての検索レッグから見えないため、「保存済み」と伝えられた呼び出し元が自分の書き込みを見つけられなくなります。失敗させることで、呼び出し元は冪等性キーを使って再試行できます。

<a id="bluegreen-rollback"></a>

## Blue/green ロールバック

`./redeploy.sh` は待機中のカラーを起動し、そのカラーの `/v1/health` が `status: ok` を報告し、ClickHouse に到達でき、`schema.pending` が空で、劣化したプロバイダーがなく、埋め込みの次元数の不一致もない状態になった場合にのみ、`LOOM_REDEPLOY_READY_TIMEOUT_S`（スクリプト変数、180 s）以内に切り替えます。旧カラーは削除されずに停止され、そのイメージには `loom:prev` のタグが付けられます。`./redeploy.sh --rollback` は旧カラーを起動して切り戻します。すべてのマイグレーションは追加のみであるため（`tests/unit/test_migrations_additive.py`）、以前のビルドは新しいスキーマに対しても動作します。詳細は[アップグレード](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md)を参照してください。

<a id="a-replica-that-dies-mid-migration-or-mid-reconfiguration"></a>

## 移行中または再構成中にレプリカが停止した場合

すべてのプロセスはプロバイダ参加者です。参加者は `loom._provider_participants` に 1 行を持ち、専用のスレッドから 10 秒ごとにその行を書き込みます。また、ClickHouse に送るすべてのクエリで、自身の ID を示す User-Agent を付与します。参加者が停止したとみなされるのは、退役した場合、または最後のハートビートが 60 秒より古く（サーバーの時計で判定）、かつ `system.processes` にどのノードでも自身のクエリが見当たらない場合です。それ以外は停止とみなしません。到達できないプロセスは、停止したプロセスではありません。

- **移行中に強制終了された場合。** 移行が保持するのはマイグレーションロックだけです（`ttl_s`。適用している間は更新されます）。プロバイダロックは保持しません。プロバイダロックを取るのは、ブート時に未完了の再構築がないかを確認する間だけです。別のコンテナは、マイグレーションロックの期限が切れた時点でそれを引き継ぎ、残りを適用します。
- **プロバイダロックを保持したまま強制終了された場合**（再構築のステップ、保存された構成）。キーの TTL は 60 秒で、20 秒ごとに更新されます。期限が切れ、かつ保持者の参加者が停止したとみなされた時点で、競合する側が引き継ぎます。保持者の参加者行が存在しない場合、その参加者は停止とはみなされません。この場合は `loom provider-lock clear --holder <holder>` でロックを解放できます。
- **再構成中に強制終了された場合。** ハートビートの期限が切れた参加者について、移行は待機します。一時停止したプロセスが、受け付け済みの処理を抱えたまま再開する可能性があるためです。待機は、同じホスト上のプロセスがその参加者の消滅を確認し（コンテナの再起動、または pid の終了）、退役させるまで続きます。workers リーダーは、1 日前に退役した参加者の行を削除します。また、移行が待機することになる参加者を 1 分ごとに一覧にし、`/v1/health` に `provider_participants_stale` として出力します。プロセスが消滅したことを確認したうえで、`loom participant retire --participant <id> --yes` を実行すると手動で退役させられます。ハートビートが新しい参加者や、クエリがまだ実行中の参加者に対しては、このコマンドは拒否されます。
- **登録後にブートが失敗した場合** は、その行を退役させます。クラッシュを繰り返すコンテナが行を残すことはありません。

ハートビートが途絶えたまま凍結されたプロセス（停止したコンテナ、VM の一時停止）がある場合、移行は、そのプロセスが再開して処理を完了させるか、オペレーターが退役させるまで保留されます。

<a id="data-loss-boundaries"></a>

## データ損失の境界

- **確認応答済みの書き込み。** `memory.set` が成功した時点で、その両方の行がコミットされています。
- **テレメトリと監査の行。** クラッシュすると、フラッシュ前の `agent_events` キュー（100 ms ごとにフラッシュ）とイベントストリームのキュー（`LOOM_EVENTS_STREAM_FLUSH_INTERVAL_S` ごと、1 秒）が失われます。イベントストリームが運ぶのは予算違反のみです。監査、露出、検索トレースの行は直接挿入されます。監査の挿入に失敗するとログに記録され、その記録に依存する 2 つの op、つまり廃止を取り消す `memory.restore` と `namespace.restore` だけが失敗します（[監査の制限](/ja/features/observability/audit#limits-and-failure-modes)）。取得処理はこれらをいずれも読みません。
- **レスポンス後のプロジェクション**がクラッシュで失われた場合は、修復ワーカーが再構築します。
- **ClickHouse OSS 単一ノード。** レプリケーションもポイントインタイムリカバリもありません。本番環境では ClickHouse Cloud、またはレプリケーション構成の OSS クラスターを使います。バックアップには ClickHouse の `BACKUP` またはネイティブバックアップを使います。`dev/backup_loom.py` はデプロイメント、組織、名前空間を移行するもので、ディザスタリカバリ用ではありません。[バックアップとリカバリ](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)を参照してください。
- **ClickHouse 外のファイル。** ドキュメントの原本は ClickHouse（`loom.document_blobs`）にあります。`LOOM_DOCUMENT_OBJECT_STORE=s3` で書き込まれたものは S3 互換バケットにあり、バケット自体のバージョニングまたはレプリケーションでバックアップします。ライフサイクルルールにより、消去された原本のコピーが残る期間が制限されます。コードミラーはボリューム上にあり、ミラーを持たないホストでは、ClickHouse に記録されている Git リポジトリのリモートから再クローンします。ここで ClickHouse が保持するのはリモートの登録情報であり、クローン元は ClickHouse ではありません。プロバイダーの再設定でホスト上に残るものはありません（[プロバイダーの再設定](/ja/architecture/provider-reconfiguration)）。
- **別のホストまたは ClickHouse への移行。** ClickHouse、env 設定、`LOOM_JWT_SECRET` を移します。行がドキュメントバケット内のオブジェクトを参照している間は、そのバケットも移します。それ以外はすべて復元されます（[デプロイメントの移行](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md#moving-a-deployment)）。

<a id="capacity"></a>

## キャパシティ

サーバープロセスは永続的な状態を持たないため、Web のキャパシティはプロセス数を増やすことでスケールします。検索処理（ベクトルスキャン、テキストインデックス、グラフ探索）は ClickHouse が担うため、Python ティアを超えるキャパシティは ClickHouse のキャパシティになります。ワーカーはレプリケーションではスケールしません。1 つのスーパーバイザーがワーカーを実行します。手順は[デプロイ](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md)と[パフォーマンスチューニング](https://github.com/ClickHouse/loom/blob/main/docs/guides/performance-tuning.md)にあります。

| ティア                     | スケール方法                                               | 上限を決める要因                                                          |
| -------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- |
| Web（HTTP、MCP、ダッシュボード） | ロードバランサー配下のコンテナを増やす。`LOOM_WEB_WORKERS` | プロセスあたりの Python CPU、プロセスごとのプール、レプリカごとのレート制限 |
| バックグラウンドワーカー   | デプロイあたり 1 つのスーパーバイザー。より大きなワーカーコンテナ | 間隔に対するパスの所要時間、LLM と埋め込み処理のプロバイダークォータ |
| 検索とストレージ           | ClickHouse のコンピュート、メモリ、ストレージ              | テナントの読み取りでスキャンされる行数、取り込み時のマージ負荷            |
| プロバイダー               | プロバイダークォータとバッチサイズ                         | プロバイダーのレート制限。`loom.embed.pending` が埋め込みのバックログを示す |

<a id="web-tier"></a>

### Web ティア

| 設定項目                         | 効果                                                                                                                                                                                                                                         |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web レプリカを増やす             | ロードバランサー配下に同一のレプリカを N 個置き、すべて `LOOM_BACKGROUND_WORKERS=auto` にします。                                                                                                                                            |
| `LOOM_WEB_WORKERS`               | コンテナあたりの uvicorn プロセス数。未設定の場合、イメージはコンテナが使える CPU ごとに 1 つ、ただしメモリ 1 GiB あたり最大 1 つ、かつ最大 8 つまで起動します。各プロセスは Python を 1 コアで実行し、ローカル埋め込みは CPU を均等に分け合います。 |
| `LOOM_REPLICA_COUNT`             | 各レート制限バケットを割るレプリカ数の下限（後述の、稼働中で提供状態の `loom.instances` 行）。                                                                                                                                               |
| `LOOM_LATENCY_BUDGET_MULTIPLIER` | バジェット違反が発火する前に、すべての op の `budget_p99_ms` に掛ける係数（デフォルト 1.0）。                                                                                                                                                |

新しいレプリカは `/v1/health/ready` が 200 を返した時点で提供を開始します。条件は、ClickHouse が応答すること、未適用のマイグレーションがないこと、失効スナップショットと署名キーリングが読み込まれて新しいこと、トラッカーレジストリとランタイムオーバーライドが一度読み込まれていること（起動時は両方を最大 `LOOM_BOOT_WARMUP_TIMEOUT_S` 待ちます）、類似度キャリブレーションが採用されていること、その設定がデプロイの設定と一致していること、サンドボックスが必須の環境で動作していること、です。SIGTERM を受けると、そこでは 503 を返し、ポートを閉じるまで `LOOM_SHUTDOWN_READY_DELAY_S` の間提供を続けます。プロセスをまたいだ read-your-writes は、プロセスアフィニティではなく ClickHouse（待機付きインサート、コミットまたはバッチ、順次の再読み取り）が処理します。

<a id="clickhouse-client"></a>

### ClickHouse クライアント

`server/core/ch.py` は、プロセスごとに 1 つのプールと、同じサイズの 1 つのアドミッションセマフォを提供します。

| 設定                                            | デフォルト | 効果                                                                                                                   |
| ----------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| `LOOM_CH_POOL_MAXSIZE`                          | 64         | プロセスあたりの接続数と同時ステートメント数。バッチインサートは待機とフラッシュの間、1 つを保持します。              |
| `LOOM_CH_POOL_WAIT_MS`                          | 500        | スロットの待機時間。超えると `Retry-After: 1` 付きで 503 `OVERLOADED`。0 でゲートを無効にします。                      |
| `LOOM_CH_TIMEOUT_READ_S`                        | 30         | 読み取りのデッドライン。                                                                                               |
| `LOOM_CH_TIMEOUT_WRITE_S`                       | 60         | `INSERT` / `UPDATE` のデッドライン。                                                                                   |
| `LOOM_CH_TIMEOUT_DDL_S`                         | 300        | DDL、`OPTIMIZE`、`SYSTEM` のデッドライン。                                                                             |
| `LOOM_CH_BATCHED_INSERTS`                       | true       | リクエストごとに書き込まれるインサートをバッチ化します。各インサートは待機の間接続を保持します。false の場合は 1 パートずつコミットします。 |
| `LOOM_CH_BATCHED_INSERT_WAIT_MIN_MS`            | 10         | バッチまたは待機付き非同期インサートの最短待機時間。単独のインサートが待つ時間で、待機の間接続を保持します。           |
| `LOOM_CH_BATCHED_INSERT_WAIT_MAX_MS`            | 50         | リクエストが待つバッチまたは待機付き非同期インサートの最長待機時間。その間接続を保持します。                           |
| `LOOM_CH_BATCHED_INSERT_BACKGROUND_WAIT_MAX_MS` | 200        | 使用イベントフラッシャーのティックとドレイン、および書き込みマークのフラッシュに対する同様の設定。                     |

**待機に上限がある理由:** ClickHouse が遅くなると、上限のないキューは、処理がキューに入った後ですべてのリクエストをクライアントタイムアウトに変えてしまいます。短い待機であれば、再試行可能な 503 で素早く失敗します。ゲージ `loom.ch.pool.in_use`、`waiters`、`overloaded_total`、`timeouts_total` は、どちら側が飽和しているかを示します。

<a id="traffic-classes"></a>

### トラフィッククラス

すべての呼び出しにはクラスがあります。`production`、`interactive`（デフォルト）、`bench`、`background`（スーパーバイザーが設定し、リクエストでは設定されません）のいずれかです。クラスはトークンのクレームから決まり、なければ名前空間レジストリ、それもなければリクエストのヒントから決まります。クラスが変えるのはスケジューリングであり、結果は変わりません。

- クラスごとの ClickHouse 読み取り設定（`LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS`）：`production` は優先度 1、`interactive` は 2、`background` は優先度 5 でスレッド 3、`bench` は優先度 10 でスレッド 4。
- レート制限バケット（`LOOM_RATELIMIT_CLASS_FRACTIONS`。`bench` は半分）。
- クラスごとの LLM ポリシー（`LOOM_LLM_POLICY_BY_TRAFFIC_CLASS`）。

新しい `bench-…` 名前空間は `bench` に分類されるため、負荷テストが本番を圧迫することはありません。

<a id="rate-limits"></a>

### レート制限

`server/core/ratelimit.py` は、（名前空間、op クラス）ごと、および（org、op クラス）ごとにトークンバケットを保持します。org ティアは名前空間ティアの 3 倍です。任意のアクターごとのティアは、名前空間バケットの一部を使います（`LOOM_RATELIMIT_ACTOR_FRACTION`、1.0 = オフ）。呼び出しはすべてのバケットを通過する必要があり、拒否されたときはどのバケットも減算されません。

| op クラス          | 対象                                                                                                          | 容量 | 補充 / 秒 |
| ------------------ | ------------------------------------------------------------------------------------------------------------- | ---- | --------- |
| `memory`           | `memory.*`、`conversation.*`（厳密キー読み取りと `memory.import` を除く）                                     | 100  | 17        |
| `memory.read`      | 厳密キー読み取り：`memory.get`、`bulk_get`、`history`、`working_memory.get`、…                                | 300  | 50        |
| `memory.import`    | `memory.import`                                                                                               | 10   | 2         |
| `knowledge.search` | `knowledge.search`                                                                                            | 20   | 3         |
| `knowledge.query`  | `knowledge.query`                                                                                             | 20   | 3         |
| `knowledge.read`   | `knowledge.inspect` を除く、`read_only` のその他の `knowledge.*` op：`knowledge.get`、`knowledge.list`、…     | 50   | 10        |
| `knowledge.add`    | その他すべての `knowledge.*` op（`knowledge.inspect`、`knowledge.synthesize`、`knowledge.dedup_list` を含む） | 10   | 2         |
| `code`             | `code.*`（`memory` から消費する `code.outcome` を除く）                                                       | 60   | 10        |
| `insights.query`   | `insights.query`                                                                                              | 20   | 3         |
| `assistant.ask`    | `assistant.ask` とアシスタントのチャットルート                                                                | 10   | 1         |
| `default`          | それ以外すべて                                                                                                | 50   | 10        |

これらは名前空間ティアのデフォルト値です（`DEFAULT_LIMITS`、`op_class_for`）。

- **レプリカごと。** バケットはプロセスまたはホスト内に存在します。各レプリカは、稼働中で提供状態の `loom.instances` 行を持つホストの数で制限を割った値を保持するため、レプリカの合計は制限に近似します。`LOOM_REPLICA_COUNT` はその数の下限であり、行を読み取れない間の数でもあります。
- **ホスト内。** `LOOM_WEB_WORKERS > 1` の場合、プロセスはメモリマップトファイル内の 1 つのバケットテーブルを共有します（`LOOM_RATELIMIT_SHARED=auto`、`LOOM_RATELIMIT_SHARED_PATH`、`LOOM_RATELIMIT_SHARED_SLOTS`）。`/v1/health` は `ratelimit.backend` を報告します。
- **フェイルオープン。** リミッターのエラーは呼び出しを許可し、カウントされます。

**ローカルバケットを使う理由:** アドミッションごとに ClickHouse へ往復すると、データベースを守るために、すべてのリクエストの経路にそのデータベースを置くことになります。

<a id="background-workers"></a>

### バックグラウンドワーカー

デプロイごとに 1 つのスーパーバイザーが動作します。`auto` モードでは、デプロイ（`LOOM_DEPLOYMENT=1`）のすべてのプロセスが ClickHouse 内の 1 つのリースを争います。キーは Keeper ロックテーブル `loom._migration_lock`（strict KeeperMap）の `workers_supervisor` です。デプロイの外（同じ ClickHouse 上の iso またはブランチサーバー）では、`auto` はワーカーを実行せず、起動ログにその旨が出力されます。`on` ではそこでも実行しますが、リーダーの仕事（保持期間の ALTER、トラッカーの名前空間行、公開された設定、プロバイダー参加者のスイープ）を行うのはデプロイのホルダーだけです。
有効期限は ClickHouse サーバーのクロックで判定されます。T = `LOOM_SUPERVISOR_LEASE_TTL_S`（デフォルト 30 秒、最小 24）とすると、次のとおりです。

| ステップ | タイミング                                                                   | 理由                                                                                        |
| -------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| 更新     | T/6 ごと。失敗した更新は T/12 ごとに再試行                                   | ホルダーが諦める前に、複数回の失敗を吸収できる                                              |
| 喪失     | 反映された最後の更新が送信されてから T/2 後                                  | 送信時点から計測するため、サーバーのスタンプがそれより前になることはない                    |
| 停止     | その期限で、更新呼び出しがまだブロック中でも停止                             | ハングした呼び出しがワーカーを動かし続けることはない。各呼び出しは 1 回だけ送信され、タイムアウトは max(1, T/24) 秒 |
| ドレイン | 最大 T/6。ワーカーは 2T/3 までに停止                                         | その時点でまだ動いているワーカーの子プロセスは kill される                                  |
| 失効     | サーバーが最後の更新にスタンプを押してから T 後。その後、別のプロセスが引き継ぐ | ドレイン後に T/3 の余裕がある                                                               |

更新に失敗したホルダーは、更新できるまで新しいパスを開始しません（一時停止から復帰したプロセスが、新しいホルダーと並んでパスを実行することはありません）。また、Keeper のキーがまだ自分を指しているホルダーは、TTL が切れるのを待たずにすぐリースを取り戻します。リースが奪われたと判断したホルダーはワーカーを停止し、ホルダーが死んだ場合は T 後に別のプロセスが引き継ぎます。起動後にホルダーになったプロセスは、リーダーの起動時の処理（トラッカーの名前空間行、公開された設定、`LOOM_RETENTION_*_DAYS`）も行います。

ワーカーを停止すると、各パスは次の `await` でキャンセルされます。キャンセルが届かない処理（PageRank やコミュニティ計算のようなスレッド、リースループが動く前に一時停止から再開したパス）は、パスの次の `pass_context.check_stop()` で停止します。これは長いループがバッチの合間に呼び出すもので、対象は ingest の各レグ、SCIP のデルタラウンド、`code_pr_history`、`code_graph_stats`、`entity_communities` です。パスが停止された、またはリースがもう新しくない場合に例外を送出するため、パスはそれ以降の書き込みを送りません。フェンシングトークンはありません。すでに送信されたステートメントは反映されます。

プロセスは、次の間は身を引きます（ホルダーはワーカーを停止してキーを手放し、候補者は争いません）。

- SIGTERM 後のドレイン中。これにより、レディ遅延の間に別のプロセスが引き継ぎます。
- 設定がデプロイの公開済みの設定と異なる場合（レディにならず、誤った空間にベクトルを書いたり、誤ったルートで署名したりするおそれがあります）。
- より新しいビルドの稼働中の `loom.instances` 行が、同じリースを争っている場合。

最後のものがローリングアップグレードの引き継ぎです。各行は、そのビルドのスキーマバージョン（最後のマイグレーション番号）と、現在争っているリースを持ちます。そのプロセスがドレイン中、設定のずれ、またはリースを手放した場合は none になるため、そのような行が古いビルドを退かせることはありません。引き継ぎはスキーマバージョンが異なる場合にのみ発生するため、コードのみのリリースでは引き継ぎは起きません。古いホルダーは停止するまでワーカーを保持します。より新しいビルドが稼働しなくなる（ロールバック）と、古い方が再び争います。ワーカーの子プロセスが起動に失敗し続けるプロセスは、5 分間リースを手放します（後述）。

つまり、次のとおりです。

- `auto` では複数のホストを動かせますが、ワーカーを実行するのはそのうち 1 つです。`on` は選出をスキップします。
- メンテナンスワーカーの 2 つ目のコピーは ClickHouse の処理を無駄にします。LLM ワーカーの 2 つ目のコピーは、スキャンとコストを倍にします。
- ホルダーはワーカーを子プロセス（`LOOM_WORKERS_PROCESS=child`）で実行するため、長いパスがリクエストを処理するイベントループを共有しません（提供側のループでパスを実行すると、リクエストの p90 がおよそ倍になりました。`code_ingest` パスの間、`memory.get` は 74〜79 ms に対して 148 ms でした）。子プロセスはスーパーバイザーとそのワーカーが使うもの（ClickHouse クライアント、プロバイダー設定、イベントエミッター、トラッカーとリポジトリのレジストリ）を実行しますが、提供側のライフスパンは実行しません。子プロセスは親からリースの期限を毎秒読み取り、リースが新しくなくなると期限は進まなくなります。子プロセスはその期限に T/6 を足した時点までに消えます。その時点で自ら終了し、親が kill し、親が死んだ場合はカーネルが kill します（`PR_SET_PDEATHSIG`）。子プロセスのイベントループは毎秒親へハートビートを送り、`/v1/health` は 15 秒間ハートビートのない子プロセスを not alive として表示します。ドレイン中のプロセス（SIGTERM）は、インラインか子プロセスかを問わずワーカーを停止し、まだリクエストを処理しながらリースを手放します。起動から 60 秒以内に終了することが 5 回連続した子プロセスがあると、そのプロセスはリースを手放して `workers_lease_given_up` を報告します。別のプロセスがワーカーを引き継ぎ、このプロセスは 5 分後に再び争います。

ワーカーの処理はプロセス間で分割されません。ワーカーは上限のあるパスによって処理に追従します。パスごとにバッチまたは時間のバジェットがあり（たとえば `embedding_worker` は最大 100 個のスタブを埋め込み、`usage_fold` は 120 秒以内に最大 1000 件のメモリを畳み込み、保留中のミューテーションが 20 件になるとバックオフします）、さらに上記のデッドラインがあります。パスが常にデッドラインに達する場合は、ワーカーコンテナにより多くの CPU が、またはプロバイダーにより多くのクォータが必要です。

<a id="batch-sizes-and-queues"></a>

### バッチサイズとキュー

| 経路                              | 上限                                                                                                       |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| リクエストボディ                  | `LOOM_MAX_REQUEST_BYTES`（32 MiB）。超えると 413                                                           |
| `memory.bulk_set`                 | 1 回の `embed_many` で最大 1000 エントリ。競合チェックは最大 `LOOM_BULK_CONFLICT_CHECK_MAX_ENTRIES`（200） |
| `memory.bulk_get`                 | 最大 1000 キー                                                                                             |
| `memory.set_from_messages`        | 最大 400 メッセージ                                                                                        |
| 埋め込みリクエスト                | プロバイダーリクエストあたり最大 100 入力（OpenAI、Gemini）                                                |
| `agent_events` エミッター         | 10,000 行のキュー。0.1 秒ごと、または 500 行ごとにフラッシュ                                               |
| イベントストリーム（バジェット違反） | 20,000 のキュー。`LOOM_EVENTS_STREAM_FLUSH_INTERVAL_S` ごと、または `_FLUSH_BATCH` 行ごとにフラッシュ   |
| ワーカーのステータス行            | 15 秒ごと、または 200 行ごとにフラッシュ                                                                   |

<a id="vector-cost"></a>

### ベクトルのコスト

1 つのメモリは、`Array(BFloat16)` のベクトルを最大 2 つ（値とキー）保存します。1536 次元で 6 KiB、3072 次元で 12 KiB です。ストレージとスキャンのバイト数は `LOOM_EMBEDDING_DIM` に比例して増加します。HNSW インデックスはないため、読み取りはテナントの名前空間のすべてのベクトルをスキャンし、レイテンシは名前空間のサイズとともに増加します。量子化コードは、コーデックを有効にできる場合にスキャンを縮小します（[ゲート付き設定](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#gated-clickhouse-settings)）。詳細は [ClickHouse](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#vector-storage) を参照してください。

<a id="measuring"></a>

### 計測

このページにはレイテンシやスループットの数値は記載していません。それらは ClickHouse のデプロイ、ネットワーク距離、名前空間のサイズに依存します。分離したサーバーに対して、自分で計測してください。

| コマンド                                                    | 計測内容                                                                                               | 出力                |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------- |
| `make bench OP=memory.set C=10 D=30`                        | 1 つの op の、同時実行数 C、D 秒間での p50 / p95 / p99 と RPS（`scripts/ops/benchmark.py`）             | stdout、または `--json` |
| `python bench/search_latency.py --namespaces … --queries …` | 名前空間サイズ帯ごとの `memory.search` の p50 / p95。`retrieval_work.stage_ms` によるステージごとの時間つき | `--out` CSV         |
| `make bench-quick`                                          | 30 問のサンプルでの検索品質（実際のプロバイダーが必要）                                                | `/tmp` 配下の CSV   |

`scripts/ops/benchmark.py` は新しい `bench-…` 名前空間に書き込むため、`bench` クラスで実行されます。`memory.search` の実行には、`memory.set` の実行で埋めた名前空間が必要です。[ベンチマークの実行](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md)を参照してください。

<a id="what-to-scale"></a>

### スケール対象の判断

| シグナル                                                        | スケール対象                                              |
| --------------------------------------------------------------- | --------------------------------------------------------- |
| Web CPU が高く、リクエストの p99 が上昇し、ClickHouse は高速に応答している | Web レプリカまたは `LOOM_WEB_WORKERS`          |
| `loom.ch.pool.waiters` と `OVERLOADED` が上昇し、ClickHouse は高速 | `LOOM_CH_POOL_MAXSIZE`、またはレプリカの追加           |
| `BACKEND_TIMEOUT` と遅い `system.query_log` エントリ            | ClickHouse のコンピュート、または読み取りあたりの名前空間を小さくする |
| `loom.embed.pending` が上昇                                     | 埋め込みのスループット（プロバイダークォータ）            |
| `loom.worker.consecutive_failures` またはパスの所要時間が増加   | ワーカーコンテナの CPU とメモリ                           |
| 取り込み時のマージ負荷、メモリエラー                            | ClickHouse のコンピュートとメモリ、または書き込み同時実行数を下げる |

メトリクスについては[モニタリング](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)で説明しています。

<a id="known-limits"></a>

### 既知の制限

- **デプロイごとにワーカーリーダーは 1 つ。** ワーカーのパスはホスト間に分散されません。
- **レプリカごとのレート制限**は近似です。バケットの充填はホストごとです。サインインとサインアップの試行制限は、`loom.auth_attempts` ですべてのプロセスにわたってカウントされます。
- **レプリカをまたぐ check-then-insert**（サインアップの名前とメール、個人の名前空間、OAuth コードまたはリフレッシュトークン、処理中の冪等性キー）は、デプロイ全体のクレーム（`loom._migration_lock` の strict KeeperMap キー）の下で、順次読み取りによるチェックを伴って実行されます。2 番目の競合者は 409 を受け取ります。応答できないクレームストアは 503 になります（その場合、冪等性キーは単なるミスとして実行されます）。
- **イベントストリームのテレメトリ**（バジェット違反）は `SIGTERM` でドレインされます。`SIGKILL` や OOM で失われるのは最大で 1 フラッシュ間隔分であり、監査行やメモリ行が失われることはありません。
- **名前空間のサイズが読み取りレイテンシを左右します。** ベクトル読み取りは、ベクトルインデックスなしで名前空間の行をスキャンするためです。
- **シングルノードの ClickHouse OSS** にはレプリケーションもフェイルオーバーもありません。

<a id="knowledge-restore"></a>

## ナレッジの復元

`knowledge.restore`（[削除したドキュメントの復元](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#restoring-a-deleted-document)）は、消去（erasure）が対象とした内容を決して復活させてはなりません。消去は自身の痕跡を残します。対象範囲のすべてのチャンクにスタンプを付け、削除済みドキュメントのチャンクにも付け、ライブ行はその場で置き換えます。復元は、そのドキュメントに及ぶ可能性があり、ドキュメントの書き込み時点で完了していなかった消去についても、消去台帳を読みます。対象は、そのドキュメントの名前空間の消去、そのドキュメントを含む名前空間リストの消去、復元されるリビジョンを書いたユーザーの消去です（中断された復元のライブ行の残りについては、書き込んだユーザーを特定できる署名がないため、任意のユーザーの消去が対象です）。

復元は、行を書き込む前と後に台帳を読みます。後の読み取りで消去が見つかった場合は、書き込んだものを取り消します。書き込みを始めた後で何かが失敗した場合も同様に取り消します。パージ（purge）の下では、自身の行を削除するため、内容のコピーは残りません。マージが削除行をその行に折り込んでいた場合、この削除によりソースには行が残らなくなります。そのドキュメントを対象とするパージでも行は残らず、対象となる可能性があるだけのパージ（読み取れないリスト、または中断された復元の残りに対する任意のユーザーのパージ）では、そのドキュメントの廃止済みの行が失われます。これはフェイルクローズの選択です。
それ以外の場合、および台帳を読めない場合は、行を廃止済みとして書き戻し、その間に消去が行に付けた印はそのまま保持します。行を削除すると、マージがいつでも削除行をその行に折り込み得るため、ソースに行が残らなくなる可能性があるからです。ソースの行が1つも残っていない場合（パージがすべてを取り去った場合）は、何も書き戻しません。

Postgres オーソリティの下では、復元はドキュメントヘッドを通じて書き込みます（[ストレージオーソリティ](/ja/architecture/storage-authority#knowledge-documents)）。ソースの公開が ClickHouse にまだ反映され得る間（未配信のもの、または配信ワーカーが引き継ぎ、そのリースの挿入上限時間内に確定したもの）は、再試行可能な形で拒否します。そうしないと、削除によるチャンクの廃止が、復元でチャンクを戻した後に反映される可能性があるためです。書き戻しは、読み取ったバージョンの上にコミットされるため、その間にソースを取得したテキスト書き込みがあれば、復元は拒否されます（409）。コミットされたものの公開できなかった場合は取り消され、503 を返します。パージの取り消しでは、復元されたヘッドとその配信も取り消し、ClickHouse の行を削除する前にその配信のリースが切れるのを待ちます。

呼び出し元がいなくなった場合（クライアントの切断、リクエストのキャンセル）、応答前であっても復元はクレームの下で最後まで実行され、自身を取り消します。監査行がその復元を記録しないためです。取り消しはクレームを手放す前に完了します。復元が応答した後、トランスポートが監査行を書いている間に呼び出し元がいなくなると、監査行のないまま復元が残ることがあります。これは監査対象のどの書き込みでも起こり得ます。

取り消せないもの：

- 取り消しの前に中断された復元は、廃止済みの行の下でチャンクを検索可能なまま残します。再度呼び出すと完了します。先に実行された削除は、ドキュメント自身の削除時点のスタンプでそれらのチャンクを廃止するため、復元はそれらを見つけられます。
- 2回の台帳読み取りの間に登録され完了した消去の後で、取り消しが失敗した場合（または2回目の読み取りと取り消しが失敗した場合、あるいはその間にプロセスが終了した場合）：行はライブのまま残り、以降の呼び出しは `live` を返します。
- 取り消しが台帳を読めなかったパージは、行を廃止済みのまま残します。すべての行を数えるパージの残存調査は、取り消しの後に実行された場合にのみ、それを報告します。
- 元ファイルの掃除は、ライブ行から参照されていない元ファイルを、十分に古くなった時点で削除し、削除時には経過時間だけを確認します。ドキュメントが削除されている間に名前空間を読んだ掃除パスは、復元が元ファイルを見つけた後でそれを削除し得ます。その場合、復元された行は存在しない元ファイルを指すことになり（`kept` を返します）、ダウンロードは失敗します。既存の元ファイルを再び指定する書き込みも、この時間窓を共有します。

並行する書き込み：テキスト書き込み（`knowledge.add`、`knowledge.upsert`）とライブドキュメントの削除は、クレームを取りません。ClickHouse オーソリティの下では、復元中に同じソースへテキスト書き込みが行われると、削除中と同様に、そのソースの次の書き込みまで両方のバージョンのチャンクが検索可能なままになることがあります。復元より前に始まった書き込みは、より低いバージョンで行を保存するため、復元された行がそれを隠します。これは、削除の行が削除より前に始まった書き込みを隠すのと同じです。その場合は再度書き込んでください。Postgres オーソリティの下では、2つのうち後にコミットしたほうが 409 を返し、自身のチャンクを廃止します。復元が、後の書き込みの行が勝った後で自身を取り消す場合は、その行をそのまま残し、自身のチャンクだけを廃止します。すでに削除されたソースの削除は、残りのチャンクをソースのクレームの下で廃止し、その下でドキュメントを逐次一貫性で再読み取りします。その間に復元がライブに戻したドキュメントは、ライブとして扱われ、チャンクを保持します。廃止して数えるのは、トゥームストーンまでのチャンクだけです。まだコミットされていない新しい書き込みのチャンクは残り、それしか見つからない削除は、何も削除されなかったと応答します。

<a id="knowledge-move"></a>

## ナレッジの移動

`knowledge.move`（[ドキュメントの移動](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#moving-documents)）は、各ドキュメントを移動先の名前空間に書き込んでから、元の場所のドキュメントを削除します。このため、移動が途中で打ち切られた場合、ドキュメントは両方の場所に残り、どちらにも存在しない状態にはなりません。ドキュメントごとに、移動先の場所を読み取り、書き込みの前に、そこに別の有効なドキュメントがあれば `exists` を返します。クレーム（claim）の下では、両方を再度読み取ります。その後、元のファイルと抽出アーティファクトを、クレームの外で新しい名前空間に保存します（どの行からもまだ参照されていない元ファイルは、行が反映されなかったアップロードと同様に、スイープの対象になります）。ClickHouse の行として保持されている元ファイルは ClickHouse 内でコピーされます。バケットにあるもの、またはその間にバケットへ移されたものは、新しい名前空間のバケット上の場所で読み取り直して書き込みます。消去（erasure）によって削除された元ファイル（ドキュメントの `blob_erased_at`）は、その sha のバイト列が別のアップロードのために保持されていても、コピーされません。

次に、移動元のクレームの下で、両方の名前空間についてソート順に取得し、待機はせずに（保持されている移動元は即座に `busy` を返します）、次のいずれかの場合に `busy` で拒否します。どちらかの場所が読み取り以降に変化した場合、どちらかの場所の公開（publication）がまだ反映される可能性がある場合、またはどちらかの ingest ジョブが開いている間です（その公開は、ドキュメントを元の場所に、またはコピーの上に書き戻してしまいます）。ドキュメントのリビジョンのチャンクを、ベクトルとともに ClickHouse 内でコピーします（`INSERT … SELECT`。行が提供するすべてのバージョンが対象で、メタデータの編集ではチャンクは自身のバージョンのままです）。続いてテーブル、行の順にコピーし、読み取ったバージョンに対して移動元を削除します。削除の前に停止した以前の移動が残したコピー（移動先で、テキスト、タイトル、説明、タグ、メタデータ、作成者、ingest 時刻が同一のもの）は、移動元と同数の有効なチャンクと同じテーブルを提供している場合、再度は書き込まれず、移動元の削除だけが行われます。チャンク数が少ないコピー、または移動元にあるテーブルがないコピー（取り消された行の INSERT は、その取り下げの後に反映されることがあり、その場合は行には手を付けません）は、削除済みのドキュメントと同様に上書きされてから、移動元が削除されます。チャンク数が多いコピーは完全なものとみなされます。移動元のチャンクを退役させてから tombstone を書き込むまでの間（チャンクを先に退役させます）に削除が打ち切られると、移動元の行はチャンクを持たないまま有効な状態で残り、残るのは削除のみです。移動元より多くのチャンクを提供するコピーは上書きされることはなく、テーブルも欠けている場合は `exists` を返します。それ以外でテーブルが異なる場合は、一方で変更が加えられたもの（承認、確認など）で、他方での変更と区別できません。そのコピーは、テキストやメタデータが編集されたものと同様に別のドキュメントであり、`exists` を返します。

完全には反映されなかったもの、または削除の前にどちらかの場所を奪った書き込みがあった場合は、移動先に書き込んだ内容を取り下げ、その移動元は `busy` を返します。取り下げは、その間にリクエストが何度キャンセルされても、クレームを手放す前に最後まで実行されます（キャンセルは完了後に発生します）。最初のステートメントは、すべての埋め込みモデルにわたってコピーのチャンクを一度に退役させます。取り下げは、クレームの打ち切りから、またはそれより前に開始されて Postgres の権威が拒否した削除の直後から始まり、そのコミットは `pg_commit_lock_timeout_ms` と `pg_statement_timeout_ms`（デフォルトでそれぞれ 2 秒と 5 秒）以内に応答します。ステートメント自身の上限（TTL の 15%、9 秒）と合わせると、この退役は約 40 秒までに終わり、クレームの 60 秒の TTL の内側に収まります。残りの処理はそれを超えることがありますが、その後にクレームを取得した移動は、そのコピーを不完全なものとして読み取ります。クレームの下で、以前の移動のコピーが完全かどうかを再確認し、完全でなければ `busy` を返し、後続の呼び出しでコピーを再び書き込みます。その呼び出しの他の移動元は、そのまま移動されます。退役の後、取り下げはコミット（Postgres の権威の下）を破棄し、その行を削除し、続いてチャンクとテーブルを削除します。途中で止まった取り下げでも、行のないままチャンクが提供される状態にはならず、チャンクの削除の後に反映された、キャンセル済みの `INSERT … SELECT` も退役されます。クレームの下での処理は、クレームの 60 秒の TTL の 40%（24 秒）で打ち切られ、コピーがそれを超えるドキュメントは取り下げられて `busy` を返します。削除は、その間にリクエストやクレームがどのように終わっても最後まで実行され、ドキュメントは tombstone が書き込まれた時点で移動済みとして数えられます。そのため、tombstone の送信中に打ち切りやキャンセルがあっても、移動済みとして返し、監査に記録します。その際に Postgres の権威が tombstone を拒否した場合も、コピーは取り下げられます。削除そのものの失敗（応答の喪失で、呼び出しが失敗します）は tombstone の後に起こりうるため、コピーは残ります。ドキュメントは両方の場所にあるか、移動先にのみあることになり、再試行ではコピーが見つかって移動元の削除だけが行われるか、`not_found` が返ります。tombstone が書き込まれれば、移動は成立しています。移動元のテーブルは、クレームを手放した後に削除されます（有効なドキュメントの削除はクレームを取らないため、打ち切りは及びません）。そこでの失敗はログに記録され、後の移動元の削除で整理されます。ドキュメントは、クレームの下で tombstone が書き込まれた時点で移動済みとして数えられ、その後に呼び出しを終わらせる事象（クレームを手放す際のキャンセルや、クリーンアップ中のキャンセル）があっても、その監査行とテーブルのクリーンアップは実行されます。移動元に固有ではない失敗（応答しないストア）は、呼び出しのすべての移動元が応答を終えた後、移動済みのものの監査行の後に送出されます。

消去台帳は、`knowledge.restore` と同じ方法（ドキュメントの名前空間と書き込み者に対する `unfinished_reaching` を `may_cover` で絞り込む）で、ドキュメントごとに 2 回読み取られます。1 回目は元ファイルを保存する前で、元の場所に及ぶ可能性のある消去（そのテキストが書き込まれた時点で未完了のもの。基準は最初のチャンクの `created_at` で、移動ではチャンクをコピーした時刻が刻まれますが、行は ingest 時刻を保持します）、または移動先に及ぶ可能性のある消去（移動の開始時点で未完了のもの）を対象とします。2 回目はクレームの下で削除の直前に、それ以降に登録されたものを対象に読み取ります。この移動のコピーまたは以前の移動のコピーを、消去が通り過ぎた可能性があるためです。その消去が見つかった場合、この移動が書き込んだコピーは取り下げられ、以前の移動のコピーは消去に委ねられ、移動元は削除せずに `erased` を返します。したがって、`erased` のドキュメントは常に元の場所に残ります。Postgres の権威の下では、その間に消去によって削除されたドキュメントに対する削除も `erased` を返します。1 回目の読み取りは新しい場所に元ファイルを保存する直前に行われるため、元ファイルの段階でこれを見逃しうる消去は、その読み取りから保存までの間に登録される必要があります。削除前の再読み取りが `erased` を返し、どの行からも参照されないその元ファイルは、行が反映されなかった元ファイルと同様に、`document_blob_min_age_seconds` の後にスイープの対象になります。移動自体は元ファイルを削除しません。元ファイルはそのバイト列をキーとし、行がまだ反映されていない同じバイト列の同時書き込みがそれを必要とする場合があるためです。

同時書き込み：テキストの書き込みはクレームを取りません。Postgres の権威の下では、コピーの行と削除はそれぞれ読み取ったバージョンに対してコミットされるため、先に移動元または移動先の場所を取得した書き込みはそれらを拒否し（409）、コピーは取り下げられます。ClickHouse の権威の下では、移動はコピーの前にクレームの下で移動先のヘッドを読み取り、行の後にもう一度読み取ります。より新しいバージョンの書き込みが優先されてコピーは取り下げられ、最初の読み取りから行までの間（チャンクとテーブルのコピー全体）に反映された、より古いバージョンの書き込みは、同じ移動元に対する 2 つのテキスト書き込みの場合と同様に置き換えられます。

<a id="invariants"></a>

## 不変条件

- 書き込みが成功した時点で、プライマリ行はコミット済みである。どちらか一方が失敗した場合、リクエストは失敗する。
- 再試行される INSERT は重複排除トークンを持つ。持たない場合は再試行されない。
- `OVERLOADED` と `AUTH_UNAVAILABLE` は再試行のヒントを返す。`SCHEMA_PENDING` はオペレーターの対応を待つ。
- ワーカーのパスは冪等である。2 回実行しても同じ状態に収束する。
- アクセスチェックと消去はフェイルクローズで動作する。可用性制御とテレメトリはフェイルオープンで動作し、その件数は計測される。
- どのリクエストも、プール、プロバイダ、キューを無期限には待たない。すべてのステートメントは、スロットの取得に最大でも `LOOM_CH_POOL_WAIT_MS` だけ待ち、実行は最大でもそのクラスのデッドラインまでである。
- トラフィッククラスが変えるのはスケジューリングとバケットだけであり、返される行は変わらない。
- すべてのマイグレーションは加算的であるため、以前のビルドも現在のスキーマに対して動作する。

<a id="source-entry-points"></a>

## ソースのエントリポイント

| 項目                     | 場所                                                                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| クライアントのリトライとゲート | `server/core/ch.py` (`_with_retry`, `_acquire_slot`, `_bounded`, `statement_timeout`), `server/core/ch_schema_guard.py`                                                                                                                     |
| エラーコード             | `server/core/errors.py`                                                                                                                                                                                                                     |
| 冪等性                   | `server/core/idempotency.py`                                                                                                                                                                                                                |
| スーパーバイザーとリース | `server/workers/supervisor.py`, `server/workers/leader.py`, `server/workers/registry.py` (`default_max_pass_seconds`)                                                                                                                       |
| 修復ワーカー             | `server/memory/workers/projection_repair.py`, `orphan_vector_reconcile.py`, `embedding.py`, `entity_extractor.py`; `server/erasure/workers/recovery.py`; `server/tasks/workers/lease_sweep.py`; `server/insights/workers/audit_verifier.py` |
| 失効スナップショット     | `server/auth/revocation.py` (`load_at_boot`)                                                                                                                                                                                                |
| クエリ埋め込みの上限     | `server/memory/app/search/embed.py`                                                                                                                                                                                                         |
| 書き込み後のプロジェクション | `server/memory/app/after_write.py`, `server/memory/app/projection_failures.py`                                                                                                                                                              |
| テレメトリキュー         | `server/observability/events.py`, `server/observability/events_stream.py`, `server/workers/status_store.py`                                                                                                                                 |
| トラフィッククラス       | `server/observability/traffic_class.py`, `server/identity/app/traffic_class_registry.py`                                                                                                                                                    |
| レートリミッター         | `server/core/ratelimit.py` (`DEFAULT_LIMITS`, `op_class_for`), `server/core/ratelimit_shared.py`, `server/auth/attempts.py`                                                                                                                 |
| スキーマの状態           | `server/core/schema/status.py`                                                                                                                                                                                                              |
| ブルー/グリーン          | `redeploy.sh`, `dev/docker-compose.colour.yml`                                                                                                                                                                                              |
| 負荷ベンチ               | `scripts/ops/benchmark.py`, `bench/search_latency.py`                                                                                                                                                                                       |

<a id="related"></a>

## 関連ドキュメント

- [トラブルシューティング](/ja/operations/troubleshooting)：症状から引ける運用手順書。
- [モニタリング](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)：ここで挙げたメトリクス。
- [セキュリティ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md)：フェイルクローズド方式のアクセスチェック。
- [ClickHouse](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md)：テーブル、ベクトルカラム、クエリの帰属。
