> Source: https://clickhouse.github.io/loom/ja/concepts/identities-and-namespaces/ (Markdown: https://clickhouse.github.io/loom/ja/concepts/identities-and-namespaces.md)

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

<a id="identities-and-namespaces"></a>

# アイデンティティと名前空間

Loom はすべての呼び出しで 2 つの問いに答えます。1 つは、その行は誰のものか（アイデンティティタプルと、サーバーが付与する 2 つのカラム）、もう 1 つは、呼び出し元がその行に触れてよいか（トークン、名前空間のグラント、およびその分類）です。このページではそのモデルを説明します。トークンの発行と失効については [トークンとグラント](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md) を、適用の仕組みについては [セキュリティ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md) を参照してください。

<a id="where-namespaces-fit"></a>

## 名前空間の位置づけ

- **org** はテナントです。
- **名前空間**は、org の内側における共有とアクセスの単位です。通常、1 つのデプロイにはチームまたはプロジェクトごとに 1 つ、分離しておく必要がある bot ごとに 1 つ、個人ごとに 1 つの `personal-<slug>`、インデックス化したブランチごとに 1 つの `code-<repo>[-<branch>]` があります。
- 名前空間のメンバーは全員、その名前空間内のすべての行を読み取れます。
- `agent` は行を書き込んだ主体を記録するもので、境界ではありません。
- `user_id` / `read_scope=own_user` は、1 つの bot の名前空間内でエンドユーザーを分離します。
- アクセスは名前空間に対するロール（viewer/writer/admin）で決まり、トークンに含まれるか、grant によって追加されます。

<a id="the-identity-tuple"></a>

## アイデンティティタプル

すべての行は 5 つのアイデンティティ列を持ちます。

```
(org, namespace, agent, user_id, session_id)
```

| 要素         | 意味                                                                                         | デフォルト                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `org`        | テナント。ワイルドカードのオペレータートークンを使う場合を除き、org の境界を越えるものはありません。 | （必須。シングルユーザーモードでは下記のとおり自動で設定されます）                                    |
| `namespace`  | org 内での分離と共有の単位。すべての読み取りは `(org, namespace)` にスコープされます。       | （必須。シングルユーザーモードでは下記のとおり自動で設定されます）                                    |
| `agent`      | 行を書き込んだ主体（`support-bot`、`claude-code`）。作成者を表すもので、読み取りの境界ではありません。 | （必須。シングルユーザーの HTTP では一部の op で自動設定されます。[HTTP リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)） |
| `user_id`    | その行が対象とするエンドユーザー。                                                           | `-`                                                                                                   |
| `session_id` | 1 つの会話、または会話の 1 回の実行。                                                        | `-`                                                                                                   |

多くの操作は `run_id`（デフォルトは `-`）も受け取り、書き込みや読み取りを 1 回のタスク実行にスコープできます。トークンは、呼び出し元がアクセスできる org と名前空間を決めます。タプルの残りは各リクエストの本文で渡されます。SDK はクライアントの構築時に `(org, namespace, agent)` を束縛し、`user_id`、`session_id`、`run_id` は呼び出しごとに渡します。呼び出しで指定されなかったものは `-` になります。これらのフィールドが読み取りのフィルタとして働く場合（検索、ask、起動パック、会話や実行の一覧、`memory.update` のキー検索）、`-` はフィルタなしを意味します。run を指定しない検索は、すべての run の行を読み取ります。フィールドが行のアドレスとして働く場合（`memory.get`、`memory.list`、`memory.stack`、ワーキングメモリ、プロフィールの書き込み、保存されたメッセージ）、`-` はユーザー、セッション、run なしで書き込まれた行を指します。

**読み取りはすべての作成者にまたがります。** 読み取りのデフォルトは `agent="*"` で、誰が書いたかにかかわらず名前空間のすべての行が対象です。`agent` を渡すと絞り込むだけです。読み取りの `user_id` と `session_id` は、それらのもとで書き込まれた行にフィルタします。

**タプルがテーブルの先頭に来る理由。** `loom.memory` と `loom.memory_embeddings` のソートキーは `(org, namespace, agent, user_id, session_id)` で始まります。そのため、1 つの名前空間にスコープした読み取りは ClickHouse ではスキャンではなくプライマリキーの範囲読み取りになり、agent を指定するとさらに絞り込まれます。デフォルトであるエージェント横断の読み取りでは、名前空間の範囲内で `user_id` と `session_id` をフィルタします。キーによるこれらのグラニュールのスキップは agent 列が許す範囲にとどまり、スキップインデックスもありません。スコープした読み取りでも、その範囲にまたがる各パートの少なくとも 1 グラニュールは読み取ります（[スケール時のメモリ](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md#memory-at-scale)）。

<a id="what-the-server-stamps"></a>

### サーバーが付与するもの

さらに 2 つの列は、書き込みのたびにサーバーが決定し、リクエスト本文からは読み取られません。ただし、呼び出し元は `source_class` を格下げできます（`actor` は `server/memory/app/provenance.py`、`source_class` は `server/memory/domain/provenance.py`）。

| 列             | 値                                                                     | 決定元                                                                                                   |
| -------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `actor`        | `human:<subject>` または `process:<subject>`（サービスアカウント）     | 検証済みのトークン（`writer_actor`）。キューに入ったジョブや CLI のインポートは、それを開始したプリンシパルとして書き込まれます。 |
| `source_class` | `asserted`, `extracted`, `observed`, `derived`, `imported`, `external` | 操作と `source_trace` の規約（`source_class_for`）。                                                     |

リクエストが宣言できるのは `source_class` の格下げのみで、`external`（ツールやページからのコンテンツ）、`imported`、`derived` が対象です。それ以外を指定すると 422 になります。これは、来歴がランキングや `memory.ask` の根拠選択に使われるためです。呼び出し元がスクレイピングしたテキストに `asserted` を付けられるなら、そのラベルは意味を失います。`agent` は、システム内での役割を表すため呼び出し元が指定しますが、`actor` はその背後にある認証済みのプリンシパルです。

<a id="orgs-and-namespaces"></a>

## 組織と名前空間

**org**（組織）はテナントであり、**名前空間**は行を保持する場所であると同時に、アクセス権を付与する単位です。名前空間は、登録されたとき（`namespace.register`。呼び出し元がその `admin` になります）、サインアップ時に取得されたとき、サーバーによってプロビジョニングされたとき（シングルユーザー用の名前空間と、サインインした各ユーザーの `personal-<slug>` 名前空間）、またはインデックス化されたリポジトリ用に作成されたときに生まれます。`loom.namespaces` のディレクトリ行には、その設定として説明、種別、可視性、参加ポリシー、競合ポリシーと提案ポリシー、コスト上限、保持期間と取得のデフォルトが格納されます。

| 名前空間の種別 | 保持するもの                                     | 読み取り元                                                                   |
| -------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| `memory`       | ファクト、ドキュメント、会話：デフォルトの種別   | メモリ、ナレッジ、会話の各オペレーションとファンアウト                       |
| `code`         | インデックス化された 1 つのリポジトリとブランチ  | 名前で指定する `code.*` オペレーション。コードスコープ下の `loom_search`     |
| `bench`        | ベンチマーク用コーパス                           | ベンチマーク。そのトラフィックは `bench` に分類されます                      |

呼び出し元のすべての名前空間にまたがるファンアウト検索の対象は、`memory` 種別のみです（`LOOM_MEMORY_SEARCH_FANOUT_KINDS`）。個人的なファクトを探してすべてのコードインデックスを走査すると、インデックスごとにステートメントが発生するうえ、何も見つかりません。

**エージェントごとのストアではなく名前空間である理由。** よくあるケースは、複数のエージェントや人が同じファクトを参照すべき場合です。たとえば、チームのデプロイウィンドウや顧客の履歴です。名前空間を読み取りの境界にすると、その内側では共有がデフォルトとなり、外側との間では共有されません。人やボットにアクセスを与えるには、行をコピーするのではなく、名前空間でロールを付与します。

<a id="visibility-joining-and-restriction"></a>

### 可視性、参加、制限

| 設定                | 値                                              | 効果                                                                                                                                      |
| ------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `visibility`        | `private`（デフォルト）、`public`               | パブリック名前空間は `namespace.browse` に一覧表示され、参加できます。可視性だけでは読み取り権限は付与されません。                        |
| `join_policy`       | `open`、`approval`、`closed`、`inherit`（未設定） | `namespace.join` の動作を決めます。`inherit` は、承認を必要としないパブリック名前空間では `open` に、それ以外では `approval` に解決されます。 |
| `requires_approval` | `true`、`false`                                 | `inherit` の場合にのみ参照されます。すべての参加が管理者の承認（`grants.approve`）を待ちます。                                            |
| `classification`    | `standard`（デフォルト）、`restricted`          | 権限を広げるすべてのデフォルトを無効にします（後述）。                                                                                    |

`open` の名前空間では、`viewer` としての参加は即座に有効になり、`writer` または `admin` としての参加は管理者が承認するまで保留されます。`approval` では、すべての参加が保留されます。`closed` では参加が拒否されます。

**restricted** 名前空間（ディレクトリ行の `classification=restricted`、または `LOOM_CODE_REPOS_JSON` のエントリで指定）は、次の条件をすべて満たす場合にのみ呼び出しを受け付けます。トークンがその名前空間の組織に属していること、名前空間を（`*` ではなく）明示的に指定していること、オペレーションのロールに達するロールをそこで持っていること、そしてトークン自身のサブジェクトが有効な直接のグラントを持っていることです。組織で読み取り可能とするルール、パブリック可視性、ワイルドカード、継承されたサービスアカウントのグラント、`org_admin`、`platform_admin` のいずれによってもバイパスできず、拒否された場合でも名前空間が存在するかどうかは明かされません。ファンアウト、コンテキストパック、ロールアップは、呼び出し元が読み取れない restricted 名前空間をスキップし、受け付けた各リクエストは監査されます。セットアップ手順は[トークンとグラント](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md#restricted-namespaces-classificationrestricted)を参照してください。

<a id="roles"></a>

## ロール

ロールには順序があり、上位のロールは下位のロールに対するすべてのチェックを満たします。各オペレーションは必要な最小ロールを宣言しています（`GET /v1/operations` で確認できます）。

| ロール           | 付与される権限                                                                                    | 保持の方法                                                                                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `viewer`         | 読み取り。                                                                                        | トークンのクレームまたは名前空間のグラント。                                                                                                                                                  |
| `writer`         | 読み取りに加え、メモリ、ナレッジ、その他のデータプレーンへの書き込み。                            | トークンのクレームまたは名前空間のグラント。                                                                                                                                                  |
| `admin`          | 1 つの名前空間の管理：グラント、設定、ポリシー、リストア、共有レイヤーへの昇格。                  | トークンのクレームまたは名前空間のグラント。名前空間を登録すると、その名前空間の admin になります。                                                                                           |
| `org_admin`      | 組織全体のビュー（たとえば名前空間を指定しないコスト）。                                          | 認識されるゲートですが、製品内に割り当て手段はありません。                                                                                                                                    |
| `platform_admin` | 組織をまたぐオペレーター向けビュー。                                                              | ログイン時に `LOOM_PLATFORM_ADMINS` のハンドルと確認済みメールアドレスに付与され、`--platform-admin` で登録されたボットのトークンにも付与されます。サービスアカウントにのみ、有効期限付きで発行されます。 |

グラントが持てるのは `viewer`、`writer`、`admin` のみで、Loom が発行するトークンも同様です。ただし `platform_admin` のトークンは例外です。組織全体の権限は、設定またはボット登録時にオペレーターが決めるものであり、トークンに持たせて持ち出せるものではありません。コード名前空間には、リーダー（`viewer`）とメンテナー（`admin`）がいて、`writer` はありません。

<a id="who-may-call-what"></a>

## 誰が何を呼び出せるか

`(org, namespace)` に対する呼び出しは、名前空間が制限されていない（または制限付きのチェックを通過する）場合で、かつ、その名前空間に対するトークン自身のロールがオペレーションに必要なロールに達しているか、有効な付与（grant）のロールがオペレーションに必要なロールに達している場合に許可されます。

- **トークン**（`sub`、`org`、`namespaces`、`roles`、任意の `ns_roles` と `ns_write`）は、呼び出し元がどの名前空間を、どの優先順位で、どのロールで読み取るかを示します。**スコープ付き**トークン（`ns_roles`、名前空間ごとのロール）は、そこに列挙された名前空間に限って正式な情報となります。**フラット**トークンは、`roles` を名前を挙げたすべての名前空間に適用します。`ns_write` は書き込みを一部の名前空間に絞り込むため、1 つのトークンでチームの名前空間を読み取りつつ、自分専用の名前空間にだけ書き込むことができます。

  ```
  namespaces = ["team-shared", "agent-private"]
  ns_write   = ["agent-private"]
  ```

- **付与**（`loom.namespace_grants`、`(org, namespace, subject)` ごとに 1 行）は、トークンが持つロールに加えて、1 つの名前空間に対するロールを追加します。付与のロールがオペレーションに必要なロールに達している場合に、その付与は有効となります。
  - **クレームは付与を超えません。** サブジェクトがトークンの挙げる名前空間に対して、ステータスを問わず付与の行を持っている場合、クレームはその付与を超えません。取り消された付与や引き下げられた付与（`grants.revoke`、`replace=true` を指定した `grants.create`、`namespace.leave`、解放されたクレーム、リストア）は、そこでの古いトークンのクレームをすべて終了させ、保留中または却下されたリクエストは、アクセスなしに制限します。スコープ付きトークンはそこで自身のロールを保持しますが、有効な付与が上限となります。
  - **影響を受けないもの。** サブジェクトが一度も付与を持ったことのない名前空間では、クレームはそのまま保持されます。これを取り消すには、トークンを失効させてください。
  - **適用のタイミング。** 付与を変更したプロセスは直ちに適用し、それ以外のプロセスは、このサーバーでも別のサーバーでも、`LOOM_ACL_WATERMARK_POLL_SECONDS`（デフォルトは 1 秒）以内に適用します。
- **サービスアカウントは継承します。** ある名前空間に自身の付与を持たないサービスアカウントは、そこでは作成者の付与を使用します。そのため、ダッシュボードから発行されたトークンは、制限付きの名前空間を除き、それを作成した人に従います。
- **組織全体の ID で指定されるオペレーション**（`memory.get_by_id` など）は、その行を保持するスコープで呼び出し元を認可します。呼び出し元がその行の名前空間でオペレーションに必要なロールを持たない場合、行が存在しない場合と同じ応答を返すため、拒否によってその ID の存在が確認されることはありません（[行スコープのオペレーション](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#row-scoped-operations)）。

トークンと付与を併用する理由：トークンは呼び出しごとにルックアップなしでローカルに検証されるため、ホットパスを低コストに保てます。付与により、管理者はトークンを再発行せずにアクセスを与えたり取り上げたりできます。失効は ClickHouse を通じて共有され、失効キャッシュの間隔以内にすべてのレプリカへ反映されます。

<a id="reading-several-namespaces"></a>

## 複数の名前空間の読み取り

検索は複数の名前空間を一度に読み取れます。`namespace_scope` は `this`（指定した名前空間。デフォルト）または `all_mine`（指定した名前空間に、呼び出し元自身の名前空間を加えたもの）です。MCP の `loom_search` ツールと `context.pack` も同じファンアウトを使います。メモリ検索は、対象となった名前空間を `namespaces_searched` に列挙し（ティア検索は最後の名前空間に到達する前に止まることがあります）、上限のために除外された名前空間を `namespaces_skipped` に列挙します。

呼び出し元自身の名前空間はトークンによって異なります。

| トークン                                                       | `all_mine` が加える名前空間                                                                     |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| フラット（ほとんどのトークン。`loom mint-token`、セルフサインアップ）          | トークンが指定する名前空間と、サブジェクトが権限（grant）を持つすべての名前空間              |
| スコープ付き（`ns_roles`。_Only what you choose_ 用のトークン）     | トークンが列挙する名前空間そのもの。列挙された順。後から追加された権限は含まれません          |
| `*` による委任（_Everything you belong to_ 用のトークン） | 作成者の有効な権限。そのため、本人が後から参加した名前空間も検索されます               |
| 名前空間を指定した委任                                 | 指定された名前空間のうち、作成者が引き続き権限を持つもの                                        |
| なし、認証オフ（`single-user`）                              | 単一ユーザーが権限を持つ名前空間：デフォルトの名前空間と、ユーザーが登録したすべての名前空間 |

その後、一覧は次のように絞り込まれます。

- **種別。** `LOOM_MEMORY_SEARCH_FANOUT_KINDS`（デフォルトは `memory`）に含まれる種別の名前空間だけが対象になります。コードとベンチマークの名前空間は、名前を指定するか、専用のツールで読み取ります。例外は、コードスコープ下の MCP `loom_search` です。呼び出し元に読み取り権限がある場合、スコープされたリポジトリのトランクのコード名前空間も、そのドキュメントと決定事項のために読み取ります（[統合検索](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md#which-namespaces-it-reads)）。
- **制限付き名前空間** は、呼び出し元が制限チェックを通過した場合にのみ残ります。
- **上限。** 指定した名前空間のほかに、最大で `LOOM_MEMORY_SEARCH_FANOUT_MAX_NAMESPACES`（デフォルトは 32）個が、呼び出し元の一覧の順に読み取られます。順序は、スコープ付きトークンではその並び、委任トークンでは指定された一覧の並びで、それ以外は名前順です。スコープ付きトークンでは先頭から残ります。それ以外では、パブリックな名前空間がプライベートなものより先に切り捨てられます。メモリ、ナレッジ、会話の検索は、残りを `namespaces_skipped` に示し（ページング付きメモリ検索では全ページに示します）、`loom_search` はそのことをテキストで伝えます。読み取るには、名前を指定してください。

指定した名前空間は常に、最初に検索されます。ファンアウトは検索を広げるだけです。メモリ検索はその後、ティアで読み取ります。スコープ付きトークンでは、残りの名前空間がその順に続き、確信度の高い一致が見つかった最初の時点で検索を止めます。それ以外では、指定した名前空間とプライベートな名前空間を先に読み取り、パブリックな名前空間は、その最初のパスで結果が不足した場合にだけ読み取ります。

呼び出し元が読み取れても、その呼び出し元自身のものではなく、ファンアウトの対象にならない名前空間もあります。`*` クレーム、組織ロール、プラットフォームロールを通じて到達するもの、参加していないパブリックな名前空間、書き込みによって作成した名前空間です（これらにはオーナー行は作られますが権限は付かないため、タスクごとに名前空間へ書き込むハーネスが、以降のすべての検索を広げてしまうことはありません）。これらは名前を指定して読み取ってください。検索の対象は、トークン自身の 1 つの組織に限られます。

<a id="read-scope-inside-a-namespace"></a>

## 名前空間内の読み取りスコープ

メンバーシップは読み取りの境界です。これはチームで共有するメモリには適していますが、1 つのトークンで多数のエンド ユーザーに応対する 1 つのエージェントには適していません。あるユーザーのプロンプトが、別のユーザーのメモリを回答に引き出してしまう可能性があるためです。`read_scope` は、名前空間内での読み取りの範囲を制限します。

| `read_scope`          | 読み取りが返す内容                                    |
| --------------------- | ----------------------------------------------------- |
| `namespace`（デフォルト） | 名前空間のすべての行                                  |
| `own_user`            | リクエストが指定する `user_id` で書き込まれた行       |
| `own_session`         | リクエストが指定する `session_id` で書き込まれた行    |

`memory.search`、`memory.search_trace`、`memory.ask`、`memory.recall`、`context.pack`、`namespace.inventory`、`profile.render`、`profile.structured` がこれを受け取ります。`profile.structured` は `own_session` を拒否します。ユーザーのプロファイルは複数のセッションにまたがるためです。トークンは `read_scope` クレーム（および固定の `read_user_id`）を持てます。これは上限として働き、リクエストは範囲を狭めることはできますが、広げることはできません。スコープ付きの読み取りで、バインド先の `user_id` または `session_id` がない場合は、黙って範囲を広げずに `IDENTITY_INCOMPLETE` で拒否されます。複数ユーザーを扱うエージェントには `own_user` トークンを発行してください。

どちらのトランスポートも、呼び出しを受け付ける時点でスコープを一度だけ解決し、その呼び出し内のメモリ行の読み取りはすべて、どの op が読み取る場合でもそのスコープを引き継ぎます。対象は `memory.get`、`get_by_id`（別のユーザーの id には `found=false` を返します）、`list`、`bulk_get`、`history`、`timeline`、`related`、`evidence`、`conflicts.list`、`memory.proposals`、セッション ブリーフ、ダイジェスト、手順、ワーキング メモリ、`loom_search` の各レッグです。`namespace` より狭いスコープでは、次のようになります。

- `user_id="*"` は `AUTH_INSUFFICIENT` で拒否されます。`own_session` での `session_id="*"` も同様です。
- `read_user_id` で固定されたトークンは、書き込みを含めて、そのユーザーとしてのみ動作します。別の `user_id` を指定した本文はすべての op で `AUTH_INSUFFICIENT` により拒否され、何も指定しない（または `-`）本文は固定されたユーザーとして実行されます。
- 書き込みの応答は、スコープ外の行を示しません。別のユーザーの行へのマージ、その行の重複、その行との固定された競合は、その行の id、ハッシュ、キーを含めずに判定だけを報告し、`conflicts.list` は `conflict_with` からそのような相手を除外します。固定された行は、あらゆるユーザーによる近接した書き込みを引き続きブロックします（名前空間全体の不変条件）。競合距離内に他のユーザーの固定された行があれば、書き込み側自身の行がそれより近くにいくつあっても、その行を示さずに書き込みを拒否します。範囲を狭められた書き込み側のチェックは、自身のスコープ付き読み取りに加えて名前空間の固定された行（その型はメモリ行から取得）を読み取るため、コストは名前空間全体の書き込み側のせいぜい約 2 倍です。遅延された `memory.set_from_messages`（`defer=true`、または `extraction_defer_agents`）は、リクエストのスコープを一緒に保存し、そのスコープで再実行されます。別のユーザーの `run_id` での `run.begin` は、新しい id で新しい実行を開始し、それに対する `run.complete` は `NOT_FOUND` を返します。呼び出し側が指定した id での begin は、ClickHouse Keeper（`loom.agent_run_claims`）でその id を確保し、実行行が書き込まれた時点で確保を解放するため、同じ id に対する 2 人のユーザーの同時 begin のうち、保持できるのは 1 人だけです。行の書き込み前に失敗した begin は確保を保持し続けるため、他のユーザーの begin がその id を取ることはありません。Keeper が失敗している間、begin は実行行のみを確認します。その間、範囲を狭められたトークンは、指定した id を自分の既存の実行を再度開く場合にのみ保持でき、新規の実行にはサーバーが生成した id が割り当てられます。そのため、id を自前で生成するクライアントは、返された `run_id` を使う必要があります。
- セッション ブリーフはユーザーごと（`own_session` ではセッションごと）に保持されます。2 人のユーザーが同じ `brief_key` を保存すると 2 つのブリーフができ、それぞれ自分のものだけが見えます。名前空間全体のトークンは、`~<user>~`（または `~<user>~<session>~`）を接頭辞としたキーでそれらを一覧します。
- `code.search` は、本文が指定する `user_id` に関係なく、スコープ自身のユーザーの最近のファイルで同順位を解決します。
- `memory.search` の用語レッグは、どの読み取りスコープでも管理された定義を返します。管理者が名前空間のすべての読み取り側に向けて公開したものだからです（[検索における管理された定義](#governed-definitions-in-search)）。
- スコープで範囲を制限できない `context.pack` のレッグ（ユーザーを持たない会話と、ユーザーのすべてのセッションを読み取る実行マニフェスト）は、何も返しません。
- `namespace.inventory` は、メモリと実行、およびそのメモリ行上のエージェント、作成者、サブジェクトをスコープ内で数えます。ドキュメントとメンバーは名前空間全体で数え（`knowledge.*` と `grants.list` の読み取りと同じ）、レコード（キーごとに 1 件で、最後に書き込んだ人を問わない）と連携（`webhook.list` は拒否される）は、カウントされないものとして示します（`complete: false`）。
- ブラックリスト パターンはすべてのユーザーの書き込みを拒否しますが、ユーザーを記録しません（その `created_by` はトークンのサブジェクトで、1 つのバックエンドのユーザーごとのトークンすべてで共通です）。そのため、すべての `blacklist.*` op は `AUTH_INSUFFICIENT` で拒否されます。パターンの追加、一覧、削除、スイープは名前空間全体のトークンで行います。パターンは範囲を狭められたトークンの書き込みを引き続き拒否し、その 422 にはパターン id も理由も含まれません。
- `policy.decisions` は、呼び出し側自身の判定のみを一覧します。`memory.unlock` と `memory.unpin`（管理者）は、`memory.lock` と同様に、呼び出し側自身の行にのみ作用します。
- 応答を 1 人のユーザーに限定できない op（エンティティ グラフの `facts.*`、`conversation.*`、名前空間のエクスポート、管理およびキュレーションの op、`ops.projection_failures.*`、`erasure.*`、`audit.list`、`cost.agent_summary`、`agents.connected`）は `AUTH_INSUFFICIENT` で拒否されます。ユーザーをキーに持たないテーブルへの書き込みも同様で、別のユーザーの行を上書きしてしまうためです。対象は `memory.record.write`、`decision.record`、`procedure.record_run`、`context.offload` です。`memory.set_from_messages` は、レコードへの `record_schema` の投影をスキップし、そのことを `degraded` で伝えます。スコープが解決されないトークン（`own_session` が上限なのに本文にセッションがない場合や、固定されていない `own_user` トークンで本文にユーザーがない場合）は、ユーザー `-` として実行されることなく、スコープ対象のすべての読み取りと、本文にユーザーまたはセッションを含むすべての書き込み（および `cost.summary`）で拒否されます。そのため `own_session` では、セッション フィールドを持たない op（`cost.summary`、`memory.outcome`）は常に拒否されます。コード インデックスの op（`code.*`）は帰属のためだけにユーザーを持ち、受け付けられますが、その中でのメモリの読み取りは拒否されます。名前空間全体のルール（`policy.set`、`policy.delete`、`memory_schema.register` / `propose` / `approve`、`blacklist.*`）には名前空間スコープのトークンが必要で、`policy.check` も同様です。これは、呼び出し側のルールをすべてのユーザーの呼び出しに対して評価するためです。一覧は `server/identity/domain/read_scope.py`（`SCOPED_OPS`、`NARROW_SAFE_OPS`）にあり、そこに挙げられていない op は拒否されます。

<a id="agent-written-rows-and-the-shared-layer"></a>

## エージェントが書き込んだ行と共有レイヤー

名前空間内では、`loom.memory` の行は完全なタプルをキーとします。同じ `memory_key` を 2 つのエージェントが書き込んだ場合、または 2 人のユーザーのために書き込んだ場合は、2 つの行になります。これがエージェントごとの（「プライベート」）レイヤーであり、`memory.search` がデフォルトで読み取る対象です（`scope="private"`）。ここでの「プライベート」は「昇格されていない」ことを意味し、「隠されている」ことではありません。`read_scope` で絞り込まない限り、名前空間のすべての読み取り側がこれらの行を読み取れます。

**共有レイヤー**である `loom.shared` は、`(org, namespace, memory_key)` ごとに 1 行を保持します。これは、その事実を学習したエージェントのものではなくなった、名前空間が所有する正規版です。`memory.promote` は、根拠と任意の承認者を付けて行をこのレイヤーにコピーします。`memory.demote` はその行を退役させます（レスポンスには、昇格の `reversible_for_days` ウィンドウ内で行われたかどうかが示されます。デフォルトは 7、最大は 90 です）。`scope="shared"` の検索はこのレイヤーを読み取り、`memory.lineage` は共有行をたどって昇格まで遡ります。`memory.promote` と `memory.demote` には `admin` が必要です。`memory.cross_promote` は、両方の名前空間で admin である呼び出し元のために、出所情報を付けて行を別の名前空間にコピーします。

`definition` が昇格されるのは、次の場合に限られます。

- `definition/` キーの下にある、名前空間全体に適用される有効な行（エージェント、ユーザー、セッションが `'-'` で、`active` であり、supersession で退役しておらず、`expires_at` や `valid_to` を過ぎていないもの）から、同じキーへ昇格する場合。別の型の行が `definition/` キーの下で昇格されることはありません。そうでない場合は 422 `DEFINITION_PROMOTION_REFUSED`。
- 承認するハッシュ（`approved_sha256`、行の `content_sha256`）を伴う場合。ハッシュがなければ拒否され（422 `VALIDATION_FAILED`）、テキストがそのハッシュを持たなくなっていれば 409 `PRECONDITION_FAILED` になります。
- 値が、空でない文字列の `term` と、任意で文字列の `aliases` のリストを持つ JSON オブジェクトである場合。そうでない場合は 422 `VALIDATION_FAILED`。
- `medium` とラベル付けされておらず、`medium` または `high` と判定されてもいない場合（422 `SENSITIVE_DEFINITION_REFUSED`。`high` のラベルは、どの行でも同様に、先に `HIGH_SENSITIVITY_PROMOTION_REFUSED` を返します）。
- `memory_shared_definitions_max` の範囲内である場合。上限にある状態での新しいキー、または名前空間が上限を超えている間の昇格はすべて拒否されます（409 `DEFINITION_CEILING`）。
- 他の有効な共有 definition が term またはエイリアスとして保持していない名前の場合（409 `DEFINITION_NAME_TAKEN`。キーと名前が示されます）。名前は畳み込んで比較されます。書式文字を除去し、NFKC、空白の圧縮、大文字小文字の畳み込みを行い、再度 NFKC を適用します。

1 つの名前空間における definition の昇格（上限と名前のチェックを含む）と definition の降格は、1 度に 1 つずつ実行され、最後に実行されたものが definition を共有するかどうかを決めます（別の処理が 10 秒を超えて名前空間を保持している場合は 503 `OVERLOADED`）。definition を降格すると、その名前と枠が戻ります。トークンのアクターが `promoted_by` になります。`approver` と `promoted_from_candidate_id` は無視され、`ignored_args` に示されます。別のキーの下にある近い共有行があっても、拒否されることはありません。`learnings.review` は、型が `definition` の候補をメモリに昇格しません。

共有 definition が**管理下**にあるのは、ちょうど 1 つの行、つまりそのキーの下にある名前空間全体の行から昇格されており、その行が `active` で、supersession で退役しておらず、`expires_at` や `valid_to` を過ぎておらず、ラベル付けも判定も `medium` や `high` ではなく、共有コピーが保持するテキストと同じテキストを持っている間です（両方の提供ハッシュで比較するので、オブジェクトのキーを異なる順序で並べるストアでも差になりません）。編集、`medium` または `high` への再ラベル、またはソースの tombstone によって管理下ではなくなります。編集を承認済みのテキストに戻すと、新たな昇格なしに再び管理下になります。`memory.search` は、名前空間全体のソースがなくなっている（削除された、または有効期限スイープで tombstone になった）か、ソースに `medium` または `high` のラベルが付いている共有 definition を除外します。共有コピーには独自のラベルがないためです。ソースを読み取れない場合は、すべての共有 definition を除外します。名前空間全体の行以外の行から昇格されたコピーは、そのキーの下にある名前空間全体の行によって判断されます。その行がなければ保留され、あればその行のラベルに基づいて提供されます。コピー自体は残ります。ラベルを戻す、またはソースを書き直すと再び提供され、`memory.demote` はそれを退役させます。`memory.definitions.list`（admin）は、名前空間の有効な共有 definition を、昇格が新しい順に、最大で `memory_shared_definitions_max` の 2 倍まで一覧し、全体の件数を `count` に示します。各エントリにはキーと `promoted_at` が含まれ、上限内のエントリにはさらに term とエイリアス、`verdict`（`governed` または `lapsed`）、`lapse_reason`（`not_namespace_wide`、`no_term`、`gone`、`superseded`、`conflicted`、`duplicate`、それ以外のステータスの `not_active`、`expired`、`valid_to` を過ぎた `ended`、`changed`、`sensitive`）が含まれ、管理下のものには `lost` も含まれます。これは、その名前を保持する別の管理下の definition に負けた各名前を、`name` と `winner` のキーで示したものです（最新の昇格が勝ち、同時の場合は昇格イベントで決まります）。上限を超えたものは `capped` となり、そのソースは読み取られません。

<a id="governed-definitions-in-search"></a>

### 検索における管理下の definition

`memory.search` は、クエリがその term またはエイリアスのいずれかを指している場合、管理下の definition を `governed: true` を付けて先頭に提供します。この term レグは `memory.search` が動作するあらゆる場所で実行されます。`memory.ask` と `context.pack` の内部、および `loom_search` のメモリセクションも含まれます。

- **読み取る内容。** `namespace_scope` がどこに展開されるかにかかわらず、対象の名前空間の有効な共有 definition の名前のみを、最大で `memory_shared_definitions_max` 件まで読み取ります（超えた場合は、昇格が新しいものが対象で、`term_leg` は `capped` になります）。クエリが指している definition と、それと名前を共有する definition については、完全な値を読み取り、ソースを読み取って評価し、それ以外は読み取りません。逐次一貫性はなく、直前に別のレプリカで行われた昇格が検索に反映されないことがあります。他のレグと並行して実行され、それらが完了した後、検索はこのレグのためにさらに最大 `memory_term_leg_wait_ms` だけ待ちます（再入パスは残り時間を超えません）。検証のための正規化、名前の比較、本文のデコードにも、固定の作業予算の上限があります。作業が過剰な場合は、レグ全体が `timed_out` として保留されます。保存された definition と昇格のルールは変わりません。
- **マッチング。** クエリと各名前は、書式文字が除去され、NFKC と空白の圧縮を通ります。結合文字は直前の文字または数字に結合されます。名前は、その端を続ける隣接文字がない完全な文字単位でマッチします。ラテン文字、数字、`_`、`+`、`#` の隣では、それらのいずれか。スペースで区切って書く別の文字体系（キリル文字、ギリシャ文字、デーヴァナーガリー）の文字の隣では、ラテン文字以外の任意の文字または任意の数字。ハングルの前ではハングルの文字、その後ろでは何も続かない（助詞が続くため）。漢字、かな、タイ文字、ラオ文字、クメール文字、ミャンマー文字、または句読点の隣では、何も続かない。したがって、`MRR` は「什么是ＭＲＲ」にマッチし、`ARR` は「ARR은」にマッチしますが、`рост` は「простой」の内部にはマッチしません。大文字小文字は名前の単語ごとに判断されます。すべて大文字の単語、または最初の文字以外に大文字を含む単語は、書かれたとおりにのみマッチします（`IT` は「what is it」にマッチしません）。それ以外は大文字小文字を畳み込んでマッチします。
- **配置。** 名前が指された definition は、クエリ内で名前が最初に現れる順に提供リストの先頭に置かれます。2 つが同じ位置で始まる場合は長い名前が先で、その次に最新の昇格が続きます。導出された集計の計算済みの行は、それらの上に残ります。対象の名前空間内で同じキーを持つ他のヒットは除外されます。これらは `top_k` の範囲内で数えられ、最後に切り捨てられます。切り捨てられたもの（管理下のヒット、またはそれに押し出されたヒット）は、次のページの先頭になります。保留された管理下のヒットは、提供される前に、元のクエリ、現在の昇格、ソースに照らして再度チェックされます。読み取れないチェックがあれば保留されます。本文全体は `body_budget_tokens` の範囲内で数えられ、収まらない definition は切り詰め済みと示された抜粋を保持します。下限、しきい値、後段のステージによって、それらが除外されたり並べ替えられたりすることはありません。`min_similarity`、キャリブレーション、`loom_search` の下限と answer-first ルール、トラッカー判定のメモリ上限（その範囲内で数えられます）、`context.pack` のパッキング、`memory.ask` の再掲値のチェックも対象外です。
- **スコア。** `similarity` と `distance` は definition の共有埋め込みの値です（埋め込みがない場合は `0` と `1`）。`rank_score` は計算済みの行を除くすべてのヒットより上で、`below_threshold` が設定されることはありません。definition を提供したレスポンスでは `abstain` が false になります。`retrieval_confidence` と `retrieval_risk` は他のヒットについて示します。
- **オフになる場合。** ページハンドル、および他の行を求めるフィールドがある場合です。`memory_type`、`tags`、`category`（`tags_soft` または `category_soft` を伴う場合を除く）、`as_of`、`min_body_chars`、0 より大きい `recent_first` または `anchor_first`、`memory` を含まない `legs` が該当します。無効な Unicode のクエリは、制限付きの Unicode チェックがそれを読み取った時点でオフになります。そのチェックの作業上限を超えるクエリは、検証の前に `timed_out` を報告します。誰の行を読み取るかを指定するフィールド（`agent`、`user_id`、`session_id`、`session_ids`、`run_id`、`scope`）ではオンのままで、`exclude_keys` はそのキーを除外します。
- **`term_leg`** はレスポンス上で、このレグが何をしたかを示します。`complete`、`empty`（definition なし）、`capped`、`timed_out`、`failed`（読み取りが失敗したため何も提供されなかった）、`off` のいずれかです。
- **スコープ。** 管理下の definition は、どの読み取りスコープでも、デフォルトの `scope` である `private` でも提供されます。admin が名前空間のすべての読み取り側に向けて公開したものだからです。
- **ミス。** 管理下の definition を提供した検索、またはレグが `complete` や `empty` を報告しなかった検索（`off` を含む）では、[ナレッジギャップ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/knowledge-gaps.md#recording-misses)のミスは記録されません。
- **保存された回答。** 昇格と降格は名前空間のメモリ書き込みマークを進めるため、マークが反映された後は、それ以前の回答を `memory.ask` が再利用することはありません。

2 つのレイヤーがある理由：エージェントは自分の ID で自由に、しばしば冗長に書き込みますが、名前空間全体が依拠すべき整理された事実には、1 つの正規キー、オーナーの判断、監査証跡が必要です。昇格がその判断です。

<a id="identity-modes"></a>

## ID モード

呼び出し元がそもそもどのようにトークンを取得するかは、デプロイの ID モード（`LOOM_IDENTITY_PROVIDER`）で決まります。

- **`single-user`**：認証なし。名前空間を指定しない呼び出しは、MCP では `code.*` を除くすべての op で、組織 `LOOM_SELF_SIGNUP_ORG`（デフォルトは `dev`）内の 1 つの名前空間（`LOOM_DEFAULT_NAMESPACE`、デフォルトは `local`）に解決されます。HTTP では、トークンのない呼び出しは `code.*` と `tracker.*` を除くすべての op で組織を取得し、日常的なメモリ操作と検索の op では名前空間も取得します。どの op が対象か、またそれぞれが得るエージェントについては、[HTTP リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)を参照してください。`all_mine` 検索は、ユーザーが登録した名前空間も読み取ります。ラップトップ専用です。
- **`trust-network`**：メールアドレスとパスワードによるセルフサインアップ。名前空間名を最初に要求したプリンシパルがその所有者になります。エージェントは自分でサインアップでき（`loom init --agent`）、人間は出力されたコードを使って後からそれを要求できます。このコードは 1 回限り有効で、その人自身のパスワードに置き換えられます。
- **`gateway`**：上流の ID レイヤーが人を認証し、共有シークレットで有効期間の短い Loom トークンを発行します。Loom は検証のみを行います。`LOOM_TRUSTED_CALLERS` に含まれるサブジェクトは、`X-Loom-On-Behalf-Of` を使ってエンドユーザーの代理として動作でき、すべての台帳の行には実際の呼び出し元が記録されます。ユーザーが Loom アカウントを持たないサービスは、代わりに `user:<id>` 用の有効期間の短いトークンをリクエストごとに署名します。そのために、エンドユーザー発行者として登録されたキーを使います（[サービスのエンドユーザーの代理として動作する](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md#act-for-a-services-end-users)）。

<a id="collections"></a>

## コレクション

コレクションは `col-…` という名前の名前空間で、アクセスを開くのは付与（grant）だけです。トークンのクレームや org admin ロールでは到達できません。コレクションは別のコレクションの内側に置いて、その付与を継承でき、付与には、個人やサービスアカウントのほかに、`user:`、`group:`、`agent:` のプリンシパル、または `everyone`（org 内で動作するすべてのリクエスト）を指定できます。ユーザーはコレクションをタイトルで呼び、サーバーはそこから `col-…` という名前を導出します。この名前は、その後もずっとコレクションのアドレスです。[ナレッジの共有](https://github.com/ClickHouse/loom/blob/main/docs/architecture/sharing.md)で、このモデルと名前の導出方法を説明しています。ユーザーはライブラリで、コレクションをコレクションとして、そのタイトルと配置場所で見ます。コレクションを格納する名前空間は、付与、検索スコープ、監査、消去の対象を決めるキーであり、ダッシュボードの名前空間ピッカーには表示されません。

`acl-` と 24 桁の16進数からなる名前の名前空間はミラーです。ストアの権限に従うドキュメントソースのドキュメントを保持し、各ドキュメントはストアが許可した閲覧者にだけ表示されます（[ドキュメントソース](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror)）。どのトークンもミラーには到達できず（消去だけがプラットフォーム管理者によって指定されます）、`namespace.register` と `namespace.restore` はこの形式を拒否します。

`LOOM_IDENTITY_PROVIDER` が空の場合、サーバーはモードを推定します。認証がオフなら `single-user`、認証がオンで `LOOM_SELF_SIGNUP=open` なら `trust-network`、認証がオンでそれ以外なら `gateway` になります。サインアップを開いたままループバック以外にバインドする場合も、`trust-network` を明示的に設定する必要があります。各モードの設定は[デプロイ](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#identity-modes)に記載しています。

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

## 関連ドキュメント

- [トークンとグラント](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md)：発行、クレーム、グラント、制限付き名前空間、履歴ポリシー、失効を手順に沿って説明します。
- [名前空間と共有](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md)：名前空間の操作と、ダッシュボードの共有ビューを説明します。
- [セキュリティ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md)：認証と認可がどのように強制されるかを説明します。
- [メモリ](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md)：タプルが指し示す行について説明します。
