docs: refine operation interfaces and batching

2.2-operation.md

@@ -2,49 +2,65 @@
 
 ## 2.2.1 目的
 
-Operationは、Objectが外部へ公開する意味的な操作を表す。WIPではドメインデータをpropertiesとして常時露出するのではなく、読み取り・検索・更新を含む行為をOperationとして公開する。
+Operationは、Objectに対して実行できる操作を表す。
 
-## 2.2.2 基本形
+WIPでは、本文を読む、metadataを取得する、検索する、状態を変更するなど、Objectに対する行為をOperationとして公開する。
 
-Operationは少なくとも次の情報を持つ。
+## 2.2.2 Interface
 
-- `name` — Operationを識別する名前。
-- `description` — 何を行う操作かを説明する短い自然言語。
-- `input` — 呼び出し時に受け取る入力の型。
-- `output` — 呼び出し結果の型。
+ObjectはOperation定義を直接持たず、一つのInterfaceを参照する。
 
-Operation名や型だけに意味を担わせず、`description`をinterface metadataの一部として扱う。長文documentationを埋め込むことは想定しない。
+Interfaceの定義は[WIP IDL](draft/wip-idl.md) documentそのものである。IDL documentに宣言された関数の集合が、そのInterfaceのOperation集合となる。Operation名、parameter、return type、短いdocumentationは一つの関数宣言としてまとめて定義し、別のOperation descriptorへ重複して記述しない。
 
-## 2.2.3 入出力型とWIP IDL
+複数のObjectが同じInterfaceを参照できる。これにより、Collectionから多数の同種Objectを取得する場合でも、Operation定義を各Objectへ重複して埋め込む必要がない。
 
-Operationのinput / outputは、機械的に検証・解釈できる構造化された型として[WIP IDL](draft/wip-idl.md)で定義する。WIP IDLのsourceをschemaのcanonicalな交換形式とし、JSON SchemaやIDLを変換したJSON ASTはCore Protocol上の交換形式にしない。
+HostはInterfaceについて、参照、IDLのlanguage identifier、source、およびcacheや同一性確認に利用できるdigestをClientへ提供する。ObjectはInterface参照だけを持ち、Clientは未知のInterface定義だけを取得してcacheできる。
 
-Hostは公開するinterfaceについて、IDLのlanguage identifier、sourceまたはsourceへの参照、およびcacheや同一性確認に利用できるdigestをClientへ提供する。ClientはIDLをparseして内部表現を構築する。AI ToolやGUIへ投影する際にJSON Schema等へ変換することはClient実装の責務であり、その変換形式をWIP interfaceとしてHostへ要求しない。
+## 2.2.3 Operation declaration
 
-WIP IDLは、Operation境界の値を記述するための小さな型システムとする。Primitive、record、list、optional field、enum、unionに加え、Worldspace内のエントリpathを示す`entry`型を表現する。任意のドメインデータをObjectのpropertiesとしてモデル化するための型システムではない。
+Operationは、WIP IDL内で関数形式により宣言する。
 
-Operationのinputは常に名前付きfieldを持つrecordとする。引数を持たないOperationのinputは空のrecordであり、位置引数は用いない。これにより、呼び出しの可読性を保ち、既存fieldの意味を変えずにoptional fieldを追加できる。
+```wip
+/// Returns items related to this Object.
+operation get_related_items(
+  relation: Relation,
+  limit?: integer,
+) -> {
+  items: [entry],
+  next_cursor?: string,
+};
+```
 
-Outputは任意のIDL型を返してよい。ただし、将来の拡張や付加情報の追加が想定されるOperationではrecordを基本とする。
+Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter list `()`で宣言する。
+
+```wip
+operation refresh() -> unit;
+```
+
+Return typeには任意のWIP IDL型を使用できる。ただし、将来fieldを追加する可能性があるOperationではrecordを基本とする。
+
+Operationの用途は`///` documentation commentで簡潔に説明する。長文documentationや大量のdomain dataをInterfaceへ埋め込むことは想定しない。
 
 ## 2.2.4 可視性
 
-Hostは、主体の権限やrole / capabilityに基づいて、その主体へ公開するOperation集合を決定してよい。
+Hostは、主体の権限やrole / capabilityに基づいて、その主体へ公開するInterfaceを決定してよい。
 
-Operationの可視性は、頻繁に変化する実行可否やdomain stateを表すものではなく、**その主体に対してどのinterfaceを公開するか**というprojectionとして扱う。
+Operationの可視性は、頻繁に変化する実行可否やdomain stateを表すものではなく、**その主体に対してどのInterfaceを公開するか**というprojectionとして扱う。
 
-例えばread-only主体には読み取り系Operationのみを公開し、maintainerやadminには追加の更新・管理Operationを公開できる。
+同じObjectでも、主体ごとに異なるInterface参照を返してよい。
 
-WIPはOperationの`available` / `disabled`のような揮発的状態をinterface metadataとして同期することを前提としない。現在状態を判断する必要がある場合は、必要に応じてdomain固有のOperationで観測する。最終的なauthorizationと実行条件の判定は`call_operation`時にHostが行う。
+WIPはOperationの`available` / `disabled`のような揮発的状態をInterfaceへ同期することを前提としない。現在状態を判断する必要がある場合は、必要に応じてdomain固有のOperationで観測する。最終的なauthorizationと実行条件の判定は`call_operation`時にHostが行う。
 
 ## 2.2.5 Operation Result
 
-Operationの結果には、通常のdomain valueに加えて、WIP IDLの`entry`型として新しいエントリのpathが含まれ得る。
+`call_operation`は、対象ObjectのInterfaceに宣言されたOperation名と、parameter listに従う名前付きargumentsを受け取る。結果はOperationのreturn typeに従う型付きvalueとして返す。
 
-`entry`は同じWorldspace内のcanonical absolute pathであり、wire上では文字列として表現する。Clientはoutput schemaに従って`entry`型の位置を認識し、返されたpathを一時的な発見結果として扱う。通常の`string`や任意JSON値に含まれるpathらしい文字列を、エントリとして推測してはならない。
+Operation Resultには、WIP IDLの`entry`型として新しいエントリのpathが含まれ得る。
 
-Clientは発見したpathを必要に応じて`fetch`または`fetch_tree`する。複数pathのbatch取得や、invoke responseへのエントリ公開情報の同梱は、Operationのoutput型とは独立したprotocol上の最適化として扱う。
+`entry`は同じWorldspace内のcanonical absolute pathであり、wire上では文字列として表現する。Clientはreturn typeに従って`entry`型の位置を認識し、返されたpathを一時的な発見結果として扱う。通常の`string`や任意JSON値に含まれるpathらしい文字列を、エントリとして推測してはならない。
+
+Clientは発見したpathを必要に応じて`fetch`または`fetch_tree`する。複数pathの取得は、それぞれ独立したCore操作をTransport Bindingでbatchする。Operation Resultへエントリ公開情報を先行同梱しない。
 
 Operationの実行対象と、結果として発見されたエントリのTree上の位置は独立している。発見されたエントリは実行対象の子である必要はなく、親、兄弟、またはWorldspace内の任意の位置にあるエントリであってよい。
 
-Operationがエントリpathを返したこと自体から、実行対象との間に親子関係や意味的関係を推論してはならない。親子関係はTree上の配置で表し、非内包の意味的関係はOperation名、outputのfield名、またはdomain固有のrelation型で表現する。
+Operationがエントリpathを返したこと自体から、実行対象との間に親子関係や意味的関係を推論してはならない。親子関係はTree上の配置で表し、非内包の意味的関係はOperation名、resultのfield名、またはdomain固有のrelation型で表現する。