docs: define HTTPS and error semantics

2-core-model.md

@@ -106,7 +106,7 @@ Objectは、同じ主体に公開された一つのWorldspace内でObjectの同
 4. 同じObjectへ条件付きで操作する場合、Clientは`path`とObjectの`validator`をtargetとしてHostへ渡す。
 5. Hostは現在のvalidatorとの一致確認とOperation実行をatomicに行う。
 
-ValidatorはClientとHostの間で扱い、AIやユーザーに直接管理させない。Transport Bindingは、同じlogical semanticsを保つ形でHTTP ETag等へ対応付けてよい。
+ValidatorはClientとHostの間で扱い、AIやユーザーに直接管理させない。Transport Bindingはvalidatorを対応するProtocol fieldとして保持し、HTTP ETag等のrepresentation metadataで置き換えない。
 
 Validatorが一致しない場合、Clientは現在のObjectに対してOperationを自動的に再試行してはならない。Hostは`validator_mismatch`を返し、Clientは再観測を要求する。
 

2.2-operation.md

@@ -129,7 +129,7 @@ Object validator、Interface membership、Interface validator、Descriptor、Ope
 
 Argumentsに未知のfieldがある場合、必須parameterがない場合、またはvalueが宣言型に一致しない場合、HostはOperationを実行せず`invalid_arguments`を返す。
 
-ClientはHostから受け取ったresultをreturn typeに従って検証する。Hostが宣言と異なるresultを返した場合は`invalid_result`として扱い、そのvalueをApplicationへ渡さない。
+ClientはHostから受け取ったsuccess responseのresultをreturn typeに従って検証する。Hostが宣言と異なるresultを返した場合はHostが返したProtocol failureではなく`InvalidResponse`として扱い、そのvalueをApplicationへ渡さない。Host Runtimeがinvalidなimplementation resultを送信前に検出した場合は、effectがcommitされていないと保証できるときだけ`Internal`を返し、保証できない場合は`OperationOutcomeUnknown`を返す。
 
 ## Application data
 
@@ -166,7 +166,7 @@ Operationがpathを返したこと自体から、実行対象との間に親子
 
 ## Protocol failureとdomain failure
 
-Protocol failureは、WIPのrequest、対象、Interface、validation、validatorによる条件付き実行に関する失敗である。
+Protocol failureは、WIPのrequest、対象、Interface、validation、validatorによる条件付き実行、Host executionに関する失敗である。
 
 - `invalid_request`
 - `not_found`
@@ -176,11 +176,16 @@ Protocol failureは、WIPのrequest、対象、Interface、validation、validato
 - `interface_validator_mismatch`
 - `operation_not_found`
 - `invalid_arguments`
-- `invalid_result`
 - `validator_required`
 - `validator_mismatch`
 - `permission_denied`
 - `resource_limit_exceeded`
+- `internal`
+- `operation_outcome_unknown`
+
+`InvalidResponse`はClientが受信したsuccess responseまたはerror responseのProtocol違反を表すlocal classificationであり、Hostが返すProtocol failureではない。`UnsupportedDescriptorFormat`もClient-localであり、validだが未対応のDescriptorをProtocol違反として扱わない。
+
+`call_operation`が`operation_outcome_unknown`以外のProtocol failureを返した場合、HostはOperationのeffectがcommitされていないことを保証する。`operation_outcome_unknown`またはresponse不達の場合、ClientはOperationを自動再実行せず、対象を再観測するかdomain固有の照会手段を利用する。
 
 Domain failureは、型として正しいOperationをApplicationが実行した結果として生じる失敗である。
 

3-protocol.md

@@ -121,7 +121,7 @@ Objectが何を表すかを説明する短い公開情報。Objectの本文やAp
 Objectで利用できるOperationを定義するInterface Descriptorへの参照を、Hostの立項順で保持するordered set。
 
 - 集合は空でもよい。
-- 同じInterface参照を重複して含めてはならない。Clientは重複を含むObject responseを`InvalidResult`として扱う。
+- 同じInterface参照を重複して含めてはならない。Clientは重複を含むObject responseをHostから返されたProtocol failureではなく`InvalidResponse`として扱う。
 - Membershipはset semanticsを持ち、列挙順はOperation解決、validation、authorizationへ影響しない。
 - Clientは列挙順をInterfaceおよびOperationのUI表示順として使用してよい。
 - Operation callは集合から一つのInterface参照を明示する。
@@ -373,6 +373,16 @@ Valueは、Operation declarationのTypeExprと照合して検証する。
 - `Entry`として宣言されたStringがcanonical pathであることを検証する。
 - Integerの相互運用範囲とNumberの有限性を検証する。
 
+## Core request validation
+
+Transport Bindingがframing、media type、authentication等を受理した後、Hostはinteraction固有のObject / Interface解決より前にlogical requestを検証する。
+
+1. Request structとして解釈できない、required fieldがない、未知fieldがある、Path等のfield semanticsに違反する場合は`InvalidRequest`。
+2. Field長、nesting、collection件数、`fetch_tree`のdepth / limit等がHostのboundedな上限を超える場合は`ResourceLimitExceeded`。
+3. 検証済みrequestについて、各interaction固有のtarget resolutionとpreconditionを評価する。
+
+`InvalidArguments`は`call_operation` request自体がvalidであり、固定したOperation declarationに対して`arguments`が適合しない場合だけに使用する。Transport route、authentication、media type、framing等のfailureはCore interactionのProtocol failureではない。
+
 ## `fetch`
 
 一つのpathで現在公開されているObjectを取得する。
@@ -385,7 +395,7 @@ struct FetchRequest {
 type FetchResponse = Object;
 ```
 
-Requestの`path`はresponseに重複して含めない。Root path `/`ではObjectの`name`が空文字列でなければならず、非root pathでは最後のsegmentとObjectの`name`が一致しなければならない。Clientは一致しないresponseを`InvalidResult`として扱う。
+Requestの`path`はresponseに重複して含めない。Root path `/`ではObjectの`name`が空文字列でなければならず、非root pathでは最後のsegmentとObjectの`name`が一致しなければならない。Clientは一致しないresponseを`InvalidResponse`として扱う。
 
 指定pathのObjectがその主体のClient-facing Worldspaceへ公開されていない場合、Host内部での存在理由にかかわらず`NotFound`を返す。`fetch`はObject取得の認可失敗として`PermissionDenied`を返さない。Objectを返すこと自体が、そのpathとObjectの公開情報を主体へ認識させるためである。
 
@@ -427,7 +437,7 @@ struct FetchTreeResponse {
 
 各nodeのObjectがvalidatorを持つため、Clientはrequest pathとObjectの`name`から各pathを導出し、Treeから発見したObjectを再度`fetch`せずに条件付きOperationのtargetを構築できる。
 
-`limit`は1以上とする。Hostはdepthとlimitへ実装上の上限を設定し、超過したrequestには`ResourceLimitExceeded`を返す。
+`limit`は1以上とし、`0`は`InvalidRequest`とする。Hostはdepthとlimitへ実装上の上限を設定し、有効範囲内だが上限を超えたrequestには`ResourceLimitExceeded`を返す。
 
 ## `fetch_interface`
 
@@ -473,11 +483,13 @@ Clientは次を検証する。
 - Descriptorの`format`がClientの対応するversionである。
 - 同じInterface参照と同じvalidator valueを持つ既存cache entryがある場合、validatorが存在する観測ではDescriptorがそのentryと一致する。
 
+ResponseまたはDescriptorがProtocol contractに違反する場合、ClientはHostが返したProtocol failureではなく`InvalidResponse`として扱う。Descriptorが構造的にはvalidだが、その`format`をClientが実装していない場合は`UnsupportedDescriptorFormat`として扱い、`InvalidResponse`と混在させない。
+
 Clientはvalidatorが存在するInterface observationを、`(interface, validator)`の組でcacheする。Interface参照ごとに最後に成功した観測を現在のcache entryとしてよいが、実行中のOperationが参照する観測はresponseのvalidationが完了するまで保持する。
 
 - 同じInterface参照でvalidatorが異なる場合は、同じInterfaceの新しい状態としてlatest observationを更新する。
 - Validatorが存在しないInterface参照はimmutableなDescriptorとして、Interface参照だけをcache keyに使用できる。
-- 同じInterface参照と同じvalidator valueで異なるDescriptorを受け取った場合は`InvalidResult`として扱い、そのDescriptorをOperationへ使用しない。
+- 同じInterface参照と同じvalidator valueで異なるDescriptorを受け取った場合は`InvalidResponse`として扱い、そのDescriptorをOperationへ使用しない。
 - 新しい観測を得ても、異なるvalidatorを使用して実行中のrequestに必要なDescriptorをresponse validation前に破棄しない。
 
 `fetch_interface`は現在のDescriptorを観測するinteractionであり、requestにvalidatorを含めない。Responseにvalidatorが存在する場合、Clientは後続の`call_operation`で、そのDescriptorに基づくOperation実行の必須preconditionとして使用する。Responseにvalidatorが存在しない場合、そのInterface参照のDescriptorはimmutableであり、`call_operation`の`interface.validator`を省略する。
@@ -542,7 +554,9 @@ Validatorの比較はopaque bytesの完全一致で行う。Clientはvalidator
 
 HostはOperationをInterfaceから除外して存在を非公開にすることも、Interfaceへ含めたうえで実行時に`PermissionDenied`として拒否することもできる。
 
-Clientはresultを、requestの`interface`が指定し、Hostがpreconditionを確認して固定したOperation return typeに従って検証する。Validationに失敗したvalueをApplicationへ渡さない。
+Clientはresultを、requestの`interface`が指定し、Hostがpreconditionを確認して固定したOperation return typeに従って検証する。Validationに失敗したsuccess responseはHostから返されたProtocol failureではなく`InvalidResponse`として扱い、そのvalueをApplicationへ渡さない。
+
+Host Runtimeがimplementation resultのencodeまたはvalidation failureを送信前に検出し、Operationのeffectがcommitされていないと保証できる場合は`Internal`を返す。Operationが未実行またはrollback済みであることを保証できず、validなsuccess responseも返せない場合は`OperationOutcomeUnknown`を返す。
 
 ## Protocol responseとfailure
 
@@ -566,7 +580,6 @@ enum ProtocolErrorCode {
     InterfaceMismatch,
     OperationNotFound,
     InvalidArguments,
-    InvalidResult,
     ValidatorRequired,
     ValidatorMismatch,
     InterfaceValidatorRequired,
@@ -574,24 +587,56 @@ enum ProtocolErrorCode {
     PermissionDenied,
     ResourceLimitExceeded,
     Internal,
+    OperationOutcomeUnknown,
 }
 ```
 
-`message`は人間向けのboundedな診断であり、Clientが分岐に使用する安定した値ではない。Clientは`code`を使用する。
+`message`は人間向けのboundedな診断であり、Clientが分岐に使用する安定した値ではない。Clientは`code`を使用する。Hostは秘密情報、非公開Object、backend path、credential、内部stack traceをmessageへ含めない。
 
-Validator関連errorの回復対象は次のとおりである。
+各interactionが返してよいcodeは次に限定する。
 
+| Code | `fetch` | `fetch_tree` | `fetch_interface` | `call_operation` |
+| --- | --- | --- | --- | --- |
+| `InvalidRequest` | ✓ | ✓ | ✓ | ✓ |
+| `ResourceLimitExceeded` | ✓ | ✓ | ✓ | ✓ |
+| `NotFound` | ✓ | ✓ | — | ✓ |
+| `InterfaceNotFound` | — | — | ✓ | — |
+| `InterfaceMismatch` | — | — | — | ✓ |
+| `InterfaceValidatorRequired` | — | — | — | ✓ |
+| `InterfaceValidatorMismatch` | — | — | — | ✓ |
+| `OperationNotFound` | — | — | — | ✓ |
+| `ValidatorRequired` | — | — | — | ✓ |
+| `ValidatorMismatch` | — | — | — | ✓ |
+| `InvalidArguments` | — | — | — | ✓ |
+| `PermissionDenied` | — | — | — | ✓ |
+| `Internal` | ✓ | ✓ | ✓ | ✓ |
+| `OperationOutcomeUnknown` | — | — | — | ✓ |
+
+Hostがinteractionに許可されていないcodeを返した場合、Clientはそのerror responseを`InvalidResponse`として扱う。
+
+Validatorおよび観測関連errorの回復対象は次のとおりである。
+
+- `NotFound`では、Clientは対象Entryをstaleとして扱い、必要に応じて親Treeを再観測する。
+- `InterfaceNotFound`では、ClientはそのInterface observationを使用せず、参照元Objectを再観測できる。
 - `ValidatorRequired`または`ValidatorMismatch`では、Clientは対象Objectを再観測してから、ユーザーまたはApplicationの判断なしにOperationを自動再実行してはならない。
 - `InterfaceMismatch`では、Clientは対象Objectを再観測し、現在公開されているInterface参照の集合を取得する。
 - `InterfaceValidatorRequired`または`InterfaceValidatorMismatch`では、Clientは同じInterface参照を`fetch_interface`で再観測してから、現在のDescriptorに基づいてOperationを再構築する。ユーザーまたはApplicationの判断なしにOperationを自動再実行してはならない。
+- `InvalidRequest`または`InvalidArguments`では、Clientは同じrequestを変更せずに再送しない。
+- `ResourceLimitExceeded`では、Clientはrequest size、depth、limit等を削減できるが、`call_operation`を自動再実行しない。
+
+`call_operation`が`OperationOutcomeUnknown`以外のProtocol failureを返した場合、HostはOperationのeffectがcommitされていないことを保証する。`OperationOutcomeUnknown`は、HostがOperationの未実行またはrollbackを保証できず、validなsuccess responseも返せないことを示す。Clientは対象Objectをstaleとして扱い、Operationを自動再実行せず、再観測またはdomain固有の照会手段を利用者へ提示する。
+
+`Internal`はHost内部のfailureであり、`call_operation`ではeffectがcommitされていないと保証できる場合だけ返す。Clientは`Internal`を理由にOperationを自動再実行しない。Transport timeoutやconnection lossでresponse自体を受け取れない場合もOperation outcomeは不明になり得るが、それはProtocol failureではなくTransport failureとして扱う。
 
 Objectを主体へ公開しない場合、HostはそのObjectをClient-facing Worldspaceに存在しないものとして扱い、`fetch`、`fetch_tree`、`call_operation`へ`NotFound`を返す。Objectの存在を秘匿する目的で`PermissionDenied`を返してはならない。
 
-`PermissionDenied`は、現在公開されているInterfaceに宣言されたOperationについて、その存在を公開しつつ実行を認めない場合に使用する。Operation自体をInterfaceから除外している場合は`OperationNotFound`を返す。
+`PermissionDenied`は、現在公開されているInterfaceに宣言されたOperationについて、その存在を公開しつつ実行を認めない場合に使用する。Operation自体をInterfaceから除外している場合は`OperationNotFound`を返す。Operation argumentが参照するdomain resourceの不存在やbusiness rule failureを、対象Objectの`NotFound`へ変換しない。
+
+`InvalidResponse`と`UnsupportedDescriptorFormat`はClient-localなclassificationであり、`ProtocolErrorCode`ではない。前者はsuccess responseまたはerror responseがProtocol contractに違反した場合、後者はvalidなDescriptor formatをClientが実装していない場合に使用する。
 
 Protocol failureとdomain failureを混在させない。現在のProtocolでは、Domain failureをApplicationのOperation resultに含まれるUnion caseとして明示する。専用のfailure envelopeは定義しない。
 
-Transport BindingはProtocol Resultをstatus code、response envelope、stream termination等へ対応付ける。
+Transport BindingはProtocol Resultをstatus code、response envelope、stream termination等へ対応付ける。Authentication、route、media type、framing、response不達等のTransport failureをProtocol errorへ変換しない。
 
 ## Resource limit
 
@@ -606,7 +651,9 @@ HostとClientは、untrusted inputによるresource exhaustionを避けるため
 - `fetch_tree`のdepthとlimit。
 - Protocol error messageの長さ。
 
-各実装はこれらにboundedな上限を設定する。上限を超えたrequestまたはresponseは`ResourceLimitExceeded`として扱い、現在のProtocolではlimit negotiationを定義しない。
+各実装はこれらにboundedな上限を設定する。上限を超えたrequestは、interaction固有のtarget resolutionまたはOperation dispatchより前に`ResourceLimitExceeded`として拒否する。Hostがread-only responseを構築する途中で上限超過を検出した場合も、success responseの代わりに`ResourceLimitExceeded`を返してよい。
+
+`call_operation`では、dispatch後にresult size、encoding、backend budget等の問題を検出しても、effectがcommitされていないと保証できる場合だけ`ResourceLimitExceeded`または`Internal`を返す。未実行またはrollbackを保証できない場合は`OperationOutcomeUnknown`とする。Client側のresponse byte limit超過やresponse不達はProtocol failureへ変換せず、Transport failureとして扱う。現在のProtocolではlimit negotiationを定義しない。
 
 ## Batch
 

4-client.md

@@ -53,9 +53,9 @@ struct CachedEntry {
 - Entry Treeはpathと親子関係を保持し、Object storeはObjectの現在状態を保持する。
 - 同じObjectを複数のEntryが参照しても、Object stateをEntryごとに複製しない。
 
-Objectの`interfaces`はmembershipをsetとして扱い、同じ参照の重複を`invalid_result`として拒否する。ClientはHostの立項順をCachedObjectへ保持し、InterfaceやOperationの表示順に使用してよい。
+Objectの`interfaces`はmembershipをsetとして扱い、同じ参照の重複を`InvalidResponse`として拒否する。ClientはHostの立項順をCachedObjectへ保持し、InterfaceやOperationの表示順に使用してよい。
 
-同じ`ref`と同じvalidator valueを持つObjectを再観測したとき、validatorが存在するにもかかわらずObject representationが異なる場合、Clientはresponseを`invalid_result`として扱う。同じ`ref`でvalidatorが異なる場合、またはvalidatorが存在しない場合は、同一Objectの新しい観測として最後に成功した観測でCachedObjectを更新する。
+同じ`ref`と同じvalidator valueを持つObjectを再観測したとき、validatorが存在するにもかかわらずObject representationが異なる場合、Clientはresponseを`InvalidResponse`として扱う。同じ`ref`でvalidatorが異なる場合、またはvalidatorが存在しない場合は、同一Objectの新しい観測として最後に成功した観測でCachedObjectを更新する。
 
 このnormalizeはClientのcache実装であり、Objectと別のWIP resourceまたはProtocol上のEntry resourceを導入するものではない。
 
@@ -122,7 +122,7 @@ Backend UIDが適している場合、Hostはそれを直接または変換し
 
 Clientは、エントリを観測した後にOperationを実行するまでの間に、そのエントリが別Objectを指すようになっていないことを検証する責務を持つ。
 
-Objectが`validator`を持つ場合、Clientは観測したpathとvalidatorを対応付ける。条件付きOperationでは両者をtargetとしてHostへ渡し、validatorの比較と実行をHost上でatomicに行わせる。ValidatorはAIやユーザーに直接管理させない。HTTPS Bindingは、semanticsが適合する場合にHTTP ETag等へ対応付けてよい。
+Objectが`validator`を持つ場合、Clientは観測したpathとvalidatorを対応付ける。条件付きOperationでは両者をtargetとしてHostへ渡し、validatorの比較と実行をHost上でatomicに行わせる。ValidatorはAIやユーザーに直接管理させず、Transport BindingでもProtocol struct上のfieldとして保持する。HTTP ETag等のrepresentation metadataをWIP validatorの代用として解釈しない。
 
 ClientはOperationに選択したInterface参照と、`fetch_interface`で観測したoptionalなInterface validatorもrequestへ含める。MutableなInterfaceがvalidatorを返す場合は必須preconditionとして使用し、`InterfaceValidatorMismatch`ではInterfaceだけを再観測する。`InterfaceMismatch`ではObjectを再観測し、現在のInterface集合を取得する。いずれの場合もOperationを自動再試行しない。
 
@@ -130,6 +130,23 @@ Operation responseが新しいObject validatorを返した場合、Clientは対
 
 対象が変化していた場合、Clientは新しいObjectに対してOperationを自動再試行せず、対象が変化したことを上位インターフェースへ通知して再観測を要求する。
 
+## Failure handling
+
+ClientはHostが返すProtocol errorの`code`で回復actionを決定し、人間向け`message`やTransport statusからcodeを推測しない。各interactionで許可されていないcode、schemaに違反するsuccess / error response、同じvalidatorに矛盾するrepresentationは`InvalidResponse`として拒否する。Validだが未対応のInterface Descriptor formatは`UnsupportedDescriptorFormat`として区別する。
+
+- `NotFound`では対象Entryをstaleとして扱い、必要に応じて親Treeを再観測する。
+- `InterfaceNotFound`では参照元Objectを再観測できる。
+- `InterfaceMismatch`では対象Objectを再観測する。
+- `InterfaceValidatorRequired`または`InterfaceValidatorMismatch`では対象Interfaceを再観測する。
+- `ValidatorRequired`または`ValidatorMismatch`では対象Objectを再観測する。
+- `InvalidRequest`または`InvalidArguments`では同じrequestを変更せずに再送しない。
+- `ResourceLimitExceeded`ではrequest size、depth、limit等を削減できるが、Operationを自動再実行しない。
+- `PermissionDenied`では公開済みOperationが実行拒否されたことを示し、Object自体が閲覧禁止で存在するとは推測しない。
+
+`OperationOutcomeUnknown`では、Operationが未実行またはrollback済みであることが保証されない。ClientはOperationを自動再実行せず、対象Objectをstaleとして再観測するか、domain固有の照会手段を提示する。`Internal`、Transport timeout、connection lossの場合も、Effect annotationがない現在のProtocolではOperationを自動再実行しない。Response不達はProtocol errorへ変換せず、Transport failureとOperation outcomeが不明な状態をClient内部で保持する。
+
+HTTP authentication failureとWorldspace endpoint全体のaccess denialはTransport layerのfailureであり、WIPの`PermissionDenied`へ変換しない。
+
 ## 想定実装
 
 Clientは用途に応じて複数の上位インターフェースを提供できる。

draft/dynamic-worldspace-projection.md

@@ -231,7 +231,9 @@ Host APIは、backend transaction、lock、revision付きconditional update、fi
 - Child enumeration、backend lookup、descriptor生成、Value変換へboundedなresource limitを適用できる。
 - `fetch_tree`の`depth`と`limit`をProvider側の無制限列挙へ変換しない。
 - Client disconnect、timeout、Host shutdown等に応じてbackend処理へcancellationを伝播できる。
-- Side effectを持つOperationでは、cancellationやtimeoutを未実行またはrollback済みの証明として扱わず、実行結果が不明なcallをHost Runtimeが自動retryしない。
+- `call_operation`をdispatchする前にresource limitへ達した場合は`ResourceLimitExceeded`として拒否し、Operationを実行しない。
+- Dispatch後のcancellation、timeout、implementation failure、result encoding failureについて、Operationが未実行またはrollback済みであると保証できる場合だけ`Internal`または`ResourceLimitExceeded`を返す。保証できない場合は`OperationOutcomeUnknown`を返す。
+- Side effectを持つOperationでは、cancellationやtimeoutを未実行またはrollback済みの証明として扱わず、Host RuntimeもClientも実行結果が不明なcallを自動retryしない。
 - Partial backend failureをProtocol上の成功Treeへ黙って変換しない。
 
 ### RustとTypeScriptで同じsemanticsを表現できること

draft/rust-api-model.md

@@ -428,15 +428,16 @@ Operation argumentとして`Entry` pathを受け取った場合も、pathの所
 
 ## Error model
 
-Rust methodのerror表現は、次の三種類を区別できなければならない。
+Rust methodのerror表現は、次の四種類を区別できなければならない。
 
 - Protocol validationまたはdispatch failure。
-- Host / backend implementation failure。
+- Effectがcommitされていないと保証できるHost / backend implementation failure。
+- Operationの未実行またはrollbackを保証できない`OperationOutcomeUnknown`。
 - Interfaceがreturn typeとして宣言したdomain failure。
 
 現在のProtocolでは、domain failureはOperation resultのUnion caseとして表す。Rustの`Result<T, E>`をdomain Union、Host error、または両方のどれへ対応付けるかは未決定である。
 
-MacroがRust panicをdomain failureへ自動変換してはならない。Panic isolationと`Internal`へのmappingはHost Runtimeの実装要件として別途決定する。
+MacroがRust panic、result encode failure、宣言型に違反するimplementation resultをdomain failureへ自動変換してはならない。Host Runtimeは、effectがcommitされていないと保証できる場合だけ`Internal`へmappingし、保証できない場合は`OperationOutcomeUnknown`へmappingする。Clientへ送信済みか不明なtransport切断も自動retryしない。
 
 ## 要件
 
@@ -461,7 +462,8 @@ Rust API modelは少なくとも次を満たす。
 - Object validatorを現在のObject identityと保護対象状態へ結び付け、別Objectに同じprovider-local revisionがあっても一致させない。
 - Object validator比較、identity confirmation、Interface membershipとvalidator比較、DescriptorとOperation実装の固定、authorization、Operation実行を同じatomic boundaryで行う。
 - Object validatorを要求するOperationへの省略を`ValidatorRequired`として拒否できる。
-- Provider、Host Runtime、macro-generated codeのerrorをProtocolErrorへ安全に対応付けられる。
+- Provider、Host Runtime、macro-generated codeのerrorを、effect未commitを保証できる`Internal`と、保証できない`OperationOutcomeUnknown`へ安全に対応付けられる。
+- InvalidなObject、Descriptor、Operation resultをsuccess responseとして送信せず、Host-side validation failureをdomain failureへ変換しない。
 - Rust SDK固有の型やlifetimeをProtocol semanticsとして要求しない。
 
 ## 非目標

draft/typescript-api-model.md

@@ -590,15 +590,16 @@ Operation argumentとして`Entry` pathを受け取った場合も、pathの所
 
 ## Error model
 
-TypeScript methodのerror表現は、次の三種類を区別できなければならない。
+TypeScript methodのerror表現は、次の四種類を区別できなければならない。
 
 - Protocol validationまたはdispatch failure。
-- Host / backend implementation failure。
+- Effectがcommitされていないと保証できるHost / backend implementation failure。
+- Operationの未実行またはrollbackを保証できない`OperationOutcomeUnknown`。
 - Interfaceがreturn typeとして宣言したdomain failure。
 
-現在のProtocolでは、domain failureはOperation resultのUnion caseとして表す。Thrown value、rejected Promise、explicit result objectをHost errorまたはdomain resultへどう対応付けるかは未決定である。
+現在のProtocolでは、domain failureはOperation resultのUnion caseとして表す。Thrown value、rejected Promise、explicit result objectをdomain resultまたはHost errorへどう対応付けるかは、Interface authoring APIで明示しなければならない。
 
-Arbitrary thrown valueをdomain failureへ自動変換してはならない。`Error`以外のthrow、Promise rejection、panicに相当するfatal conditionのisolationと`Internal`へのmappingはHost Runtimeの実装要件として別途決定する。
+Arbitrary thrown value、Promise rejection、result encode failure、宣言型に違反するimplementation resultをdomain failureへ自動変換してはならない。Host Runtimeは、effectがcommitされていないと保証できる場合だけ`Internal`へmappingし、保証できない場合は`OperationOutcomeUnknown`へmappingする。Abortやtransport切断を未実行の証明として扱わず、自動retryしない。
 
 ## Custom transpilerを必須にしない
 
@@ -659,7 +660,8 @@ TypeScript API modelは少なくとも次を満たす。
 - Object validatorを現在のObject identityと保護対象状態へ結び付け、別Objectに同じprovider-local revisionがあっても一致させない。
 - Object validator比較、identity confirmation、Interface membershipとvalidator比較、DescriptorとInterface-specific implementation bindingの固定、authorization、Operation実行を同じatomic boundaryで行う。
 - Object validatorを要求するOperationへの省略を`ValidatorRequired`として拒否できる。
-- Provider、Host Runtime、runtime definition codeのerrorをProtocolErrorへ安全に対応付けられる。
+- Provider、Host Runtime、runtime definition codeのerrorを、effect未commitを保証できる`Internal`と、保証できない`OperationOutcomeUnknown`へ安全に対応付けられる。
+- InvalidなObject、Descriptor、Operation resultをsuccess responseとして送信せず、Host-side validation failureをdomain failureへ変換しない。
 - Custom transpiler、decorator、特定bundlerをHost実装の必須要件にしない。
 - TypeScript SDK固有の型をProtocol semanticsとして要求しない。
 

draft/unresolved-issues.md

@@ -41,7 +41,5 @@
 対象: [WIP over HTTPS](wip-over-https.md)
 
 - Protocol primitive、Object、Interface Descriptor、ValueのJSON encoding。
-- Protocol failureのHTTP statusとerror body。
+- Batch件数、request / response byte size、timeoutの具体的な上限。
-- Batch件数、request / response byte size、timeoutの上限。
-- Batch envelope自体が不正な場合のHTTP statusとerror body。
 - Effect annotationを採用した場合に、副作用のない`call_operation`をbatch対象へ加えるか。

draft/wip-over-https.md

@@ -23,13 +23,71 @@ OperationがWebSocket等のendpointを通常のApplication dataとして返す
 - `fetch_interface`
 - `call_operation`
 
-具体的なHTTP method、endpoint、content type、error mapping、認証方式、validator mapping、batch表現は、このbinding仕様側で定義する。
+HTTP method、endpoint、content type、success / error response、Protocol errorのHTTP status、validator mapping、authenticationの位置付けは以下で定義する。Batch表現の残る詳細も、このbinding仕様側で定義する。
+
+## Endpointとroute
+
+WIP endpointは、一つのWorldspace access surfaceを指すabsolute HTTPS URLである。Endpoint URLのpath prefixはdeploymentが任意に選択できる。Clientはorigin直下や`/wip`等の既定prefixを仮定しない。
+
+Endpoint URLはqueryとfragmentを持たず、pathが`/`で終わるcanonical formとする。利用者から末尾`/`のないURLを受け付ける実装は、routeを解決する前に`/`を追加してcanonical formへ変換する。
+
+各routeはendpoint URLをbase URLとして、次のrelative pathをRFC 3986に従って解決する。すべてのinteractionは`POST`を使用する。
+
+| Interaction | HTTP method | Relative path |
+| --- | --- | --- |
+| `fetch` | `POST` | `v1/fetch` |
+| `fetch_tree` | `POST` | `v1/fetch_tree` |
+| `fetch_interface` | `POST` | `v1/fetch_interface` |
+| `call_operation` | `POST` | `v1/call_operation` |
+| batch | `POST` | `v1/batch` |
+
+`v1`はWIP over HTTPS Bindingのmajor versionである。Interactionごとに独立したrouteを設定したり、固定suffixを別名へ置き換えたりしない。
+
+例えば、次のendpointを指定した場合、
+
+```text
+https://gateway.example/tenants/acme/proxies/filesystem/wip/
+```
+
+`fetch` routeは次になる。
+
+```text
+https://gateway.example/tenants/acme/proxies/filesystem/wip/v1/fetch
+```
+
+Endpointのpath prefixはHTTP deployment上のroutingであり、Worldspace内のpathではない。Worldspace pathは常に各WIP requestのlogical fieldとして渡す。Hostまたはreverse proxyは異なるbase pathに複数のWorldspaceやproxy surfaceをmountできるが、一つのendpointに属するinteractionはすべて同じbase URL配下へ公開する。
+
+Clientは異なるcanonical endpoint間でKnown Space、Object observation、Interface cacheを混在させない。同じendpointであっても認証またはsecurity contextによって異なるWorldspaceが見える場合、それらの観測状態を共有しない。
+
+## HTTP message
+
+Requestおよびbodyを持つresponseは`Content-Type: application/json`を使用し、JSON textをUTF-8でencodeする。Clientは`Accept: application/json`を送信する。
+
+WIP routeで受信したbodyがmalformed JSONである、logical request structへdecodeできない、required fieldがない、未知fieldがある、またはfield semanticsに違反する場合、Hostは`400 Bad Request`と`invalid_request` envelopeを返す。Unsupported media typeは`415 Unsupported Media Type`、受理できない`Accept`は`406 Not Acceptable`とし、これらTransport BindingのfailureをProtocol errorへ変換しない。
+
+単独interactionが成功した場合、Hostは`200 OK`を返し、response bodyへ対応するProtocol responseを直接encodeする。単独interactionのsuccess bodyを`result`等の追加envelopeで包まない。
+
+Protocol failureの場合、Hostは非2xx statusを返し、response bodyへ後述するProtocol error envelopeをencodeする。HTTP statusは成功と失敗の大分類および既存HTTP infrastructureのための補助情報であり、Protocol failureの機械可読な意味を決定しない。ClientはHTTP status、reason phrase、または人間向けmessageからProtocol error codeや回復actionを推測しない。
+
+非2xx responseが有効なProtocol error envelopeを含まない場合、Clientは特定のProtocol errorへ変換せず、HTTPまたはTransport Bindingのfailureとして扱う。これにより、reverse proxyやgatewayが生成したresponseをHost由来の`NotFound`、`PermissionDenied`等と誤認しない。
+
+Clientに再観測、WIP request修正、Operationの権限要求、resource削減等の具体的なactionを求めるProtocol failureは、HTTP statusだけで表さず、対応する`ProtocolErrorCode`としてProtocolに定義する。
+
+## Authentication
+
+WIP over HTTPSは特定のauthentication schemeを要求せず、HTTP authentication、mTLS、gateway、reverse proxy等の既存infrastructureを使用できる。AuthenticationはWIP interactionを実行する主体とsecurity contextを確立するTransport / deployment concernであり、WIP Protocolの`ProtocolErrorCode`を追加して表現しない。
+
+Credentialが欠落または無効でWIP interactionを開始できない場合、HTTP layerは`401 Unauthorized`と、使用するschemeに応じた`WWW-Authenticate`を返してよい。HTTP layerは、特定のWIP endpointが表すWorldspace access surface全体へのaccessを認めない場合に、そのendpointへのrequestを`403 Forbidden`等で拒否してよい。ClientはこれらをProtocol failureへ変換せず、Transport authentication / authorization failureとして扱う。
+
+HTTP layerによるWorldspace全体のaccess controlを通過してWIP interactionを開始した後は、個別Objectへのaccess拒否を「Objectは存在するが閲覧禁止」という状態として公開しない。その主体へ公開しないObjectはClient-facing Worldspaceに存在しないものとして扱い、`fetch`、`fetch_tree`、`call_operation`では`NotFound`を返す。個別Objectの存在を示唆する`PermissionDenied`や、Protocol error envelopeを持たない`403 Forbidden`へ置き換えない。
+
+Authentication後に確立された主体に対するInterface / Operation visibilityとOperation authorizationもWIP Protocol semanticsに従う。現在公開されていないInterfaceには`InterfaceNotFound`、現在のInterfaceに宣言されていないOperationには`OperationNotFound`を返す。`PermissionDenied`は、現在公開されているOperationの存在を示したうえで、その主体による実行だけを拒否する場合に使用する。
 
 ## JSON encodingの基本規則
 
 ProtocolのrecordはJSON object、listはJSON array、optional fieldの省略はJSON fieldの省略としてencodeする。
 
-Protocol structの`String`はJSON string、`Vec<u8>`はbindingが定めるopaque encodingへ対応付ける。Path、Interface参照、Object identity、名前等の意味はJSON typeではなくfieldの位置によって決まる。
+Protocol structの`String`はJSON string、`Vec<u8>`はRFC 4648 Section 4のbase64 stringへ対応付ける。Path、Interface参照、Object identity、名前等の意味はJSON typeではなくfieldの位置によって決まる。
 
 | Field | JSON encoding | 解釈 |
 | --- | --- | --- |
@@ -39,9 +97,9 @@ Protocol structの`String`はJSON string、`Vec<u8>`はbindingが定めるopaque
 | `interface`、`InterfaceTarget.reference` | string | 一つのInterfaceへのopaqueな参照 |
 | `format` | string | Descriptor format identifier |
 | `ref` | string | opaqueなObject identity |
-| `validator` | base64 stringまたはHTTP metadata | opaqueな条件付き操作用value |
+| `validator` | RFC 4648 Section 4のbase64 string | opaqueな条件付き操作用value |
 
-Validatorをresponse bodyのbase64 stringとして運ぶか、HTTP ETag等へ対応付けるかは、このbindingがresponse形態ごとに定める。どちらの場合もClient runtimeは値をopaqueに扱い、AIやユーザーへ直接管理させない。
+すべてのWIP validatorは、対応するProtocol struct上のfieldとしてJSON bodyへencodeする。HTTP headerへ移したことを理由にbody fieldを省略してはならない。Client runtimeはvalidatorをopaqueに扱い、AIやユーザーへ直接管理させない。
 
 未知のJSON fieldを許可する箇所はProtocol側で明示する。Object、Interface Descriptor、request / response、Protocol errorの未宣言fieldは既定で拒否する。
 
@@ -244,30 +302,17 @@ Payloadを持たないUnionは`value`を省略する。
 
 ClientはInterface Descriptorに従ってvalueをdecodeし、`entry`と宣言された位置にあるstringだけをエントリとして認識する。通常の`string`やopaqueな`json`に含まれるpathらしいstringをエントリとして推測してはならない。
 
-## ValidatorとHTTP conditional request
+## Validatorのencoding
 
-WIP Protocolのlogical fieldには、ObjectおよびOperation responseのObject `validator`、Operation requestの`target.validator`、`FetchInterfaceResponse.validator`、Operation requestの`interface.validator`がある。Object validatorとInterface validatorは別のpreconditionであり、同じHTTP headerへ曖昧に畳み込まない。
+WIP Protocolのlogical fieldには、ObjectおよびOperation responseのObject `validator`、Operation requestの`target.validator`、`FetchInterfaceResponse.validator`、Operation requestの`interface.validator`がある。Object validatorとInterface validatorは別のpreconditionであり、それぞれ対応するJSON body fieldへRFC 4648 Section 4のbase64 stringとしてencodeする。
 
-単独のHTTP request / responseで、WIP validatorがHTTPのstrong validator semanticsを満たす場合、HTTPS Bindingは次へ対応付けてよい。
+単独request / responseとbatch subrequest / subresponseは同じvalidator表現を使用する。HostはWIP validatorを`ETag`、`If-Match`、その他のHTTP headerだけにencodeしてbody fieldを省略してはならず、ClientはそれらのheaderをWIP validatorとして解釈しない。
 
-```text
+Host、gateway、またはHTTP cacheは通常のHTTP representation metadataとして`ETag`等を追加してよいが、その値はWIP validatorとは独立しており、WIPのObject identity、Interface observation、またはOperation preconditionを置き換えない。
-Object.validatorまたはCallOperationResponse.validator -> ETag
-CallOperationRequest.target.validator                  -> If-Match
-FetchInterfaceResponse.validator                       -> ETag on fetch_interface response
-CallOperationRequest.interface.validator               -> request body or dedicated header
-validator_mismatch                                     -> 412 Precondition Failed
-validator_required                                     -> 428 Precondition Required
-interface_validator_mismatch                           -> 412 Precondition Failed
-interface_validator_required                           -> 428 Precondition Required
-```
-
-HTTP headerへmappingした場合も、Client adapterは値を対応するProtocol上のObject、Operation response、またはInterface observationへ復元する。Object validatorとInterface validatorの両方がある`call_operation`では、標準`If-Match`だけで二つを表したと推測してはならない。Validatorが対象HTTP response representationの変更を反映しない場合、strong ETagとして使用してはならず、body fieldまたは意味を区別できる専用headerで運ぶ。
-
-Batchではsubresponseごとにvalidatorが存在し得るため、各Object、Operation response、または`fetch_interface` responseのbody fieldとしてencodeする。
 
 ## Protocol error
 
-Protocol failureをJSON response bodyへ含める場合、概念的に次の形を使用する。
+Protocol failureは、非2xx HTTP responseのJSON bodyへ次のenvelopeでencodeする。
 
 ```json
 {
@@ -278,9 +323,36 @@ Protocol failureをJSON response bodyへ含める場合、概念的に次の形
 }
 ```
 
-`code`はProtocolが定義する安定した識別子、`message`は人間向けのboundedな診断である。Clientは`message`の内容で分岐しない。
+`code`はProtocolが定義する`ProtocolErrorCode`をsnake_caseへ変換した安定した識別子、`message`は人間向けのboundedな診断である。Clientは`message`の内容で分岐しない。Clientがfailureの種類と回復actionを決定するときは`code`を使用し、HTTP statusだけから`NotFound`、`InterfaceMismatch`、validator failure等を推測しない。
 
-Protocol error codeとHTTP statusのmapping、およびvalidation errorのstructured detailは未確定である。`not_found`、`interface_mismatch`、`operation_not_found`、`permission_denied`の使い分けと、Object / Interfaceそれぞれのvalidator failureの区別はProtocol semanticsに従い、HTTP statusへのmappingによって変更しない。
+単独interactionのProtocol error codeを次のHTTP statusへ対応付ける。
+
+| Protocol error code | HTTP status |
+| --- | --- |
+| `invalid_request` | `400 Bad Request` |
+| `not_found` | `404 Not Found` |
+| `interface_not_found` | `404 Not Found` |
+| `interface_mismatch` | `409 Conflict` |
+| `operation_not_found` | `404 Not Found` |
+| `invalid_arguments` | `422 Unprocessable Content` |
+| `validator_required` | `428 Precondition Required` |
+| `validator_mismatch` | `412 Precondition Failed` |
+| `interface_validator_required` | `428 Precondition Required` |
+| `interface_validator_mismatch` | `412 Precondition Failed` |
+| `permission_denied` | `403 Forbidden` |
+| `resource_limit_exceeded` | `413 Content Too Large`または`422 Unprocessable Content` |
+| `internal` | `500 Internal Server Error` |
+| `operation_outcome_unknown` | `500 Internal Server Error` |
+
+`resource_limit_exceeded`がrequestまたはresponse representationのbyte size超過を表す場合は`413 Content Too Large`、depth、limit、nesting、collection件数等のlogical limit超過を表す場合は`422 Unprocessable Content`を使用する。Rate limitまたはconcurrency limitによる`429 Too Many Requests`はTransport / deployment concernであり、Core interactionの`resource_limit_exceeded`へ自動変換しない。
+
+HTTP statusはProtocol error codeを置き換えない。複数のcodeが同じstatusを使用し、同じcodeがresource limitの種類に応じて異なるstatusを使用できる。Hostは上記mappingに従わなければならないが、Clientが非2xx responseからvalidなProtocol error envelopeを取得できた場合、statusがmappingと一致しなくても回復actionは`code`に従い、statusから別のcodeを推測しない。Clientはstatus mismatchをTransport Binding違反として診断してよい。2xx responseのerror envelope、または非2xx responseのsuccess bodyは`InvalidResponse`として扱う。
+
+`operation_outcome_unknown`はretryを促す`503 Service Unavailable`へmappingしない。Clientは`500`であってもcodeに従い、Operationを自動再実行せず対象をstaleとして扱う。`internal`についてもEffect annotationがない現在のProtocolではOperationを自動再実行しない。
+
+`InvalidResponse`と`UnsupportedDescriptorFormat`はClient-localなclassificationであり、Hostがerror envelopeで返してはならない。非2xx responseが有効なProtocol error envelopeを含まない場合も、Clientは特定のProtocol errorへ変換せずTransport Binding failureとして扱う。
+
+Clientに特定の回復actionを求める条件をHTTP statusだけで新設しない。その条件がTransport Binding固有のfailureではなくWIP interactionとして回復可能である場合、対応する`ProtocolErrorCode`をProtocolへ追加してからbindingする。
 
 Domain failureをProtocol errorへ変換しない。Domain failureはOperation resultのApplication dataとしてencodeする。
 
@@ -290,7 +362,7 @@ WIP over HTTPSは、複数の独立したCore取得requestを一つのHTTP reque
 
 ClientはKnown SpaceとInterface cacheをもとに必要なrequestだけを選択してbatchを構成する。HostはClientの既知状態を推測して、要求されていないObjectやInterface Descriptorをresponseへ追加しない。
 
-Batch endpointは概念的に`POST {wip-endpoint}/batch`とし、bodyに一意な`id`を持つsubrequestの配列を格納する。
+Batchは上記の`POST v1/batch` routeを使用し、bodyに一意な`id`を持つsubrequestの配列を格納する。
 
 ```json
 {
@@ -358,10 +430,15 @@ Batchには次の規則を適用する。
 - 各`result`は対応するProtocol interactionを単独で呼んだ場合と同じvalueとする。
 - 各`error`は通常のProtocol errorと同じschemaを使用する。
 - HostはClientが要求していないsubresponseを追加してはならない。
+- 各subresponseは`result`または`error`の一方だけを持つ。
 
 初期のbatch形式に格納できるのは`fetch`、`fetch_tree`、`fetch_interface`とし、`call_operation`は含めない。将来Effect annotationを採用する場合に、副作用を持たないと明示されたOperationをbatch対象へ加えるかを改めて検討する。
 
-Batch件数、request / response byte size、timeoutの上限、およびbatch envelope自体が不正な場合のHTTP statusはbindingの詳細として定める。
+Batch envelopeがvalidである場合、Hostは一部または全部のsubrequestがProtocol failureでも`200 OK`を返す。各subresponseの`error`は対応するinteractionで許可されたProtocol errorの`code`と`message`を直接含み、itemごとのHTTP statusは持たない。
+
+`requests`の欠落、duplicate `id`、未知の`method`、subrequest envelope自体のfield違反等によりbatch全体をsubrequest列として解釈できない場合、Hostは`400 Bad Request`とtop-levelの`invalid_request` error envelopeを返す。既知の`method`を持つsubrequestの`arguments`が対応するlogical requestとして不正な場合は、batch全体を拒否せず、その`id`のsubresponseへ`invalid_request`を返す。Batch requestのbyte size超過には`413 Content Too Large`、件数等のlogical limit超過には`422 Unprocessable Content`を使用し、いずれもtop-levelの`resource_limit_exceeded` error envelopeを返す。
+
+Batch件数、request / response byte size、timeoutの具体的な上限はbindingの運用profileまたはHost configurationでboundedに定める。
 
 ## 非目標