docs: define operation IDL and entry discovery

draft/wip-over-https.md

@@ -24,6 +24,79 @@ HTTPSを利用することで、TLS、認証、Proxy、Gateway、Observability
 
 具体的なHTTP method、endpoint、content type、error mapping、認証方式、streaming表現などは、このbinding仕様側で定義する。
 
+## WIP IDLの取得
+
+Operationのinput / output schemaは[WIP IDL](wip-idl.md)のsourceとして交換する。HostはIDLのlanguage identifier、sourceまたはsourceを取得するための参照、およびcacheと同一性確認に利用できるdigestを公開する。
+
+HTTPS response全体をJSON envelopeにする場合、IDL sourceをJSON stringとして格納してよい。ただし、これはIDLをJSON ASTへ変換するものではない。BindingはIDL sourceを専用resourceおよびcontent typeで直接取得する方法を定義してもよい。
+
+## Operation valueのJSON encoding
+
+WIP over HTTPSでは、`call_operation`のinputとoutputをWIP IDLに従うJSON valueとしてencodeする。JSONはHTTPS binding上の値表現であり、WIP Coreの型定義形式ではない。
+
+`input`は常に名前付きfieldを持つJSON objectとする。位置引数は用いず、引数を持たないOperationには空のobjectを渡す。
+
+概念的なrequest bodyは次の形になる。
+
+```json
+{
+  "target": "/items/current",
+  "operation": "get_related_item",
+  "input": {
+    "relation": "sibling",
+    "limit": 10
+  }
+}
+```
+
+IDL型からJSONへのmappingはbindingで一意に定める。少なくとも次の規則を持つ。
+
+- `boolean`、`string`、`number`、record、listは対応するJSON valueで表す。
+- optionalなrecord fieldはfieldの省略で表し、`null`とは区別する。
+- unit形式のenumはstring、payloadを持つunionは明示的なdiscriminatorを持つobjectで表す。
+- `bytes`はbase64でencodeしたstringとして表す。
+- 通常のJSON numberで表す`integer`は相互運用可能な安全範囲に制限する。それを超える整数型を設ける場合はdecimal string等のlosslessな表現を定義する。
+- WIP IDLの`entry`は、同じWorldspace内のcanonical absolute pathをJSON stringとして表す。
+
+ClientはWIP IDLに従ってvalueをdecodeし、IDL上で`entry`と宣言された位置にある文字列だけをエントリとして認識する。通常の`string`や任意JSON値に含まれるpathらしい文字列を、エントリとして推測してはならない。
+
+## Entry取得のbatching
+
+Operation Resultに複数のentry pathが含まれる場合、Clientはそれらを抽出して重複を除去し、必要なpathを取得できる。
+
+Core Protocol上では各`fetch`を独立した観測として扱う。WIP over HTTPSは、複数の`fetch`を一つのHTTP requestへまとめ、個別に実行した場合と同じ結果を返すbatch表現を定義してよい。Batchingは通信上の最適化であり、Core Protocolへ別の意味を追加しない。
+
+## Invoke responseへの同梱
+
+Hostは追加のround tripを避けるため、Operation Resultに含まれるentry pathの公開情報を、invoke responseの`included` sidecarへ同梱してよい。
+
+```json
+{
+  "output": {
+    "items": [
+      "/items/123",
+      "/items/456"
+    ]
+  },
+  "included": {
+    "/items/123": {
+      "type": "item",
+      "description": "First item",
+      "operations": []
+    },
+    "/items/456": {
+      "type": "item",
+      "description": "Second item",
+      "operations": []
+    }
+  }
+}
+```
+
+`included`のkeyはOperation Resultに現れるcanonical entry path、valueは同じpathに対する通常の`fetch`結果と同じ観測とする。`included`はOperationのtyped outputには含まれず、Operationのoutput schemaを変更しない。
+
+Clientは`included`をfetch済みの観測として利用しても、無視して改めて取得してもよい。Clientが同梱を要求する方法、Hostが自動的に同梱できる条件、response sizeの上限はbindingの詳細として定める。
+
 ## 非目標
 
 WIP over HTTPSはHost内部のAPIやデータソース接続方式を規定しない。また、WIP Core ProtocolそのものをHTTP依存のモデルへ変えることも目的としない。