docs: draft object and interface text views

2.2-operation.md

@@ -44,7 +44,7 @@ operation get_related_items(
 };
 ```
 
-Signature ViewはInterfaceの交換形式や入力言語ではなく、検証済みDescriptorから生成する表示である。
+Signature ViewはInterfaceの交換形式や入力言語ではなく、検証済みDescriptorから生成する表示である。ObjectとInterfaceをAIおよび人間向けのplain textへ投影する表示サブ仕様案は、[WIP Text View（草案）](draft/text-view.md)で扱う。
 
 Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter listとして表し、`call_operation`には空のrecordを渡す。
 

4.1-ai-tools-example.md

@@ -31,6 +31,8 @@ Operationの関数宣言と短いdocumentationは、Objectが参照する各[Int
 
 Clientは検証済みDescriptorからIDL風のSignature Viewを生成し、人間と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の交換形式を定義するものではない。
+
 ## `invoke`
 
 `invoke(target, interface, operation, arguments)` は、`inspect`によって発見したInterfaceとOperationの組を実行する。`arguments`はOperationのparameter declarationに従う名前付きfieldのrecordであり、位置引数は用いない。引数を持たないOperationには空のrecordを渡す。Clientはargumentsを検証し、対象path、観測したObjectのoptionalなvalidator、選択したInterface参照とvalidatorから`call_operation` requestを構築する。

draft/text-view.md

@@ -0,0 +1,218 @@
+# 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ではない。
+
+表示は観測時点の公開情報であり、最新状態、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";
+  /// "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`の後に`/// "..."`で表示する。これはObject全体の説明である。
+- `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名へ連結したりしない。単独のOperation抜粋でもInterface blockを残す。
+
+### 型の表記
+
+| 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`、`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 descriptionも同じ表記を使用するが、DescriptorのDocumentationへ変換するわけではない。
+
+通常表示では`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等を選ぶ。
+
+## 表示範囲と省略
+
+基本表示はObjectの概要と、展開対象に選ばれた各Interfaceの全type / Operationおよびsummaryで構成する。Details、`ref`、validator、childrenを通常表示しないことは、このViewの範囲定義であって、欠損したProtocol responseを意味しない。
+
+Interface参照の一覧とDescriptorの展開は別である。Descriptorを展開していないInterfaceはObjectの一覧から消さず、blockの代わりに次のrenderer注記を置く。
+
+```text
+// view: interface "issue.lifecycle" not expanded
+```
+
+これは未取得、未対応format、取得失敗、表示範囲外等を区別するProtocol statusではない。いずれの場合も、空のInterface blockとして表示して「Operationがない」と見せてはならない。検証に失敗したDescriptorから宣言を生成しない。理由を提示する場合はClientの診断表示として分離する。
+
+Operation選択や表示budgetによって宣言を省略したInterface blockの先頭には`// view: partial`を置く。表示するOperationから参照するNamed typeは推移的に含める。型依存も含めて収まらない場合は、そのOperation全体を省略するか、Interfaceを展開しない。
+
+```text
+interface "issue.read" {
+  // view: partial
+  operation read_body() -> { body: string };
+}
+```
+
+Field、parameter、caseを黙って削ったり、型を`...`へ置き換えて完全なsignatureのように見せたりしない。説明を短縮する場合は、対象の説明行の直後に`// view: documentation shortened`を置く。出力上限でblockやescapeの途中を切らず、必要ならView全体を出さずにClientの診断を返す。
+
+`// view:`はrendererが生成する表示上の注記であり、Hostのdocumentationとは区別する。取得済みの公開情報についての省略だけを示し、非公開Object、Interface、Operationの存在や件数を推測して示さない。
+
+## 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,7 @@
 - Interface参照をcontent-addressedにし、Descriptor digestをProtocolへ導入するか。
 - Descriptor version間の互換性規則。
 - 現在plain textであるDocumentationへmarkup、localization、構造化exampleを追加するか。
-- Signature Viewのfull renderingをどこまで標準化するか。
+- Object / InterfaceのAI・人間向けplain text表示。[WIP Text View（草案）](text-view.md)をたたき台に、表示サブ仕様としての表記と省略規則を詰める。
 - 現在Unionで表すDomain failureへ専用declarationを追加するか。
 
 ## 3. Protocol