51 lines
4.5 KiB
Markdown
51 lines
4.5 KiB
Markdown
# 2.2. Operation
|
|
|
|
## 2.2.1 目的
|
|
|
|
Operationは、Objectが外部へ公開する意味的な操作を表す。WIPではドメインデータをpropertiesとして常時露出するのではなく、読み取り・検索・更新を含む行為をOperationとして公開する。
|
|
|
|
## 2.2.2 基本形
|
|
|
|
Operationは少なくとも次の情報を持つ。
|
|
|
|
- `name` — Operationを識別する名前。
|
|
- `description` — 何を行う操作かを説明する短い自然言語。
|
|
- `input` — 呼び出し時に受け取る入力の型。
|
|
- `output` — 呼び出し結果の型。
|
|
|
|
Operation名や型だけに意味を担わせず、`description`をinterface metadataの一部として扱う。長文documentationを埋め込むことは想定しない。
|
|
|
|
## 2.2.3 入出力型とWIP IDL
|
|
|
|
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または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として同期することを前提としない。現在状態を判断する必要がある場合は、必要に応じてdomain固有のOperationで観測する。最終的なauthorizationと実行条件の判定は`call_operation`時にHostが行う。
|
|
|
|
## 2.2.5 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型で表現する。
|