docs: specify object and interface text signatures

2.2-operation.md

@@ -25,7 +25,7 @@ Interface参照へWorldspaceのpath scopeを導入する変更案は、[Scoped I
 - 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)で扱う。
+Descriptorのlogical structは[3. Protocol](3-protocol.md)で定義する。Code-firstな生成は本章、人間とAIへのInterface signatureは[4.2. Text View](4.2-text-view.md)で扱う。
 
 Clientは取得したDescriptorを構造検証および意味検証してからcacheする。Named typeの参照解決、Operation callのvalidation、表示生成には検証済みのInterfaceだけを使用する。
 
@@ -33,10 +33,10 @@ Clientは取得したDescriptorを構造検証および意味検証してからc
 
 Operationは、名前付きparameter、return type、documentationを持つ。
 
-人間とAIへ提示する場合は、Interface DescriptorからIDL風のSignature Viewを生成できる。
+人間とAIへ提示する場合は、Interface DescriptorからIDL風のInterface signatureを生成できる。以下はOperation部分の表示例である。
 
-```wip
+```text
-/// Returns items related to this Object.
+/// "Returns items related to this Object."
 operation get_related_items(
   relation: Relation,
   limit?: integer,
@@ -46,7 +46,7 @@ operation get_related_items(
 };
 ```
 
-Signature ViewはInterfaceの交換形式や入力言語ではなく、検証済みDescriptorから生成する表示である。ObjectとInterfaceをAIおよび人間向けのplain textへ投影する表示サブ仕様案は、[WIP Text View（草案）](draft/text-view.md)で扱う。
+Interface signatureはInterfaceの交換形式や入力言語ではなく、検証済みDescriptorから生成する表示である。Object signatureとInterface signatureの表記は[4.2. Text View](4.2-text-view.md)で定義する。
 
 Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter listとして表し、`call_operation`には空のrecordを渡す。
 

3-protocol.md

@@ -88,7 +88,7 @@ struct Documentation {
 }
 ```
 
-`summary`は一覧やSignature Viewへ短く表示する説明、`details`は明示的に展開したときに使用する説明である。
+`summary`は一覧やInterface signatureへ短く表示する説明、`details`は明示的に展開したときに使用する説明である。
 
 DocumentationはHostが提供するplain text dataであり、Clientのsystem instructionとして信頼しない。Transport BindingおよびClientはresource limitを適用できる。Markup、localization、構造化exampleは現在のProtocolに含めない。
 
@@ -299,7 +299,7 @@ struct ReturnDeclaration {
 
 一つの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)で扱う。
+Interface Descriptorの生成と意味論は[2.2. Interface / Operation](2.2-operation.md)、人間とAIへのInterface signatureは[4.2. Text View](4.2-text-view.md)で扱う。
 
 ## Value
 

4.1-ai-tools-example.md

@@ -29,9 +29,9 @@ Objectのドメインデータをpropertiesとして直接公開することは
 
 Operationの関数宣言と短いdocumentationは、Objectが参照する各[Interface Descriptor](2.2-operation.md)から取得する。ClientはObjectの立項順でInterfaceを表示し、異なるInterfaceで同じOperation名が存在する場合や出所を明示したい場合は、`<interface-reference>.<operation-name>`の形でqualifyできる。この表記は表示用であり、Protocol callではInterface参照とOperation名を別fieldとして送る。
 
-Clientは検証済みDescriptorからIDL風のSignature Viewを生成し、人間とAIへ提示する。利用するAI providerがTool schemaを要求する場合、Client adapterがDescriptorからJSON Schema等へ変換する。Provider固有schemaをHostがWIP Interfaceとして提供する必要はない。
+Clientは検証済みDescriptorからIDL風のInterface signatureを生成し、人間とAIへ提示する。利用するAI providerがTool schemaを要求する場合、Client adapterがDescriptorからJSON Schema等へ変換する。Provider固有schemaをHostがWIP Interfaceとして提供する必要はない。
 
-Objectの概要とInterfaceのSignature Viewを組み合わせるplain text表示のたたき台は、[WIP Text View（草案）](draft/text-view.md)で扱う。これは`inspect`結果に使える表示形式の一種であり、Tool responseのdata structureやProtocolの交換形式を定義するものではない。
+Object signatureとInterface signatureのplain text表記は、[4.2. Text View](4.2-text-view.md)で定義する。これは`inspect`結果に使える表示形式の一種であり、signatureの組み合わせ、Tool responseのdata structure、Protocolの交換形式を定義するものではない。
 
 ## `invoke`
 

4.2-text-view.md

@@ -0,0 +1,186 @@
+# 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の表示は本章の対象に含めない。
+
+## 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: "";`となる。Interface参照は元の値を引用表示し、略称や別の識別子へ置き換えない。例中の`issue.read`等はopaque参照の例であり、参照の命名規則を定めない。
+
+`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>" { ... }`と表示する。Interface参照は元の値を引用表示する。
+
+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は要求しない。文字列・名前の内部にある空白は元の値として保持する。

draft/ai-tools-interaction.md

@@ -8,14 +8,14 @@
 
 [AI用Toolsの例](../4.1-ai-tools-example.md)にある `discover(scope, query)` に対し、本draftでは `tree(path, depth)` を基本とする。既存章を書き換え済み、またはすべてのWIP Clientへ採用済みという意味ではない。Protocolの `observe` / `fetch_interface` / `call_operation` は変更しない。
 
-関連する責務は[Client](../4-client.md)、表示書式の候補は[WIP Text View](text-view.md)、FSの探索境界は[Filesystem Discovery](filesystem-discovery.md)を参照する。Yoi側の実装追跡はT-713で行う。
+関連する責務は[Client](../4-client.md)、Object signatureとInterface signatureの表示書式は[4.2. Text View](../4.2-text-view.md)、FSの探索境界は[Filesystem Discovery](filesystem-discovery.md)を参照する。Yoi側の実装追跡はT-713で行う。
 
 ## 基本的な利用モデル
 
 | AI向け操作 | AIが行うこと | Clientが引き受けること |
 | --- | --- | --- |
 | `tree(path, depth)` | indexableな対象の配置を見る | 必要なdepthの観測とtree表示 |
-| `inspect(path)` | 対象の説明とできることを知る | Object観測、Interface集合の解決、Signature View生成 |
+| `inspect(path)` | 対象の説明とできることを知る | Object観測、Interface集合の解決、Interface signature生成 |
 | `invoke(target, interface, operation, arguments)` | 選択した操作を名前付き引数で呼ぶ | 引数検証、観測との対応、validator、Protocol requestと結果の処理 |
 
 これらはProtocol interactionとの一対一対応ではない。特に `inspect` の対象はInterface参照ではなく、Objectを指すpathである。必要な `observe` と複数の `fetch_interface` はClient内部で行う。
@@ -48,7 +48,7 @@ Clientは必要に応じて次を行う。
 1. 対象pathのObjectを観測する。対象だけが必要なら `depth = 0` を使用する。
 2. Objectが公開するInterface参照のordered setを取得する。
 3. 必要なDescriptorをcacheから解決し、不足するものを取得・検証する。
-4. Objectの説明と、InterfaceごとのSignature Viewをまとめて提示する。
+4. Objectの説明と、InterfaceごとのInterface signatureをまとめて提示する。
 
 AIに「先にObjectをobserveして、Interface参照を抜き出し、一つずつfetchする」という手順を要求しない。一方で、Objectの本文やドメインmetadataまで暗黙に読み込むわけではない。それらの取得は対象のOperationとして扱う。
 
@@ -59,9 +59,9 @@ AIに「先にObjectをobserveして、Interface参照を抜き出し、一つ
 - Operation名、短い用途説明、名前付き引数、必須性、引数・結果の型。
 - 操作を理解するために必要な名前付き型・複合型の定義。
 
-生のDescriptor JSONを返すだけではなく、検証済みの情報から読みやすいSignature Viewを生成する。同名Operationが複数Interfaceに存在しても、一つへ平坦化したり、出所を失ったりしない。Invokeへ渡すInterface参照とOperation名は区別して保持し、表示textを再parseして呼出先を決めない。
+生のDescriptor JSONを返すだけではなく、検証済みの情報から読みやすいInterface signatureを生成する。同名Operationが複数Interfaceに存在しても、一つへ平坦化したり、出所を失ったりしない。Invokeへ渡すInterface参照とOperation名は区別して保持し、表示textを再parseして呼出先を決めない。
 
-具体的なObject block、Interface block、型、documentation、省略の表記は、既存の[WIP Text View草案](text-view.md)を参照する。本draftはその表示候補を重複定義せず、最終採用も決定しない。未展開や取得失敗を「操作が存在しない」と誤表示しないことは、取得側と表示側の共通条件である。
+具体的なObject signature、Interface signature、型、documentationの表記は、[4.2. Text View](../4.2-text-view.md)を参照する。Text Viewは個々のsignatureの表記を定義し、inspectでの表示対象や配置はAI Tools側で扱う。未展開や取得失敗を「操作が存在しない」と誤表示しないことは、取得側と表示側の共通条件である。
 
 ## invoke: 選んだ操作を実行する
 
@@ -69,7 +69,7 @@ AIに「先にObjectをobserveして、Interface参照を抜き出し、一つ
 
 Interfaceを明示するのは、同じObjectの複数Interfaceに同名Operationがあり得るためである。Interfaceの選択をAIへ示すことと、Descriptorの取得手順をAIに管理させることは別である。
 
-ClientはObjectとDescriptorの観測を保持し、引数を検証し、path、Object validator、Interface参照とvalidatorをProtocol requestへ設定する。AIにvalidatorの取得・コピー・更新をさせない。通常のSignature Viewへ同一性管理やvalidatorを混ぜる必要もない。
+ClientはObjectとDescriptorの観測を保持し、引数を検証し、path、Object validator、Interface参照とvalidatorをProtocol requestへ設定する。AIにvalidatorの取得・コピー・更新をさせない。通常のInterface signatureへ同一性管理やvalidatorを混ぜる必要もない。
 
 Pathを知っていることやInterfaceが表示されたことは、実行権限を意味しない。Hostは呼出時の公開状態、権限、capability、実行条件を引き続き検証する。
 
@@ -109,7 +109,7 @@ Clientが付随的なentry取得を行う場合、その取得失敗と元のOpe
 ## 未決事項と既存文書への反映
 
 - Treeの具体的なtext layout、Tool引数のdefault、Tool response envelope。
-- WIP Text View草案の最終採用と、inspectでの詳細表示・表示範囲の選択方法。
+- Inspectでの詳細表示・表示対象の選択方法とsignatureの配置。
 - 既存の `discover(scope, query)` 例を、汎用Clientの別の投影例として残すか、tree中心の説明へ改訂するか。
 
 取得・表示・cache保持を分離することは決定事項だが、特定の内部class構成、eviction algorithm、prefetch schedulerを採用することは、このdraftの決定に含めない。

draft/interface-scope.md

@@ -135,7 +135,7 @@ Scopeの変換だけでObjectの`ref`やvalidatorの安全性が保証される
 
 Interface cacheはClient-facing Worldspaceの接続先・主体等のcontextで分離した上で、完全なscope付き参照とoptionalなvalidatorに基づいて扱う。異なるWorldspaceに同じ`/github::issue.read`があっても、同一Interfaceとはみなさない。ScopeはグローバルなURL namespaceではない。
 
-[WIP Text View](text-view.md)では公開先の参照をそのまま引用表示する。表示側でscopeを省略したり、Upstreamの参照へ戻したりしない。
+[4.2. Text View](../4.2-text-view.md)では公開先の参照をそのまま引用表示する。表示側でscopeを省略したり、Upstreamの参照へ戻したりしない。
 
 ```text
 object at "/github/my-rep/issues" {
@@ -149,7 +149,7 @@ interface "/github::issue.read" {
 }
 ```
 
-Text Viewがscopeを定義するのではなく、採用後のProtocol参照を表示する。現在のText View草案のopaque参照例は、Protocol側の採用時に更新する。
+Text Viewがscopeを定義するのではなく、採用後のProtocol参照を表示する。現在のText Viewのopaque参照例は、Protocol側の採用時に更新する。
 
 ## 採用前に詰める点
 

draft/text-view.md

@@ -1,194 +0,0 @@
-# WIP Text View（草案）
-
-## 位置付け
-
-WIP Text Viewは、ObjectとInterfaceをAIおよび人間へ提示するための、プレーンテキスト表示フォーマットのサブ仕様案である。Clientの`inspect`結果、CLI、GUIのテキスト表示などで共通に利用できる。Interfaceの型とOperationを示す部分をSignature Viewと呼ぶ。
-
-この文書は標準化のたたき台であり、以下の表記とrendering ruleは採用候補である。Protocolの必須機能や新しいdata structureを追加するものではない。
-
-正本は[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とは独立させる。
-
-旧`draft/wip-idl.md`（削除直前: `7567007^:draft/wip-idl.md`）から、`operation`、`type`、record、list、enum、union、`entry`、documentationの表記を引き継ぐ。IDL sourceを交換する設計、language identifier、source digest、parser用EBNFは引き継がない。旧文書のeffect annotation案も、現行Descriptorに対応する情報がないため表示へ持ち込まない。
-
-## 表示対象と入力
-
-Rendererが利用するのは、Clientが既に保持する次の情報である。Rendererの呼び出しAPIや内部structは規定しない。
-
-- 検証済みObject。
-- Objectを観測したpath（分かる場合）。PathはObjectのfieldではなく配置contextである。
-- ObjectのInterface参照に対応する、検証済みかつ対応formatのInterface Descriptor。
-- Clientが選んだ表示範囲およびdocumentationの展開方針。
-
-Interface単独の表示も可能とする。その場合は、取得時のInterface参照とDescriptorを使用する。Interface参照はDescriptor自身のfieldではない。
-
-Interfaceを展開するか、どのInterfaceを表示するかは呼び出し側が選択する。展開しないInterfaceもObjectの`interfaces`に参照が示されるため、未展開の注記は追加しない。選択したInterfaceは全宣言を表示し、表示側での折りたたみ、抜粋、budgetによる省略は行わない。
-
-表示は観測時点の公開情報であり、最新状態、Operationの実行権限、実行成功を保証しない。再観測やDescriptor取得のタイミングはClient policyのままとし、表示形式から暗黙のnetwork取得を要求しない。
-
-この草案の対象はObjectの概要とInterfaceの宣言である。Object tree全体の描画、Operation arguments / resultのvalue表示、Protocol errorや診断metadataの表示は対象に含めない。
-
-## 全体例
-
-以下は一つのObjectと、そのObjectが公開する二つのInterfaceを展開した表示である。例中のInterface参照はopaque stringの例であり、参照の命名規則を定めない。
-
-```text
-object at "/issues/123" {
-  name: "123";
-  description: "Issue 123の公開操作。本文はOperationで取得する。";
-  interfaces: ["issue.read", "issue.lifecycle"];
-}
-
-/// "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;
-}
-
-/// "Issueのライフサイクルを操作する。"
-interface "issue.lifecycle" {
-  type CloseResult = union {
-    closed,
-    blocked({ dependencies: [entry] }),
-  };
-
-  /// "理由を添えてIssueをクローズする。"
-  operation close(reason: string) -> CloseResult;
-}
-```
-
-ObjectとInterfaceは別blockにする。Object blockはInterface参照を示し、後続のInterface blockはその宣言を展開する。この並置は表示上の合成であり、HostがObjectへDescriptorを同梱する仕様ではない。
-
-## Object View
-
-Objectは`object at "<path>" { ... }`と表示する。Pathが分からない場合は`object { ... }`とし、`name`や`ref`からpathを推測しない。
-
-- `name: "...";`にObjectの`name`をそのまま表示する。自由なtitleへ置き換えない。
-- `description`がある場合は`name`の後に`description: "...";`で表示する。Object全体の説明を通常のpropertyとして示す。
-- `interfaces: ["...", "..."];`に全Interface参照をHostの立項順で表示する。空集合は`interfaces: [];`と明示する。
-- `ref`とvalidatorは通常表示へ含めない。同一性管理と条件付き実行はClient runtimeの責務のままである。
-- Objectの本文やdomain metadataを推測してpropertyとして追加しない。
-
-Rootは`object at "/"`かつ`name: "";`となる。Descriptionがない場合は説明行を省略する。説明の欠落からObjectの用途を補完しない。
-
-ChildrenはこのObject Viewに含めない。表示にchildrenがないことは、未観測、観測済みの空集合、表示対象外を区別する情報にはならない。将来tree表示を追加する場合も、Protocolの未観測と空集合の違いを維持する必要がある。
-
-## Interface / Signature View
-
-Interfaceは`interface "<reference>" { ... }`と表示する。Objectと併記するときは、そのObjectの`interfaces`順で展開する。異なるInterfaceの宣言を一つのnamespaceへ平坦化しない。
-
-Block内では、Descriptorの`types`を宣言順に、続いて`operations`を宣言順に表示する。Record field、parameter、enum / union caseも元の順序を保持する。この順序は表示上の規則であり、Protocol上の名前解決やvalidationを変更しない。
-
-同名Operationが異なるInterfaceにある場合も、それぞれのblock内に表示する。BlockのInterface参照が出所を示すため、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の同名typeと混同しない。
-
-`?`は`required = false`のfieldまたはparameterにだけ付ける。Nullable、default value、一般化したoptional型は意味しない。`unit`とoptionalの違いを維持する。
-
-Payloadのないunion caseは`empty`、payloadがあるcaseは`found(Type)`とする。`empty`と`empty(unit)`を区別する。空record、空enum、空unionが検証済みDescriptorに現れる場合は、それぞれ`{}`、`enum {}`、`union {}`と表示し、caseを補わない。
-
-型の意味、numeric range、validationはProtocolに従い、表示仕様で再定義しない。特に`entry`はWorldspaceのpath型であり、`string`へ置き換えない。Unionのwire discriminatorやbytesのwire encodingはSignature Viewに混ぜない。
-
-### 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規則を使って表示する。これは文字列を安全に区切るための表記の借用であり、View全体を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の文字種制限を追加しない。旧IDLのUpperCamelCase / snake_caseを表示時の強制変換として復活させない。
-
-すべてのHost由来文字列について、改行や制御文字が表示の構造、端末制御列、別の宣言を作らないようescapeする。JSON stringの標準escapeに加えて、DEL、C1制御文字、Unicodeの改行文字（U+2028 / U+2029）と双方向表示制御文字は`\uXXXX`表記にする。改行escapeは表示上のものであり、元の値は変更しない。
-
-## Documentation
-
-Documentationは対象の直前に`/// "<summary>"`を表示する。対象はInterface、type、Operation、parameter、record field、enum / union caseである。Objectの説明はこの表記ではなく、Object Viewの`description` propertyで表示する。
-
-通常表示では`summary`だけを使い、明示的な詳細表示では同じ対象のsummary行に続けて`/// details "<details>"`を追加する。Documentationがない対象へ説明を生成しない。Empty stringとfieldの欠落は区別し、存在する空文字列は`""`として表示する。
-
-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の境界を維持する。Markdown内へ埋め込む場合はadapterが内容に衝突しないcode fence等を選ぶ。
-
-## Layout
-
-Text ViewはUTF-8 plain textとし、ANSI color、Markdown、syntax highlightingがなくても読めるようにする。文書中のcode fenceは説明用であり、Viewそのものの一部ではない。
-
-標準的なlayoutはLF、2 space indent、block間の空行とする。短いrecord、parameter list、enum / unionは1行に置ける。Documentationを持つfieldやcaseは別行に置く。改行幅や空白の違いは意味を持たず、byte単位のcanonical renderingは要求しない。
-
-## 今後詰める点
-
-- 名称をWIP Text Viewとするか、Object View / Signature Viewを別々の表示仕様として公開するか。
-- 名前のquoteとdocumentationの引用表記の読みやすさ。特に旧IDLの非引用`///`表記との使い分け。
-- Object treeやvalue表示を別profileとして追加するか。
-- 共通rendererのgolden exampleと、Unicode・制御文字・同名Operation・大きなDescriptorに対する表示testの整備。

draft/unresolved-issues.md

@@ -11,7 +11,6 @@
 - Interface参照をcontent-addressedにし、Descriptor digestをProtocolへ導入するか。
 - Descriptor version間の互換性規則。
 - 現在plain textであるDocumentationへmarkup、localization、構造化exampleを追加するか。
-- Object / InterfaceのAI・人間向けplain text表示。[WIP Text View（草案）](text-view.md)をたたき台に、表示サブ仕様としての表記を詰める。
 - 現在Unionで表すDomain failureへ専用declarationを追加するか。
 
 ## 3. Protocol