wip-reference/contents/2-core-model.md

2. コアモデル

Clientは、Hostが提供するWorldspaceからObjectを発見し、Interfaceに従って操作する。WIP Core Modelは、その観測と操作の意味論を定義する。

具体的なrequest / response structは3. Protocol、Transport Bindingの共通要件は5. Transport Bindings、HTTPとJSONへの対応付けは5.1. WIP over HTTPで定義する。

基本構造

Worldspaceは、Clientが探索できるObjectのTreeである。Treeの途中にあるNodeも操作対象になってよい。例えば、articlesというObjectに集合を扱うquery等のOperationをInterfaceとして公開し、その配下へ個別Articleを配置できる。

ObjectをTree上の位置として扱うとき、そのObjectをエントリと呼ぶ。Objectとエントリを別の構造として定義するわけではない。

ClientとHost

Worldspaceを提供するのがHostであり、それをユーザーまたはAIへ提示するのがClientである。

Client

ClientはHostから取得したObjectとInterface Descriptorをcacheする。その観測を使って、refによるObject同一性の追跡、観測時と操作時の対応関係の検証、GUI、AI用Tools、PTC / REPL向けAPI等への投影を行う。

Host

Hostは、Clientに対して一つのWorldspaceを提供する。どのObject、エントリ、Interface、可視性を公開するかを決め、そのClientから見えるWorldspaceを構成する。

内部でGitHub API、Database、Filesystem、RAG、他Agent、別protocol等をどう接続、集約、永続化するかは、WIPの規定対象外である。ClientとHostの境界は通信境界であると同時に、ある主体へどのWorldspaceを公開するかを決めるtrust boundaryでもある。

Object / エントリ

Objectは、Worldspace上で観測・操作できる対象をProtocolとして表現したものである。探索に必要な公開情報とInterface参照の集合を持つが、Host内部のdomain entityやApplication dataをそのまま公開する必要はない。本文、状態、domain metadata等は、現在公開しているInterfaceのOperationを通して取得・変更する。

そのObjectをTree上の位置として見たときの呼び名が、エントリである。Protocolの交換形式に「Objectへの参照を別途持つエントリ」という二重構造を要求しない。ただし、Client内部のcacheでは、Objectをflat storeへnormalizeし、Entry Treeから内部keyで参照してよい。

Tree上の位置を示すpathは、rootから各Objectのnameを順に/で連結して構成する。同じ親の直下ではnameは一意であり、非root Objectのnameは空であってはならない。

同じObjectが複数の位置に現れる場合、そのObjectは同じnameを持ちながら、異なる親を経由する複数のpathで観測され得る。Pathは恒久的なidentityではなく、その時点でのnavigation coordinateである。公開情報、name、path、配置の詳細は2.1. Object tree / Schemaで定義する。

Interface

ObjectはOperation定義を直接持たず、0個以上のInterface参照をordered setとして持つ。Interfaceは、Operation、parameter、return type、documentationをまとめた、再利用可能なcapability unitである。

実装者はRustのtraitやTypeScriptのdefinition API等でInterfaceを宣言し、Libraryがその宣言からmachine-readableなInterface Descriptorを生成する。複数のObjectが同じInterfaceを共有でき、一つのObjectも複数のInterfaceを組み合わせて公開できる。Operation定義を各Objectへ重複して持たせずに済み、ClientもDescriptorを参照単位でcacheできる。

Interface集合のmembershipはset semanticsを持ち、同じ参照を重複して含めない。列挙順はOperation解決には影響しないが、Hostが公開した順序としてUI表示に使える。

InterfaceとOperationの意味論は2.2. Operation and Interface、Descriptorのlogical structは3. Protocol、AI向け操作は4.1. AI Tools、人間とAIへのsignature表記は4.2. Text Viewで定義する。

Core interaction

Worldspaceの観測と操作には、次の3操作を使う。

• observe(path, depth) — 指定pathのObjectと、指定した深さまでのindexableな子Objectを一つの観測として取得する。depth = 0では対象Objectだけを取得する。
• fetch_interface(interface) — Interface参照から現在のInterface Descriptorとoptionalなvalidatorを取得する。
• call_operation(target, interface, operation, arguments) — pathとoptionalなObject validatorを持つtarget、およびObjectが現在公開する一つのInterface observationを指定してOperationを実行する。

各parameterとreturn valueの具体的なstructは、Protocolで定義する。

複数のobserveやfetch_interfaceは、それぞれ独立したCore interactionである。Clientは個別に並行実行でき、Transport実装は複数のexchangeを一つのconnection上でmultiplexできる。ただし、並行実行やmultiplexingによって、新たなCore interaction、request間のdata dependency、共通snapshot、暗黙の先読みを導入しない。

ref

異なるpathで観測したObjectが同じ対象を表す場合、Hostはoptionalなrefでその同一性を示せる。有効範囲は、同じ主体に公開された一つのWorldspace内である。

refはopaque stringであり、Objectのprimary key、永続的なUID、navigation coordinateではない。Backendに適切なUIDがあれば、Hostは直接または変換して使用できるが、WIPはbackend dataから得られるUIDの公開を要求しない。

• 同じWorldspace内で同じ有効なrefを持つObjectは、同じObjectを表す。
• Hostは同じ有効なrefを異なるObjectへ付与してはならない。
• refが異なる、または片方に存在しない場合、同じObjectかどうかについて保証しない。
• Hostが複数のエントリを同じObjectとしてClientへ認識させる場合、同じrefを使用する。
• refの比較は、一つの主体に公開された同じWorldspace内でのみ意味を持つ。
• 異なるWorldspace間で同じ文字列のrefが同じObjectを表すとはみなさない。
• Session、再接続、Host restart、Worldspace再構築をまたぐ永続性を要求しない。
• refからObjectを取得するinteractionは提供しない。Objectの取得にはpathを使用する。

つまり、refによって複数の観測やエントリを同一Objectとして対応付けられるのは、Hostがその同一性を明示した場合だけである。完全なidentity systemではない。

観測整合性

AIが/issues/currentを観測したときにはIssue Aだったのに、invoke時にはIssue Bへ差し替わっていることがある。そのまま実行すれば、Issue Aを操作するつもりでIssue Bへ作用してしまう可能性がある。

Client / Runtimeは、以前のObjectを対象としたOperationを、新しいObjectへ黙って適用してはならない。実行前に観測時の対応関係を検証し、変化していれば中止する。この性質をobservation consistencyと呼ぶ。エントリをObjectとは別実体にする必要はないが、観測から実行までの変化は扱う必要がある。

観測整合性の管理は利用者ではなくClientの責務である。

1. Clientがpath上のObjectを観測する。
2. Objectがvalidatorを持つ場合、ClientはObjectとrequest pathを対応付けて保持する。
3. ユーザーまたはAIが観測したObjectについて判断する。
4. 同じObjectへ条件付きで操作する場合、ClientはpathとObjectのvalidatorをtargetとしてHostへ渡す。
5. Hostは現在のvalidatorとの一致確認とOperation実行をatomicに行う。

ValidatorはClientとHostの間で扱い、AIやユーザーに直接管理させない。Transport Bindingも対応するProtocol fieldとして保持し、HTTP ETag等のrepresentation metadataで置き換えない。

Validatorが一致しなければ、Hostはvalidator_mismatchを返し、Operationを実行しない。同じOperationを再試行するには、先に新しい観測を取得しなければならない。

同一性と観測整合性の分離

refは、複数の観測またはエントリが同じObjectを表すことを明示するmarkerである。一方、validatorは、条件付きOperationにおいてHostが定める現在状態との一致を検証するための値である。

この二つを区別することで、refのないObjectも安全な操作対象になり得る。Object identityの公開はoptionalであり、観測したpath上のObjectと操作対象のObjectの一致を保証するobservation consistencyは、refの有無とは別に扱う。

Application data

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状態を追跡・更新することは要求しない。

WIPは任意状態を同期するdata store protocolではないため、Object propertyのreplication、change feed、reactive subscription、分散transaction、domain event deliveryもCore Modelの規定対象外とする。この責務の分担は、Object、Interface、Operationに共通する。

Transportとの分離

Core ModelとProtocol structは、HTTP、TCP、WebSocket等の特定transportを要求しない。通信方式、concrete encoding、endpointへの対応付けはTransport Bindingとして定義する。

共通要件は5. Transport Bindings、標準bindingは5.1. WIP over HTTPに定める。Worldspaceの意味論、Client / Host間のlogical contract、通信方式を分け、それぞれを独立して進化させる。