From caf683aa80019b0f8fb4f937bb0f18d1c0ee7295 Mon Sep 17 00:00:00 2001 From: Hare Date: Wed, 7 Oct 2026 03:45:59 +0900 Subject: [PATCH] docs: specify object and interface text signatures --- 2.2-operation.md | 10 +- 3-protocol.md | 4 +- 4.1-ai-tools-example.md | 4 +- 4.2-text-view.md | 186 ++++++++++++++++++++++++++++++++ draft/ai-tools-interaction.md | 14 +-- draft/interface-scope.md | 4 +- draft/text-view.md | 194 ---------------------------------- draft/unresolved-issues.md | 1 - 8 files changed, 204 insertions(+), 213 deletions(-) create mode 100644 4.2-text-view.md delete mode 100644 draft/text-view.md diff --git a/2.2-operation.md b/2.2-operation.md index 2854dce..c3584ce 100644 --- a/2.2-operation.md +++ b/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 -/// Returns items related to this Object. +```text +/// "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を渡す。 diff --git a/3-protocol.md b/3-protocol.md index 8f7f702..6a65201 100644 --- a/3-protocol.md +++ b/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 diff --git a/4.1-ai-tools-example.md b/4.1-ai-tools-example.md index 764771a..bf03967 100644 --- a/4.1-ai-tools-example.md +++ b/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名が存在する場合や出所を明示したい場合は、`.`の形で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` diff --git a/4.2-text-view.md b/4.2-text-view.md new file mode 100644 index 0000000..6757ee4 --- /dev/null +++ b/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が分からない場合は`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 "" { ... }`と表示する。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がある場合は対象の直前に`/// ""`を表示する。対象はInterface、type、Operation、parameter、record field、enum / union caseである。Objectの説明はこの表記ではなく、Object signatureの`description` propertyで表示する。 + +通常表示では`summary`を使う。表示側がdetailsを含める場合は、同じ対象のsummary行に続けて`/// 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は要求しない。文字列・名前の内部にある空白は元の値として保持する。 diff --git a/draft/ai-tools-interaction.md b/draft/ai-tools-interaction.md index 113ef38..01dd9cf 100644 --- a/draft/ai-tools-interaction.md +++ b/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の決定に含めない。 diff --git a/draft/interface-scope.md b/draft/interface-scope.md index 572db5a..e4cc1bf 100644 --- a/draft/interface-scope.md +++ b/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側の採用時に更新する。 ## 採用前に詰める点 diff --git a/draft/text-view.md b/draft/text-view.md deleted file mode 100644 index 45847cb..0000000 --- a/draft/text-view.md +++ /dev/null @@ -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が分からない場合は`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 "" { ... }`と表示する。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は対象の直前に`/// ""`を表示する。対象はInterface、type、Operation、parameter、record field、enum / union caseである。Objectの説明はこの表記ではなく、Object Viewの`description` propertyで表示する。 - -通常表示では`summary`だけを使い、明示的な詳細表示では同じ対象のsummary行に続けて`/// 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の整備。 diff --git a/draft/unresolved-issues.md b/draft/unresolved-issues.md index 095558c..3459faa 100644 --- a/draft/unresolved-issues.md +++ b/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