# 3. Core Protocol WIP Core Protocolは、ClientとHostの間でWorldspaceを観測・操作するための**transport-independentな意味論**を定義する。 ## 3.1 役割 WIP上の主要な登場主体は**Client**と**Host**である。 ### Client ClientはHostが提供するWorldspaceをユーザーまたはAIへ提示する。 Hostから取得したエントリを既知の空間として保持・キャッシュし、`ref`によるObject同一性の追跡や、観測時と操作時の対応関係の検証を行う。 GUI、AI用Tools、PTC / REPL向けAPIなどへの投影はClient実装の責務とする。 ### Host HostはClientに対して一つのWorldspaceを提供する。 どのObject、エントリ、Operation、Guard、可視性を公開するかを決定し、そのClientから見えるWorldspaceを構成する。 Host内部でGitHub API、Database、Filesystem、RAG、他Agent、別プロトコルなどをどう接続・集約するかはWIPの規定対象外とする。 ## 3.2 規定範囲 Core Protocolが規定するのは、ClientがHostからWorldspaceを観測し、操作するための契約である。 特定のデータソース構成、内部RPC、永続化方式、Adapter構成、同期方式は規定しない。 ClientとHostの境界は通信境界であると同時に、ある主体へどのWorldspaceを公開するかを決める信頼境界として扱える。 ## 3.3 基本操作 現時点では次の3操作をCore Protocolの基本とする。 - `fetch(entry)` — 1つのエントリにあるObjectの公開情報を取得する。 - `fetch_tree(entry, depth, limit)` — 指定エントリを起点に、indexableな子エントリを幅優先探索してエントリツリーとして取得する。 - `call_operation(target, operation, input)` — Objectが公開するOperationを実行する。 Operationのinterfaceは[WIP IDL](draft/wip-idl.md)で定義する。`call_operation`の`input`はOperationが宣言したinput recordに従う名前付きの型付き値であり、引数がない場合も空のrecordを渡す。Core Protocolはこの値をJSONに限定せず、transport bindingが具体的なencodingを定める。 ## 3.4 `fetch_tree` `fetch_tree`は、Clientが機械的探索のために多数の`fetch`を連打することを避けるための操作である。 探索対象はindexableな子エントリのみとし、幅優先探索（BFS）で辿る。Clientは探索深度`depth`と返却エントリ総数の上限`limit`を指定できる。 探索が`depth`または`limit`によって途中で終了した場合、レスポンスは`truncated`であることを必ず明示する。Clientは取得結果を完全なツリーと誤認してはならない。 件数が非常に多いCollectionの個々の要素は、通常indexableな子エントリとして自然露出させない。必要な要素はCollection Objectの`query`や`list`等のOperationによって発見する。 ## 3.5 Operation実行と発見 `call_operation`の結果はOperationのWIP IDL output型に従う型付き値である。Output schema上で`entry`として宣言された位置には、同じWorldspace内のエントリを指すcanonical absolute pathを返せる。 Clientはoutput schemaに従って`entry`型の位置を認識する。通常の`string`や任意JSONに含まれるpathらしい文字列を、エントリとして推測してはならない。 返されたエントリpathのTree上の位置はOperationの実行対象から独立しており、実行対象の子に限定されない。Operationの実行対象と返されたエントリの間に、暗黙の親子関係や意味的関係を作ってはならない。 ClientはOperation結果として発見したpathを一時的に扱い、必要なものを`fetch`または`fetch_tree`して既知の空間へ統合できる。複数pathに対する`fetch`は意味上それぞれ独立しており、Transport Bindingは同じ意味を保ったまま一つのrequestへbatchしてよい。 ## 3.6 Transportとの分離 Core ProtocolはHTTP、TCP、WebSocketなど特定のtransportを要求しない。 通信方式への具体的な対応付けはTransport Bindingとして別に定義する。標準bindingは`WIP over HTTPS`で扱う。 この分離により、Worldspaceの意味論と通信方式を独立して進化させる。