# 2.2. Operation

## 2.2.1 目的

Operationは、Objectに対して実行できる操作を表す。

WIPでは、本文を読む、metadataを取得する、検索する、状態を変更するなど、Objectに対する行為をOperationとして公開する。

## 2.2.2 Interface

ObjectはOperation定義を直接持たず、一つのInterfaceを参照する。

Interfaceの定義は[WIP IDL](draft/wip-idl.md) documentそのものである。IDL documentに宣言された関数の集合が、そのInterfaceのOperation集合となる。Operation名、parameter、return type、短いdocumentationは一つの関数宣言としてまとめて定義し、別のOperation descriptorへ重複して記述しない。

複数のObjectが同じInterfaceを参照できる。これにより、Collectionから多数の同種Objectを取得する場合でも、Operation定義を各Objectへ重複して埋め込む必要がない。

HostはInterfaceについて、参照、IDLのlanguage identifier、source、およびcacheや同一性確認に利用できるdigestをClientへ提供する。ObjectはInterface参照だけを持ち、Clientは未知のInterface定義だけを取得してcacheできる。

## 2.2.3 Operation declaration

Operationは、WIP IDL内で関数形式により宣言する。

```wip
/// Returns items related to this Object.
operation get_related_items(
  relation: Relation,
  limit?: integer,
) -> {
  items: [entry],
  next_cursor?: string,
};
```

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に基づいて、その主体へ公開するInterfaceを決定してよい。

Operationの可視性は、頻繁に変化する実行可否やdomain stateを表すものではなく、**その主体に対してどのInterfaceを公開するか**というprojectionとして扱う。

同じObjectでも、主体ごとに異なるInterface参照を返してよい。

WIPはOperationの`available` / `disabled`のような揮発的状態をInterfaceへ同期することを前提としない。現在状態を判断する必要がある場合は、必要に応じてdomain固有のOperationで観測する。最終的なauthorizationと実行条件の判定は`call_operation`時にHostが行う。

## 2.2.5 Operation Result

`call_operation`は、対象ObjectのInterfaceに宣言されたOperation名と、parameter listに従う名前付きargumentsを受け取る。結果はOperationのreturn typeに従う型付きvalueとして返す。

Operation Resultには、WIP IDLの`entry`型として新しいエントリのpathが含まれ得る。

`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名、resultのfield名、またはdomain固有のrelation型で表現する。