feat: add Astro reference site and organize book contents

2026-10-09 23:40:37 +09:00
parent 6086f3c5ef
commit 01c9498e6d
39 changed files with 7772 additions and 0 deletions
@@ -0,0 +1,228 @@
+# 4.2. Text View
+
+## 位置付け
+
+WIP Text Viewは、ObjectとInterfaceをAIおよび人間へ提示するためのプレーンテキスト表示形式である。ClientのTool結果、CLI、GUIのテキスト表示などで共通に利用できる。
+
+この章では、一つのObjectの公開情報を表す **Object signature** と、一つのInterfaceの型・Operation・documentationを表す **Interface signature** の表記を定義する。ここでのsignatureは表示上のまとまりを指し、暗号学的な署名やidentityではない。
+
+どのObjectやInterfaceを表示するか、各signatureをどこにどの順序で並べるか、同時に提示するかは表示側が決める。本章はsignatureを包む共通document構造、ObjectとInterfaceの組み合わせ、Tool response envelopeを定義しない。
+
+データの正本は[3. Protocol](3-protocol.md)のObjectおよびInterface Descriptorであり、Text Viewは検証済みの情報から生成する表示である。
+
+- Interfaceの交換形式、手書きのschema言語、Objectのserializationではない。
+- Parser、round-trip、表示textからのDescriptor復元は要求しない。
+- Operationの実行言語ではない。Clientは保持するInterface参照とOperation名を別々に扱い、表示textを再parseしてProtocol requestを構築しない。
+- Textの一致をObject identity、Descriptorの同一性、validator、digestの代用にしない。
+- HostへText Viewの生成・配信を要求せず、Transport BindingやAI providerのTool schemaとは独立させる。
+
+## 表示の入力と責務
+
+Object signatureは検証済みObjectと、分かる場合はそのObjectを観測したpathから生成する。PathはObjectのfieldではなく配置contextである。Object signatureの生成にInterface Descriptorは必要ない。
+
+Interface signatureは、Interface参照と、それに対応する検証済みかつ対応formatのInterface Descriptorから生成する。Interface参照はDescriptor自身のfieldではない。Interface signatureの生成にObjectは必要ない。
+
+観測、Descriptor取得、cache、表示対象の選択、rendererの呼び出しAPIや内部structは本章で規定しない。表示は観測時点の公開情報であり、最新状態、Operationの実行権限、実行成功を保証しない。
+
+Object tree全体の描画、Operation arguments / resultのvalue表示、Protocol errorや診断metadataの表示は本章の対象に含めない。
+
+## 参照表記
+
+Interface参照のscopeとlocal nameの境界は`::`、InterfaceとOperationの境界は`#`で表す。
+
+| 対象 | 短縮表記 |
+| --- | --- |
+| 完全なOperation指定 | `/github::issue.read#read` |
+| 完全なInterface参照 | `/github::issue.read` |
+| Scope省略のOperation指定 | `issue.read#read` |
+| Root scopeのOperation指定 | `/::issue.read#read` |
+
+`/github::issue.read#read`は`scope = "/github"`、`name = "issue.read"`、`operation = "read"`の組を示す。対象Objectのpath、arguments、validatorを含まず、request全体の代わりにはならない。Protocolでは構造化Interface参照とOperation名を別fieldに保持し、この連結stringをwireやcache keyに使用しない。
+
+### 成分の引用
+
+- Scopeはcanonical absolute pathであり、文字列全体が`[A-Za-z0-9_./-]+`に一致する場合は引用せず表示できる。
+- Interface名とOperation名は、文字列全体が`[A-Za-z0-9_.-]+`に一致する場合は引用せず表示できる。
+- それ以外は成分全体を二重引用符で囲み、JSON stringのescape規則を使用する。単純な成分も引用してよい。
+- `::`と`#`は引用符の外側でだけ境界となる。区切りの前後に空白を出力しない。
+
+```text
+"/github::archive"::issue.read#read
+/github::"issue#read"#read
+/github::issue.read#"read#raw"
+"/開発"::"課題.read"#read
+"/github"::"issue.read"#"read"
+```
+
+最後の例は`/github::issue.read#read`と同じ成分を表す。引用やescapeは元の値を変えず、ProtocolへASCII制限や禁止文字を追加しない。Unicode normalization、case変換、URL encodingをしない。制御文字等には[名前と文字列](#名前と文字列)の安全なescape規則も適用する。境界を読む場合は引用とescapeを考慮し、単純な文字列splitを使用しない。
+
+### Scope省略とcontext
+
+Scopeの相対pathは、Protocol dataにも短縮表記にも認めない。`github::issue.read`や`../github::issue.read`を相対scopeとして解決しない。Scopeを明示するなら、引用の有無にかかわらずcanonical absolute pathを使う。
+
+`issue.read#read`やInterfaceだけの`issue.read`は、scopeが別途明示されたcontextでのみ使える省略形である。Scopeの省略はroot scope `/`の指定とは異なる。Contextがなければ解決できず、rootへのdefault、対象Objectのpathからの推測、祖先の同名Interfaceの探索は行わない。Scopeが確定してもmembership、祖先制約、authorizationは検証する。
+
+短縮表記を入力として受けるかはToolやUIが決める。受ける場合は専用の入力境界で成分を検証し、構造化参照とOperation名へ変換する。Signature全体を再parseして呼出先を決めることとは区別し、`invoke`を単一string引数の操作へ変更しない。
+
+### Signature内の参照
+
+Object signatureとInterface signatureでは、公開先の絶対scopeを含む完全な短縮表記を生成し、その全体をJSON stringとして引用表示する。外側の引用はsignatureの文字列表記であり、成分の引用とは別の層である。例えばscope `/github`、name `issue#read`の参照は`"/github::\"issue#read\""`と表示する。Scopeを省略したり、Upstreamの参照へ戻したりしない。
+
+## Object signature
+
+```text
+object at "/issues/123" {
+  name: "123";
+  description: "Issue 123の公開操作。本文はOperationで取得する。";
+  interfaces: ["/::issue.read", "/::issue.lifecycle"];
+}
+```
+
+Objectは`object at "<path>" { ... }`と表示する。Pathが分からない場合は`object { ... }`とし、`name`や`ref`からpathを推測しない。
+
+Block内は次の順に表示する。
+
+1. `name: "...";`にObjectの`name`をそのまま表示する。自由なtitleへ置き換えない。
+2. `description`がある場合は`description: "...";`で表示する。Object全体の説明を通常のpropertyとして示す。
+3. `interfaces: ["...", "..."];`に全Interface参照をHostの立項順で表示する。空集合は`interfaces: [];`と明示する。
+
+Descriptionがない場合はそのpropertyを省略し、存在する空文字列は`description: "";`と表示する。説明の欠落からObjectの用途を補完しない。
+
+Rootは`object at "/"`かつ`name: "";`となり、scope `/`のInterfaceを公開できる。Interface参照は[参照表記](#参照表記)に従い絶対scopeを含め、別の参照やlocal nameだけへ置き換えない。Scope Objectの`ref`やvalidatorを`@...`として参照へ付け足さず、`scope_ref`はClient runtimeの観測・precondition metadataとして扱う。
+
+`ref`とvalidatorはObject signatureへ含めない。同一性管理と条件付き実行はClient runtimeの責務のままである。Objectの本文やdomain metadataを推測してpropertyとして追加しない。
+
+ChildrenもObject signatureに含めない。表示にchildrenがないことは、未観測または観測済みの空集合を意味しない。
+
+## Interface signature
+
+```text
+/// "Issueの内容と関連項目を読む。"
+interface "/::issue.read" {
+  type Relation = enum { parent, sibling, related };
+
+  type RelatedItems = {
+    /// "同じWorldspace内の関連項目。"
+    items: [entry],
+    next_cursor?: string,
+  };
+
+  /// "本文を取得する。"
+  operation read_body() -> { body: string };
+
+  /// "関係を指定して関連項目を取得する。"
+  operation get_related_items(
+    relation: Relation,
+    limit?: integer,
+  ) -> RelatedItems;
+}
+```
+
+Interfaceは`interface "<reference>" { ... }`と表示する。`<reference>`は構造化参照から生成した完全な短縮表記であり、前述の規則で全体を引用表示する。
+
+Block内では、Descriptorの全`types`を宣言順に、続いて全`operations`を宣言順に表示する。Record field、parameter、enum / union caseもすべて元の順序で表示する。この順序はsignature内部の表示規則であり、Protocol上の名前解決やvalidationを変更しない。
+
+Interface signatureでは宣言の折りたたみや抜粋、budgetによる省略を行わない。型を`...`へ置き換えたり、field、parameter、caseを削ったりしない。DescriptorにtypeもOperationもない場合は空のblockとなる。
+
+異なるInterfaceの宣言を一つのnamespaceへ平坦化しない。同名Operationも各Interfaceのblock内に表示する。Blockの参照が出所を示すため、Operation名を改名したり、参照をOperation名へ連結したりしない。
+
+### 型の表記
+
+| DescriptorのTypeExpr | 表示 |
+| --- | --- |
+| Unit / Boolean / Integer / Number | `unit` / `boolean` / `integer` / `number` |
+| String / Bytes / Json / Entry | `string` / `bytes` / `json` / `entry` |
+| Named | 参照先typeの名前 |
+| Record | `{ field: Type, optional_field?: Type }` |
+| List | `[Type]` |
+| Enum | `enum { first, second }` |
+| Union | `union { empty, found(Type) }` |
+
+Named type declarationは`type Name = Type;`とする。Enum、unionを含むすべてのTypeExprを、Descriptorで現れる位置にそのまま表示する。Named typeは同じInterface Descriptor内の宣言を参照し、別Interfaceの同名typeとは混同しない。
+
+`?`は`required = false`のfieldまたはparameterにだけ付ける。Nullable、default value、一般化したoptional型は意味しない。`unit`とoptionalの違いを維持する。
+
+Payloadのないunion caseは`empty`、payloadがあるcaseは`found(Type)`とする。`empty`と`empty(unit)`を区別する。
+
+```text
+type CloseResult = union {
+  closed,
+  blocked({ dependencies: [entry] }),
+};
+```
+
+空record、空enum、空unionが検証済みDescriptorに現れる場合は、それぞれ`{}`、`enum {}`、`union {}`と表示し、caseを補わない。
+
+型の意味、numeric range、validationはProtocolに従い、表示仕様で再定義しない。特に`entry`はWorldspaceのpath型であり、`string`へ置き換えない。Unionのwire discriminatorやbytesのwire encodingはInterface signatureに混ぜない。
+
+### Operationの表記
+
+```text
+operation get_related_items(
+  relation: Relation,
+  limit?: integer,
+) -> {
+  items: [entry],
+  next_cursor?: string,
+};
+
+operation refresh() -> unit;
+```
+
+Operationは`operation Name(parameters) -> ReturnType;`とする。Parameterは名前付きであり、並び順から位置引数を導入しない。引数がない場合は`()`、return typeは`unit`を含め必ず表示する。
+
+Operation名からread / write、idempotency、retry可否、domain failure、実行可能状態を推測してannotationを付けない。Domain failureがreturn typeのUnionとして宣言されていれば、そのUnionを通常どおり表示する。
+
+## 名前と文字列
+
+Path、Object name、Interface参照、説明文は、二重引用符で囲んだJSON stringのescape規則を使って表示する。これは文字列を安全に区切るための表記の借用であり、signature全体をJSONにするものではない。Unicode normalization、case変換、pathのURL encodingを行わない。
+
+Type名、Operation名、parameter名、field名、case名は次のように表示する。
+
+- `[A-Za-z_][A-Za-z0-9_]*`に一致し、下記の表示keywordでなければ、そのまま表示する。
+- それ以外はbacktickで囲む。内部のbacktickは`` \` ``、backslashは`\\`、改行・tab等はJSON stringと同じescapeで表示する。
+- 表示keywordは`object`、`at`、`name`、`description`、`interfaces`、`interface`、`type`、`operation`、`enum`、`union`、および`unit`、`boolean`、`integer`、`number`、`string`、`bytes`、`json`、`entry`とする。
+
+```text
+interface "/::example" {
+  type `string` = { `表示名`: string };
+  operation `find-item`(`search term`: string) -> `string`;
+}
+```
+
+この規則はProtocolへidentifierの文字種制限を追加しない。UpperCamelCase / snake_case等への変換を表示時に行わない。
+
+すべてのHost由来文字列について、改行や制御文字が表示の構造、端末制御列、別の宣言を作らないようescapeする。JSON stringの標準escapeに加えて、次の文字は`\uXXXX`表記にする。
+
+- DELおよびC1制御文字（U+007F–U+009F）。
+- Unicodeの行・段落区切り（U+2028 / U+2029）。
+- 双方向表示制御文字（U+061C、U+200E–U+200F、U+202A–U+202E、U+2066–U+2069）。
+
+Escapeは表示上のものであり、元の値は変更しない。
+
+## Documentation
+
+Documentationがある場合は対象の直前に`/// "<summary>"`を表示する。対象はInterface、type、Operation、parameter、record field、enum / union caseである。Objectの説明はこの表記ではなく、Object signatureの`description` propertyで表示する。
+
+通常表示では`summary`を使う。表示側がdetailsを含める場合は、同じ対象のsummary行に続けて`/// details "<details>"`を追加する。Summaryと選択されたdetailsは短縮せず表示し、documentationがない対象へ説明を生成しない。存在する空文字列は`""`として表示する。
+
+ReturnDeclarationのdocumentationは、parameter listの閉じ括弧の後、return arrowの直前に置く。
+
+```text
+/// "対象を検索する。"
+/// details "結果には同じWorldspace内のpathだけを含む。\n本文は別途取得する。"
+operation search(
+  /// "検索語。"
+  query: string,
+)
+/// "条件に一致する項目。"
+-> { items: [entry] };
+```
+
+説明はすべてHost由来のplain text dataであり、system instruction、rendererの指示、markupとして解釈しない。引用やescapeだけでprompt injectionを防げるとはみなさず、AIへ渡すadapterもTool結果と信頼済みinstructionの境界を維持する。
+
+## Layout
+
+Text ViewはUTF-8 plain textとし、ANSI color、Markdown、syntax highlightingがなくても読めるようにする。本章のcode fenceは説明用であり、signatureそのものの一部ではない。Markdown内へ埋め込む場合は、表示側が内容に衝突しないcode fence等を選ぶ。
+
+Signature内部の標準的なlayoutはLF、2 space indentとする。短いrecord、parameter list、enum / unionは1行に置ける。Documentationを持つfieldやcaseは別行に置く。表示用の改行幅やindentの違いは意味を持たず、byte単位のcanonical renderingは要求しない。文字列・名前の内部にある空白は元の値として保持する。