docs: define scoped interface and operation shorthand

2026-10-07 04:05:58 +09:00
parent 126e038ee2
commit 1dcc7efdc8
1 changed files with 61 additions and 18 deletions
@@ -13,21 +13,22 @@ Interface参照にWorldspace上のpathをscopeとして持たせ、独立したP

 現行の[3. Protocol](../3-protocol.md)ではInterface参照全体をopaque stringとして扱っている。本案はその一部に構造と意味を与えるものであり、単なる表示上の修飾ではない。Canonical文書へ採用するまでは草案として扱い、未確定の構文や境界条件を末尾にまとめる。

-## Interface参照
+## Interface参照のデータ構造

-表記案は次のとおりとする。
+Interface参照は`scope`とlocal nameを別々に持つ構造化データとする。Operationの指定は、その参照とOperation名を組み合わせる。以下はlogicalな構成の例であり、request全体のwire schemaではない。

 ```text
-<scope-path>::<local-name>
-
-/github::issue.read
-/gitlab::issue.read
-/github/my-rep::issue.admin
-/::common.read
+interface = {
+  scope = "/"
+  name = "issue.read"
+}
+operation = "read"
 ```

- `scope-path`はHostが公開するWorldspace内のcanonical absolute path。
- `local-name`はそのscope内でInterfaceを識別する名前。例の`issue.read`に含まれる`.`はObjectの階層やOperation名との区切りを意味しない。
+`scope`、Interfaceの`name`、`operation`はClient内部でも別々に保持する。後述の短縮表記をProtocol上の正本やcache keyとして扱わない。現行Protocolのopaque stringから、この構造化参照への移行は別途行う。
+
+- `scope`はHostが公開するWorldspace内のcanonical absolute path。
+- `name`はそのscope内でInterfaceを識別するlocal name。例の`issue.read`に含まれる`.`はObjectの階層やOperation名との区切りを意味しない。
 - Interfaceはscopeとlocal nameの組で識別する。同じscope内の異なるInterfaceへ同じlocal nameを割り当てない。
 - 同じlocal nameでもscopeが異なれば別の参照である。Descriptorの内容が似ていても同一性を推測しない。
 - 同じscopeに複数のProviderを登録する場合、そのscope内の名前の衝突はHostが検出・解消する。Scopeを付けるだけで同一scope内の重複が自動的に解消されるわけではない。
@@ -36,7 +37,49 @@ Scopeはbackendのpath、OSのfilesystem root、URL origin、HTTP endpointのpre

 Scope pathの比較にはProtocolのpath規則を用いる。Unicode normalization、case変換、URL decode、文字列prefixだけによる祖先判定は行わない。`/github`は`/github-extra`の祖先ではない。

-`::`による連結は表記案である。現行のpath segmentには`:`を含められるため、区切りの一意性とlocal nameの許可文字は構文確定時に決める。既存のpath規則へ暗黙に禁止文字を追加しない。
+## 人間・AI向けの短縮表記
+
+ScopeとInterfaceの境界には`::`、InterfaceとOperationの境界には`#`を使う。境界ごとに異なる記号を用いることで、scopeまたはOperationを省略した表記も区別できる。
+
+| 対象 | 表記 | 含まれる成分 |
+| --- | --- | --- |
+| 完全なOperation指定 | `/github::issue.read#read` | scope、Interface名、Operation名 |
+| 完全なInterface参照 | `/github::issue.read` | scope、Interface名 |
+| Scope省略のOperation指定 | `issue.read#read` | Interface名、Operation名 |
+| Root scopeのOperation指定 | `/::issue.read#read` | scope `/`、Interface名、Operation名 |
+
+`/github::issue.read#read`は`scope = "/github"`、`name = "issue.read"`、`operation = "read"`に対応する。`#read`はInterface名の一部ではない。短縮表記には呼び出し対象Objectのpath、arguments、validatorは含まれず、これだけでOperation request全体を表すものではない。
+
+### 成分の引用
+
+各成分は次の規則で表示する。
+
+- Scopeはcanonical pathであり、文字列全体が`[A-Za-z0-9_./-]+`に一致する場合は引用せずに表示できる。
+- Interface名とOperation名は、文字列全体が`[A-Za-z0-9_.-]+`に一致する場合は引用せずに表示できる。
+- それ以外は成分全体を二重引用符で囲み、JSON stringのescape規則を使う。単純な成分も引用してよい。
+- `::`と`#`は引用符の外側にある場合だけ境界となる。区切りの前後に空白は出力しない。
+
+この規則は表示のためのものであり、pathや名前の文字種をASCIIへ制限しない。引用を外した元の値には、それぞれのProtocol validationを適用する。Unicode normalization、case変換、percent encodingは行わない。制御文字等の安全な表示には[4.2. Text Viewの文字列規則](../4.2-text-view.md#名前と文字列)を適用する。
+
+```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`は同じ成分を表す。`::`や`#`がpath segmentに含まれていても引用によって区別できるため、既存のpath規則へ禁止文字を追加しない。引用とescapeを考慮して境界を判定し、文字列を単純に`::`や`#`でsplitしてはならない。
+
+### Scope省略と解決context
+
+`issue.read#read`は、scopeが別途明示されたcontextで使う相対的な表記である。Scopeの省略とroot scope `/`の指定は異なる。
+
+- 表示・入力を扱う側が明示的に保持するscope contextがある場合、そのscopeとInterface名を組み合わせる。
+- Contextがなければ完全な参照へ解決できない。Rootへのdefault、対象Objectのpathからの推測、祖先の同名Interfaceの探索は行わない。
+- Contextでscopeが確定しても、対象ObjectのInterface membership、祖先制約、authorizationの検証は省略しない。
+
+短縮表記を入力として受け付けるかはToolやUIが決める。受け付ける場合はその入力境界で成分を取り出して検証し、構造化された参照とOperation名へ変換する。Object / Interface signature等の表示text全体を再parseして呼出先を決めることとは区別する。本案は`invoke`の引数を短縮表記の単一stringへ変更するものではない。

 ## Objectとscopeの関係

@@ -65,12 +108,12 @@ ClientはObjectを観測したpathと、そこに公開された完全なInterfa

 1. `observe`のrequest pathと各Objectの`name`から配置pathを得る。
 2. `Object.interfaces`の各参照についてscopeがその配置pathの祖先であることを検証する。
-3. 条件を満たす参照を、その完全な表記で`fetch_interface`へ渡す。
-4. Operation callでは同じ参照を`InterfaceTarget.reference`へ設定し、Operation名は従来どおり別fieldへ設定する。
+3. 条件を満たす構造化参照を、scopeとlocal nameを保持したまま`fetch_interface`へ渡す。
+4. Operation callでは同じ構造化参照をInterface targetへ設定し、Operation名は従来どおり別fieldへ設定する。現行の`InterfaceTarget.reference`等の具体的な型変更はProtocol採用時に反映する。

 Hostは祖先制約に違反する参照をObjectへ公開してはならない。ClientはそのようなObject responseをProtocol違反として扱い、その参照を対象ObjectのInterfaceとして解決・使用しない。既存の分類に合わせ、Client-localな`InvalidResponse`として拒否する案とする。

-Local nameだけによる検索、近い祖先から順に同名Interfaceを探すlookup、shadowing、scopeを省略した参照の補完は導入しない。`/::issue.read`と`/github::issue.read`の両方が公開されている場合も、完全な参照で明示的に区別する。
+Local nameだけによる検索、近い祖先から順に同名Interfaceを探すlookup、shadowingは導入しない。Scope省略の短縮表記は前節の明示的なcontextで解決してから、この手順へ渡す。`/::issue.read`と`/github::issue.read`の両方が公開されている場合も、完全な構造化参照で明示的に区別する。

 `fetch_interface`は完全な参照を受け取るため、祖先Objectを順に取得する必要はない。現行requestには対象Objectのpathがないので、「どのObjectから利用するか」の祖先検証はObject観測時とOperation call時に行う。Interface単独の取得可否はHostの公開可視性によって決まり、scope外のObjectから使えないこととDescriptor自体を取得できないことは同一視しない。

@@ -82,7 +125,7 @@ Operation名とNamed typeのnamespaceは引き続きInterface Descriptor内に

 Clientが扱う絶対pathは、常に接続先HostのClient-facing Worldspaceのrootに基づく。Upstreamのrootや内部mount構成をClientに追跡・補完させない。

-Upstream Worldspaceのrootを`/github`へ配置する例を示す。
+Upstream Worldspaceのrootを`/github`へ配置する例を示す。表中のInterface参照は構造化されたscopeとlocal nameの短縮表記であり、連結stringをwireへ送る意味ではない。

 | 項目 | Upstreamでの値 | Clientへ公開する値 |
 | --- | --- | --- |
@@ -133,9 +176,9 @@ Scopeの変換だけでObjectの`ref`やvalidatorの安全性が保証される

 ## Cacheと表示

-Interface cacheはClient-facing Worldspaceの接続先・主体等のcontextで分離した上で、完全なscope付き参照とoptionalなvalidatorに基づいて扱う。異なるWorldspaceに同じ`/github::issue.read`があっても、同一Interfaceとはみなさない。ScopeはグローバルなURL namespaceではない。
+Interface cacheはClient-facing Worldspaceの接続先・主体等のcontextで分離した上で、構造化参照の`(scope, name)`とoptionalなvalidatorに基づいて扱う。引用やescapeの違いは別参照を作らない。異なるWorldspaceに同じ`/github::issue.read`があっても、同一Interfaceとはみなさない。ScopeはグローバルなURL namespaceではない。

-[4.2. Text View](../4.2-text-view.md)では公開先の参照をそのまま引用表示する。表示側でscopeを省略したり、Upstreamの参照へ戻したりしない。
+本案を[4.2. Text View](../4.2-text-view.md)へ適用するときは、公開先の構造化参照からscopeを含む短縮表記を生成し、参照の表示位置へ引用表示する。そこでの外側の引用はText Viewの文字列表記であり、短縮表記の成分を引用する規則とは別の層である。表示側でscopeを省略したり、Upstreamの参照へ戻したりしない。

 ```text
 object at "/github/my-rep/issues" {
@@ -154,7 +197,7 @@ Text Viewがscopeを定義するのではなく、採用後のProtocol参照を
 ## 採用前に詰める点

 - **Self-scopeとroot Object**：Object自身のpathをscopeとして許すか。Strict ancestorだけではroot Objectに利用可能なscopeがないため、rootの扱いを含めて決める。
- **参照構文**：path内の`::`と区切りの扱い、local nameの許可文字、canonicalな表記、既存opaque参照からの移行。現行のstring fieldを使う案を基本とし、具体的encodingは未確定とする。
+- **Protocolへの移行**：既存opaque参照から構造化された`scope` / `name`への移行、request / response fieldへの配置、Transport Bindingのencoding。`::` / `#`と成分の引用は短縮表記として定義済みであり、wire上の単一string encodingにはしない。
 - **Scopeの公開単位**：scope登録とそのpathのObjectの公開・削除の関係。祖先Object自身が同じInterfaceを公開することは要求しないが、registryのlifecycleを定める必要がある。
 - **有効期間と移動**：scopeのrename、mountの付け替え、同じpathへの再登録、進行中callおよび古いcacheの扱い。
 - **複数配置と部分合成**：同じObjectを複数scopeへ投影する場合の`ref`、切り出したsubtreeの外にあるscope・`entry`への対応付け。