feat: add Astro reference site and organize book contents

2026-10-09 23:40:37 +09:00
parent 6086f3c5ef
commit 01c9498e6d
39 changed files with 7772 additions and 0 deletions
@@ -0,0 +1,715 @@
+# 5.1. WIP over HTTP
+
+WIP over HTTPは、[3. Protocol](3-protocol.md)のlogical data modelをHTTP request / responseとJSONへ対応付ける標準Transport Bindingである。[5. Transport Bindings](5-transports.md)の共通要件に従う。
+
+## 目的と範囲
+
+このbindingは、次のCore interactionをHTTPへ対応付ける。
+
+- `observe`
+- `fetch_interface`
+- `call_operation`
+
+HTTP version、communication scheme、TLS、authentication方式、connection reuse、multiplexing、proxy、gateway、cache、Host内部のframework、backend接続方式は規定しない。HTTP実装とdeploymentは、それらをWIPとは独立して選択する。複数のCore interactionが必要な場合も、それぞれを独立したHTTP request / responseとして交換する。
+
+OperationがWebSocket等のendpointをApplication dataとして返すことは妨げない。そのendpoint上のprotocol、状態、lifecycleはWIPの規定対象外である。
+
+## Endpoint
+
+WIP endpointは、一つのWorldspace access surfaceを指すabsolute hierarchical base URLである。Endpoint URLのpath prefixはdeploymentが任意に選択できる。Clientはorigin直下、`/wip`等の既定prefix、またはWorldspace pathとの対応を仮定しない。
+
+Endpoint URLは次を満たす。
+
+- HTTP実装がrequest先として使用できるabsolute URLである。
+- Authorityとhostを持つ。
+- Queryとfragmentを持たない。
+- Pathが`/`で終わるcanonical formである。
+
+利用者から末尾`/`のないURLを受け付ける実装は、routeを解決する前に`/`を追加してcanonical formへ変換する。URL schemeと通信securityの選択はHTTP実装とdeploymentの責務であり、このbindingは制約しない。
+
+各routeはendpoint URLをbase URLとして、次のrelative referenceをRFC 3986に従って解決する。すべてのinteractionは`POST`を使用する。
+
+| Interaction | Method | Relative reference |
+| --- | --- | --- |
+| `observe` | `POST` | `v1/observe` |
+| `fetch_interface` | `POST` | `v1/fetch_interface` |
+| `call_operation` | `POST` | `v1/call_operation` |
+
+`v1`はWIP over HTTP Bindingのmajor versionである。Interactionごとに独立したrouteを設定したり、固定suffixを別名へ置き換えたりしない。
+
+例えば、次のendpointを指定した場合、
+
+```text
+http://gateway.example/tenants/acme/filesystem/wip/
+```
+
+`observe` routeは次になる。
+
+```text
+http://gateway.example/tenants/acme/filesystem/wip/v1/observe
+```
+
+Endpointのpath prefixはHTTP deployment上のroutingであり、Worldspace内のpathではない。Worldspace pathはrequest bodyのlogical fieldとして渡す。標準route URLはqueryを持たず、query付きURLまたは追加path segmentを同じrouteとして扱わない。
+
+Clientは異なるcanonical endpoint間でKnown Space、Object observation、Interface observation、validatorを混在させない。同じendpointでも認証主体、tenant、capability、その他のsecurity contextによって異なるWorldspaceが見える場合、それらを異なるeffective Worldspace viewとして分離する。
+
+## HTTP request metadata
+
+標準routeへのrequestは次を満たす。
+
+- Methodは`POST`。
+- `Content-Type`は`application/json`または`application/json; charset=utf-8`。
+- BodyはUTF-8のJSON text。
+- 標準Clientは`Accept: application/json`を送る。
+- Request URLは標準routeと完全に一致し、queryを持たない。
+
+Media typeとparameter名の比較はHTTPの規則に従ってcase-insensitiveに行う。`charset`を指定する場合は`utf-8`だけを許可する。同じparameterの重複、UTF-8以外のcharset、その他のmedia type parameterを標準bindingでは使用しない。
+
+`Accept`がないrequestをHostは受理してよい。`Accept`がある場合はHTTP content negotiationの規則を適用し、`application/json`に対するeffective quality valueが正である場合だけJSON responseを返す。
+
+すべての実装はHTTP identity content codingを扱える。Requestまたはresponseのcontent codingはoptionalなHTTP機能であり、本bindingは特定の圧縮方式を必須にしない。Hostが対応しないrequest content codingはTransport-levelの`415 Unsupported Media Type`として拒否する。Clientが対応しないresponse content codingはTransport failureとして扱う。
+
+## Routeとmetadataのfailure
+
+Route、method、content negotiation、Transport authenticationはlogical WIP requestの外側にある。次のresponseはProtocol error envelopeを要求しない。
+
+| 条件 | HTTP response |
+| --- | --- |
+| 未知route、query付きroute、追加path segment | `404 Not Found` |
+| 既知routeへの`POST`以外のmethod | `405 Method Not Allowed`と`Allow: POST` |
+| Unsupportedな`Content-Type`またはrequest content coding | `415 Unsupported Media Type` |
+| JSON responseを拒否する`Accept` | `406 Not Acceptable` |
+| Transport authenticationが必要 | `401 Unauthorized`、必要なら`WWW-Authenticate` |
+| Endpoint access surface全体へのaccess拒否 | `403 Forbidden` |
+
+Clientはこれらを`InvalidRequest`、`NotFound`、`PermissionDenied`等へ変換しない。
+
+標準route、method、media type、authenticationが受理された後、bodyがmalformed JSONである、logical requestへdecodeできない、required fieldがない、未知fieldがある、またはfield semanticsに違反する場合、Hostは`400 Bad Request`と`invalid_request`のProtocol error envelopeを返す。
+
+HTTP server、proxy、gateway、またはClientの運用設定によってmessage size、timeout、rate等の上限に達した場合はTransport failureである。HTTP statusが後述するProtocol error mappingと同じでも、validなProtocol error envelopeを持たないresponseをProtocol failureへ変換しない。
+
+## HTTP response
+
+各interactionが成功した場合、Hostは`200 OK`を返し、response bodyへ対応するProtocol responseを直接encodeする。Success bodyを`result`等の共通envelopeで包まない。
+
+Protocol failureの場合、Hostは非2xx statusを返し、bodyへ本章のProtocol error envelopeをencodeする。
+
+WIP Hostが生成するbody付きresponseは`Content-Type: application/json`または`application/json; charset=utf-8`を持つ。Protocol successまたはProtocol failureのbodyはUTF-8 JSON textである。
+
+HTTP statusは大分類とHTTP infrastructureのための補助情報であり、Protocol failureの意味を決定しない。Clientはstatus、reason phrase、人間向けmessageから`ProtocolErrorCode`を推測しない。
+
+非2xx responseが、正しいContent-TypeとvalidなProtocol error envelopeを持たない場合、ClientはTransport failureとして扱う。これにより、proxyやgatewayが生成したresponseをHost由来のProtocol failureと誤認しない。
+
+次は`InvalidResponse`である。
+
+- `200 OK`以外の2xx statusにvalidなsuccess bodyがある。
+- 2xx statusにProtocol error envelopeがある。
+- 非2xx statusにvalidなsuccess bodyがある。
+- Success bodyまたはProtocol error envelopeがschema、request correlation、interactionごとのcode制約に違反する。
+
+## JSON共通規則
+
+JSON encodingには次の規則を適用する。
+
+- JSON textはUTF-8でencodeする。
+- RecordはJSON object、listはJSON arrayで表す。
+- Field名と列挙stringはcase-sensitiveである。
+- 同じJSON object内のduplicate memberを拒否する。
+- 本章がschemaを定義するobjectでは、許可していないmemberを拒否する。Descriptorの未知formatとTypeExpr `Json`のobjectには、それぞれ後述する例外を適用する。
+- Required fieldは必ず存在する。
+- Protocol structのoptional fieldはmemberの省略で表し、`null`で置き換えない。
+- JSON objectのmember順に意味を持たせない。
+- Protocol listのarray順は保持する。
+- StringへUnicode normalizationを適用しない。
+- JSON syntaxが表現できないNaNと正負Infinityを使用しない。
+
+本章のschema表で`optional`と記していないfieldはrequiredである。
+
+`Vec<u8>`はRFC 4648 Section 4のstandard base64 alphabetを使用し、必要な`=` paddingを含むcanonical base64 stringとしてencodeする。Whitespace、URL-safe alphabet、padding省略、同じoctet列に対する別表現を受理しない。
+
+Path、Interface参照、Object identity、名前、validatorの意味はfieldの位置とProtocolの型によって決まる。
+
+| Logical field | JSON encoding |
+| --- | --- |
+| Path / `entry` | canonical absolute Worldspace pathのstring |
+| Object、Operation、Type、Field、Parameter、Case名 | string |
+| Interface参照 | `InterfaceReference` object |
+| `ref` | string |
+| `format` | string |
+| Object / Interface validator | canonical base64 string |
+
+JSON serializationのwhitespace、escapeの選択、object member順をcanonical化しない。同じlogical valueがbyte-for-byte同一のJSONになることを要求しない。
+
+## Interface Reference
+
+`InterfaceReference`は次のexactなJSON objectとしてencodeする。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `scope` | canonical absolute Worldspace pathのstring | required |
+| `name` | 空でないUnicode string | required |
+
+```json
+{
+  "scope": "/github",
+  "name": "issue.read"
+}
+```
+
+`Object.interfaces`の各要素、`FetchInterfaceRequest.interface`、`FetchInterfaceResponse.interface`、`InterfaceTarget.reference`のすべてでこの形を使用する。Scopeの省略、relative scope、`null`、空name、追加member、旧形式のopaque string、`"/github::issue.read"`等の短縮表記stringは認めない。Requestでの違反は`400 Bad Request`と`invalid_request`、responseでの違反はClient-localな`InvalidResponse`とする。
+
+参照の比較はJSON decode後の`scope`と`name`の完全一致であり、object member順やJSON escapeの違いは同一性に影響しない。ScopeへURL encoding / decodingを追加せず、name内の`::`や`#`も通常の文字として保持する。ScopeはWorldspace上のpathであり、HTTP endpointのprefixを加えたりscope用のHTTP routeを生成したりしない。合成によるscope変換は[ProtocolのWorldspace composition](3-protocol.md#worldspace-composition)に従う。
+
+## ObjectとObjectObservation
+
+`Object`は次のJSON objectとしてencodeする。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `name` | string | required |
+| `description` | string | optional |
+| `interfaces` | `InterfaceReference` objectのarray | required |
+| `ref` | string | optional |
+| `validator` | canonical base64 string | optional |
+
+例:
+
+```json
+{
+  "name": "123",
+  "description": "First item",
+  "interfaces": [
+    { "scope": "/", "name": "item-interface-v1" },
+    { "scope": "/", "name": "item-marker-interface-v1" }
+  ],
+  "ref": "item:123",
+  "validator": "aXRlbS12YWxpZGF0b3I="
+}
+```
+
+`interfaces`のarray順はHostの立項順を保持し、`(scope, name)`の完全一致による重複を含まない。各参照のscopeは観測pathに対してProtocolの祖先制約を満たす。
+
+`ObjectObservation`は次のJSON objectとしてencodeする。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `object` | `Object` | required |
+| `children` | `ObjectObservation`のarray | optional |
+
+`children`の省略は未観測を、空arrayは観測済みで直接のindexable childが存在しないことを表す。Requested depthより浅いnodeでは`children`を必ず含め、depth境界のnodeでは省略する。Success responseはrequested depthまで完全であり、truncated markerやpartial successを返さない。
+
+## Interface Descriptor
+
+### Format discriminator
+
+標準v1のInterface Descriptor formatは`wip-interface/1`である。このformatでは以下のJSON grammarを使用する。
+
+ClientはDescriptor objectのstring `format`を先に読み、対応しないformatを`UnsupportedDescriptorFormat`として扱える。未知formatでもDescriptorはJSON objectであり、string `format`を必ず持つ。それ以外のmemberはそのformat固有であるため、Clientは`wip-interface/1`のschemaで存在、欠落、型を判定せず、内容をOperationへ使用しない。標準v1 Hostは`wip-interface/1`を返す。
+
+### Documentation
+
+`Documentation`は次のJSON objectである。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `summary` | string | required |
+| `details` | string | optional |
+
+### Descriptor root
+
+`InterfaceDescriptor`は次のJSON objectである。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `format` | string。標準v1では`wip-interface/1` | required |
+| `documentation` | `Documentation` | optional |
+| `types` | `TypeDeclaration`のarray | required |
+| `operations` | `OperationDeclaration`のarray | required |
+
+`types`と`operations`のarray順はdeclaration順を保持する。
+
+### TypeDeclaration
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `name` | string | required |
+| `documentation` | `Documentation` | optional |
+| `definition` | `TypeExpr` | required |
+
+### TypeExpr
+
+すべての`TypeExpr`はstring `kind`を持つJSON objectとしてencodeする。`kind`ごとの正確なmemberは次のとおりである。
+
+| TypeExpr | `kind` | その他のmember |
+| --- | --- | --- |
+| Unit | `unit` | なし |
+| Boolean | `boolean` | なし |
+| Integer | `integer` | なし |
+| Number | `number` | なし |
+| String | `string` | なし |
+| Bytes | `bytes` | なし |
+| Json | `json` | なし |
+| Entry | `entry` | なし |
+| Named | `named` | required string `name` |
+| Record | `record` | required `FieldDeclaration` array `fields` |
+| List | `list` | required `TypeExpr` `items` |
+| Enum | `enum` | required `EnumCase` array `cases` |
+| Union | `union` | required `UnionCase` array `cases` |
+
+例:
+
+```json
+{
+  "kind": "list",
+  "items": {
+    "kind": "named",
+    "name": "ItemSummary"
+  }
+}
+```
+
+Primitive kindのobjectへ別memberを追加してはならない。例えばUnitは`{"kind":"unit"}`だけで表す。
+
+### FieldDeclaration
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `name` | string | required |
+| `required` | boolean | required |
+| `documentation` | `Documentation` | optional |
+| `type` | `TypeExpr` | required |
+
+### EnumCase
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `name` | string | required |
+| `documentation` | `Documentation` | optional |
+
+### UnionCase
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `name` | string | required |
+| `documentation` | `Documentation` | optional |
+| `payload` | `TypeExpr` | optional |
+
+`payload`の省略はpayloadを持たないcaseを表す。
+
+### OperationDeclaration
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `name` | string | required |
+| `documentation` | `Documentation` | optional |
+| `parameters` | `ParameterDeclaration`のarray | required |
+| `returns` | `ReturnDeclaration` | required |
+
+### ParameterDeclaration
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `name` | string | required |
+| `required` | boolean | required |
+| `documentation` | `Documentation` | optional |
+| `type` | `TypeExpr` | required |
+
+### ReturnDeclaration
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `documentation` | `Documentation` | optional |
+| `type` | `TypeExpr` | required |
+
+Descriptorの名前一意性、Named参照、cycle、型整合性等は[3. Protocol](3-protocol.md)に従って検証する。JSON shapeが正しいことだけではvalidなDescriptorにならない。
+
+完全なDescriptorの例:
+
+```json
+{
+  "format": "wip-interface/1",
+  "documentation": {
+    "summary": "Reads items and their relationships."
+  },
+  "types": [
+    {
+      "name": "Relation",
+      "definition": {
+        "kind": "enum",
+        "cases": [
+          { "name": "parent" },
+          { "name": "sibling" }
+        ]
+      }
+    },
+    {
+      "name": "RelatedItem",
+      "definition": {
+        "kind": "union",
+        "cases": [
+          {
+            "name": "found",
+            "payload": { "kind": "entry" }
+          },
+          { "name": "not_found" }
+        ]
+      }
+    }
+  ],
+  "operations": [
+    {
+      "name": "get_related_item",
+      "parameters": [
+        {
+          "name": "relation",
+          "required": true,
+          "type": {
+            "kind": "named",
+            "name": "Relation"
+          }
+        }
+      ],
+      "returns": {
+        "type": {
+          "kind": "named",
+          "name": "RelatedItem"
+        }
+      }
+    }
+  ]
+}
+```
+
+## Operation Value
+
+Operationのargumentsとresultは、選択したInterface Descriptorの`TypeExpr`に従ってJSONへencodeする。Raw `Value` variantを示す共通tagged envelopeは使用しない。
+
+| TypeExpr | JSON encoding |
+| --- | --- |
+| Unit | `null` |
+| Boolean | boolean |
+| Integer | 小数部と指数部を持たないJSON number。`-9007199254740991`から`9007199254740991`まで |
+| Number | finiteなJSON number |
+| String | string |
+| Bytes | canonical base64 string |
+| Json | JSONの`null`、boolean、number、string、array、object |
+| Entry | canonical absolute Worldspace pathのstring |
+| Named | 同じDescriptor内の参照先TypeExprと同じencoding |
+| Record | declarationされたfieldをmemberとするobject |
+| List | items TypeExprに従うarray |
+| Enum | 宣言されたcase名のstring |
+| Union | `$case`と、必要なら`value`を持つobject |
+
+`Json`内部でもnumberは相互運用可能なsafe integerまたはfinite binary64として扱い、Bytesの特別なencodingは適用しない。小数部と指数部を持たずsafe integer範囲にあるJSON numberはlogical `Integer`、それ以外のfiniteなJSON numberはlogical `Number`としてdecodeする。`Json`内のbase64らしいstringをBytesと推測しない。
+
+RecordとOperation argumentsでは、`required = false`のfieldまたはparameterを省略できる。省略と`null`は異なる。TypeExprがUnit、Json、またはそれらへ解決されるNamedである場合、存在するmemberの`null`はその型のvalueであり、省略を表さない。それ以外の型で`null`を使用してはならない。
+
+Record valueはdeclarationされていないmemberを持たない。Operation argumentsはparameter名をmember名とするJSON objectであり、位置引数を使用しない。引数のないOperationは空objectを使用する。
+
+Enumはcase名だけをstringで表し、object envelopeを使用しない。
+
+Payloadを持つUnionは次の形である。
+
+```json
+{
+  "$case": "found",
+  "value": "/items/123"
+}
+```
+
+Payloadを持たないUnionは`value`を省略する。
+
+```json
+{
+  "$case": "not_found"
+}
+```
+
+Union objectは`$case`と必要な`value`以外のmemberを持たない。Payloadありcaseでは`value`がrequired、payloadなしcaseでは`value`は禁止される。
+
+ClientはDescriptorに従ってvalueをdecodeし、`entry`と宣言された位置のstringだけをWorldspace entryとして認識する。通常のStringやopaqueなJsonに含まれるpathらしいstringをentryとして推測しない。
+
+## `observe`
+
+### Request
+
+`POST v1/observe`のbodyは次のJSON objectである。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `path` | canonical absolute Worldspace pathのstring | required |
+| `depth` | `0`以上`4294967295`以下のinteger | required |
+
+```json
+{
+  "path": "/items",
+  "depth": 1
+}
+```
+
+### Success response
+
+Success bodyはrootの`ObjectObservation`を直接encodeする。
+
+```json
+{
+  "object": {
+    "name": "items",
+    "description": "Item collection",
+    "interfaces": [{ "scope": "/", "name": "item-collection-interface-v1" }],
+    "validator": "cm9vdC12YWxpZGF0b3I="
+  },
+  "children": [
+    {
+      "object": {
+        "name": "123",
+        "description": "First item",
+        "interfaces": [{ "scope": "/", "name": "item-interface-v1" }],
+        "ref": "item:123",
+        "validator": "aXRlbS12YWxpZGF0b3I="
+      }
+    }
+  ]
+}
+```
+
+Responseのpath、name、depth、children completenessはrequestと[3. Protocol](3-protocol.md)に従って検証する。完全なresponseをresource budget内で構築できない場合、Hostはpartial successではなく`resource_limit_exceeded`を返す。
+
+## `fetch_interface`
+
+### Request
+
+`POST v1/fetch_interface`のbodyは次のJSON objectである。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `interface` | `InterfaceReference` object | required |
+
+```json
+{
+  "interface": { "scope": "/", "name": "item-interface-v1" }
+}
+```
+
+### Success response
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `interface` | `InterfaceReference` object | required |
+| `scope_ref` | scope Objectの`ref`を表すstring | optional |
+| `descriptor` | Interface Descriptor object | required |
+| `validator` | canonical base64 string | optional |
+
+```json
+{
+  "interface": { "scope": "/", "name": "item-interface-v1" },
+  "scope_ref": "world:root",
+  "descriptor": {
+    "format": "wip-interface/1",
+    "types": [],
+    "operations": []
+  },
+  "validator": "aW50ZXJmYWNlLXZhbGlkYXRvcg=="
+}
+```
+
+Responseの`interface`はrequestと完全一致しなければならない。`scope_ref`、Descriptor、validatorは一つのInterface observationとして扱う。`scope_ref`はscope Objectの`ref`と同じopaque stringであり、base64化しない。Scope Objectが`ref`を持つ場合は含め、持たない場合は省略する。`null`は使用しない。
+
+Scope Objectに`ref`がない場合のvalidなresponse例:
+
+```json
+{
+  "interface": { "scope": "/", "name": "item-interface-v1" },
+  "descriptor": {
+    "format": "wip-interface/1",
+    "types": [],
+    "operations": []
+  }
+}
+```
+
+`scope_ref`もvalidatorもない観測は許可される。Scopeのidentity追跡はできず、Descriptorはその参照の有効期間中immutableとして扱う。
+
+## `call_operation`
+
+### Request
+
+`POST v1/call_operation`のbodyは次のJSON objectである。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `target` | `Target` object | required |
+| `interface` | `InterfaceTarget` object | required |
+| `operation` | Operation名のstring | required |
+| `arguments` | 選択したOperation declarationに従うobject | required |
+
+`Target`は次のfieldを持つ。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `path` | canonical absolute Worldspace pathのstring | required |
+| `validator` | canonical base64 string | optional |
+
+`InterfaceTarget`は次のfieldを持つ。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `reference` | `InterfaceReference` object | required |
+| `scope_ref` | 観測したscope Objectの`ref`を表すstring | optional |
+| `validator` | canonical base64 string | optional |
+
+```json
+{
+  "target": {
+    "path": "/items/current",
+    "validator": "b2JqZWN0LXZhbGlkYXRvcg=="
+  },
+  "interface": {
+    "reference": { "scope": "/", "name": "item-interface-v1" },
+    "scope_ref": "world:root",
+    "validator": "aW50ZXJmYWNlLXZhbGlkYXRvcg=="
+  },
+  "operation": "get_related_item",
+  "arguments": {
+    "relation": "sibling"
+  }
+}
+```
+
+`interface.reference`と`operation`は別fieldである。表示用の`/::item-interface-v1#get_related_item`を一つのfieldへencodeしない。`scope_ref`も`InterfaceReference`のmemberや短縮表記の一部にはせず、`InterfaceTarget`の独立したoptional fieldとして送る。
+
+Clientは`fetch_interface`の観測に`scope_ref`があればコピーし、なければ省略する。`scope_ref`に`null`や非stringを指定したrequestは`invalid_request`である。Validなstringを指定したが現在のscope Objectの`ref`と一致しない場合（現在の`ref`の欠落を含む）は、Protocolの検証順に従って`interface_mismatch`とする。省略時はscope identity preconditionを適用せず、それだけを理由に拒否しない。
+
+HostはDescriptorに依存しない`target`、`interface`、`operation`のshapeを検証し、Protocolのerror precedenceに従って現在のObjectとInterface observationを固定した後、そのDescriptorに従って`arguments`をdecodeする。
+
+### Success response
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `result` | Operation return TypeExprに従うJSON value | required |
+| `validator` | 実行後のObject validatorを表すcanonical base64 string | optional |
+
+```json
+{
+  "result": {
+    "$case": "found",
+    "value": "/items/123"
+  },
+  "validator": "bmV3LW9iamVjdC12YWxpZGF0b3I="
+}
+```
+
+`result`はrequestで指定し、Hostがprecondition確認時に固定したOperation declarationのreturn TypeExprに従ってencodeする。
+
+## Validator
+
+Object validatorとInterface validatorは対応するJSON body fieldへcanonical base64としてencodeする。
+
+- `Object.validator`
+- `Target.validator`
+- `FetchInterfaceResponse.validator`
+- `InterfaceTarget.validator`
+- `CallOperationResponse.validator`
+
+WIP validatorを`ETag`、`If-Match`、その他のHTTP headerだけへ移してbody fieldを省略してはならない。Host、gateway、HTTP cacheは通常のHTTP representation metadataとして`ETag`等を追加してよいが、その値はWIP validatorと独立している。ClientはHTTP metadataをObject identity、Interface observation、Operation preconditionとして解釈しない。
+
+## Protocol error envelope
+
+各interactionのProtocol failureは、次のexactなJSON objectとしてencodeする。
+
+```json
+{
+  "error": {
+    "code": "invalid_arguments",
+    "message": "Required argument `relation` is missing"
+  }
+}
+```
+
+Top-level objectは`error`だけを持つ。`error` objectは次のfieldだけを持つ。
+
+| Field | JSON type | Presence |
+| --- | --- | --- |
+| `code` | 下表のstableなsnake_case string | required |
+| `message` | boundedな人間向け診断string | required |
+
+Clientは`message`で分岐しない。Hostは秘密情報、credential、非公開Object、backend path、内部stack traceをmessageへ含めない。
+
+`ProtocolErrorCode`のwire spellingとcanonical HTTP statusは次のとおりである。
+
+| Protocol error code | Wire spelling | HTTP status |
+| --- | --- | --- |
+| `InvalidRequest` | `invalid_request` | `400 Bad Request` |
+| `NotFound` | `not_found` | `404 Not Found` |
+| `InterfaceNotFound` | `interface_not_found` | `404 Not Found` |
+| `InterfaceMismatch` | `interface_mismatch` | `409 Conflict` |
+| `OperationNotFound` | `operation_not_found` | `404 Not Found` |
+| `InvalidArguments` | `invalid_arguments` | `422 Unprocessable Content` |
+| `ValidatorRequired` | `validator_required` | `428 Precondition Required` |
+| `ValidatorMismatch` | `validator_mismatch` | `412 Precondition Failed` |
+| `InterfaceValidatorRequired` | `interface_validator_required` | `428 Precondition Required` |
+| `InterfaceValidatorMismatch` | `interface_validator_mismatch` | `412 Precondition Failed` |
+| `PermissionDenied` | `permission_denied` | `403 Forbidden` |
+| `ResourceLimitExceeded` | `resource_limit_exceeded` | `422 Unprocessable Content` |
+| `Internal` | `internal` | `500 Internal Server Error` |
+| `OperationOutcomeUnknown` | `operation_outcome_unknown` | `500 Internal Server Error` |
+
+`resource_limit_exceeded`は、observation completeness、logical nesting、collection件数等、WIP Protocolが扱うlogical requestまたはresponseの上限超過を表し、`422 Unprocessable Content`を使用する。HTTP implementationやdeploymentのmessage-size上限超過をこのcodeへ変換しない。
+
+Rate limitまたはdeployment concurrency limitによる`429 Too Many Requests`はTransport / deployment concernである。ValidなProtocol error envelopeがない限り`ResourceLimitExceeded`へ変換しない。
+
+Hostはinteractionごとに[3. Protocol](3-protocol.md)で許可されたcodeだけを返す。ClientがvalidなProtocol error envelopeを取得した場合、HTTP statusがcanonical mappingと一致しなくても回復actionは`code`に従い、statusから別codeを推測しない。Status mismatchはBinding違反として診断してよい。
+
+`InvalidResponse`と`UnsupportedDescriptorFormat`はClient-local classificationであり、Hostがerror envelopeで返してはならない。Domain failureもProtocol errorへ変換せず、Operation return typeに従うApplication dataとしてencodeする。
+
+## HTTP authentication boundary
+
+Authentication方式、credential、mTLS、proxy、gateway等はHTTP implementationとdeploymentの関心であり、本bindingは規定しない。
+
+HTTP layerがWIP interactionを開始せずに返す`401 Unauthorized`または`403 Forbidden`は、validなProtocol error envelopeを持たないTransport failureである。Clientはそれらを`PermissionDenied`へ変換しない。
+
+WIP interactionを開始した後のObject、Interface、Operation visibilityとauthorizationはProtocol semanticsに従う。Protocolの`PermissionDenied`はvalidなWIP error envelopeを持つ`403 Forbidden`であり、HTTP layerのaccess rejectionと区別する。
+
+## HTTP replay
+
+`3xx` response自体はWIP successまたはProtocol failureではなく、Transport failureである。Endpoint discovery、redirect、proxy routingをどう扱うかはHTTP implementationとdeploymentの責務である。
+
+ただし、それらの機構によって一つのlogical `call_operation` requestを複数回dispatchしてはならない。Dispatch後にredirect responseを受け取った場合も、methodとbodyを維持して別endpointへ自動再送しない。
+
+## Dispatchとretry
+
+RequestがHostへ送信されていないとTransport実装が証明できるfailureはnot dispatchedである。送信開始後にresponseを取得できない場合、ClientはHostがrequestを受理した可能性を否定しない。
+
+`observe`と`fetch_interface`を再送するか、どのtimeout、retry、cancellation policyを使用するかはClientとHTTP実装の責務である。Response ownershipとProtocol上のcache semanticsは[4. Client](4-client.md)に従う。
+
+`call_operation`には次を適用する。
+
+- Redirect、connection retry、HTTP stackのautomatic replay、proxy retryによって再送しない。
+- `Retry-After`またはHTTP statusだけを理由に再送しない。
+- Response不達またはlocal cancellationを、Operationが未実行またはrollback済みである証拠として扱わない。
+- `internal`または`operation_outcome_unknown`を受信しても自動再実行しない。
+- 同じOperationを利用者が改めて実行する場合は、Protocolの回復規則に従って必要なObjectまたはInterfaceを再観測する。
+
+HTTP implementationとdeploymentは、失敗した`POST v1/call_operation`を透過的にreplayしない。
+
+## HTTP facilitiesとの境界
+
+HTTP cache、proxy、gateway、compression、connection管理、TLS、message size、timeout、concurrency、rate limit等の設定と運用は、本bindingの規定対象外である。
+
+HTTP cache metadataはWIP ClientのKnown Space、Interface cache、Object validator、Interface validatorとは別の機構である。`ETag`、`If-Match`、Age、Last-Modified等をWIP observationまたはvalidatorとして解釈しない。それ以外のHTTP cache policyはHTTP implementationとdeploymentが決定する。
+
+HTTP implementationまたはdeploymentの都合でrequestまたはresponseを交換できない場合、ClientはTransport failureとして扱う。WIPはそれらの運用設定を規定せず、そのfailureを`resource_limit_exceeded`その他のProtocol errorへ包み直さない。
+
+## 非目標
+
+本bindingは次を定義しない。
+
+- Host内部のAPI、database、filesystem、queueとの接続方法。
+- Endpoint discovery service。
+- 固定のauthentication scheme。
+- HTTP cacheを使ったWorldspace同期。
+- Operation idempotency keyまたはexactly-once execution。
+- Operation cancellation protocol。
+- Streaming、subscription、server push、WebSocket binding。
+- 複数のCore interactionを一つのWIP requestへまとめる共通envelope。
+- Domain failureの共通HTTP mapping。