feat: add Astro reference site and organize book contents

contents/2-core-model.md

@@ -0,0 +1,137 @@
+# 2. コアモデル
+
+WIP Core Modelは、ClientがHostの提供するWorldspaceを観測し、Objectを発見し、Interfaceに従って操作するための意味論を定義する。
+
+具体的なrequest / response structは[3. Protocol](3-protocol.md)、Transport Bindingの共通要件は[5. Transport Bindings](5-transports.md)、HTTPとJSONへの対応付けは[5.1. WIP over HTTP](5.1-wip-over-http.md)で定義する。
+
+## 基本構造
+
+Worldspaceは、Clientが探索できる**ObjectのTree**として公開される。
+
+WIPではObjectとエントリを別の構造として定義しない。**ObjectをWorldspaceのTree上の位置として扱うとき、そのObjectをエントリと呼ぶ。**
+
+したがって、ObjectはTree上で親子関係を持ち得るし、途中のNodeもそのまま操作対象になってよい。例えば`articles`は対象の集合を扱う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**は、Worldspace上で観測および操作できる対象のprotocol-level projectionである。
+
+Objectは、探索に必要な公開情報とInterface参照の集合を持つ。Host内部のdomain entityやApplication dataをそのままObjectとして公開する必要はない。Objectの本文、状態、domain metadata等は、現在公開されているいずれかのInterfaceに宣言されたOperationを通して取得または変更する。
+
+**エントリ**は、そのObjectをTree上の位置として見たときの呼び名である。
+
+エントリがObjectへの参照を別途持つ、という二重構造はProtocolの交換形式として前提としない。Clientはcache実装上、Objectをflat storeへnormalizeし、Entry Treeから内部keyで参照してよい。
+
+Tree上の位置はpathで表される。Pathはrootから各Objectの`name`を順に`/`で連結して構成する。Pathは恒久的なIdentityではなく、その時点でのnavigation coordinateである。
+
+同じ親の直下では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定義を直接持たず、0個以上のInterface参照をordered setとして持つ。
+
+各Interfaceは、Objectで利用できるOperation、parameter、return type、documentationを定義する再利用可能なcapability unitである。Interface実装者はRustのtraitやTypeScriptのdefinition API等を使って実装コード上でInterfaceを宣言し、Libraryはその宣言からmachine-readableなInterface Descriptorを生成する。
+
+複数のObjectが同じInterfaceを共有でき、一つのObjectも複数のInterfaceを組み合わせて公開できる。ObjectとInterfaceを分離することで、Operation定義を各Objectへ重複して持たせず、ClientがInterface Descriptorを参照単位でcacheできる。
+
+Interface集合のmembershipはset semanticsを持ち、同じ参照を重複して含めない。列挙順はOperation解決には影響しないが、HostがInterfaceを公開した順序としてUI表示に使用できる。
+
+InterfaceとOperationの意味論は[2.2. Operation and Interface](2.2-operation-and-interface.md)、Descriptorのlogical structは[3. Protocol](3-protocol.md)、AI向け操作は[4.1. AI Tools](4.1-ai-tools.md)、人間とAIへのsignature表記は[4.2. Text View](4.2-text-view.md)で扱う。
+
+## Core interaction
+
+Clientは、次の3操作によってWorldspaceを観測および操作する。
+
+- `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は必要なinteractionを個別に並行実行でき、Transport実装は複数のexchangeを一つのconnection上でmultiplexできる。並行実行やmultiplexingによって新しいCore interaction、request間のdata dependency、共通snapshot、または暗黙の先読みを導入しない。
+
+## `ref`
+
+Objectは、同じ主体に公開された一つのWorldspace内でObjectの同一性を示すために、optionalな`ref`を公開できる。
+
+`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`は完全なidentity systemではなく、Hostが明示した場合だけ複数の観測またはエントリを同一Objectとしてcorrelateするためのmarkerである。
+
+## 観測整合性
+
+エントリ自体をObjectとは別実体として扱う必要はない。ただし、あるpath上のObjectを観測した後、Operationを実行するまでの間に、そのpathが別のObjectを指すことはあり得る。
+
+その場合、Client / Runtimeは、以前のObjectを対象としたOperationを新しいObjectへ黙って適用してはならない。実行前に観測時の対応関係を検証し、変化していればOperationを中止する。この性質を**observation consistency**と呼ぶ。
+
+例えば、AIが`/issues/current`を観測した時点ではIssue Aだったが、`invoke`時にはIssue Bへ差し替わっていた場合、AIはIssue Aへ作用するつもりでIssue Bを操作してしまう可能性がある。
+
+この観測整合性は利用者に追跡させるのではなく、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はvalidatorを対応するProtocol fieldとして保持し、HTTP ETag等のrepresentation metadataで置き換えない。
+
+Validatorが一致しない場合、Hostは`validator_mismatch`を返してOperationを実行しない。同じOperationを再試行するなら、先に新しい観測を取得しなければならない。
+
+## 同一性と観測整合性の分離
+
+WIPでは次の二つを分けて扱う。
+
+- **Object identity (`ref`)** — 一つのClient-facing Worldspace内で、複数の観測またはエントリが同じObjectを表すことを明示するoptionalなmarker。
+- **Observation consistency** — `ref`の有無にかかわらず、観測したpath上のObjectと操作対象のObjectが一致していることを保証する仕組み。
+
+したがって、`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への対応付けはTransport Bindingとして定義する。共通要件は[5. Transport Bindings](5-transports.md)、標準bindingは[5.1. WIP over HTTP](5.1-wip-over-http.md)で扱う。
+
+この分離により、Worldspaceの意味論、Client / Host間のlogical contract、通信方式を独立して進化させる。