docs: rewrite reference and clarify interface abstraction

2026-10-15 17:53:48 +09:00
parent 6e9e675c70
commit f6905074b1
20 changed files with 981 additions and 826 deletions
@@ -1,79 +1,12 @@
 # 1. コンセプト

-## 背景
+WIP（Worldspace Interface Protocol）は、人間・AI・システムがアプリケーションを操作するための共通インタフェースを目指す。

-現在のLLMエージェントは、Filesystem、検索、Issue Tracker、データベース、外部API、他のAgentなどを、それぞれ別個のToolとして扱うことが多い。統合先が増えるほど、モデルに提示するTool SchemaとAction Spaceも増えていく。
+同じアプリケーションでも、人間は画面、AIはTool、システムはAPIを通して利用することが多い。接点の違いは必要だが、その下にある操作対象や利用可能な操作まで、利用者の種類ごとに別のモデルとして扱う必要があるのだろうか。

-Unix filesystemは、異なる資源を単一の名前空間へ配置し、少数の操作で探索できる強い抽象化を持つ。一方、file / directoryとread / write中心の操作だけでは、`Issue.close()`、`PullRequest.merge()`、`Agent.ask()`のような意味的操作を自然に表現しにくい。
+WIPでは、対象を発見し、その対象で何ができるかを知り、操作するという共通モデルを定める。人間向けのView、AI向けのTools、プログラム向けのAPIは、そのモデルをそれぞれの用途に合わせて提示する。

-## 中心アイデア
-
-WIPは、任意のデジタル環境を一つの**Worldspace**として公開する。
-
-WorldspaceはObjectのTreeとして構成される。本書では、Tree上に配置され、Pathで到達できるObjectを**エントリ**と呼ぶ。Objectとエントリは別スキーマではない。
-
-Objectは、短いdescription、利用可能なOperation、子Object、必要に応じて`ref`を公開できる。本文やmetadataなどのドメインデータは常時露出せず、Operationを通して取得・操作することを基本とする。
-
-## Tool DiscoveryではなくWorld Discovery
-
-一般的なTool Callingでは、モデルは提示されたTool一覧から操作を選ぶ。
-
-WIPでは、モデルは既知のWorldspaceを辿り、目的に関連する対象を見つけ、公開されたOperationを確認して実行する。Operation Resultの`entry`型から未知のpathを発見し、必要なものを取得してClientのKnown Spaceへ追加できる。
-
-中心となる問題を**Tool SelectionからWorld Explorationへ移す**ことがWIPの狙いである。
-
-## Worldspaceの構造
-
-Pathはidentityではなく、現在のWorldspace上の配置位置である。同一Objectが複数のエントリとして現れてもよい。
-
-親子関係は所有・内包を表す。所有関係にない意味的な関連は、それを表す名前付きOperationから関連エントリのpathを返し、Treeへ無理に押し込まない。
-
-Worldspace全体を事前にmaterializeする必要はない。Hostはlazy / virtualなTreeとして、必要な範囲だけを動的に公開できる。
-
-## 操作中心のモデル
-
-WIPではObjectを受動的なJSON recordとして扱わない。
-
-本文を読む、metadataを取得する、検索する、状態を変更するといった行為はいずれもOperationとして表現する。例えばIssueであれば、`read_body()`、`get_metadata()`、`close(reason)`などを公開できる。
-
-Operationには、名前や型に加えて、用途を判断するための短いdescriptionを持たせる。長文documentationや大量のドメインデータをInterfaceへ埋め込むことは想定しない。
-
-ObjectはOperation定義を直接埋め込まず、実装コード上のInterface Declarationから生成された0個以上のInterface Descriptorを参照する。各Interfaceに宣言された関数の集合が再利用可能なcapability unitとなり、複数のObjectが同じInterfaceを共有できる。Objectは現在公開するInterface集合を持ち、Operation callではそのうち一つを明示してOperationを実行する。
-
-## 発見と既知世界
-
-Clientは、これまでに発見したエントリを既知のWorldspaceとして保持できる。既知のエントリはClient側で自由に辿り、Operation結果から得たエントリを追加して、さらに探索できる。
-
-機械的な広域探索の対象は、Hostがindexableとして公開した範囲に限定できる。これにより、大量の検索結果や動的Objectが自動的に探索indexへ流入することを防ぐ。
-
-## Operation Resultと新規発見
-
-OperationはHost背後の環境を変更し得るが、WIPはその状態遷移や変更差分をClientへ同期するprotocolではない。
-
-Operation Resultは型付きの値であり、Interface Descriptorの`entry`型として、未観測だったエントリのpathを返せる。例えばRAG検索からResult群を発見したり、Agentへの問い合わせからConversationを発見したりできる。
-
-Clientは必要に応じて返されたpathを取得し、変更後の状態を改めて観測する。
-
-## Narrow Waist
-
-WIPの目的は、Filesystem、GitHub、RAG、DBなどを一つの巨大APIへ統合することではない。
-
-任意のデジタル環境を共通のWorldspaceとして投影し、発見・観測・Operation実行という小さなInteraction Modelへ収束させる。Host内部のAPI、DB、RPC、永続化方式は規定せず、TransportもProtocolのlogical data modelから分離する。
-
-## 状態管理の非目標
-
-WIPは、Host上の任意状態をClientへ同期するdata store protocolではない。Object propertyのreplication、change feed、reactive subscription、分散transaction、domain event deliveryはCore Modelの規定対象外とする。
-
-Clientが保持するKnown SpaceとDiscoverable Spaceは、過去の観測から構成されたcacheであり、Host上の現在状態を同期したreplicaではない。HostがClientのcache状態を追跡または更新することを要求しない。Operationのauthorizationと実行条件はHostが実行時に評価する。
-
-## Post-trainingとの仮説
-
-Tool Useが事後学習の対象になるなら、個別Tool名ではなくWorldspace上のinteraction policyを学習できる可能性がある。
-
-1. 既知の世界を探索する。
-2. 対象の意味とOperationを理解する。
-3. 必要ならOperationから未知のエントリを発見する。
-4. Operationを実行する。
-5. 必要ならOperation Resultやentry pathをもとに対象を再観測する。
-
-最も強い仮説は、**未知のToolを使えるモデルではなく、未知のDigital Environmentを探索できるモデルを作れるのではないか**という点にある。
+- [1.1. アプリケーション操作の抽象化](1.1-interaction-abstraction.md)
+- [1.2. 既存の抽象化と、その範囲](1.2-existing-abstractions.md)
+- [1.3. WIPの設計方針](1.3-design-principles.md)
+- [1.4. WIPの概念と適用範囲](1.4-concepts-and-scope.md)