docs: define operation IDL and entry discovery

4-client.md

@@ -4,27 +4,40 @@
 
 Clientは、Hostが提供するWorldspaceをユーザーへ提示する実装主体である。WIPのCore Protocolを直接利用しつつ、用途に応じたViewやAPIへ投影する。
 
-ClientはHostから得た情報をそのまま一時表示するだけでなく、これまでに発見したエントリを保持し、ユーザーから見た**既知の空間**を構成する。
+ClientはHostから得た情報をそのまま一時表示するだけでなく、rootからindexable edgeを辿って構成したエントリツリーと、必要に応じて選択したエントリを保持し、ユーザーから見た**既知の空間**を構成する。
 
 ## Known Space
 
-Clientは、これまでに発見したエントリをKnown Spaceとして保持・キャッシュしてよい。
+Known Spaceは、Clientが**現在保持しているエントリの集合**である。過去に発見したすべてのエントリを単調に蓄積する集合ではない。
 
-Known Spaceには、次のような経路で得られたエントリが含まれる。
+次のような経路で得られたエントリをKnown Spaceへ追加できる。
 
 - `fetch`または`fetch_tree`で取得したエントリ
-- Operationの結果として返されたエントリまたはエントリツリー
-- Operation結果に含まれるLinkから発見したエントリ
+- Operation結果の`entry`型pathを`fetch`して取得したエントリ
+
+Operationを通して発見されたpathは、必ずしもKnown Spaceへ追加する必要はない。Clientは現在の結果として一時的に扱うことも、取得後に必要なエントリだけを選択して保持することもできる。
 
 既知エントリ間の移動や参照はClient側で処理できる。既知の空間を辿るたびにHostへ問い合わせる必要はない。
 
 ## Discoverable Space
 
-Clientは、Hostから`fetch_tree`で取得したindexableなエントリツリーをDiscoverable Spaceとして保持してよい。
+Clientは、Hostから`fetch_tree`で取得したindexableなエントリツリーをDiscoverable Spaceとして保持する。Discoverable Spaceとして扱う間、Clientはそのtreeの構造を保持する必要がある。
 
-Discoverable SpaceはKnown Spaceの部分集合であり、AI向け`discover`などの機械的探索に利用する。
+Discoverable SpaceはKnown Spaceの部分集合であり、AI向け`discover`などの機械的探索に利用する。Worldspace rootまたはClientが選択した起点からindexable edgeで到達できる、materialize済みの範囲によって構成される。
 
-OperationやLinkを通して偶発的に発見されたエントリはKnown Spaceには追加されるが、それだけではDiscoverable Spaceには追加しない。そのエントリを起点として`fetch_tree`を取得した場合に、そのindexableな範囲をDiscoverable Spaceへ追加できる。
+Treeの再取得やHostからの更新によって親の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取得