diff --git a/1-concept.md b/1-concept.md index 9aadd1f..7d47769 100644 --- a/1-concept.md +++ b/1-concept.md @@ -38,7 +38,7 @@ WIPではObjectを受動的なJSON recordとして扱わない。 Operationには、名前や型に加えて、用途を判断するための短いdescriptionを持たせる。長文documentationや大量のドメインデータをInterfaceへ埋め込むことは想定しない。 -ObjectはOperation定義を直接埋め込まず、WIP IDLで記述されたInterfaceを参照する。一つのInterfaceに宣言された関数の集合がOperation一覧となり、複数のObjectが同じInterfaceを共有できる。 +ObjectはOperation定義を直接埋め込まず、実装コード上のInterface Declarationから生成されたInterface Descriptorを参照する。一つのInterfaceに宣言された関数の集合がOperation一覧となり、複数のObjectが同じInterfaceを共有できる。 ## 発見と既知世界 @@ -50,7 +50,7 @@ Clientは、これまでに発見したエントリを既知のWorldspaceとし OperationはHost背後の環境を変更し得るが、WIPはその状態遷移や変更差分をClientへ同期するprotocolではない。 -Operation Resultは型付きの値であり、WIP IDLの`entry`型として、未観測だったエントリのpathを返せる。例えばRAG検索からResult群を発見したり、Agentへの問い合わせからConversationを発見したりできる。 +Operation Resultは型付きの値であり、Interface Descriptorの`entry`型として、未観測だったエントリのpathを返せる。例えばRAG検索からResult群を発見したり、Agentへの問い合わせからConversationを発見したりできる。 Clientは必要に応じて返されたpathを取得し、変更後の状態を改めて観測する。 @@ -58,11 +58,11 @@ Clientは必要に応じて返されたpathを取得し、変更後の状態を WIPの目的は、Filesystem、GitHub、RAG、DBなどを一つの巨大APIへ統合することではない。 -任意のデジタル環境を共通のWorldspaceとして投影し、発見・観測・Operation実行という小さなInteraction Modelへ収束させる。Host内部のAPI、DB、RPC、永続化方式は規定せず、TransportもCore Protocolから分離する。 +任意のデジタル環境を共通のWorldspaceとして投影し、発見・観測・Operation実行という小さなInteraction Modelへ収束させる。Host内部のAPI、DB、RPC、永続化方式は規定せず、TransportもProtocolのlogical data modelから分離する。 ## 状態管理の非目標 -WIPは、Host上の任意状態をClientへ同期するdata store protocolではない。Object propertyのreplication、change feed、reactive subscription、分散transaction、domain event deliveryはCore Protocolの規定対象外とする。 +WIPは、Host上の任意状態をClientへ同期するdata store protocolではない。Object propertyのreplication、change feed、reactive subscription、分散transaction、domain event deliveryはCore Modelの規定対象外とする。 Clientが保持するKnown SpaceとDiscoverable Spaceは、過去の観測から構成されたcacheであり、Host上の現在状態を同期したreplicaではない。HostがClientのcache状態を追跡または更新することを要求しない。Operationのauthorizationと実行条件はHostが実行時に評価する。 diff --git a/2-core-model.md b/2-core-model.md index fb90f01..fd00bd4 100644 --- a/2-core-model.md +++ b/2-core-model.md @@ -1,32 +1,73 @@ # 2. コアモデル +WIP Core Modelは、ClientがHostの提供するWorldspaceを観測し、Objectを発見し、Interfaceに従って操作するための意味論を定義する。 + +具体的なrequest / response structは[3. Protocol](3-protocol.md)、HTTPとJSONへの対応付けは[WIP over HTTPS](draft/wip-over-https.md)で定義する。 + ## 基本構造 -Worldspaceは、LLMが探索できる**ObjectのTree**として公開される。 +Worldspaceは、Clientが探索できる**ObjectのTree**として公開される。 WIPではObjectとエントリを別の構造として定義しない。**ObjectをWorldspaceのTree上の位置として扱うとき、そのObjectをエントリと呼ぶ。** したがって、ObjectはTree上で親子関係を持ち得るし、途中のNodeもそのまま操作対象になってよい。例えば`articles`はCollection Objectとして、そのInterfaceに`query`等を宣言し、配下に個別Articleを配置できる。 +## ClientとHost + +WIP上の主要な実装主体は**Client**と**Host**である。 + +### Client + +Clientは、Hostが提供するWorldspaceをユーザーまたはAIへ提示する。 + +Hostから取得したObjectとInterface Descriptorをcacheし、`ref`によるObject同一性の追跡、観測時と操作時の対応関係の検証、GUI、AI用Tools、PTC / REPL向けAPI等への投影を行う。 + +### Host + +Hostは、Clientに対して一つのWorldspaceを提供する。 + +どのObject、エントリ、Interface、可視性を公開するかを決定し、そのClientから見えるWorldspaceを構成する。 + +Host内部でGitHub API、Database、Filesystem、RAG、他Agent、別protocol等をどう接続、集約、永続化するかはWIPの規定対象外とする。 + +ClientとHostの境界は通信境界であると同時に、ある主体へどのWorldspaceを公開するかを決めるtrust boundaryである。 + ## Object / エントリ -**Object**はWIP上で観測・操作される対象そのものである。 +**Object**は、Worldspace上で観測および操作できる対象のprotocol-level projectionである。 + +Objectは、探索に必要な公開情報とInterface参照を持つ。Host内部のdomain entityやApplication dataをそのままObjectとして公開する必要はない。Objectの本文、状態、domain metadata等は、Interfaceに宣言されたOperationを通して取得または変更する。 **エントリ**は、そのObjectをTree上の位置として見たときの呼び名である。 エントリがObjectへの参照を別途持つ、という二重構造は前提としない。 -Tree上の位置はpathで表される。Pathは恒久的なIdentityではなく、その時点でのnavigation coordinateである。 +Tree上の位置はpathで表される。Pathはrootから各Objectの`name`を順に`/`で連結して構成する。Pathは恒久的なIdentityではなく、その時点でのnavigation coordinateである。 -同じObjectが複数の位置に現れる場合、一つのObjectが複数のエントリとして観測され得る。 +同じ親の直下ではObjectの`name`は一意であり、非root Objectの`name`は空であってはならない。同じObjectが複数の位置に現れる場合、一つのObjectが異なる`name`とpathを持つ複数のエントリとして観測され得る。Objectの公開情報、name、path、Tree上の配置については[2.1. Object tree / Schema](2.1-object-tree-schema.md)で扱う。 ## Interface ObjectはOperation定義を直接持たず、一つのInterfaceを参照する。 -Interfaceの実体は一つのWIP IDL documentであり、document内に宣言された関数の集合が、そのInterfaceのOperation集合となる。複数のObjectが同じInterfaceを共有できる。 +Interfaceは、Objectで利用できるOperation、parameter、return type、documentationを定義する。Interface実装者はRustのtraitやTypeScriptのdefinition API等を使って実装コード上でInterfaceを宣言し、Libraryはその宣言からmachine-readableなInterface Descriptorを生成する。 -ObjectとInterfaceを分離することで、Collection内の多数の同種Objectに同じOperation定義を重複して持たせず、ClientがInterface定義を参照単位でcacheできる。 +複数のObjectが同じInterfaceを共有できる。ObjectとInterfaceを分離することで、Collection内の多数の同種Objectに同じOperation定義を重複して持たせず、ClientがInterface Descriptorを参照単位でcacheできる。 + +InterfaceとOperationの意味論は[2.2. Interface / Operation](2.2-operation.md)、Descriptorのlogical structは[3. Protocol](3-protocol.md)、人間とAIへの表示は[4.1. AI用Tools](4.1-ai-tools-example.md)で扱う。 + +## Core interaction + +Clientは、次の4操作によってWorldspaceを観測および操作する。 + +- `fetch(path)` — 一つのpathで現在公開されているObjectを取得する。 +- `fetch_tree(path, depth, limit)` — 指定pathを起点にindexableな子ObjectをTreeとして取得する。 +- `fetch_interface(interface)` — Interface参照からInterface Descriptorを取得する。 +- `call_operation(target, operation, arguments)` — `path`とoptionalな`validator`を持つtargetに対してOperationを実行する。 + +この節は各操作の意味だけを定める。Parameterとreturn valueの具体的なstructはProtocolで定義する。 + +複数の`fetch`や`fetch_interface`は、それぞれ独立したCore interactionである。Transport Bindingは、個別に実行した場合と同じ意味を保ったまま複数のinteractionを一つのrequestへbatchしてよい。Batchingによって新しいCore interactionや暗黙の先読みを導入しない。 ## `ref` @@ -39,6 +80,7 @@ Objectは必要に応じて`ref`を公開できる。 - `ref`のscopeや有効期間はWorldspaceまたは実装が定めてよい。 - `ref`はグローバルかつ永続的なUIDである必要はない。 - 同じObjectが複数のエントリとして観測される場合、同じ`ref`によって同一性を示せる。 +- `ref`はnavigation coordinateではない。Objectの取得にはentry pathを使用する。 ## 観測整合性 @@ -48,24 +90,43 @@ Objectは必要に応じて`ref`を公開できる。 例えば、AIが`/issues/current`を観測した時点ではIssue Aだったが、`invoke`時にはIssue Bへ差し替わっていた場合、AIはIssue Aへ作用するつもりでIssue Bを操作してしまう可能性がある。 -この観測整合性は利用者に追跡させるのではなく、クライアントの責務とする。 +この観測整合性は利用者に追跡させるのではなく、Clientの責務とする。 処理の流れは次の通り。 1. Clientがpath上のObjectを観測する。 -2. Clientはその時点のpathとObjectの対応を内部的に記録する。 -3. モデルは観測したObjectについて推論する。 -4. モデルが同じpathを対象に操作を要求した場合、Client / Runtimeは実行前に対応関係が変化していないことを検証する。 +2. Objectがvalidatorを持つ場合、ClientはObjectとrequest pathを対応付けて保持する。 +3. ユーザーまたはAIが観測したObjectについて判断する。 +4. 同じObjectへ条件付きで操作する場合、Clientは`path`とObjectの`validator`をtargetとしてHostへ渡す。 +5. Hostは現在のvalidatorとの一致確認とOperation実行をatomicに行う。 -実装はETagやgeneration、opaque token等の内部メタデータを用いてよいが、それらを利用者へ露出する必要はない。 +ValidatorはClientとHostの間で扱い、AIやユーザーに直接管理させない。Transport Bindingは、同じlogical semanticsを保つ形でHTTP ETag等へ対応付けてよい。 -対応関係が変化していた場合、Clientは新しいObjectに対して操作を自動的に再試行してはならない。操作を中止し、`target_changed`のような意味的エラーを返して再観測を要求する。 +Validatorが一致しない場合、Clientは現在のObjectに対してOperationを自動的に再試行してはならない。Hostは`validator_mismatch`を返し、Clientは再観測を要求する。 ## 同一性と観測整合性の分離 -WIPでは次の2つを分けて扱う。 +WIPでは次の二つを分けて扱う。 -- **Object identity (`ref`)**: 複数の観測にまたがって同一Objectであることを明示するための任意の外部Handle。 -- **Observation consistency**: `ref`の有無に関わらず、観測したpath上のObjectと操作対象のObjectが一致していることをClient / Runtimeが保証する仕組み。 +- **Object identity (`ref`)** — 複数の観測にまたがって同一Objectであることを明示するための任意の外部Handle。 +- **Observation consistency** — `ref`の有無にかかわらず、観測したpath上のObjectと操作対象のObjectが一致していることを保証する仕組み。 -したがって、`ref`を持たないObjectであっても安全な操作対象になり得る。`ref`は同一性を公開する仕組みであり、Observation consistencyは操作の安全性を担保する仕組みである。 \ No newline at end of file +したがって、`ref`を持たないObjectであっても安全な操作対象になり得る。`ref`は同一性を公開する仕組みであり、validatorはHostが定める現在状態との一致を条件付きOperationで検証する仕組みである。 + +## Application data + +WIPは、Host上の任意状態をClientへ同期するdata store protocolではない。Object propertyのreplication、change feed、reactive subscription、分散transaction、domain event deliveryはCore Modelの規定対象外とする。 + +Operationが交換するApplication dataについて、WIPはInterfaceに宣言された型、wire encoding、boundary validationを規定する。値のdomain上の意味、保存方法、business validation、Client内部での利用方法はApplicationの責務である。 + +Clientが保持するKnown SpaceとDiscoverable Spaceは、過去の観測から構成されたcacheであり、Host上の現在状態を同期したreplicaではない。HostがClientのcache状態を追跡または更新することを要求しない。 + +この責務境界はObject、Interface、Operationの各節で一貫して適用する。 + +## Transportとの分離 + +Core ModelとProtocol structは、HTTP、TCP、WebSocket等の特定transportを要求しない。 + +通信方式、concrete encoding、endpoint、batch packagingへの対応付けはTransport Bindingとして定義する。標準bindingは[WIP over HTTPS](draft/wip-over-https.md)で扱う。 + +この分離により、Worldspaceの意味論、Client / Host間のlogical contract、通信方式を独立して進化させる。 diff --git a/2.1-object-tree-schema.md b/2.1-object-tree-schema.md index 8b4a625..f71a2c1 100644 --- a/2.1-object-tree-schema.md +++ b/2.1-object-tree-schema.md @@ -1,75 +1,173 @@ # 2.1. Object tree / Schema -## 2.1.1 目的 +## Objectの公開情報 -このページでは、WIP Core ModelにおけるObject treeと、それらをClientへ公開する際の最小スキーマを整理する。 +Objectは、Worldspace上の対象を発見し、理解し、操作するためのprotocol-level projectionである。 -WIPでは、**Objectとエントリを別のデータ構造として定義しない**。ObjectをWorldspaceのTree上に配置されたものとして扱うとき、そのObjectをエントリと呼ぶ。 +Objectは少なくとも次の公開情報を持つ。 -## 2.1.2 Objectとエントリ +- **name** — 親Objectの下でのpath segment。 +- **description** — Objectが何を表すかを説明する情報。 +- **interface** — Objectで利用できるOperationを定義するInterfaceへの参照。 +- **ref** — 同じObjectを複数の観測にまたがって識別するための任意の外部Handle。 +- **validator** — HostがObjectの現在状態へ付与する任意のopaque value。 -**Object**はWIP上で観測・操作される対象そのものである。 +具体的な型、必須性、resource limitは[3. Protocol](3-protocol.md)で定義する。 -**エントリ**は、そのObjectをWorldspaceのTree上の位置として見たときの呼び名である。 +Objectの本文、状態、domain metadata等のApplication dataを、共通のproperty bagとしてObjectへ格納しない。それらはInterfaceに宣言されたOperationを通して取得または変更する。 -したがって、エントリがObjectへの参照を別途保持する、あるいはエントリ schemaとObject schemaを二重に定義することは前提としない。 +`description`は探索時に対象を理解するための短い公開情報であり、長い本文やdomain entityの完全な表現を格納する場所ではない。 -ObjectがTree上に配置されることでエントリとなり、pathはその配置位置を表すnavigation coordinateとなる。 +## Interface参照 -同じObjectが複数の位置に現れる場合、一つのObjectが複数のエントリとして観測され得る。 +Objectは一つのInterfaceを参照する。 -## 2.1.3 公開情報 +Interfaceは次を定義する。 -Object / エントリが公開する情報は、Worldspaceを探索し、対象に対して何ができるかを理解するための最小限のmetadataである。 +- Operation名 +- Operationの説明 +- Parameter名と型 +- Return type +- Named typeとdocumentation -現時点では、少なくとも次の情報を想定する。 +Interface実装者は実装コード上でInterfaceを宣言し、Libraryはその宣言からInterface Descriptorを生成する。ClientはObjectのInterface参照を使ってDescriptorを取得し、検証、cache、表示、Operation callのvalidationに利用する。 -- `name` — Objectの短い名前。Tree上ではエントリ名としても用いられる。 -- `description` — Objectが何を表すかを説明する短い自然言語。長文documentationではなく、探索・判断に必要な最小限のsemantic metadataとする。 -- `interface` — Objectが実装するInterfaceへの参照。 -- `children` — Tree上でindexableとして公開される子Object / エントリ。 -- `ref` — 必要に応じて公開される、同一Objectを再参照するための外部Handle。 +同じInterfaceを持つObjectは同じDescriptor参照を共有できる。 -Interfaceの実体は[WIP IDL](draft/wip-idl.md) documentである。IDL内に宣言された関数の集合が、そのInterfaceのOperation集合となる。ObjectはOperation定義を個別に埋め込まず、一つのInterface参照だけを持つ。 +## Object / エントリ / path -複数のObjectが同じInterfaceを参照できる。これにより、Collectionから多数の同種エントリを取得する場合でも、Operation名、documentation、parameter、return typeを各エントリへ重複して送る必要がない。 +WIPでは、Objectとエントリを別のdomain entityとして定義しない。ObjectをTree上の位置として扱うとき、そのObjectをエントリと呼ぶ。 -Interface参照は、HostがそのClientへ投影したInterfaceを識別する。同じObjectでも主体のroleや権限により異なるInterfaceを参照し得るが、頻繁に変化する実行可否を表すためには使用しない。 +### `name` -ClientはInterface参照をcacheと比較し、未知のInterfaceだけを`fetch_interface`で取得する。HostはClientのcache状態を推測せず、ObjectのresponseへInterface定義を先行同梱しない。複数のInterface取得はTransport Bindingでbatchできる。 +Objectの`name`は表示用labelではなく、親Objectの下でそのObjectを識別するpath segmentである。 -WIPではドメインデータそのものをpropertiesとして直接公開することを前提としない。本文、metadata、状態などを読む行為もOperationとして表現する。 +- Root Objectの`name`は空文字列とする。 +- 非root Objectの`name`は空であってはならない。 +- `name`に`/`を含めてはならない。 +- `name`全体が`.`または`..`であってはならない。 +- `name`はUnicode stringとする。 +- Unicode normalizationは行わない。 +- Nameの比較はUnicode code point sequenceの完全一致で行う。 +- 同じ親の直接のchildrenは、互いに異なる`name`を持たなければならない。 -## 2.1.4 Tree +`name`を人間向けの自由なtitleとして扱わない。探索時の短い説明には`description`を使い、domain上のtitle等はOperationからApplication dataとして取得する。 -Worldspaceは、Objectが親子関係によって配置されたTreeとして観測される。 +### Pathの構成 -Tree上のObjectをエントリとして呼び、その位置をpathで表す。 +Rootのpathは`/`とする。非root Objectのpathは、rootからそのObjectまでの各`name`を`/`で連結して構成する。 -子エントリは所有・内包関係を表す。非内包の意味的関係は、それを表すOperationから関連エントリのpathを返す。 +```text +root.name = "" +root.path = "/" -例えばRepository配下の`issues`は子エントリとして自然だが、Issueから関連Pull Requestを得る場合は`get_related_pull_requests`のようなOperationで表現する。 +projects.name = "projects" +projects.path = "/projects" -Treeはmaterializedな全世界ではなく、HostがそのClientに対して公開する**lazy / virtual tree**である。Hostは全Objectを事前保持する必要はなく、`fetch`や`fetch_tree`に応じて動的に解決してよい。 +example.name = "example" +example.path = "/projects/example" +``` -## 2.1.5 Indexable children +Pathには空segment、`.`、`..`を含めない。Root以外のpathは末尾に`/`を持たない。Nameに`/`を許可しないため、Core Modelではsegment escapeを定義しない。Transport BindingがPathをURL componentへ格納する場合のURL encodingは、WIP Pathの構成とは別に扱う。 -子エントリには、機械的探索で辿ってよいものと、Operationによってのみ発見されるものがある。 +非root pathについては、最後のsegmentと取得したObjectの`name`が一致しなければならない。 -`fetch_tree`が辿るのは**indexableとして公開された子エントリのみ**とする。 +```text +fetch("/projects/example") + -> Object.name == "example" +``` -indexableな子エントリは、Worldspaceの構造理解に必要で、通常は件数が小さいものを想定する。 +同じObjectが複数のpathへ配置される場合、同じ`ref`を持ちながら配置ごとに異なる`name`を持ち得る。Objectをrenameまたは別の親へ移動すると、そのObjectとdescendantのpathは変化する。Pathは恒久的なObject identityとして使用しない。 -一方、大量のIssue、検索結果、一時的なObject群などはindexable childとして露出しない。必要なエントリはCollection Objectの`query` / `list`等のOperation結果として返す。 +`ref`、path、Interface参照は異なる役割を持つ。 -Operation結果として返されることは、実行対象との親子関係を意味しない。Collectionの要素を返す場合だけでなく、親、兄弟、関連Objectなど、Worldspace内の別の位置にあるエントリを発見するためにもOperationを利用できる。 +| 値 | 役割 | +| --- | --- | +| path / `entry` | RootからObjectの`name`を辿って構成するnavigation coordinate | +| `ref` | 複数の観測にまたがる任意のObject identity | +| Interface参照 | Objectで利用可能なcapability definition | -## 2.1.6 Core Protocolとの対応 +通常のstringを内容だけからpathまたは`ref`と推測しない。Operation value内でWorldspace上の位置を返す場合は、Descriptorで`entry`型として宣言する。 -`fetch(entry)`は、指定されたTree上の位置にあるObjectの公開情報を取得する。 +## Tree -`fetch_tree(entry, depth, limit)`は、指定エントリからindexable child edgeだけを幅優先探索し、Treeとしてまとめて返す。 +Objectは子Objectを持つことができる。 -探索が`depth`または`limit`により打ち切られた場合は、レスポンスで`truncated`を必ず明示する。 +Parent / child関係はWorldspaceにおける**所有または内包**を表す。 -Operationを実行した結果には、WIP IDLの`entry`型として新しいエントリのpathが含まれる場合がある。Clientはそれらを一時的な発見結果として扱い、後続の参照に必要なものだけを取得してKnown Spaceへ統合できる。 +- Filesystem: Directory / File +- GitHub: Repository / Issue +- Database: Database / Table +- RAG: Index / Document + +関連、依存、参照等の非所有関係を、Treeの親子関係として濫用しない。そのような関係はOperationのresultとして`entry`を返し、Clientが必要に応じて移動できるようにする。 + +### `children`の意味 + +`children`はApplication dataではなく、Objectを指定pathで観測した時点におけるWorldspace上のprojectionである。 + +一つのObjectが複数pathへ配置される場合、そのObjectから見えるchildrenは配置ごとに異なり得る。したがって、childrenを`ref`が示すObject identityの一部とはみなさない。 + +Protocolでは`Object`自体にchildrenとpathを含めず、`fetch_tree`の`ObjectTreeNode`としてObjectとchildrenをまとめる。ValidatorはObjectに含まれる。各nodeのpathは、request pathを起点にObjectの`name`を辿って導出する。このwrapperはObjectとは別のdomain entityを導入するものではなく、Tree traversalのresponse shapeである。 + +## `fetch` + +`fetch(path)`は、指定されたpathで現在公開されている一つのObjectを観測する。 + +```text +fetch(path) -> Object +``` + +返されたObjectは、Host内部のdomain entityの完全なcopyではない。そのClientへ現在公開されているname、description、Interface参照、任意の`ref`とvalidator等のprotocol projectionである。Clientは非rootのrequest pathについて、最後のsegmentとObjectの`name`が一致することを検証する。 + +ClientはObjectがvalidatorを持つ場合、そのObjectとrequest pathを対応付けて保持し、条件付きOperationのtargetを構築できる。 + +## `fetch_tree` + +`fetch_tree(path, depth, limit)`は、指定pathを起点にindexableな子ObjectをTreeとして取得する。 + +```text +fetch_tree(path, depth, limit) -> ObjectTree +``` + +探索順序は**Breadth-First Search (BFS)**とする。 + +- `depth`は起点Objectを`0`とする最大深さ。 +- `limit`はresponse全体に含めるObject数の上限。 +- 起点Objectはlimitへ含める。 +- `depth`または`limit`によって存在するindexable childを省略した場合は、responseで`truncated = true`を返す。 +- 要求範囲内のindexable childをすべて含む場合は、`truncated = false`を返す。 + +Tree responseは各nodeにObjectを含み、Clientはrequest pathとchildrenの`name`から各Objectのpathを導出する。各ObjectはHostが発行したvalidatorを持ち得るため、Clientは導出したpathとvalidatorから条件付きOperationのtargetを構築できる。 + +Depth、limitの有効範囲、Tree node、truncationの具体的なstructはProtocolで定義する。 + +## Indexable children + +Tree上のchildrenとして自然に列挙できるのは、**indexableなObject**だけである。 + +- 件数がboundedまたは現実的な範囲で列挙できる。 +- 比較的安価に取得できる。 +- 所有または内包関係として自然に理解できる。 + +全件列挙が高コストまたは不自然な集合は、Treeへ直接展開しない。Collection ObjectのOperationを使って検索、filter、paginationを行い、resultとして関連する`entry`を返す。 + +例えば、大規模なIssue collectionは次のように公開できる。 + +```text +/issues + interface: IssueCollection + operation: query(filter, cursor, limit) -> IssueQueryResult +``` + +```text +IssueQueryResult.items: [entry] +``` + +## Batch + +複数のObjectやInterface Descriptorをまとめて取得する機能は、Core Model上の新しいinteractionではない。 + +Transport Bindingは、個別に実行した場合と同じ意味を保つ形で、複数の`fetch`、`fetch_tree`、`fetch_interface`を一つのrequestへまとめてよい。 + +WIPは自動的な全量取得、暗黙の再帰展開、Clientが要求していない先読みを要求しない。 diff --git a/2.2-operation.md b/2.2-operation.md index 07d7173..b24db42 100644 --- a/2.2-operation.md +++ b/2.2-operation.md @@ -1,24 +1,35 @@ -# 2.2. Operation +# 2.2. Interface / Operation -## 2.2.1 目的 - -Operationは、Objectに対して実行できる操作を表す。 - -WIPでは、本文を読む、metadataを取得する、検索する、状態を変更するなど、Objectに対する行為をOperationとして公開する。 - -## 2.2.2 Interface +## Interface ObjectはOperation定義を直接持たず、一つのInterfaceを参照する。 -Interfaceの定義は[WIP IDL](draft/wip-idl.md) documentそのものである。IDL documentに宣言された関数の集合が、そのInterfaceのOperation集合となる。Operation名、parameter、return type、短いdocumentationは一つの関数宣言としてまとめて定義し、別のOperation descriptorへ重複して記述しない。 +Interfaceは、Objectで利用できるOperationと、各Operationのparameter、return type、documentationを定義する。複数のObjectが同じInterfaceを共有できるため、Operation定義をObjectごとに重複して送る必要はない。 -複数のObjectが同じInterfaceを参照できる。これにより、Collectionから多数の同種Objectを取得する場合でも、Operation定義を各Objectへ重複して埋め込む必要がない。 +Interface実装者は、RustのtraitやTypeScriptのdefinition API等を使って実装コード上でInterfaceを宣言する。Libraryはその宣言から、typed handler、runtime validation、およびmachine-readableなInterface Descriptorを生成する。 -HostはInterfaceについて、参照、IDLのlanguage identifier、source、およびcacheや同一性確認に利用できるdigestをClientへ提供する。ObjectはInterface参照だけを持ち、Clientは未知のInterface定義だけを取得してcacheできる。 +Interface Descriptorは人間が手書きするschema fileではない。Hostが`fetch_interface`で公開し、Clientが参照単位でcacheするprotocol dataである。 -## 2.2.3 Operation declaration +## Interface Descriptor -Operationは、WIP IDL内で関数形式により宣言する。 +一つの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へのSignature Viewは[4.1. AI用Tools](4.1-ai-tools-example.md)で扱う。 + +Clientは取得したDescriptorを構造検証および意味検証してからcacheする。Named typeの参照解決、Operation callのvalidation、表示生成には検証済みのInterfaceだけを使用する。 + +## Operation declaration + +Operationは、名前付きparameter、return type、documentationを持つ。 + +人間とAIへ提示する場合は、Interface DescriptorからIDL風のSignature Viewを生成できる。 ```wip /// Returns items related to this Object. @@ -31,17 +42,31 @@ operation get_related_items( }; ``` -Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter list `()`で宣言する。 +Signature ViewはInterfaceの交換形式や入力言語ではなく、検証済みDescriptorから生成する表示である。 + +Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter listとして表し、`call_operation`には空のrecordを渡す。 ```wip operation refresh() -> unit; ``` -Return typeには任意のWIP IDL型を使用できる。ただし、将来fieldを追加する可能性があるOperationではrecordを基本とする。 +Return typeにはDescriptorで定義される任意のvalue typeを使用できる。Evolution compatibilityが必要なOperationでは、fieldを追加できるrecordをreturn typeの基本とする。 -Operationの用途は`///` documentation commentで簡潔に説明する。長文documentationや大量のdomain dataをInterfaceへ埋め込むことは想定しない。 +Operationの用途は短いdocumentationで説明する。長文documentationや大量のApplication dataをInterface Descriptorへ埋め込まない。 -## 2.2.4 可視性 +## `fetch_interface` + +`fetch_interface(interface)`は、Interface参照に対応するInterface Descriptorを取得する。 + +```text +fetch_interface(interface) -> Interface Descriptor +``` + +ObjectはInterface参照だけを持ち、Descriptorを先行同梱しない。ClientはInterface cacheと参照を比較し、未知のDescriptorだけを取得する。 + +HostはClientのcache状態を推測して、要求されていないDescriptorをObject responseへ追加しない。複数のDescriptor取得はTransport Bindingでbatchできる。 + +## Operationの可視性 Hostは、主体の権限やrole / capabilityに基づいて、その主体へ公開するInterfaceを決定してよい。 @@ -51,16 +76,87 @@ Operationの可視性は、頻繁に変化する実行可否やdomain stateを WIPはOperationの`available` / `disabled`のような揮発的状態をInterfaceへ同期することを前提としない。現在状態を判断する必要がある場合は、必要に応じてdomain固有のOperationで観測する。最終的なauthorizationと実行条件の判定は`call_operation`時にHostが行う。 -## 2.2.5 Operation Result +## `call_operation` -`call_operation`は、対象ObjectのInterfaceに宣言されたOperation名と、parameter listに従う名前付きargumentsを受け取る。結果はOperationのreturn typeに従う型付きvalueとして返す。 +`call_operation`は、指定pathにあるObjectに対して、Interfaceに宣言されたOperationを実行する。 -Operation Resultには、WIP IDLの`entry`型として新しいエントリのpathが含まれ得る。 +```text +call_operation(target, operation, arguments) -> result, validator? +``` -`entry`は同じWorldspace内のcanonical absolute pathであり、wire上では文字列として表現する。Clientはreturn typeに従って`entry`型の位置を認識し、返されたpathを一時的な発見結果として扱う。通常の`string`や任意JSON値に含まれるpathらしい文字列を、エントリとして推測してはならない。 +- `target.path`は対象Objectを観測したpath。 +- `target.validator`はObjectから得たoptionalなopaque validator。 +- `operation`は対象ObjectのInterfaceに宣言されたOperation名。 +- `arguments`はOperationのparameterに従う名前付きrecord。 +- `result`はOperationのreturn typeに従うvalue。 +- Responseの`validator`はOperation実行後の現在状態に対してHostが発行したoptionalな値。 -Clientは発見したpathを必要に応じて`fetch`または`fetch_tree`する。複数pathの取得は、それぞれ独立したCore操作をTransport Bindingでbatchする。Operation Resultへエントリ公開情報を先行同梱しない。 +HostはOperationを実行する前に、次を検証する。 -Operationの実行対象と、結果として発見されたエントリのTree上の位置は独立している。発見されたエントリは実行対象の子である必要はなく、親、兄弟、またはWorldspace内の任意の位置にあるエントリであってよい。 +1. `target.path`が存在する。 +2. `target.validator`が指定されている場合、現在のvalidatorと一致する。 +3. Objectが参照するInterfaceにOperationが宣言されている。 +4. Argumentsがparameter declarationに従っている。 +5. ClientがOperationを実行できる。 -Operationがエントリpathを返したこと自体から、実行対象との間に親子関係や意味的関係を推論してはならない。親子関係はTree上の配置で表し、非内包の意味的関係はOperation名、resultのfield名、またはdomain固有のrelation型で表現する。 +Validatorの比較とOperation実行はatomicに行う。一致しない場合、HostはOperationを実行せず`validator_mismatch`を返す。Hostがvalidatorを要求するOperationに指定がない場合は`validator_required`を返す。 + +Argumentsに未知のfieldがある場合、必須parameterがない場合、またはvalueが宣言型に一致しない場合、HostはOperationを実行せず`invalid_arguments`を返す。 + +ClientはHostから受け取ったresultをreturn typeに従って検証する。Hostが宣言と異なるresultを返した場合は`invalid_result`として扱い、そのvalueをApplicationへ渡さない。 + +## 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を必要に応じて`fetch`または`fetch_tree`する。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による条件付き実行に関する失敗である。 + +- `invalid_request` +- `not_found` +- `interface_not_found` +- `operation_not_found` +- `invalid_arguments` +- `invalid_result` +- `validator_required` +- `validator_mismatch` +- `permission_denied` +- `resource_limit_exceeded` + +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は定義しない。 diff --git a/3-core-protocol.md b/3-core-protocol.md deleted file mode 100644 index dba6c85..0000000 --- a/3-core-protocol.md +++ /dev/null @@ -1,72 +0,0 @@ -# 3. Core Protocol - -WIP Core Protocolは、ClientとHostの間でWorldspaceを観測・操作するための**transport-independentな意味論**を定義する。 - -## 3.1 役割 - -WIP上の主要な登場主体は**Client**と**Host**である。 - -### Client - -ClientはHostが提供するWorldspaceをユーザーまたはAIへ提示する。 - -Hostから取得したエントリとInterface定義を既知の空間として保持・キャッシュし、`ref`によるObject同一性の追跡や、観測時と操作時の対応関係の検証を行う。 - -GUI、AI用Tools、PTC / REPL向けAPIなどへの投影はClient実装の責務とする。 - -### Host - -HostはClientに対して一つのWorldspaceを提供する。 - -どのObject、エントリ、Interface、可視性を公開するかを決定し、そのClientから見えるWorldspaceを構成する。 - -Host内部でGitHub API、Database、Filesystem、RAG、他Agent、別プロトコルなどをどう接続・集約するかはWIPの規定対象外とする。 - -## 3.2 規定範囲 - -Core Protocolが規定するのは、ClientがHostからWorldspaceを観測し、操作するための契約である。 - -特定のデータソース構成、内部RPC、永続化方式、Adapter構成、同期方式は規定しない。 - -ClientとHostの境界は通信境界であると同時に、ある主体へどのWorldspaceを公開するかを決める信頼境界として扱える。 - -## 3.3 基本操作 - -現時点では次の4操作をCore Protocolの基本とする。 - -- `fetch(entry)` — 1つのエントリにあるObjectの公開情報とInterface参照を取得する。 -- `fetch_tree(entry, depth, limit)` — 指定エントリを起点に、indexableな子エントリを幅優先探索してエントリツリーとして取得する。 -- `fetch_interface(interface)` — Interface参照からWIP IDL documentを取得する。 -- `call_operation(target, operation, arguments)` — Objectが参照するInterfaceに宣言されたOperationを実行する。 - -Interfaceの定義は[WIP IDL](draft/wip-idl.md) documentそのものであり、そこに宣言された関数の集合がOperation一覧となる。`call_operation`の`arguments`は選択したOperationのparameter listに従う名前付きの型付き値であり、引数がない場合は空のrecordとする。Core Protocolはこの値をJSONに限定せず、Transport Bindingが具体的なencodingを定める。 - -## 3.4 `fetch_tree` - -`fetch_tree`は、Clientが機械的探索のために多数の`fetch`を連打することを避けるための操作である。 - -探索対象はindexableな子エントリのみとし、幅優先探索（BFS）で辿る。Clientは探索深度`depth`と返却エントリ総数の上限`limit`を指定できる。 - -探索が`depth`または`limit`によって途中で終了した場合、レスポンスは`truncated`であることを必ず明示する。Clientは取得結果を完全なツリーと誤認してはならない。 - -件数が非常に多いCollectionの個々の要素は、通常indexableな子エントリとして自然露出させない。必要な要素はCollection Objectの`query`や`list`等のOperationによって発見する。 - -## 3.5 Operation実行と発見 - -`call_operation`の結果は、選択したOperationのWIP IDL return typeに従う型付き値である。Return type上で`entry`として宣言された位置には、同じWorldspace内のエントリを指すcanonical absolute pathを返せる。 - -Clientはreturn typeに従って`entry`型の位置を認識する。通常の`string`や任意JSONに含まれるpathらしい文字列を、エントリとして推測してはならない。 - -返されたエントリpathのTree上の位置はOperationの実行対象から独立しており、実行対象の子に限定されない。Operationの実行対象と返されたエントリの間に、暗黙の親子関係や意味的関係を作ってはならない。 - -ClientはOperation結果として発見したpathを一時的に扱い、必要なものを`fetch`または`fetch_tree`して既知の空間へ統合できる。 - -複数の`fetch`または`fetch_interface`は、Core Protocol上ではそれぞれ独立した操作である。Transport Bindingは、個別に実行した場合と同じ意味を保ったまま、Clientが選択した複数の操作を一つのrequestへbatchしてよい。HostがClientの既知状態を推測して追加情報を先行同梱することはCore Protocolの一部としない。 - -## 3.6 Transportとの分離 - -Core ProtocolはHTTP、TCP、WebSocketなど特定のtransportを要求しない。 - -通信方式への具体的な対応付けはTransport Bindingとして別に定義する。標準bindingは`WIP over HTTPS`で扱う。 - -この分離により、Worldspaceの意味論と通信方式を独立して進化させる。 \ No newline at end of file diff --git a/3-protocol.md b/3-protocol.md new file mode 100644 index 0000000..1274906 --- /dev/null +++ b/3-protocol.md @@ -0,0 +1,545 @@ +# 3. Protocol + +WIP Protocolは、ClientとHostの間で交換するlogical data modelと、Core interactionのrequest / responseを定義する。 + +この章のstructはRust風の記法を使用するが、Rust固有のmemory layoutやserialization libraryを要求しない。TypeScriptを含む他言語でも同じ型、必須性、validation semanticsを実装できなければならない。 + +HTTP endpoint、JSON fieldへのencoding、status code、batch packagingはTransport Bindingの責務とし、[WIP over HTTPS](draft/wip-over-https.md)で扱う。 + +## Protocol dataの分類 + +WIPがfirst-classなprotocol dataとして定義し、Clientが取得およびcacheするものは次の二つである。 + +- `Object` +- `InterfaceDescriptor` + +Operationのargumentsとresultには、Interface Descriptorで宣言された`Value`を使用する。Application dataは独立したWIP resourceではなく、Operation callの入力または出力として交換される。 + +```text +Protocol data + |-- Object + `-- InterfaceDescriptor + +Operation value + |-- arguments + `-- result +``` + +Path、Object参照、Interface参照、validator、error等の意味は、それらが現れるfieldまたはenvelopeによって決まる。Protocol上のnamed scalarとしては定義しない。 + +## 記法 + +この章では次の記法を使用する。 + +```rust +struct T { ... } // 名前付きfieldを持つrecord +enum T { ... } // 閉じたcaseの集合 +Option // 省略可能なfield +Vec // 順序付きlist +BTreeMap // string keyを持つlogical map +``` + +`Option`はfieldの省略を表し、`null`を表さない。Transport Bindingは、省略されたfieldをwire valueへ出力してはならない。 + +`BTreeMap`はstring-keyed mapをRust風に示すための記法であり、keyのiteration orderをProtocol semanticsには含めない。 + +## Primitiveとfield semantics + +Protocol structは、次のprimitiveおよびcompositeだけで表す。 + +```text +unit +boolean +integer +number +string +bytes +list +record +``` + +Path、Interface参照、Object identity、Operation名等を独立したProtocol scalarにはしない。それらは`String`または`Vec`として交換し、fieldの位置とvalidation ruleによって意味を与える。 + +| Field | Primitive | 解釈 | +| --- | --- | --- | +| `FetchRequest.path` | `String` | rootからObjectの`name`を辿って構成したabsolute Worldspace path | +| `CallOperationRequest.target.path` | `String` | Operation対象のabsolute Worldspace path | +| `Object.interface` | `String` | Interface Descriptorへの参照 | +| `Object.ref` | `String` | 任意のopaque Object identity | +| `Object.validator` | `Vec` | HostがObjectへ付与するopaque validator | +| `CallOperationResponse.validator` | `Vec` | Operation実行後のopaque validator | +| `CallOperationRequest.operation` | `String` | Interface内のOperation名 | + +同じprimitiveを使用するfieldでも意味は交換可能ではない。例えば、`Object.ref`を`FetchRequest.path`へ渡してnavigationに使用してはならない。ただし、この区別をProtocol上のnewtypeとして表す必要はない。 + +Rust SDKは利便性や安全性のために`Path`等のnewtypeを公開してよく、TypeScript SDKはbrand等を利用してよい。それらは言語bindingのAPIであり、Protocol structの一部ではない。 + +### Pathとして解釈されるstring + +Pathとして宣言されたfieldのvalueは、同じWorldspace内のObjectを取得するためのcanonical absolute pathでなければならない。 + +- Root pathは`/`とする。 +- 非root pathは、rootから対象Objectまでの各`name`を`/`で連結して構成する。 +- 空segmentを含めない。 +- `.`または`..`であるsegmentを含めない。 +- Root以外は末尾に`/`を持たない。 +- Pathに含まれる各segmentはUnicode stringとして扱い、Unicode normalizationを行わない。 +- Segmentの比較はUnicode code point sequenceの完全一致で行う。 +- Navigationに使用できるが、恒久的なObject identityとして使用しない。 + +Nameに`/`を許可しないため、Protocolはpath segment escapeを定義しない。Transport BindingによるURL encodingはWIP Pathの構成とは別に扱う。 + +### Opaqueな参照とvalidator + +`Object.interface`と`FetchInterfaceRequest.interface`はInterface Descriptorへのopaqueな参照として解釈する。同じInterface参照が有効である間、Hostは異なるDescriptorを返してはならない。Descriptorを変更した場合は新しいInterface参照をObjectで公開する。 + +`Object.ref`は複数の観測にまたがって同一Objectであることを示す任意のopaque stringである。Navigationには使用せず、すべてのObjectに存在するとは限らない。Scopeと有効期間はWorldspaceまたはHost実装が定める。 + +`Object.validator`は、HostがそのObjectの現在状態へ付与するoptionalなopaque bytesである。Clientは内容を解釈せず、観測に基づくOperationを条件付きで実行するときに、pathとともに`target.validator`へコピーする。 + +Hostはvalidatorの生成方法を自由に選べる。Generation、content hash、database revision等を使用してよい。Hostは、どの状態変化によってvalidatorを無効にするかについて、そのObjectとInterfaceに対して一貫した方針を適用する。 + +ValidatorはAIやユーザーへ公開するApplication dataではなく、Client runtimeがObjectとともに保持するprotocol metadataである。 + +## Documentation + +Interface、Operation、type、field、parameter、caseに付与するdocumentationを次のlogical structで表す。 + +```rust +struct Documentation { + summary: String, + details: Option, +} +``` + +`summary`は一覧やSignature Viewへ短く表示する説明、`details`は明示的に展開したときに使用する説明である。 + +DocumentationはHostが提供するplain text dataであり、Clientのsystem instructionとして信頼しない。Transport BindingおよびClientはresource limitを適用できる。Markup、localization、構造化exampleは現在のProtocolに含めない。 + +## Object + +`Object`は、一つのpathで現在公開されているprotocol-level projectionを表す。 + +```rust +struct Object { + name: String, + description: Option, + interface: String, + r#ref: Option, + validator: Option>, +} +``` + +### `name` + +親Objectの下でObjectを識別するpath segment。Root Objectの`name`は空文字列とし、非root Objectの`name`は空であってはならない。Nameに`/`を含めてはならず、Name全体が`.`または`..`であってはならない。 + +NameはUnicode stringとして扱い、Unicode normalizationを行わない。同じ親のchildrenは、Unicode code point sequenceの完全一致で互いに異なる`name`を持たなければならない。 + +### `description` + +Objectが何を表すかを説明する短い公開情報。Objectの本文やApplication data全体を格納するfieldではない。 + +### `interface` + +Objectで利用できるOperationを定義するInterface Descriptorへの参照。 + +### `ref` + +同一Objectを複数の観測にまたがって識別するための任意のopaque identity。 + +### `validator` + +Objectの現在状態にHostが付与する任意のopaque value。ClientはObjectとともに保持し、その観測に基づく条件付きOperationのtargetへ使用する。 + +`Object`はchildrenとpathを直接持たない。これらはObject identityに固有とは限らず、Objectを観測したentryまたはTree traversalのcontextに属するため、requestまたはTree responseで表す。 + +Objectの意味とApplication dataとの境界は[2. Core Model](2-core-model.md)と[2.1. Object tree / Schema](2.1-object-tree-schema.md)で扱う。 + +## Interface Descriptor + +`InterfaceDescriptor`は、実装コード上のInterface Declarationから生成されるmachine-readable metadataである。 + +```rust +struct InterfaceDescriptor { + format: String, + documentation: Option, + types: Vec, + operations: Vec, +} +``` + +Interface実装者がこのstructのJSON encodingを手書きすることは想定しない。Rust macro、TypeScript definition API、code generator等が生成し、Hostが公開する。 + +`types`と`operations`のdeclaration順は表示時に保持してよいが、名前解決とvalidationの結果には影響しない。 + +### Type declaration + +```rust +struct TypeDeclaration { + name: String, + documentation: Option, + definition: TypeExpr, +} +``` + +一つのDescriptor内でType名は一意でなければならない。 + +### Type expression + +```rust +enum TypeExpr { + Unit, + Boolean, + Integer, + Number, + String, + Bytes, + Json, + Entry, + + Named { + name: String, + }, + + Record { + fields: Vec, + }, + + List { + items: Box, + }, + + Enum { + cases: Vec, + }, + + Union { + cases: Vec, + }, +} +``` + +`Named`は同じInterface Descriptor内の`TypeDeclaration`を参照する。External type importとrecursive type referenceは定義しない。Descriptorの意味検証では、存在しないTypeへの参照と参照cycleを拒否する。 + +### Record + +```rust +struct FieldDeclaration { + name: String, + required: bool, + documentation: Option, + r#type: TypeExpr, +} +``` + +一つのRecord内でfield名は一意でなければならない。`required = false`はfieldの省略を許可するが、`null`を許可する意味ではない。 + +Record valueに未宣言fieldが存在する場合はvalidation failureとする。 + +### Enum + +```rust +struct EnumCase { + name: String, + documentation: Option, +} +``` + +Enum caseはpayloadを持たない。一つのEnum内でcase名は一意でなければならない。 + +### Union + +```rust +struct UnionCase { + name: String, + documentation: Option, + payload: Option, +} +``` + +Union caseは、caseごとに0個または1個のpayloadを持つ。一つのUnion内でcase名は一意でなければならない。 + +### Operation declaration + +```rust +struct OperationDeclaration { + name: String, + documentation: Option, + parameters: Vec, + returns: ReturnDeclaration, +} + +struct ParameterDeclaration { + name: String, + required: bool, + documentation: Option, + r#type: TypeExpr, +} + +struct ReturnDeclaration { + documentation: Option, + r#type: TypeExpr, +} +``` + +一つのDescriptor内でOperation名は一意でなければならない。一つのOperation内でparameter名は一意でなければならない。 + +Interface Descriptorの生成と意味論は[2.2. Interface / Operation](2.2-operation.md)、人間とAIへのSignature Viewは[4.1. AI用Tools](4.1-ai-tools-example.md)で扱う。 + +## Value + +Operation argumentsとresultは、schema上の意味を持たない次のlogical valueで表す。 + +```rust +enum Value { + Unit, + Boolean(bool), + Integer(i64), + Number(f64), + String(String), + Bytes(Vec), + Record(BTreeMap), + List(Vec), +} +``` + +`Value`はHostとClientが交換するprimitiveおよびcompositeだけを表す。Path、enum case、union case等のsemantic variantを持たない。既知のInterfaceに対するgenerated bindingは、言語固有DTOと`Value`のcodecを提供できる。 + +### Primitive semantics + +| Value | 意味 | 制約 | +| --- | --- | --- | +| `Unit` | 値を持たない | Optional fieldの省略とは異なる | +| `Boolean` | 真偽値 | — | +| `Integer` | 符号付き整数 | `-9007199254740991`から`9007199254740991`まで | +| `Number` | IEEE 754 binary64 | NaN、正負Infinityを禁止する | +| `String` | Unicode string | — | +| `Bytes` | 任意のoctet列 | Transport Bindingがencodingを定める | +| `Record` | String keyを持つvalueの集合 | Key順に意味を持たない | +| `List` | 順序付きvalue | — | + +`integer`の範囲はRustとTypeScript間でlosslessに相互運用できる範囲へ制限する。 + +`number`を受信したruntimeは、有限値であることを検証する。 + +### Descriptorによる解釈 + +Interface Descriptorの`TypeExpr`は、rawな`Value`に意味と追加validationを与える。 + +| TypeExpr | 対応するValue | 追加の解釈 | +| --- | --- | --- | +| `Unit` | `Value::Unit` | 値を持たないresult等 | +| `Boolean` | `Value::Boolean` | — | +| `Integer` | `Value::Integer` | 相互運用範囲を検証する | +| `Number` | `Value::Number` | 有限値を検証する | +| `String` | `Value::String` | 通常の文字列として扱う | +| `Bytes` | `Value::Bytes` | Octet列として扱う | +| `Json` | JSON data modelで表現可能なValue | 内部構造をWIP schemaとして解釈しない | +| `Entry` | `Value::String` | Canonical absolute Worldspace pathとして検証する | +| `Record` | `Value::Record` | Field declarationに従って検証する | +| `List` | `Value::List` | 各要素をitems typeに従って検証する | +| `Enum` | `Value::String` | 宣言されたcase名として検証する | +| `Union` | `Value::Record` | Discriminatorとpayloadをcase declarationに従って検証する | + +`Json`が受け付けるのはJSONのnull、boolean、number、string、array、objectに対応するValueだけであり、`Bytes`は含まない。JSON内の整数と数値にも`Value::Integer`と`Value::Number`と同じ範囲および有限性の制約を適用する。 + +`Entry`と`String`は同じprimitiveで交換する。ClientはDescriptor上で`Entry`と宣言された位置だけをWorldspace pathとして扱い、通常のStringを内容からEntryへ変換しない。 + +EnumもString、UnionもRecordとして交換する。SDKまたはruntimeは、Descriptorによるvalidation後の内部表現としてtyped enum、union、Path等を構築してよい。それらはProtocolの送受信形式ではない。 + +### Value validation + +Valueは、Operation declarationのTypeExprと照合して検証する。 + +- `Named`を参照先Typeへ解決する。 +- Required fieldまたはparameterの欠落を拒否する。 +- 未宣言のRecord fieldを拒否する。 +- Optional fieldの省略と`Unit`を区別する。 +- EnumおよびUnionの未知caseを拒否する。 +- Union discriminator、payloadの有無、payload typeをcase declarationに照合する。 +- `Entry`として宣言されたStringがcanonical pathであることを検証する。 +- Integerの相互運用範囲とNumberの有限性を検証する。 + +## `fetch` + +一つのpathで現在公開されているObjectを取得する。 + +```rust +struct FetchRequest { + path: String, +} + +type FetchResponse = Object; +``` + +Requestの`path`はresponseに重複して含めない。Root path `/`ではObjectの`name`が空文字列でなければならず、非root pathでは最後のsegmentとObjectの`name`が一致しなければならない。Clientは一致しないresponseを`InvalidResult`として扱う。 + +返されたObjectが`validator`を持つ場合、Clientはrequest pathとObjectを対応付けてcacheし、条件付きOperationの`target`を構築できる。Batch Transport Bindingも各itemのrequestとresponseを一意に対応付けなければならない。 + +## `fetch_tree` + +一つのpathを起点に、indexableなObjectをBreadth-First Searchで取得する。 + +```rust +struct FetchTreeRequest { + path: String, + depth: u32, + limit: u32, +} + +struct ObjectTreeNode { + object: Object, + children: Vec, +} + +struct FetchTreeResponse { + root: ObjectTreeNode, + truncated: bool, +} +``` + +- 起点Objectはdepth `0`とする。 +- `limit`はrootを含むresponse全体のnode数に適用する。 +- Root nodeのObjectはrequest pathが指すObjectであり、Root pathが`/`でない場合は最後のsegmentとObjectの`name`が一致する。 +- 各childのpathは、parent pathへchild Objectの`name`を追加して導出する。 +- 同じparent nodeのchildrenは、互いに異なる`name`を持つ。 +- `children`はWorldspace上の直接の子だけを含む。 +- `depth`または`limit`によって存在するindexable childを省略した場合、`truncated = true`とする。 +- 要求範囲内のindexable childをすべて含む場合、`truncated = false`とする。 + +各nodeのObjectがvalidatorを持つため、Clientはrequest pathとObjectの`name`から各pathを導出し、Treeから発見したObjectを再度`fetch`せずに条件付きOperationのtargetを構築できる。 + +`limit`は1以上とする。Hostはdepthとlimitへ実装上の上限を設定し、超過したrequestには`ResourceLimitExceeded`を返す。 + +## `fetch_interface` + +Interface参照に対応するInterface Descriptorを取得する。 + +```rust +struct FetchInterfaceRequest { + interface: String, +} + +struct FetchInterfaceResponse { + interface: String, + descriptor: InterfaceDescriptor, +} +``` + +Clientは次を検証する。 + +- Responseの`interface`がrequestと一致する。 +- Descriptorが構造検証および意味検証に成功する。 +- Descriptorの`format`がClientの対応するversionである。 + +Interface参照はHostが発行するopaque stringである。Clientは参照をcache keyとして使用し、同じ有効な参照から異なるDescriptorを受け取った場合はProtocol failureとして扱う。 + +## `call_operation` + +指定pathにあるObjectへOperationを実行する。 + +```rust +struct Target { + path: String, + validator: Option>, +} + +struct CallOperationRequest { + target: Target, + operation: String, + arguments: BTreeMap, +} + +struct CallOperationResponse { + result: Value, + validator: Option>, +} +``` + +`target.path`はOperationを実行するObjectのpathである。`target.validator`は、Clientが観測したObjectのvalidatorを条件として指定する。Validatorを持たないObjectまたは無条件実行では省略する。 + +`arguments`はOperation parameterに対応する名前付きrecordである。引数がない場合は空のmapを送る。 + +`target.validator`が指定された場合、Hostは現在のvalidatorとの比較とOperation実行をatomicに行う。一致しない場合はOperationを実行せず`ValidatorMismatch`を返す。Hostがvalidatorを要求するOperationに指定がない場合は`ValidatorRequired`を返す。 + +Hostはvalidatorの生成方法と無効化する状態変化を決定する。Content hash、generation、database revision等を使用できる。比較はopaque bytesの完全一致で行う。 + +Responseの`validator`はOperation実行後の現在状態に対してHostが発行した値である。Read-only Operationでもresultを観測した時点のvalidatorを返してよい。Validatorを提供しない場合は省略する。 + +ClientはresultをOperationのreturn typeに従って検証する。Validationに失敗したvalueをApplicationへ渡さない。 + +## Protocol responseとfailure + +Core interactionは、成功responseまたはProtocol failureを返す。 + +```rust +enum ProtocolResult { + Success(T), + Failure(ProtocolError), +} + +struct ProtocolError { + code: ProtocolErrorCode, + message: String, +} + +enum ProtocolErrorCode { + InvalidRequest, + NotFound, + InterfaceNotFound, + OperationNotFound, + InvalidArguments, + InvalidResult, + ValidatorRequired, + ValidatorMismatch, + PermissionDenied, + ResourceLimitExceeded, + Internal, +} +``` + +`message`は人間向けのboundedな診断であり、Clientが分岐に使用する安定した値ではない。Clientは`code`を使用する。 + +Hostは情報漏洩を避けるため、存在するが閲覧できないObjectに`NotFound`を返してもよい。 + +Protocol failureとdomain failureを混在させない。現在のProtocolでは、Domain failureをApplicationのOperation resultに含まれるUnion caseとして明示する。専用のfailure envelopeは定義しない。 + +Transport BindingはProtocol Resultをstatus code、response envelope、stream termination等へ対応付ける。 + +## Resource limit + +HostとClientは、untrusted inputによるresource exhaustionを避けるため、少なくとも次へ上限を設ける。 + +- Pathとして解釈するstring、validator、name、description、documentationの長さ。 +- Interface Descriptor全体のbyte数。 +- Type declaration、Operation、parameter、field、caseの数。 +- TypeExprとValueのnesting depth。 +- Record field数とList要素数。 +- `fetch_tree`のdepthとlimit。 +- Protocol error messageの長さ。 + +各実装はこれらにboundedな上限を設定する。上限を超えたrequestまたはresponseは`ResourceLimitExceeded`として扱い、現在のProtocolではlimit negotiationを定義しない。 + +## Batch + +BatchはCore interactionではなくTransport Bindingのoptimizationである。 + +Transport Bindingは、複数の`FetchRequest`、`FetchTreeRequest`、`FetchInterfaceRequest`を一つのphysical requestへまとめてよい。それぞれのlogical requestは独立して成功または失敗し、個別に実行した場合と同じ意味を持たなければならない。 + +`call_operation`は副作用、順序、部分的成功の意味が不明確になるため、Coreの標準batch対象にしない。 + +## Transport Bindingの要件 + +Transport Bindingは、この章のlogical structについて次を定義する。 + +- Requestとresponseのframing。 +- Protocol primitiveのconcrete encoding。 +- Object、Descriptor、Valueのencoding。 +- Optional fieldの省略。 +- Protocol failureのmapping。 +- Validatorのmapping。 +- Batch packagingを提供する場合はitemの対応付けと部分的failure。 +- Message size、timeout、concurrency等のtransport固有limit。 + +Transport Bindingは、logical typeの区別またはvalidation semanticsを失ってはならない。 diff --git a/4-client.md b/4-client.md index 5e2f676..f3c3db4 100644 --- a/4-client.md +++ b/4-client.md @@ -2,7 +2,7 @@ ## 役割 -Clientは、Hostが提供するWorldspaceをユーザーへ提示する実装主体である。WIPのCore Protocolを直接利用しつつ、Objectが参照するInterfaceを解決し、用途に応じたViewやAPIへ投影する。 +Clientは、Hostが提供するWorldspaceをユーザーへ提示する実装主体である。WIP Protocolを利用しつつ、Objectが参照するInterfaceを解決し、用途に応じたViewやAPIへ投影する。 ClientはHostから得た情報をそのまま一時表示するだけでなく、rootからindexable edgeを辿って構成したエントリツリーと、必要に応じて選択したエントリを保持し、ユーザーから見た**既知の空間**を構成する。 @@ -23,9 +23,9 @@ Operationを通して発見されたpathは、必ずしもKnown Spaceへ追加 ## Interface cache -Objectの公開情報はOperation定義を直接含まず、Interface参照を持つ。Clientは未知のInterface参照を`fetch_interface`で解決し、取得したWIP IDL documentを参照ごとにcacheする。 +Objectの公開情報はOperation定義を直接含まず、Interface参照を持つ。Clientは未知のInterface参照を`fetch_interface`で解決し、取得したInterface Descriptorを参照ごとにcacheする。 -一つのInterface documentに宣言された関数の集合が、そのInterfaceのOperation一覧である。複数のObjectが同じInterfaceを参照する場合、ClientはIDLを一度だけ取得・parseすればよい。 +一つのInterface Descriptorに宣言されたOperationの集合が、そのInterfaceのOperation一覧である。複数のObjectが同じInterfaceを参照する場合、ClientはDescriptorを一度だけ取得、検証すればよい。 ClientはInterface cacheとObjectのInterface参照を比較し、未知のInterfaceだけを取得する。複数の`fetch_interface`は、Transport Bindingが提供するbatchを利用してまとめてよい。 @@ -45,7 +45,7 @@ Clientは、Operation Resultの`entry`型として発見したpathを現在の 一時的に取得したエントリは、結果の利用が終わった時点で破棄してよい。 -後続のInteractionでも必要なエントリは、Client側でpinしてKnown Spaceへ保持できる。PinはClient内部の保持方針であり、Host上のObject lifetimeやCore Protocol上の状態を変更しない。 +後続のInteractionでも必要なエントリは、Client側でpinしてKnown Spaceへ保持できる。PinはClient内部の保持方針であり、Host上のObject lifetimeやWIP Protocol上の状態を変更しない。 単純なClientは発見したエントリをすべて保持してもよいが、WIPはそれを必須としない。具体的な容量制限やeviction algorithmはClient実装に委ねる。 @@ -53,7 +53,7 @@ Clientは、Operation Resultの`entry`型として発見したpathを現在の Clientは、機械的にエントリを探索する必要がある場合、個別の`fetch`を多数発行するのではなく`fetch_tree`を利用する。 -`fetch_tree`では起点エントリ、探索深度`depth`、返却エントリ総数の上限`limit`を指定する。Hostはindex edgeを幅優先探索してTreeを返す。 +`fetch_tree`では起点path、探索深度`depth`、返却エントリ総数の上限`limit`を指定する。Hostはindex edgeを幅優先探索してTreeを返す。Tree nodeはpathを重複して持たず、Clientは起点pathと各Objectの`name`からchild pathを導出する。 レスポンスが`truncated`である場合、Clientは取得したTreeが完全ではないことを保持し、完全な空間として扱ってはならない。 @@ -69,7 +69,7 @@ Objectが`ref`を公開している場合、Clientはそれを用いて複数の Clientは、エントリを観測した後にOperationを実行するまでの間に、そのエントリが別Objectを指すようになっていないことを検証する責務を持つ。 -この検証に必要なopaque token、generation、ETag等はClient / Host間で透過的に扱い、AIやユーザーに直接管理させる必要はない。 +Objectが`validator`を持つ場合、Clientは観測したpathとvalidatorを対応付ける。条件付きOperationでは両者をtargetとしてHostへ渡し、validatorの比較と実行をHost上でatomicに行わせる。ValidatorはAIやユーザーに直接管理させない。HTTPS Bindingは、semanticsが適合する場合にHTTP ETag等へ対応付けてよい。 対象が変化していた場合、Clientは新しいObjectに対してOperationを自動再試行せず、対象が変化したことを上位インターフェースへ通知して再観測を要求する。 diff --git a/4.1-ai-tools-example.md b/4.1-ai-tools-example.md index 1321f4e..fa8546e 100644 --- a/4.1-ai-tools-example.md +++ b/4.1-ai-tools-example.md @@ -2,7 +2,7 @@ ## 目的 -AI用Toolsは、WIP ClientがAIへ提供する想定インターフェースである。Core Protocolをそのまま露出せず、Clientが保持するKnown Space / Discoverable Spaceと組み合わせて、AIがWorldspaceを理解・探索・操作しやすい形へ投影する。 +AI用Toolsは、WIP ClientがAIへ提供する想定インターフェースである。Protocol structをそのまま露出せず、Clientが保持するKnown Space / Discoverable Spaceと組み合わせて、AIがWorldspaceを理解・探索・操作しやすい形へ投影する。 現時点では、**discover / inspect / invoke** の3操作を基本とする。 @@ -16,7 +16,7 @@ AI用Toolsは、WIP ClientがAIへ提供する想定インターフェースで ## `inspect` -`inspect(target)` は、対象エントリ / Objectについて**何ができるか**を把握するための操作である。ClientはObjectのInterface参照を解決し、WIP IDL documentに宣言されたOperationを提示する。 +`inspect(target)` は、対象エントリ / Objectについて**何ができるか**を把握するための操作である。ClientはObjectのInterface参照を解決し、Interface Descriptorに宣言されたOperationを提示する。 Objectのドメインデータをpropertiesとして直接公開することは前提としない。データを読む行為もOperationとして表現する。 @@ -27,11 +27,11 @@ Objectのドメインデータをpropertiesとして直接公開することは - `get_related_items()` — 関連Objectのentry pathを取得する。 - `close(reason: string)` — 理由を添えてIssueをクローズする。 -Operationの関数宣言と短いdocumentationは、Objectが参照する[WIP IDL](draft/wip-idl.md) documentから取得する。ClientはIDLをparseし、利用するAI providerが要求するTool schemaへ変換する。JSON Schema等への変換はAI向けClient adapterの責務であり、HostがWIP Interfaceとして提供する必要はない。 +Operationの関数宣言と短いdocumentationは、Objectが参照する[Interface Descriptor](2.2-operation.md)から取得する。Clientは検証済みDescriptorからIDL風のSignature Viewを生成し、人間とAIへ提示する。利用するAI providerがTool schemaを要求する場合、Client adapterがDescriptorからJSON Schema等へ変換する。Provider固有schemaをHostがWIP Interfaceとして提供する必要はない。 ## `invoke` -`invoke(target, operation, arguments)` は、`inspect`によって発見したOperationを実行する。`arguments`はOperationのWIP IDL parameter listに従う名前付きfieldのrecordであり、位置引数は用いない。引数を持たないOperationには空のrecordを渡す。 +`invoke(target, operation, arguments)` は、`inspect`によって発見したOperationを実行する。`arguments`はOperationのparameter declarationに従う名前付きfieldのrecordであり、位置引数は用いない。引数を持たないOperationには空のrecordを渡す。Clientはargumentsを検証し、対象pathと観測したObjectのoptionalなvalidatorから`call_operation`のtargetを構築する。 PTC / REPL bindingでは、通常のメソッド呼び出しへ投影してよい。 diff --git a/draft/unresolved-issues.md b/draft/unresolved-issues.md index e920dd3..ecb17e2 100644 --- a/draft/unresolved-issues.md +++ b/draft/unresolved-issues.md @@ -1,36 +1,56 @@ # 未解決事項 -各設計ページに未解決事項を分散させず、このページで対象ページとともに一元管理する。 +主要な未解決事項を、canonicalなCore文書とTransport Bindingへのindexとしてまとめる。 ## 2.1. Object tree / Schema 対象: [2.1. Object tree / Schema](../2.1-object-tree-schema.md) -- Object / エントリ公開情報とInterface参照の具体的なwire schema。 -- `name`とpath segmentの関係。 -- entry pathのcanonicalization規則。 -- Object `description`の長さや必須性をprotocol上でどこまで規定するか。 +- 一つのObjectが複数pathへ配置された場合、`description`をObject固有または配置固有のどちらとするか。 +- Partial visibility、redaction、authorization failureの表現。 -## 2.2. Operation / WIP IDL +## 2.2. Interface / Operation -対象: [2.2. Operation](../2.2-operation.md)、[WIP IDL](wip-idl.md) +対象: [2.2. Interface / Operation](../2.2-operation.md) + +- RustとTypeScriptのcode-level Interface Declaration API。 +- Interface参照をcontent-addressedにし、Descriptor digestをProtocolへ導入するか。 +- Descriptor version間の互換性規則。 +- 現在plain textであるDocumentationへmarkup、localization、構造化exampleを追加するか。 +- Signature Viewのfull renderingをどこまで標準化するか。 +- Effect annotationを採用するか。 +- 現在Unionで表すDomain failureへ専用declarationを追加するか。 + +## 3. Protocol + +対象: [3. Protocol](../3-protocol.md) + +### Field semantics + +- `ref` fieldのencoding、scope、有効期間。 +- `interface` fieldで使用するopaque参照のscopeと有効期間。 +- Validatorの生成、期限、再利用、およびObjectごとの無効化方針をどこまで標準化するか。 + +### Type / Value -- WIP IDL sourceのcanonicalization、digest algorithm、Interface参照の形式とscope。 -- WIP IDLのversion間における互換性規則。 - String length、numeric range、pattern等のconstraintを導入するか。 -- Recursive named typeを許可するか。 +- 現在拒否するrecursive named typeを許可するか。 - `i64`、`u64`、`bigint`、`decimal`等を追加するか。 -- Operation documentationの必須性と長さ。 -- Effect annotationを採用するか、および構文と標準effectの集合。 -- `fail`を採用する場合のdomain failure表現。 -- domain errorをOperationのreturn typeに含めるか、Protocol errorとして分離するか。 +- `json` escape hatchをすべてのTransport Bindingへ要求するか。 + +### Interaction / Error + +- `fetch_tree`のdepthとlimitへ相互運用上の共通上限を定義するか。 +- ProtocolErrorへstructured detailを追加するか。 +- Resource limitを固定値またはcapability negotiationのどちらで定義するか。 ## WIP over HTTPS 対象: [WIP over HTTPS](wip-over-https.md) -- `fetch_interface`のrequest / response wire schema。 -- Effect annotationを採用した場合に、副作用のない`call_operation`をbatch対象へ加えるか。 +- Protocol primitive、Object、Interface Descriptor、ValueのJSON encoding。 +- Validatorをresponse body、HTTP ETag / If-Match、または両方へどうmappingするか。 +- Protocol failureのHTTP statusとerror body。 - Batch件数、request / response byte size、timeoutの上限。 - Batch envelope自体が不正な場合のHTTP statusとerror body。 -- Subrequest共通のProtocol error schema。 \ No newline at end of file +- Effect annotationを採用した場合に、副作用のない`call_operation`をbatch対象へ加えるか。 diff --git a/draft/wip-idl.md b/draft/wip-idl.md deleted file mode 100644 index 36320e5..0000000 --- a/draft/wip-idl.md +++ /dev/null @@ -1,335 +0,0 @@ -# WIP IDL - -WIP IDLは、Objectが実装するInterfaceを記述するための小さなinterface definition languageである。 - -一つのWIP IDL documentが一つのInterfaceを定義する。Documentに宣言された関数の集合が、そのInterfaceのOperation集合となる。Operation名、parameter、return type、documentationはIDL内の一つの宣言としてまとめ、別のOperation descriptorへ重複して記述しない。 - -WIP IDLのsourceそのものをInterface定義のcanonicalな交換形式とする。HostとClientの間でJSON SchemaやIDLを変換したJSON ASTを交換することは前提としない。Clientはsourceをparseして内部表現を構築し、必要に応じてAI Tool schemaやGUI formへ投影する。 - -この文書では、WIP IDLの初期文法と型を定義する。 - -## 設計方針 - -- 一つのdocumentで一つのInterfaceを定義する。 -- Document内のOperation declarationを、そのInterfaceのOperation一覧とする。 -- Operationを関数として、parameterとreturn typeを一体で表現する。 -- 文法を小さく保ち、一般的なschema validation languageにはしない。 -- Wire上の値表現はTransport Bindingが定める。 -- JSON SchemaはWIPの交換形式にせず、必要なClientが生成する。 -- Worldspaceのエントリは、そのpathを表す`entry`型として扱う。 - -## Source - -WIP IDL sourceはUTF-8 textとする。ASCII space、tab、LFによる空白は、tokenを分離する場合を除いて意味を持たない。 - -`//`から行末までは通常のcommentとし、parserは無視する。 - -`///`から行末まではdocumentation commentとする。Operationまたはtype declarationの直前に連続するdocumentation commentは、そのdeclarationのdocumentationとしてparserが保持する。 - -```wip -/// Returns entries related to the target Object. -operation get_related_items() -> { - items: [entry], -}; -``` - -IdentifierはASCIIの英字または`_`で始まり、以降にASCIIの英数字または`_`を含められる。 - -```text -identifier = (ALPHA | "_") { ALPHA | DIGIT | "_" }; -``` - -Keyword、primitive type名、Worldspace固有型名はidentifierとして使用できない。 - -Named typeにはUpperCamelCase、Operation、parameter、field、enum case、union caseにはsnake_caseを使用する。 - -## Grammar - -以下のEBNFは空白とcommentを省略して示す。 - -```ebnf -document = { declaration } ; - -declaration = [ documentation ], - ( type-declaration | operation-declaration ) ; - -documentation = doc-comment, { doc-comment } ; - -type-declaration = "type", type-name, "=", type-definition, ";" ; - -type-definition = type-expression | enum-type | union-type ; - -operation-declaration = - "operation", identifier, - "(", [ parameter, { ",", parameter }, [ "," ] ], ")", - "->", type-expression, ";" ; - -parameter = identifier, [ "?" ], ":", type-expression ; - -type-expression = - primitive-type - | worldspace-type - | type-name - | record-type - | list-type ; - -record-type = - "{", [ record-field, { ",", record-field }, [ "," ] ], "}" ; - -record-field = identifier, [ "?" ], ":", type-expression ; - -list-type = "[", type-expression, "]" ; - -enum-type = - "enum", "{", identifier, { ",", identifier }, [ "," ], "}" ; - -union-type = - "union", "{", union-case, { ",", union-case }, [ "," ], "}" ; - -union-case = identifier, [ "(", type-expression, ")" ] ; - -primitive-type = - "unit" - | "boolean" - | "integer" - | "number" - | "string" - | "bytes" - | "json" ; - -worldspace-type = "entry" ; - -type-name = identifier ; -``` - -同じdocument内でtype名またはOperation名を重複して宣言してはならない。同じOperation内でparameter名を重複してはならない。Named typeは同じdocument内で宣言されたtypeを参照する。 - -## Primitive types - -| Type | 意味 | WIP over HTTPSでの表現 | 制約 | -| --- | --- | --- | --- | -| `unit` | 値を持たない | JSON `null` | Optional parameter / fieldの省略とは区別する | -| `boolean` | 真偽値 | JSON boolean | — | -| `integer` | 符号付き整数 | 小数部を持たないJSON number | `-9007199254740991`以上、`9007199254740991`以下 | -| `number` | IEEE 754 binary64値 | JSON number | NaN、positive infinity、negative infinityは不可 | -| `string` | Unicode string | JSON string | — | -| `bytes` | 任意のoctet列 | RFC 4648 Section 4のbase64を格納したJSON string | paddingを含む | -| `json` | opaqueな任意のJSON value | JSON value | Clientは内部構造をschemaとして解釈しない | - -`integer`の範囲は、異なる言語のClient間で正確に交換できる範囲に制限している。この範囲を超える整数は`integer`としてencodeしない。`i64`、`u64`、`bigint`等の追加型とlosslessなwire表現は将来の拡張として扱う。 - -`json`は外部APIの応答など構造を事前に固定できない値のためのescape hatchであり、通常のOperationではより具体的な型を優先する。 - -## Composite types - -| Type | 構文 | 意味 | WIP over HTTPSでの表現 | -| --- | --- | --- | --- | -| Record | `{ field: Type }` | 名前付きfieldの集合 | JSON object | -| List | `[Type]` | 同じ型の順序付き値 | JSON array | -| Named type | `type Name = Type;` | 型への名前付け | 参照先と同じ表現 | -| Enum | `enum { first, second }` | payloadを持たないcaseの集合 | case名のJSON string | -| Union | `union { case(Type), empty }` | discriminatorを持つcaseの集合 | `$case`を持つJSON object | - -### Record - -Recordは名前付きfieldの集合である。 - -```wip -type QueryResult = { - items: [entry], - next_cursor?: string, -}; -``` - -`?`を持たないfieldはrequired、`?`を持つfieldはoptionalである。Optionalはparameterまたはrecord fieldにのみ適用し、一般化しない。 - -WIP over HTTPSではrecordをJSON objectとしてencodeする。Optional fieldに値がない場合はfield自体を省略する。FieldをJSON `null`にすることは省略と同じ意味ではなく、そのfieldの型が`unit`または`json`として`null`を許す場合に限る。 - -宣言されていないfieldをrecordに含めてはならない。 - -### List - -Listは同じ型の0個以上の順序付き値を表す。 - -```wip -[entry] -``` - -WIP over HTTPSではJSON arrayとしてencodeする。 - -### Named type - -`type`宣言によって型へ名前を付けられる。 - -```wip -type IssueList = [entry]; -``` - -Aliasを参照する値のwire表現は、参照先の型と同じである。 - -### Enum - -Enumはpayloadを持たないcaseの集合である。 - -```wip -type Relation = enum { - parent, - sibling, - related, -}; -``` - -WIP over HTTPSではcase名をJSON stringとしてencodeする。 - -```json -"sibling" -``` - -### Union - -Unionはdiscriminatorを持つcaseの集合である。Caseは0個または1個のpayloadを持つ。 - -```wip -type LookupResult = union { - found(entry), - not_found, - ambiguous([entry]), -}; -``` - -WIP over HTTPSでは`$case` discriminatorを持つJSON objectとしてencodeする。Payloadを持つcaseは`value` fieldに値を格納する。 - -```json -{ - "$case": "found", - "value": "/items/123" -} -``` - -Payloadを持たないcaseには`value`を含めない。 - -```json -{ - "$case": "not_found" -} -``` - -## Worldspace type - -| Type | 意味 | WIP over HTTPSでの表現 | -| --- | --- | --- | -| `entry` | 同じWorldspace内のエントリを指すcanonical absolute path | JSON string | - -```json -"/items/123" -``` - -Wire上では通常の`string`と同じ表現だが、WIP IDL上で`entry`と宣言された位置にある値だけをClientがエントリとして認識する。通常の`string`やopaqueな`json`に含まれるpathらしい文字列を、Clientがエントリとして推測してはならない。 - -Operation Resultから`entry`を発見したClientは、そのpathを一時的に利用し、必要に応じて`fetch`または`fetch_tree`する。複数のpathを効率的に取得する場合は、Clientが必要なpathを選択した後、Transport Bindingが提供するbatchを利用する。Operation Resultへエントリ公開情報を先行同梱しない。 - -Operationが返したpathは、Operationの実行対象の子に限定されない。親、兄弟、関連Objectなど、Worldspace内の任意のエントリを指してよい。Operationの実行対象と返されたpathの間に、暗黙のTree edgeや意味的関係を推論してはならない。 - -`fetch`が返すエントリ公開情報と、`fetch_tree`が返すindexableなtreeはCore Protocolのresponseであり、WIP IDLの値型としては定義しない。 - -## Operation declarations - -Operationは名前付きparameterとreturn typeを一つの関数宣言として定義する。 - -```wip -type Relation = enum { - parent, - sibling, - related, -}; - -/// Returns entries related to the target Object. -operation get_related_items( - relation: Relation, - limit?: integer, -) -> { - items: [entry], - next_cursor?: string, -}; -``` - -Operationのparameterは、WIP over HTTPSでは一つのJSON objectへencodeする。Parameter名がobjectのfield名になる。位置引数は定義しない。 - -引数を持たないOperationは空のparameter listで宣言し、空のJSON objectをargumentsとして渡す。 - -```wip -operation refresh() -> unit; -``` - -Return typeには任意のtype expressionまたはNamed typeを使用できる。ただし、将来fieldを追加する可能性があるOperationではrecordを推奨する。 - -`///` documentation commentは、AIやユーザーがOperationの用途を判断するための短いdescriptionとして扱う。長文documentationをIDLへ埋め込むことは想定しない。 - -## Effect annotation（検討案） - -Operationがdomain-levelな副作用や失敗を発生させ得ることを、関数宣言上のeffect rowとして表す案を検討する。この節は確定仕様ではなく、前掲のEBNFにもまだ含めない。 - -構文は、return typeの後に`! { ... }`を付ける形を候補とする。 - -```wip -operation get_item( - id: string, -) -> Item ! {}; - -operation update_item( - id: string, - value: Item, -) -> Item ! { - write, - fail, -}; -``` - -| Annotation | 意味の候補 | -| --- | --- | -| `! {}` | 宣言上、domain-levelな副作用およびfailureを持たない | -| `write` | 外部から観測可能な副作用を発生させ得る | -| `fail` | `E`型のdomain failureを返し得る | -| annotationなし | Effect情報が未指定 | - -Network error、authorization失敗、target消失、Protocol decode errorなど、すべてのremote callで起こり得るProtocol errorは`fail`に含めない。`fail`はOperation固有のdomain failureだけを表す候補とする。 - -Effect annotationは、ClientによるOperationの説明や、HTTP batchへ安全に含められるOperationの判定材料として利用できる可能性がある。ただし、具体的なbatch可否規則はまだ確定しない。 - -この案はKokaのeffect rowやUnisonのability requirementのように、関数が起こし得るeffectをsignatureへ表す記法を参考にしている。ただしWIP IDLへ導入するのは宣言上のannotationだけであり、effect handler、`perform`、continuation、resume、handlerへのnetwork転送、algebraic effect runtimeは導入しない。 - -## Interface identity and sharing - -一つのWIP IDL documentが一つのInterfaceを定義する。ObjectはOperation定義ではなく、そのInterfaceへの参照を持つ。 - -複数のObjectが同じInterface参照を共有できる。Clientは未知のInterfaceだけを`fetch_interface`で取得し、参照ごとにIDL sourceとparse済み表現をcacheできる。 - -Hostは主体のroleや権限に応じて異なるOperation集合を投影する場合、異なるWIP IDL documentとInterface参照を返してよい。Interfaceは頻繁に変化するOperationの実行可否を表すものではない。 - -Interface参照をcontent-addressed digestにすることが想定されるが、参照形式、sourceのcanonicalization、digest algorithmはTransport Bindingで定義する。 - -## Interface exchange - -HostはInterfaceについて、少なくとも次をClientへ提供する。 - -| 項目 | 内容 | -| --- | --- | -| Interface reference | Objectが保持し、`fetch_interface`の対象となる参照 | -| Language identifier | 初期versionは`wip-idl/1` | -| Source | WIP IDL source | -| Digest | Cacheと同一性確認に利用するdigest | - -交換されるInterface定義の正本はWIP IDL sourceである。HostはJSON SchemaやIDL ASTを併記する必要はない。 - -ClientはIDLを内部ASTへparseし、必要に応じてAI provider用JSON Schema、GUI form、言語固有の型などを生成できる。 - -ClientはObjectのInterface参照をcacheと比較し、未知のInterfaceだけを`fetch_interface`する。複数のInterface取得はTransport Bindingでbatchできる。HostはClientのcache状態を推測せず、ObjectのresponseへInterface定義を先行同梱しない。 - -## 未解決事項 - -- Sourceのcanonicalizationとdigestの厳密な計算方法。 -- Interface参照の具体的な形式とscope。 -- String length、numeric range、pattern等のconstraintを導入するか。 -- Recursive named typeを許可するか。 -- `i64`、`u64`、`bigint`、`decimal`等を追加するか。 -- `entry`が参照するpathのcanonicalization規則。 diff --git a/draft/wip-over-https.md b/draft/wip-over-https.md index e32e463..5880e08 100644 --- a/draft/wip-over-https.md +++ b/draft/wip-over-https.md @@ -1,49 +1,165 @@ # WIP over HTTPS -WIP over HTTPSは、**WIP Core ProtocolをHTTPS上へ対応付ける標準Transport Binding**である。 +WIP over HTTPSは、[WIP Protocol](../3-protocol.md)のlogical data modelをHTTPS上へ対応付ける標準Transport Bindingである。 ## 目的 -Core Protocolの意味論を変えずに、既存のWebインフラを利用してClientとHostを接続する。 +Protocolの意味論を変えずに、既存のWeb infrastructureを利用してClientとHostを接続する。 ## 方針 初期の標準bindingはHTTPS上のrequest / responseのみを規定する。TLS、認証、Proxy、Gateway、Observability、Caching、connection reuse、multiplexing、compression等の既存機構を利用してよいが、特定のHTTP versionや実装方式を必須にしない。 -OperationがWebSocket等のendpointを通常のdomain valueとして返すことは妨げない。そのendpoint上のprotocol、状態、lifecycleはWIPの規定対象外であり、ClientとHost固有実装の責務とする。 +OperationがWebSocket等のendpointを通常のApplication dataとして返すことは妨げない。そのendpoint上のprotocol、状態、lifecycleはWIPの規定対象外であり、ClientとHost固有実装の責務とする。 双方向socket transportをWIP bindingとして標準化する場合は、将来の独立した拡張として定義する。 ## Binding対象 -少なくとも、Core Protocolの以下の操作をHTTP request / responseへ対応付ける。 +少なくとも、Protocolの以下のinteractionをHTTP request / responseへ対応付ける。 - `fetch` - `fetch_tree` - `fetch_interface` - `call_operation` -具体的なHTTP method、endpoint、content type、error mapping、認証方式、batch表現などは、このbinding仕様側で定義する。 +具体的なHTTP method、endpoint、content type、error mapping、認証方式、validator mapping、batch表現は、このbinding仕様側で定義する。 -## Interfaceの取得 +## JSON encodingの基本規則 -Objectの公開情報はOperation定義を直接含まず、[WIP IDL](wip-idl.md) documentで定義されたInterfaceへの参照を持つ。`fetch_interface`は、その参照に対応するInterfaceのlanguage identifier、source、digestを返す。 +ProtocolのrecordはJSON object、listはJSON array、optional fieldの省略はJSON fieldの省略としてencodeする。 -HTTPS response全体をJSON envelopeにする場合、IDL sourceをJSON stringとして格納してよい。ただし、これはIDLをJSON ASTへ変換するものではない。BindingはIDL sourceを専用resourceおよびcontent typeで直接取得する方法を定義してもよい。 +Protocol structの`String`はJSON string、`Vec`はbindingが定めるopaque encodingへ対応付ける。Path、Interface参照、Object identity、名前等の意味はJSON typeではなくfieldの位置によって決まる。 -ClientはObjectのInterface参照をcacheと比較し、未知のInterfaceだけを`fetch_interface`する。HostはClientのcache状態を推測せず、`fetch`や`fetch_tree`のresponseへInterface定義を先行同梱しない。複数のInterface取得はHTTP batchingでまとめられる。 +| Field | JSON encoding | 解釈 | +| --- | --- | --- | +| `path` | string | canonical absolute Worldspace path | +| `name`、Operation / Type / Field / Parameter / Case名 | string | 各struct内の名前 | +| `interface` | string | Interface Descriptorへの参照 | +| `format` | string | Descriptor format identifier | +| `ref` | string | opaqueなObject identity | +| `validator` | base64 stringまたはHTTP metadata | opaqueな条件付き操作用value | -## Operation valueのJSON encoding +Validatorをresponse bodyのbase64 stringとして運ぶか、HTTP ETag等へ対応付けるかは、このbindingがresponse形態ごとに定める。どちらの場合もClient runtimeは値をopaqueに扱い、AIやユーザーへ直接管理させない。 -WIP over HTTPSでは、`call_operation`のargumentsとresultを、選択したOperation declarationに従うJSON valueとしてencodeする。JSONはHTTPS binding上の値表現であり、WIP CoreのInterface定義形式ではない。 +未知のJSON fieldを許可する箇所はProtocol側で明示する。Object、Interface Descriptor、request / response、Protocol errorの未宣言fieldは既定で拒否する。 -`arguments`はOperationのparameter名をfield名とするJSON objectとする。位置引数は用いず、引数を持たないOperationには空のobjectを渡す。 +## Objectの取得 + +`fetch` requestはpathとして解釈されるstringを`path`に渡し、Objectを直接受け取る。 概念的なrequest bodyは次の形になる。 ```json { - "target": "/items/current", + "path": "/items/123" +} +``` + +Responseは次の形になる。 + +```json +{ + "name": "123", + "description": "First item", + "interface": "item-interface-v1", + "ref": "item:123", + "validator": "b3BhcXVlLXZhbGlkYXRvcg==" +} +``` + +`ref`、`description`、`validator`はoptional fieldであり、存在しない場合はfield自体を省略する。JSON `null`を代わりに使用しない。 + +Request pathはresponseへ重複して含めない。HTTP batchを使用する場合も、subrequestの`id`によってrequest pathとObject responseを対応付ける。 + +## Treeの取得 + +`fetch_tree` requestは起点path、depth、limitを渡す。 + +```json +{ + "path": "/items", + "depth": 1, + "limit": 100 +} +``` + +Responseは各nodeのObjectとchildrenを含む。各Objectのpathはrequest pathとObjectの`name`から導出し、validatorはObjectのfieldとしてencodeする。 + +```json +{ + "root": { + "object": { + "name": "items", + "description": "Item collection", + "interface": "sha256:item-collection-interface", + "validator": "cm9vdC12YWxpZGF0b3I=" + }, + "children": [ + { + "object": { + "name": "123", + "description": "First item", + "interface": "item-interface-v1", + "ref": "item:123", + "validator": "aXRlbS12YWxpZGF0b3I=" + }, + "children": [] + } + ] + }, + "truncated": false +} +``` + +`depth`または`limit`によって存在するindexable childを省略した場合、`truncated`を`true`にする。 + +## Interfaceの取得 + +ObjectはOperation定義を直接含まず、Interface Descriptorへの参照を持つ。`fetch_interface`は、その参照に対応するDescriptorを返す。 + +Conceptual requestは次の形になる。 + +```json +{ + "interface": "item-interface-v1" +} +``` + +Responseは次の形になる。 + +```json +{ + "interface": "item-interface-v1", + "descriptor": { + "format": "wip-interface/1", + "documentation": { + "summary": "Operations provided by an item." + }, + "types": [], + "operations": [] + } +} +``` + +Interface DescriptorはJSON-compatibleなlogical structとしてProtocolで定義される。JSONはHTTPS上のencodingであり、Interface実装者が手書きするauthoring形式ではない。 + +ClientはObjectのInterface参照をcacheと比較し、未知のDescriptorだけを`fetch_interface`する。HostはClientのcache状態を推測せず、`fetch`や`fetch_tree`のresponseへDescriptorを先行同梱しない。複数のInterface取得はHTTP batchingでまとめられる。 + +## Operation valueのJSON encoding + +`call_operation`のargumentsとresultは、選択したOperation declarationに従うJSON valueとしてencodeする。 + +`arguments`はOperationのparameter名をfield名とするJSON objectとする。位置引数は用いず、引数を持たないOperationには空のobjectを渡す。 + +Conceptual request bodyは次の形になる。 + +```json +{ + "target": { + "path": "/items/current", + "validator": "b3BhcXVlLXZhbGlkYXRvcg==" + }, "operation": "get_related_item", "arguments": { "relation": "sibling", @@ -52,22 +168,101 @@ WIP over HTTPSでは、`call_operation`のargumentsとresultを、選択したOp } ``` -IDL型からJSONへのmappingはbindingで一意に定める。少なくとも次の規則を持つ。 +ResponseはOperation resultと、実行後の現在状態に対してHostが発行したoptionalなvalidatorを返す。 -- `boolean`、`string`、`number`、record、listは対応するJSON valueで表す。 -- optionalなparameterまたは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として表す。 +```json +{ + "result": { + "item": "/items/123" + }, + "validator": "bmV3LXZhbGlkYXRvcg==" +} +``` -ClientはWIP IDLに従ってvalueをdecodeし、IDL上で`entry`と宣言された位置にある文字列だけをエントリとして認識する。通常の`string`や任意JSON値に含まれるpathらしい文字列を、エントリとして推測してはならない。 +RawなProtocol ValueからJSONへのmappingはbindingで一意に定める。 + +| Protocol value | JSON encoding | +| --- | --- | +| `Unit` | `null` | +| `Boolean` | boolean | +| `Integer` | safe integer範囲のnumber | +| `Number` | finiteなnumber | +| `String` | string | +| `Bytes` | RFC 4648 Section 4のbase64 string | +| `Record` | object | +| `List` | array | + +`Entry`、Enum、Union、`Json`はraw Valueのvariantではなく、Interface Descriptorがprimitiveおよびcompositeへ与える解釈である。 + +| TypeExpr | JSON encoding | +| --- | --- | +| `Entry` | canonical absolute pathのstring | +| Enum | case名のstring | +| Union | `$case`とoptionalな`value`を持つobject | +| `Json` | 任意のJSON value。ただし`Bytes`を含まない | + +Optionalなparameterまたはrecord fieldはfieldの省略で表し、`null`とは区別する。 + +Payloadを持つUnionは次のようにencodeする。 + +```json +{ + "$case": "found", + "value": "/items/123" +} +``` + +Payloadを持たないUnionは`value`を省略する。 + +```json +{ + "$case": "not_found" +} +``` + +ClientはInterface Descriptorに従ってvalueをdecodeし、`entry`と宣言された位置にあるstringだけをエントリとして認識する。通常の`string`やopaqueな`json`に含まれるpathらしいstringをエントリとして推測してはならない。 + +## ValidatorとHTTP conditional request + +WIP Protocolのlogical fieldは、ObjectおよびOperation responseの`validator`と、Operation requestの`target.validator`である。 + +単独のHTTP request / responseで、WIP validatorがHTTPのstrong validator semanticsを満たす場合、HTTPS Bindingは次へ対応付けてよい。 + +```text +Object.validatorまたはCallOperationResponse.validator -> ETag +CallOperationRequest.target.validator -> If-Match +validator_mismatch -> 412 Precondition Failed +validator_required -> 428 Precondition Required +``` + +HTTP headerへmappingした場合も、Client adapterはProtocol上のObjectまたはresponseへvalidatorを復元する。ValidatorがHTTP response representationの変更を反映しない場合、strong ETagとして使用してはならず、body fieldで運ぶ。 + +Batchではsubresponseごとにvalidatorが存在し得るため、各ObjectまたはOperation responseのbody fieldとしてencodeする。 + +## Protocol error + +Protocol failureをJSON response bodyへ含める場合、概念的に次の形を使用する。 + +```json +{ + "error": { + "code": "invalid_arguments", + "message": "Required argument `relation` is missing" + } +} +``` + +`code`はProtocolが定義する安定した識別子、`message`は人間向けのboundedな診断である。Clientは`message`の内容で分岐しない。 + +Protocol error codeとHTTP statusのmapping、認証情報を漏らさないための`not_found`と`permission_denied`の使い分け、validation errorのstructured detailは未確定である。 + +Domain failureをProtocol errorへ変換しない。Domain failureはOperation resultのApplication dataとしてencodeする。 ## HTTP batching -WIP over HTTPSは、複数の独立したCore取得requestを一つのHTTP requestへまとめるbatch形式を提供する。Batchingは通信上のpackagingであり、Core Protocolへ新しい操作や意味論を追加しない。 +WIP over HTTPSは、複数の独立したCore取得requestを一つのHTTP requestへまとめるbatch形式を提供する。Batchingは通信上のpackagingであり、Protocolへ新しいinteractionや意味論を追加しない。 -Clientは、Known SpaceとInterface cacheをもとに必要なrequestだけを選択してbatchを構成する。HostはClientの既知状態を推測して、要求されていないentry公開情報やInterface定義をresponseへ追加しない。 +ClientはKnown SpaceとInterface cacheをもとに必要なrequestだけを選択してbatchを構成する。HostはClientの既知状態を推測して、要求されていないObjectやInterface Descriptorをresponseへ追加しない。 Batch endpointは概念的に`POST {wip-endpoint}/batch`とし、bodyに一意な`id`を持つsubrequestの配列を格納する。 @@ -78,21 +273,14 @@ Batch endpointは概念的に`POST {wip-endpoint}/batch`とし、bodyに一意 "id": "entry-123", "method": "fetch", "arguments": { - "entry": "/items/123" - } - }, - { - "id": "entry-456", - "method": "fetch", - "arguments": { - "entry": "/items/456" + "path": "/items/123" } }, { "id": "item-interface", "method": "fetch_interface", "arguments": { - "interface": "sha256:item-interface" + "interface": "item-interface-v1" } } ] @@ -109,23 +297,20 @@ Hostは各subrequestを、単独で受け取った場合と同じ規則で処理 "result": { "name": "123", "description": "First item", - "interface": "sha256:item-interface" - } - }, - { - "id": "entry-456", - "error": { - "code": "not_found", - "message": "Entry not found" + "interface": "item-interface-v1", + "ref": "item:123", + "validator": "b3BhcXVlLXZhbGlkYXRvcg==" } }, { "id": "item-interface", "result": { - "interface": "sha256:item-interface", - "language": "wip-idl/1", - "digest": "sha256:item-interface", - "source": "..." + "interface": "item-interface-v1", + "descriptor": { + "format": "wip-interface/1", + "types": [], + "operations": [] + } } } ] @@ -140,14 +325,14 @@ Batchには次の規則を適用する。 - Batch全体はtransactionではなく、atomicity、共通snapshot、実行順序を保証しない。 - Hostはsubrequestを直列または並列に実行してよい。 - Subrequest間で、先行requestのresultを後続requestのargumentsとして参照できない。 -- 各`result`は対応するCore操作を単独で呼んだ場合と同じvalueとする。 +- 各`result`は対応するProtocol interactionを単独で呼んだ場合と同じvalueとする。 - 各`error`は通常のProtocol errorと同じschemaを使用する。 - HostはClientが要求していないsubresponseを追加してはならない。 -初期のbatch形式に格納できるのは`fetch`、`fetch_tree`、`fetch_interface`とし、`call_operation`は含めない。将来、WIP IDLのEffect annotationを採用する場合に、副作用を持たないと明示されたOperationをbatch対象へ加えるかを改めて検討する。 +初期のbatch形式に格納できるのは`fetch`、`fetch_tree`、`fetch_interface`とし、`call_operation`は含めない。将来Effect annotationを採用する場合に、副作用を持たないと明示されたOperationをbatch対象へ加えるかを改めて検討する。 Batch件数、request / response byte size、timeoutの上限、およびbatch envelope自体が不正な場合のHTTP statusはbindingの詳細として定める。 ## 非目標 -WIP over HTTPSはHost内部のAPIやデータソース接続方式を規定しない。また、WIP Core ProtocolそのものをHTTP依存のモデルへ変えることも目的としない。 \ No newline at end of file +WIP over HTTPSはHost内部のAPIやdata source接続方式を規定しない。また、WIP ProtocolそのものをHTTP依存のmodelへ変えることも目的としない。