239 lines
15 KiB
Markdown
239 lines
15 KiB
Markdown
# 4.2. Text View
|
||
|
||
## 位置付け
|
||
|
||
Objectの公開情報と、Interfaceの型・Operation・documentationは、Clientが取得・検証したデータである。それをAIや人間へプレーンテキストで示す形式が、WIP Text Viewである。Tool結果、CLI、GUIのテキスト表示などで共通に使える。
|
||
|
||
一つのObjectの公開情報を表すまとまりをObject signature、一つのInterfaceの型・Operation・documentationを表すまとまりをInterface signatureと呼ぶ。Signatureは表示上のまとまりであり、暗号学的な署名やidentityではない。
|
||
|
||
表示対象、配置、順序、両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である。Interface Descriptorは必要ない。PathはObjectのfieldではなく、配置contextとして使う。
|
||
|
||
一方、Interface signatureの入力は、Interface参照と、それに対応する検証済みかつ対応formatのDescriptorである。Objectは必要ない。Interface参照も、Descriptor自身のfieldではない。
|
||
|
||
どちらも観測時点の公開情報を表示するものであり、最新状態、Operationの実行権限、実行成功は保証しない。観測、Descriptor取得、cache、表示対象の選択、rendererの呼び出しAPIや内部structは規定しない。
|
||
|
||
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でのみ使える省略形である。省略はroot scope `/`の指定ではない。Contextがなければ解決できず、rootへのdefault、対象Objectのpathからの推測、祖先の同名Interfaceの探索も行わない。
|
||
|
||
Scopeが確定した後も、membership、祖先制約、authorizationは検証する。
|
||
|
||
短縮表記を入力として受けるかはToolやUIが決める。受ける場合は専用の入力境界で成分を検証し、構造化参照とOperation名へ変換する。Signature全体を再parseして呼出先を決めることとは区別し、`invoke`を単一string引数の操作へ変更しない。
|
||
|
||
### Signature内の参照
|
||
|
||
両signature内のInterface参照は、公開先の絶対scopeを含む完全な短縮表記を生成し、その全体をJSON stringとして引用する。例えば、scope `/github`、name `issue#read`の参照は`"/github::\"issue#read\""`となる。
|
||
|
||
成分ごとの引用と、参照全体をsignature内の文字列として示す外側の引用は、別の層である。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である。Object自身の`ref`とvalidatorもsignatureへ含めず、同一性管理と条件付き実行はClient runtimeが引き受ける。
|
||
|
||
Objectの本文やdomain metadataを推測してpropertyとして追加しない。Childrenも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も元の順序を保つ。これは表示の順序であり、Protocol上の名前解決やvalidationには影響しない。
|
||
|
||
宣言を折りたたんだり抜粋したりせず、budgetによる省略も行わない。型を`...`へ置き換えず、field、parameter、caseを削らない。DescriptorにtypeもOperationもなければ、空のblockを表示する。
|
||
|
||
同名Operationが異なるInterfaceにあっても、それぞれのblock内に表示する。Blockの参照によって出所を示し、Operation名を改名したり、参照をOperation名へ連結したりしない。異なるInterfaceの宣言を、一つのnamespaceへ平坦化しない。
|
||
|
||
### 型の表記
|
||
|
||
| 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`とも区別する。
|
||
|
||
Unionでは、payloadがなければ`empty`、あれば`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は要求しない。一方、文字列・名前の内部にある空白は表示上の余白ではないため、元の値として保持する。
|