# 4. クライアント ## 役割 Clientは、Hostが提供するWorldspaceをユーザーへ提示する実装主体である。WIPのCore Protocolを直接利用しつつ、用途に応じたViewやAPIへ投影する。 ClientはHostから得た情報をそのまま一時表示するだけでなく、rootからindexable edgeを辿って構成したエントリツリーと、必要に応じて選択したエントリを保持し、ユーザーから見た**既知の空間**を構成する。 ## Known Space Known Spaceは、Clientが**現在保持しているエントリの集合**である。過去に発見したすべてのエントリを単調に蓄積する集合ではない。 Known SpaceとDiscoverable SpaceはClientが過去の観測から構築したcacheであり、Host上の現在状態を同期したreplicaではない。HostはClientのcache状態を追跡または更新しない。 次のような経路で得られたエントリをKnown Spaceへ追加できる。 - `fetch`または`fetch_tree`で取得したエントリ - Operation結果の`entry`型pathを`fetch`して取得したエントリ Operationを通して発見されたpathは、必ずしもKnown Spaceへ追加する必要はない。Clientは現在の結果として一時的に扱うことも、取得後に必要なエントリだけを選択して保持することもできる。 既知エントリ間の移動や参照はClient側で処理できる。既知の空間を辿るたびにHostへ問い合わせる必要はない。 ## Discoverable Space Clientは、Hostから`fetch_tree`で取得したindexableなエントリツリーをDiscoverable Spaceとして保持する。Discoverable Spaceとして扱う間、Clientはそのtreeの構造を保持する必要がある。 Discoverable SpaceはKnown Spaceの部分集合であり、AI向け`discover`などの機械的探索に利用する。Worldspace rootまたはClientが選択した起点からindexable edgeで到達できる、materialize済みの範囲によって構成される。 Clientが`fetch_tree`を再実行した結果、以前存在した親のindexable edgeが返されなくなった場合、その子エントリをDiscoverable Spaceから除外する。その結果、保持しているどの起点からも到達不能になったsubtreeは、その場で破棄できる。ただし、別の経路から到達できるエントリ、Clientがpinしたエントリ、実行中のOperationが参照しているエントリは引き続き保持してよい。 Operationを通して発見されたpathは、それだけではDiscoverable Spaceへ追加しない。そのエントリを起点として`fetch_tree`を取得した場合に、そのindexableな範囲をDiscoverable Spaceへ追加できる。 ## 一時的な発見とpin Clientは、Operation Resultの`entry`型として発見したpathを現在の結果として一時的に扱える。標準的なClientはoutput schemaからentry pathを抽出して重複を除去し、必要なpathの公開情報を取得する。Transportがbatch fetchやinvoke responseへの同梱を提供する場合は、それを利用してround tripを削減してよい。 一時的に取得したエントリは、結果の利用が終わった時点で破棄してよい。 後続のInteractionでも必要なエントリは、Client側でpinしてKnown Spaceへ保持できる。PinはClient内部の保持方針であり、Host上のObject lifetimeやCore Protocol上の状態を変更しない。 単純なClientは発見したエントリをすべて保持してもよいが、WIPはそれを必須としない。具体的な容量制限やeviction algorithmはClient実装に委ねる。 ## 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、観測整合性管理を共有してよい。