init

4-client.md

@@ -0,0 +1,61 @@
+# 4. クライアント
+
+## 役割
+
+Clientは、Hostが提供するWorldspaceをユーザーへ提示する実装主体である。WIPのCore Protocolを直接利用しつつ、用途に応じたViewやAPIへ投影する。
+
+ClientはHostから得た情報をそのまま一時表示するだけでなく、これまでに発見したエントリを保持し、ユーザーから見た**既知の空間**を構成する。
+
+## Known Space
+
+Clientは、これまでに発見したエントリをKnown Spaceとして保持・キャッシュしてよい。
+
+Known Spaceには、次のような経路で得られたエントリが含まれる。
+
+- `fetch`または`fetch_tree`で取得したエントリ
+- Operationの結果として返されたエントリまたはエントリツリー
+- Operation結果に含まれるLinkから発見したエントリ
+
+既知エントリ間の移動や参照はClient側で処理できる。既知の空間を辿るたびにHostへ問い合わせる必要はない。
+
+## Discoverable Space
+
+Clientは、Hostから`fetch_tree`で取得したindexableなエントリツリーをDiscoverable Spaceとして保持してよい。
+
+Discoverable SpaceはKnown Spaceの部分集合であり、AI向け`discover`などの機械的探索に利用する。
+
+OperationやLinkを通して偶発的に発見されたエントリはKnown Spaceには追加されるが、それだけではDiscoverable Spaceには追加しない。そのエントリを起点として`fetch_tree`を取得した場合に、そのindexableな範囲をDiscoverable Spaceへ追加できる。
+
+## Tree取得
+
+Clientは、機械的にエントリを探索する必要がある場合、個別の`fetch`を多数発行するのではなく`fetch_tree`を利用する。
+
+`fetch_tree`では起点エントリ、探索深度`depth`、返却エントリ総数の上限`limit`を指定する。Hostはindex edgeを幅優先探索してTreeを返す。
+
+レスポンスが`truncated`である場合、Clientは取得したTreeが完全ではないことを保持し、完全な空間として扱ってはならない。
+
+件数の非常に多いCollectionの個々の要素は、通常indexableな子エントリとして露出しない。個別要素はCollection Objectの`query`や`list`等のOperationを通して発見することを想定する。
+
+## Objectの同一性
+
+Objectが`ref`を公開している場合、Clientはそれを用いて複数のエントリや複数回の観測が同一Objectを指していることを追跡できる。
+
+`ref`はHost内部のIDそのものとは限らず、WIP上でObjectを再参照するための外部Handleとして扱う。
+
+## 観測整合性
+
+Clientは、エントリを観測した後にOperationを実行するまでの間に、そのエントリが別Objectを指すようになっていないことを検証する責務を持つ。
+
+この検証に必要なopaque token、generation、ETag等はClient / Host間で透過的に扱い、AIやユーザーに直接管理させる必要はない。
+
+対象が変化していた場合、Clientは新しいObjectに対してOperationを自動再試行せず、対象が変化したことを上位インターフェースへ通知して再観測を要求する。
+
+## 想定実装
+
+Clientは用途に応じて複数の上位インターフェースを提供できる。
+
+- GUI上のWorldspace View
+- AI向けTools
+- PTC / REPL向けスクリプティングAPI
+
+これらは同一のKnown Space、Discoverable Space、Object identity、観測整合性管理を共有してよい。