wip-reference/2-core-model.md

# 2. コアモデル

## 基本構造

Worldspaceは、LLMが探索できる**ObjectのTree**として公開される。

WIPではObjectとエントリを別の構造として定義しない。**ObjectをWorldspaceのTree上の位置として扱うとき、そのObjectをエントリと呼ぶ。**

したがって、ObjectはTree上で親子関係を持ち得るし、途中のNodeもそのまま操作対象になってよい。例えば`articles`はCollection Objectとして`query`等を公開でき、その配下に個別Articleが配置され得る。

## Object / エントリ

**Object**はWIP上で観測・操作される対象そのものである。

**エントリ**は、そのObjectをTree上の位置として見たときの呼び名である。

エントリがObjectへの参照を別途持つ、という二重構造は前提としない。

Tree上の位置はpathで表される。Pathは恒久的なIdentityではなく、その時点でのnavigation coordinateである。

同じObjectが複数の位置に現れる場合、一つのObjectが複数のエントリとして観測され得る。

## `ref`

Objectは必要に応じて`ref`を公開できる。

`ref`は内部IDそのものではなく、WIP上で同一Objectとして再参照するための外部Handleである。

- Objectが`ref`を持つことは必須ではない。
- 複数回のInteractionを通して同一Objectとして扱われることを意図する場合、同じ有効な`ref`を公開する。
- `ref`のscopeや有効期間はWorldspaceまたは実装が定めてよい。
- `ref`はグローバルかつ永続的なUIDである必要はない。
- 同じObjectが複数のエントリとして観測される場合、同じ`ref`によって同一性を示せる。

## 観測整合性

エントリ自体をObjectとは別実体として扱う必要はない。ただし、あるpath上のObjectを観測した後、Operationを実行するまでの間に、そのpathが別のObjectを指すことはあり得る。

その場合、Client / Runtimeは、以前のObjectを対象としたOperationを新しいObjectへ黙って適用してはならない。実行前に観測時の対応関係を検証し、変化していればOperationを中止する。この性質を**observation consistency**と呼ぶ。

例えば、AIが`/issues/current`を観測した時点ではIssue Aだったが、`invoke`時にはIssue Bへ差し替わっていた場合、AIはIssue Aへ作用するつもりでIssue Bを操作してしまう可能性がある。

この観測整合性は利用者に追跡させるのではなく、クライアントの責務とする。

処理の流れは次の通り。

1. Clientがpath上のObjectを観測する。
2. Clientはその時点のpathとObjectの対応を内部的に記録する。
3. モデルは観測したObjectについて推論する。
4. モデルが同じpathを対象に操作を要求した場合、Client / Runtimeは実行前に対応関係が変化していないことを検証する。

実装はETagやgeneration、opaque token等の内部メタデータを用いてよいが、それらを利用者へ露出する必要はない。

対応関係が変化していた場合、Clientは新しいObjectに対して操作を自動的に再試行してはならない。操作を中止し、`target_changed`のような意味的エラーを返して再観測を要求する。

## 同一性と観測整合性の分離

WIPでは次の2つを分けて扱う。

- **Object identity (`ref`)**: 複数の観測にまたがって同一Objectであることを明示するための任意の外部Handle。
- **Observation consistency**: `ref`の有無に関わらず、観測したpath上のObjectと操作対象のObjectが一致していることをClient / Runtimeが保証する仕組み。

したがって、`ref`を持たないObjectであっても安全な操作対象になり得る。`ref`は同一性を公開する仕組みであり、Observation consistencyは操作の安全性を担保する仕組みである。