wip-reference/3-core-protocol.md

3. Core Protocol

WIP Core Protocolは、ClientとHostの間でWorldspaceを観測・操作するためのtransport-independentな意味論を定義する。

3.1 役割

WIP上の主要な登場主体はClientとHostである。

Client

ClientはHostが提供するWorldspaceをユーザーまたはAIへ提示する。

Hostから取得したエントリとInterface定義を既知の空間として保持・キャッシュし、refによるObject同一性の追跡や、観測時と操作時の対応関係の検証を行う。

GUI、AI用Tools、PTC / REPL向けAPIなどへの投影はClient実装の責務とする。

Host

HostはClientに対して一つのWorldspaceを提供する。

どのObject、エントリ、Interface、可視性を公開するかを決定し、そのClientから見えるWorldspaceを構成する。

Host内部でGitHub API、Database、Filesystem、RAG、他Agent、別プロトコルなどをどう接続・集約するかはWIPの規定対象外とする。

3.2 規定範囲

Core Protocolが規定するのは、ClientがHostからWorldspaceを観測し、操作するための契約である。

特定のデータソース構成、内部RPC、永続化方式、Adapter構成、同期方式は規定しない。

ClientとHostの境界は通信境界であると同時に、ある主体へどのWorldspaceを公開するかを決める信頼境界として扱える。

3.3 基本操作

現時点では次の4操作をCore Protocolの基本とする。

• fetch(entry) — 1つのエントリにあるObjectの公開情報とInterface参照を取得する。
• fetch_tree(entry, depth, limit) — 指定エントリを起点に、indexableな子エントリを幅優先探索してエントリツリーとして取得する。
• fetch_interface(interface) — Interface参照からWIP IDL documentを取得する。
• call_operation(target, operation, arguments) — Objectが参照するInterfaceに宣言されたOperationを実行する。

Interfaceの定義はWIP IDL documentそのものであり、そこに宣言された関数の集合がOperation一覧となる。call_operationのargumentsは選択したOperationのparameter listに従う名前付きの型付き値であり、引数がない場合は空の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 return typeに従う型付き値である。Return type上でentryとして宣言された位置には、同じWorldspace内のエントリを指すcanonical absolute pathを返せる。

Clientはreturn typeに従ってentry型の位置を認識する。通常のstringや任意JSONに含まれるpathらしい文字列を、エントリとして推測してはならない。

返されたエントリpathのTree上の位置はOperationの実行対象から独立しており、実行対象の子に限定されない。Operationの実行対象と返されたエントリの間に、暗黙の親子関係や意味的関係を作ってはならない。

ClientはOperation結果として発見したpathを一時的に扱い、必要なものをfetchまたはfetch_treeして既知の空間へ統合できる。

複数のfetchまたはfetch_interfaceは、Core Protocol上ではそれぞれ独立した操作である。Transport Bindingは、個別に実行した場合と同じ意味を保ったまま、Clientが選択した複数の操作を一つのrequestへbatchしてよい。HostがClientの既知状態を推測して追加情報を先行同梱することはCore Protocolの一部としない。

3.6 Transportとの分離

Core ProtocolはHTTP、TCP、WebSocketなど特定のtransportを要求しない。

通信方式への具体的な対応付けはTransport Bindingとして別に定義する。標準bindingはWIP over HTTPSで扱う。

この分離により、Worldspaceの意味論と通信方式を独立して進化させる。