feat: add Astro reference site and organize book contents

contents/2.2-operation-and-interface.md

@@ -0,0 +1,230 @@
+# 2.2. Operation and Interface
+
+## Interface
+
+ObjectはOperation定義を直接持たず、0個以上のInterface参照をordered setとして持つ。各InterfaceはObjectが公開する一つのcapability namespaceである。
+
+Interfaceは、Objectで利用できるOperationと、各Operationのparameter、return type、documentationを定義する。複数のObjectが同じInterfaceを共有できるため、Operation定義をObjectごとに重複して送る必要はない。
+
+ObjectのInterface集合はset semanticsを持ち、同じ参照を重複して含めない。列挙順はOperation解決には影響しないが、Hostの立項順としてUI表示に使用できる。Operation callは集合から一つのInterfaceを明示して、そのDescriptor内のOperationを実行する。
+
+Interface実装者は、RustのtraitやTypeScriptのdefinition API等を使って実装コード上でInterfaceを宣言する。Libraryはその宣言から、typed handler、runtime validation、およびmachine-readableなInterface Descriptorを生成する。
+
+Interface Descriptorは人間が手書きするschema fileではない。Hostが`fetch_interface`で公開し、Clientが参照単位でcacheするprotocol dataである。
+
+## Interfaceの識別とscope
+
+Interface参照は、Worldspace上の絶対pathである`scope`と、そのscope内のlocal nameである`name`を別fieldとして持つ構造化データである。同じClient-facing Worldspace内の同じ有効な`(scope, name)`は同じInterfaceを表す。
+
+```text
+{ scope: "/github", name: "issue.read" }
+{ scope: "/gitlab", name: "issue.read" }
+```
+
+この二つは同じlocal nameを持つが、異なるInterface参照である。Local nameの`.`等に階層やOperationとの区切りの意味を持たせない。同じscope内の異なるInterfaceへ同じnameを割り当てない。複数Providerを同じscopeへ登録する場合も、Hostが名前の衝突を検出・解消する。
+
+ScopeはClientに対してHostが公開するWorldspaceのrootを基準とする。Backendのpath、filesystem root、HTTP endpointのprefixではなく、相対pathは認めない。異なるWorldspace間で同じ`(scope, name)`を同一Interfaceとして扱わない。
+
+Objectが利用できるscopeは、そのObjectの配置pathとの[祖先関係](2.1-object-tree-schema.md#interface-scope)に従う。この制約はInterfaceの自動継承ではない。Objectは使用するInterfaceを明示的に公開し、scopeだけを根拠にOperationを追加したり、実行を認可したりしない。
+
+構造とvalidationは[3. Protocol](3-protocol.md#interface-reference)、`/github::issue.read#read`等の人間・AI向け短縮表記は[4.2. Text View](4.2-text-view.md#参照表記)で定義する。Interface参照とOperation名を連結した表示文字列をProtocolの参照fieldへ格納しない。
+
+Hostによるproxy・Worldspace合成では、Hostがscopeを公開先の配置へ変換する。Path、typed `entry`、identity、validatorとの一貫性は[Worldspace composition](3-protocol.md#worldspace-composition)に従う。
+
+## Scope Objectと有効期間
+
+Scopeは、そのpathにあるObject（scope Object）に紐づく。Object自身のpathをscopeにするself-scopeを許可し、root Objectもscope `/`を利用できる。Scope Object自身がそのscopeの全Interfaceを`interfaces`へ公開する必要はない。
+
+Interfaceの識別は`(scope, name)`のままであり、scope Objectの`ref`はその識別子の第三成分ではない。`ref`がある場合は観測したObjectとの紐付きを確認するために用いる。Objectの状態を確認するvalidatorや、Descriptorの版を確認するInterface validatorとは役割が異なる。Scope Objectの通常の状態更新だけを理由に、scopeの紐付きを無効にしない。
+
+Scope Objectがそのpathから削除・移動・差し替えられると、旧Objectに紐づくInterface参照の有効期間は終了する。同じpathへ新しいObjectとInterfaceを公開することは許可するが、旧Objectの登録を暗黙に引き継がない。移動先では新しいscopeによる別の参照となり、同じ`ref`を観測してもClientにInterface参照の移動追跡やcacheの付け替えを要求しない。
+
+Scope Objectの`ref`はoptionalである。`ref`のないObjectが同じpathで差し替えられても、そのidentityを追跡できないことは仕様上許容される。これを不正なHostとしたり、差し替えの検出を必須にしたりしない。ただし、現在のObjectへのInterface membership、scopeの適合、指定されたvalidator、authorizationは引き続き検証する。存続中の同じInterfaceについて、`ref`がないことを理由にDescriptorのimmutable / validator規則を弱めない。
+
+Clientはscope Objectがそのpathから消えたことを確認した場合、そのscopeのInterface cacheを破棄できる。Client-localなcache evictionやindexable edgeの消失だけをObject削除の証拠にしない。実行中callは固定済みの観測を使用し、結果検証が終わるまで必要なDescriptorを保持する。削除通知やClientによる常時監視は要求しない。
+
+具体的な紐付きの観測とcall preconditionは[Protocol](3-protocol.md#scope-objectの紐付き)に従う。
+
+## Interface Descriptor
+
+一つのInterface Descriptorは一つのInterfaceを定義し、少なくとも次を保持する。
+
+- Format version
+- Interface documentation
+- Named type declaration
+- Operation declaration
+- Operationごとのparameterとreturn type
+- Type、field、parameter、case等のdocumentation
+
+Descriptorのlogical structは[3. Protocol](3-protocol.md)で定義する。Code-firstな生成は本章、人間とAIへのInterface signatureは[4.2. Text View](4.2-text-view.md)で扱う。
+
+Clientは取得したDescriptorを構造検証および意味検証してからcacheする。Named typeの参照解決、Operation callのvalidation、表示生成には検証済みのInterfaceだけを使用する。
+
+## Operation declaration
+
+Operationは、名前付きparameter、return type、documentationを持つ。
+
+人間とAIへ提示する場合は、Interface DescriptorからIDL風のInterface signatureを生成できる。以下はOperation部分の表示例である。
+
+```text
+/// "Returns items related to this Object."
+operation get_related_items(
+  relation: Relation,
+  limit?: integer,
+) -> {
+  items: [entry],
+  next_cursor?: string,
+};
+```
+
+Interface signatureはInterfaceの交換形式や入力言語ではなく、検証済みDescriptorから生成する表示である。Object signatureとInterface signatureの表記は[4.2. Text View](4.2-text-view.md)で定義する。
+
+Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter listとして表し、`call_operation`には空のrecordを渡す。
+
+```wip
+operation refresh() -> unit;
+```
+
+Return typeにはDescriptorで定義される任意のvalue typeを使用できる。Evolution compatibilityが必要なOperationでは、fieldを追加できるrecordをreturn typeの基本とする。
+
+Operationの用途は短いdocumentationで説明する。長文documentationや大量のApplication dataをInterface Descriptorへ埋め込まない。
+
+Operation名は一つのInterface Descriptor内で一意とする。異なるInterface間では同じOperation名を使用でき、`call_operation`は構造化Interface参照とOperation名の組で解決する。表示用のqualified表記は[Text Viewの参照表記](4.2-text-view.md#参照表記)に従い、Protocolでは参照とOperation名を別fieldとして扱う。
+
+## `fetch_interface`
+
+`fetch_interface(interface)`は、Interface参照に対応する現在のInterface Descriptor、optionalなscope Objectの`ref`（`scope_ref`）、optionalなInterface validatorを一つの観測として取得する。
+
+```text
+fetch_interface(interface) -> Interface Descriptor, scope_ref?, validator?
+```
+
+ObjectはInterface参照のordered setだけを持ち、Descriptorを先行同梱しない。ClientはInterface cacheと各参照を比較し、未知のDescriptorを取得する。Interface validator mismatch等で更新が必要になった参照は再取得する。Hostは主体へ公開したObjectの各Interface参照について、現在のDescriptorをその主体から取得可能にしなければならない。
+
+同じ有効期間内のInterface参照とvalidatorの組は同じDescriptorを表す。Validatorを返さないInterface参照は、その参照の有効期間中immutableでなければならない。`scope_ref`はこの観測の紐付きmetadataとして保持し、参照の識別子へ組み込まない。
+
+HostはClientのcache状態を推測して、要求されていないDescriptorをObject responseへ追加しない。複数のDescriptorが必要なClientは、それぞれの`fetch_interface`を個別に並行実行できる。
+
+## Operationの可視性
+
+Hostは、主体の権限やrole / capabilityに基づいて、その主体へ公開するInterface参照の集合を決定してよい。同じObjectでも、主体ごとに異なるInterface集合を返してよい。
+
+Operationを主体に認識させない場合、Hostは次のいずれかを選べる。
+
+- そのOperationをcapabilityとしてまとめたInterface参照をObjectの集合から除外する。
+- そのOperationを宣言しない別のInterface Descriptorを参照する。
+
+ClientがObjectで公開されていないInterface参照を指定した場合は`InterfaceMismatch`、公開されているInterfaceに宣言されていないOperation名を指定した場合は`OperationNotFound`を返す。
+
+Operationの存在を公開しつつ実行だけを認めない設計も可能である。この場合はOperationをいずれかのInterfaceに宣言し、`call_operation`時のauthorizationで拒否して`PermissionDenied`を返す。
+
+したがって、Hostは主体に対して次を独立に選択できる。
+
+- Object自体を公開せず、そのObjectへの`observe`とOperation callを`NotFound`にする。
+- Objectを公開するが、特定Interfaceを集合から除外する。
+- Objectを公開し、特定Operationを含まないInterfaceを使用する。
+- Object、Interface、Operationを公開するが、そのOperationの実行を`PermissionDenied`にする。
+
+Interface集合と各Interface内のOperation可視性は、頻繁に変化する実行可否やdomain stateを表すものではなく、**その主体に対してどのcapabilityを公開するか**というprojectionとして扱う。
+
+WIPはOperationの`available` / `disabled`のような揮発的状態をInterface集合へ同期することを前提としない。現在状態を判断する必要がある場合は、必要に応じてdomain固有のOperationで観測する。公開されたOperationについても、最終的なauthorizationと実行条件の判定は`call_operation`時にHostが行う。
+
+## `call_operation`
+
+`call_operation`は、指定pathにあるObjectに対して、Interfaceに宣言されたOperationを実行する。
+
+```text
+call_operation(target, interface, operation, arguments) -> result, validator?
+```
+
+- `target.path`は対象Objectを観測したpath。
+- `target.validator`はObjectから得たoptionalなopaque validator。
+- `interface.reference`は対象Objectの`interfaces`から選んだInterface参照。
+- `interface.scope_ref`は`fetch_interface`で観測したscope Objectのoptionalな`ref`。
+- `interface.validator`は`fetch_interface`で観測したoptionalなInterface validator。
+- `operation`は選択したInterfaceに宣言されたOperation名。
+- `arguments`はOperationのparameterに従う名前付きrecord。
+- `result`はOperationのreturn typeに従うvalue。
+- Responseの`validator`はOperation実行後のObject状態に対してHostが発行したoptionalな値。
+
+HostはOperationを実行する前に、次を検証する。
+
+1. `target.path`が存在する。
+2. `target.validator`が指定されている場合、現在のObject validatorと一致する。
+3. `interface.reference`が`(scope, name)`の完全一致でObjectの現在の`interfaces`に含まれ、対象pathに対するscopeの祖先制約（self-scopeを含む）を満たす。`interface.scope_ref`が指定されている場合は現在のscope Objectの`ref`と一致する。
+4. MutableなInterfaceでは`interface.validator`が指定され、現在のInterface validatorと一致する。
+5. 選択したInterfaceにOperationが宣言されている。
+6. Argumentsがparameter declarationに従っている。
+7. ClientがOperationを実行できる。
+
+対象Objectが現在のClient-facing Worldspaceへ公開されていない場合は`not_found`、指定Interfaceが対象Objectの現在の`interfaces`に含まれない場合や、指定された`scope_ref`の紐付きを確認できない場合は`interface_mismatch`、Operationが指定Interfaceに宣言されていない場合は`operation_not_found`、宣言されたOperationの実行が認められない場合は`permission_denied`を返す。`scope_ref`を持たない観測とcallも許可し、その省略だけでは拒否しない。
+
+Object validator、Interface membership、scope Objectの紐付きと指定された`scope_ref`、Interface validator、Descriptor、Operation implementation、backend対象の確認と固定は、Operation実行に対して一貫したpreconditionとして扱う。Object validatorが一致しない場合は`validator_mismatch`、要求されるObject validatorがない場合は`validator_required`を返す。Mutable Interfaceのvalidatorがない場合は`interface_validator_required`、一致しない場合は`interface_validator_mismatch`を返す。いずれの場合もHostはOperationを実行しない。
+
+Argumentsに未知のfieldがある場合、必須parameterがない場合、またはvalueが宣言型に一致しない場合、HostはOperationを実行せず`invalid_arguments`を返す。
+
+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
+
+Operation argumentsとresultは、Applicationが定義し、利用するdataである。
+
+WIPは次を規定する。
+
+- Descriptor上の型表現
+- Transport上のencoding
+- ClientとHostのboundary validation
+- `entry`等のWIP固有型の意味
+
+WIPは次を規定しない。
+
+- Dataのdomain上の意味
+- 永続化方法
+- Application内部のdomain model
+- Business rule
+- Clientが取得したdataを利用する方法
+
+Wire schema上正しいことと、domain上有効であることは別である。例えばargumentsが型に従っていても、現在のdomain stateが操作を許可しない場合、Operation implementationはdomain failureを返し得る。
+
+## Operation Resultとエントリの発見
+
+Operation Resultには、Descriptorの`entry`型として新しいエントリのpathが含まれ得る。
+
+`entry`は同じWorldspace内のcanonical absolute pathである。Clientはreturn typeに従って`entry`型の位置を認識する。通常の`string`やopaqueな`json`に含まれるpathらしい文字列を、エントリとして推測してはならない。
+
+Clientは発見したpathを参照として利用でき、Objectの公開情報が必要になったときに、必要な深さで`observe`する。発見したすべてのpathの即時取得は要求しない。Operation ResultへObject公開情報やInterface Descriptorを先行同梱しない。
+
+Operationの実行対象と、結果として発見されたエントリのTree上の位置は独立している。発見されたエントリは実行対象の子である必要はなく、親、兄弟、またはWorldspace内の任意の位置にあってよい。
+
+Operationがpathを返したこと自体から、実行対象との間に親子関係や意味的関係を推論しない。親子関係はTree上の配置で表し、非内包の意味的関係はOperation名、result field名、またはApplication固有のrelation型で表現する。
+
+## Protocol failureとdomain failure
+
+Protocol failureは、WIPのrequest、対象、Interface、validation、validatorによる条件付き実行、Host executionに関する失敗である。
+
+- `invalid_request`
+- `not_found`
+- `interface_not_found`
+- `interface_mismatch`
+- `interface_validator_required`
+- `interface_validator_mismatch`
+- `operation_not_found`
+- `invalid_arguments`
+- `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が実行した結果として生じる失敗である。
+
+- `issue_has_open_dependencies`
+- `payment_declined`
+- `merge_conflict`
+
+Domain failureをProtocol failureへ混在させない。現在のProtocolでは、Domain failureをOperation return typeのUnion caseとして宣言する。専用のfailure declarationは定義しない。