4.8 KiB
2.2. Operation
2.2.1 目的
Operationは、Objectが外部へ公開する意味的な操作を表す。WIPではドメインデータをpropertiesとして常時露出するのではなく、読み取り・検索・更新を含む行為をOperationとして公開する。
2.2.2 基本形
Operationは少なくとも次の情報を持つ。
name— Operationを識別する名前。description— 何を行う操作かを説明する短い自然言語。input— 呼び出し時に受け取る入力の型。output— 呼び出し結果の型。guard— 必要に応じて公開される実行条件・precondition。
Operation名や型だけに意味を担わせず、descriptionをinterface metadataの一部として扱う。長文documentationを埋め込むことは想定しない。
2.2.3 入出力型とWIP IDL
Operationのinput / outputは、機械的に検証・解釈できる構造化された型としてWIP IDLで定義する。WIP IDLのsourceをschemaのcanonicalな交換形式とし、JSON SchemaやIDLを変換したJSON ASTはCore Protocol上の交換形式にしない。
Hostは公開するinterfaceについて、IDLのlanguage identifier、sourceまたはsourceへの参照、およびcacheや同一性確認に利用できるdigestをClientへ提供する。ClientはIDLをparseして内部表現を構築する。AI ToolやGUIへ投影する際にJSON Schema等へ変換することはClient実装の責務であり、その変換形式をWIP interfaceとしてHostへ要求しない。
WIP IDLは、Operation境界の値を記述するための小さな型システムとする。Primitive、record、list、optional field、enum、unionに加え、Worldspace内のエントリpathを示すentry型を表現する。任意のドメインデータをObjectのpropertiesとしてモデル化するための型システムではない。
Operationのinputは常に名前付きfieldを持つrecordとする。引数を持たないOperationのinputは空のrecordであり、位置引数は用いない。これにより、呼び出しの可読性を保ち、既存fieldの意味を変えずにoptional fieldを追加できる。
Outputは任意のIDL型を返してよい。ただし、将来の拡張や付加情報の追加が想定されるOperationではrecordを基本とする。
2.2.4 可視性
Hostは、主体の権限やrole / capabilityに基づいて、その主体へ公開するOperation集合を決定してよい。
Operationの可視性は、頻繁に変化する実行可否やdomain stateを表すものではなく、その主体に対してどのinterfaceを公開するかというprojectionとして扱う。
例えばread-only主体には読み取り系Operationのみを公開し、maintainerやadminには追加の更新・管理Operationを公開できる。
WIPはOperationのavailable / disabledのような揮発的状態をinterface metadataとして同期することを前提としない。現在の実行可否やpreconditionは、必要に応じてdomain固有のOperationで観測し、最終的なauthorizationや実行条件はcall_operation時にHostが検証する。
2.2.5 Guard
Guardを設ける場合は、現在時点のavailabilityを同期する仕組みではなく、Operationに一般的に課されるpreconditionやconstraintを説明するsemantic metadataとして扱う。
Guardの具体的schemaは未解決事項として管理する。
2.2.6 Operation Result
Operationの結果には、通常のdomain valueに加えて、WIP IDLのentry型として新しいエントリのpathが含まれ得る。
entryは同じWorldspace内のcanonical absolute pathであり、wire上では文字列として表現する。Clientはoutput schemaに従ってentry型の位置を認識し、返されたpathを一時的な発見結果として扱う。通常のstringや任意JSON値に含まれるpathらしい文字列を、エントリとして推測してはならない。
Clientは発見したpathを必要に応じてfetchまたはfetch_treeする。複数pathのbatch取得や、invoke responseへのエントリ公開情報の同梱は、Operationのoutput型とは独立したprotocol上の最適化として扱う。
Operationの実行対象と、結果として発見されたエントリのTree上の位置は独立している。発見されたエントリは実行対象の子である必要はなく、親、兄弟、またはWorldspace内の任意の位置にあるエントリであってよい。
Operationがエントリpathを返したこと自体から、実行対象との間に親子関係や意味的関係を推論してはならない。親子関係はTree上の配置で表し、非内包の意味的関係はOperation名、outputのfield名、またはdomain固有のrelation型で表現する。