feat: add Astro reference site and organize book contents

contents/2.1-object-tree-schema.md

@@ -0,0 +1,202 @@
+# 2.1. Object tree / Schema
+
+## Objectの公開情報
+
+Objectは、Worldspace上の対象を発見し、理解し、操作するためのprotocol-level projectionである。
+
+Objectは少なくとも次の公開情報を持つ。
+
+- **name** — 親Objectの下でのpath segment。
+- **description** — Objectが何を表すかを説明する情報。
+- **interfaces** — Objectで利用できるOperationを定義するInterface参照のordered set。
+- **ref** — 同じClient-facing Worldspace内で複数の観測またはエントリが同じObjectを表すことを示すoptionalなmarker。
+- **validator** — HostがObjectの現在状態へ付与する任意のopaque value。
+
+`interfaces`のmembershipはset semanticsを持ち、同じInterface参照を重複して含めてはならない。集合は空でもよい。列挙順はOperation解決には影響せず、HostがInterfaceを立項した順序としてUI表示に使用できる。
+
+具体的な型、必須性、resource limitは[3. Protocol](3-protocol.md)で定義する。
+
+Objectの本文、状態、domain metadata等のApplication dataを、共通のproperty bagとしてObjectへ格納しない。それらはInterfaceに宣言されたOperationを通して取得または変更する。
+
+`description`は探索時に対象を理解するための短い公開情報であり、長い本文やdomain entityの完全な表現を格納する場所ではない。
+
+### 同じ`ref`を持つObject
+
+同じClient-facing Worldspace内で同じ`ref`を持つObjectは、一つの共有された現在状態を持つ。同じObjectを異なるpathへ配置したことを理由に、path固有の`name`、`description`、Interface集合を返してはならない。
+
+- 同じ`ref`と同じvalidator valueを持つObjectは、validatorが存在する場合、`name`、`description`、Interface集合を含むObject representationが一致しなければならない。
+- 同じ`ref`と異なるvalidatorを持つObjectは、同一Objectの異なる状態として扱う。
+- Hostは異なるpathから同じ`ref`を観測した場合も、一つの現在状態を一貫して返す。
+- Clientは最後に成功した観測を、その`ref`を持つObjectの現在状態として扱う。
+
+同じObjectを異なる親の下へ配置する場合もObjectの`name`は共通である。Pathは親から各Objectの`name`を辿って構成するため、同じObjectは異なる親を経由して異なるpathに現れ得る。
+
+## Interface参照
+
+Objectは0個以上のInterfaceを参照する。各Interface Descriptorは、Objectに対して実行可能なOperationの一つのcapability namespaceを宣言する。
+
+Operation名は一つのInterface Descriptor内で一意であればよく、異なるInterface間で同じOperation名を使用できる。Operation callはscopeとlocal nameからなるInterface参照を明示するため、Protocol上の解決は曖昧にならない。人間・AI向けのqualified表記は[Text Viewの参照表記](4.2-text-view.md#参照表記)に従う。
+
+Interfaceは次を定義する。
+
+- Operation名
+- Operationの説明
+- Parameter名と型
+- Return type
+- Named typeとdocumentation
+
+Interface実装者は実装コード上でInterfaceを宣言し、Libraryはその宣言からInterface Descriptorを生成する。ClientはObjectの各Interface参照を使ってDescriptorを取得し、検証、cache、表示、Operation callのvalidationに利用する。
+
+同じInterfaceを持つObjectは同じDescriptor参照を共有できる。
+
+## Interface scope
+
+Objectをpath `P`で公開するとき、そのInterface参照のscopeは`P`自身またはその祖先でなければならない。Self-scopeを許可し、rootから`P`までの各pathを含む。Path segmentの完全一致で判定し、単純な文字列prefixで判定しない。本仕様でInterface scopeの「祖先制約」と呼ぶ場合もself-scopeを含む。
+
+例えば`/github/my-rep/issues`は、scope `/`、`/github`、`/github/my-rep`、`/github/my-rep/issues`のInterfaceを公開できる。`/gitlab`、`/github/other-rep`、`/github/my-rep/issues/123`のscopeは使用できない。`/github`は`/github-extra`の祖先ではない。Root Objectはscope `/`のInterfaceを公開できる。
+
+この制約は配置pathに基づき、indexableかどうかには依存しない。非indexableなObjectを直接観測した場合も同じ規則を適用する。Scope Objectを先に観測することも、そのObject自身が同じInterfaceを公開することも要求しない。
+
+Scopeの適合と`Object.interfaces`への明示的なmembershipは別の条件である。祖先scopeのInterfaceを自動継承せず、scopeをauthorizationの証明として扱わない。
+
+ScopeはそのpathにあるObjectに紐づき、Objectとは独立して存続するnamespaceではない。Scope Objectがそのpathから消えれば、そのscopeのInterfaceの公開も終了する。消えたObjectの配下を、親Objectの存在しない孤立したsubtreeとして公開し続けない。別のObjectを同じpathへ公開し直すことはできる。
+
+Scope Objectに`ref`があれば、ClientはそのObjectとの紐付きを確認できる。`ref`はoptionalであり、存在しない場合は同じpathでの差し替えをidentityによって追跡できない。これは許可された公開形態であり、Hostに`ref`の生成を強制したり、Clientが代替identityを推測したりしない。参照の有効期間、呼出時の確認、移動とcacheの扱いは[Operation and Interface](2.2-operation-and-interface.md#scope-objectと有効期間)および[Protocol](3-protocol.md#scope-objectの紐付き)に従う。
+
+## Object / エントリ / path
+
+WIPでは、Objectとエントリを別のdomain entityとして定義しない。ObjectをTree上の位置として扱うとき、そのObjectをエントリと呼ぶ。
+
+### `name`
+
+Objectの`name`は表示用labelではなく、親Objectの下でそのObjectを識別するpath segmentである。
+
+- Root Objectの`name`は空文字列とする。
+- 非root Objectの`name`は空であってはならない。
+- `name`に`/`を含めてはならない。
+- `name`全体が`.`または`..`であってはならない。
+- `name`はUnicode stringとする。
+- Unicode normalizationは行わない。
+- Nameの比較はUnicode code point sequenceの完全一致で行う。
+- 同じ親の直接のchildrenは、互いに異なる`name`を持たなければならない。
+
+`name`を人間向けの自由なtitleとして扱わない。探索時の短い説明には`description`を使い、domain上のtitle等はOperationからApplication dataとして取得する。
+
+### Pathの構成
+
+Rootのpathは`/`とする。非root Objectのpathは、rootからそのObjectまでの各`name`を`/`で連結して構成する。
+
+```text
+root.name = ""
+root.path = "/"
+
+projects.name = "projects"
+projects.path = "/projects"
+
+example.name = "example"
+example.path = "/projects/example"
+```
+
+Pathには空segment、`.`、`..`を含めない。Root以外のpathは末尾に`/`を持たない。Nameに`/`を許可しないため、Core Modelではsegment escapeを定義しない。Transport BindingがPathをURL componentへ格納する場合のURL encodingは、WIP Pathの構成とは別に扱う。
+
+非root pathについては、最後のsegmentと取得したObjectの`name`が一致しなければならない。
+
+```text
+observe("/projects/example", depth = 0)
+  -> ObjectObservation.object.name == "example"
+```
+
+同じObjectが複数のpathへ配置される場合、同じ`ref`と`name`を持ち、異なる親を経由して異なるpathに現れる。Objectをrenameすると、そのObjectを参照するすべての配置とdescendantのpathが変化する。Pathは恒久的なObject identityとして使用しない。
+
+`ref`、path、Interface参照は異なる役割を持つ。
+
+| 値 | 役割 |
+| --- | --- |
+| path / `entry` | RootからObjectの`name`を辿って構成するnavigation coordinate |
+| `ref` | 複数の観測にまたがる任意のObject identity |
+| Interface参照 | Objectで利用可能なcapability definition |
+
+通常のstringを内容だけからpathまたは`ref`と推測しない。Operation value内でWorldspace上の位置を返す場合は、Descriptorで`entry`型として宣言する。
+
+## Tree
+
+Objectは子Objectを持つことができる。
+
+Parent / child関係はWorldspaceにおける**所有または内包**を表す。
+
+- 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を含めず、`observe` responseの`ObjectObservation`としてObjectとoptionalなchildren observationをまとめる。ValidatorはObjectに含まれる。各nodeのpathは、request pathを起点にObjectの`name`を辿って導出する。このwrapperはObjectとは別のdomain entityを導入するものではなく、指定depthまでの観測結果を表すresponse shapeである。
+
+`children` fieldが省略されているnodeではchildrenを観測していない。`children` fieldが存在する場合、そのarrayはその主体へ公開された直接のindexable childrenをすべて含み、空arrayは観測時点でindexable childが存在しなかったことを表す。
+
+## Objectの可視性
+
+Hostは、主体に認識させるObjectだけでClient-facing Worldspaceを構成する。ObjectをWorldspaceへ公開することは、そのpathとObjectの公開情報を主体が認識できることを意味する。
+
+主体に認識させないObjectは、そのWorldspaceに存在しないものとして扱う。
+
+- `observe`では、そのObjectと、そのObjectだけを経由して到達するsubtreeをresponseから省略する。
+- 省略されたObjectやchild数を示すredaction markerは返さない。
+- 非公開pathを起点とする`observe`には、Host内部での存在理由にかかわらず`NotFound`を返す。Object観測に対する`PermissionDenied`は使用しない。
+
+Objectを公開しながら、特定Interfaceを集合から除外すること、公開したInterfaceから一部のOperationを除外すること、公開されたOperationの実行を認可時に拒否することはできる。Operationの可視性と`PermissionDenied`の使い分けは[2.2. Operation and Interface](2.2-operation-and-interface.md)で定義する。
+
+Objectの`description`には、その主体へ公開できる説明だけを含める。安全な説明を公開できない場合はoptionalな`description`を省略できるが、Protocolはfield-level redaction markerを定義しない。Objectの本文やdomain dataの部分的な開示は、各Operationのresult schemaとdomain semanticsで表現する。
+
+## `observe`
+
+`observe(path, depth)`は、指定pathのObjectと、そのObjectからindexable child edgeを指定depthまで辿った範囲を一つの観測として取得する。
+
+```text
+observe(path, depth) -> ObjectObservation
+```
+
+起点Objectをdepth `0`とする。`depth = 0`では起点Objectだけを返し、そのnodeの`children` fieldを省略する。成功responseはrequested depthまでの公開されたindexable childrenを完全に含み、requested depthより深いObjectを含めない。
+
+- Nodeのdepthがrequestの`depth`より小さい場合、`children` fieldを必ず含める。
+- 観測した直接のindexable childが存在しない場合、`children`は空arrayとする。
+- Nodeのdepthがrequestの`depth`と等しい場合、`children` fieldを省略する。省略はemptyを意味しない。
+- 同じparent nodeのchildrenは、互いに異なる`name`を持つ。
+- Clientはrequest pathとchildrenの`name`から各nodeのpathを導出する。
+
+各ObjectはHostが発行したvalidatorを持ち得るため、Clientは導出したpathとvalidatorから条件付きOperationのtargetを構築できる。Responseを部分的な成功として返す`limit`や`truncated`は定義しない。Requested depthまでの完全な観測をresource budget内で構築できない場合、Hostはsuccess responseの代わりに`ResourceLimitExceeded`を返す。
+
+## Indexable children
+
+Tree上のchildrenとして自然に列挙できるのは、**indexableなObject**だけである。
+
+- 件数がboundedまたは現実的な範囲で列挙できる。
+- 比較的安価に取得できる。
+- 所有または内包関係として自然に理解できる。
+
+全件列挙が高コストまたは不自然な集合は、Treeへ直接展開しない。対象の集合を扱うObjectのOperationを使って検索、filter、paginationを行い、resultとして関連する`entry`を返す。
+
+例えば、大規模なIssue collectionは次のように公開できる。参照はscope `/`を含む短縮表記で示す。
+
+```text
+/issues
+  interfaces: ["/::IssueCollection"]
+  operation: /::IssueCollection#query(filter, cursor, limit) -> IssueQueryResult
+```
+
+```text
+IssueQueryResult.items: [entry]
+```
+
+## 複数の取得
+
+複数のObjectやInterface Descriptorが必要な場合も、各`observe`と`fetch_interface`は独立したCore interactionである。Clientは必要なrequestを個別に並行実行でき、Transport実装はconnection reuseやmultiplexingを利用できる。
+
+WIPは複数のinteractionを包む共通request envelope、自動的な全量取得、暗黙の再帰展開、Clientが要求していない先読みを定義しない。