Capsule の runtime Interface

このページは、普通の OpenTofu Output と Takos が使う runtime サービスの境界を定義します。URL は既存のリンクのために残していますが、現在のモデルは Takosumi の Interface / InterfaceBinding であり、Output 駆動の runtime projection プロトコルではありません。

1. モデル

Takosumi の OpenTofu Stack flow (Capsule) と、1 つの共有 runtime interaction 層があります。

text

OpenTofu Stack flow (Capsule)
        |
        +---- 公開 Output
                       |
        Takosumi の Interface input 解決
                       |
        Interface + 解決済み revision / provenance
                       |
        InterfaceBinding + permission / delivery
                       |
        Takos または他のプロトコル利用者

OpenTofu Output は root module の戻り値のままです。Interface は service-side の runtime 宣言です。 InterfaceBinding は明示的な runtime 利用者の認可です。どれも他を置き換えるものではありません。

2. 所有権

関心事	所有者
インフラと root Output の形	OpenTofu module と provider
Source / Capsule / Run / StateVersion / Output の記録	Takosumi Stack flow
runtime の宣言と input mapping	Takosumi Interface 設定
runtime 利用者の認可	Takosumi InterfaceBinding
プロトコルの解釈と製品での見せ方	Takos または他の利用者
plan / apply / destroy 用の provider 認証情報	ProviderConnection / CredentialRecipe / ProviderBinding

Takosumi は、HCL や Output 名がどうであっても、そこから runtime の意味を推測しません。Takos は Interface を利用するからといって、OpenTofu の state や provider の認証情報の所有者にはなりません。

3. Interface の宣言

Interface には owner (Workspace または Capsule)、安定した名前、label、generation があります。その spec は意図的に小さく作られています。

フィールド	意味
`type`	利用者が解釈する、開かれたプロトコル/サービスの識別子
`version`	その type の契約バージョン
`document`	その契約が持つ、任意の non-secret な JSON
`inputs`	明示的な公開値への named mapping
`access`	`private` / `workspace` / `public` と、任意の policy / resource URI mapping

Takosumi core は document を中身を解釈せずそのまま保存します。利用者は、自分が対応する exact な type、 version、document のサブセット、解決済みの input、permission を検証する必要があります。これが主な拡張ポイントです。プロトコルを追加しても、新しい OpenTofu Output の慣習や Takosumi 専用のリポジトリファイルは必要ありません。

MCP の例

json

{
  "workspaceId": "ws_1",
  "name": "researchTools",
  "ownerRef": { "kind": "Capsule", "id": "cap_1" },
  "spec": {
    "type": "mcp.server",
    "version": "2025-11-25",
    "document": {
      "transport": "streamable-http",
      "display": { "title": "Research tools" }
    },
    "inputs": {
      "endpoint": {
        "source": "capsule_output",
        "capsuleId": "cap_1",
        "outputName": "mcp_url"
      }
    },
    "access": {
      "visibility": "workspace",
      "resourceUriInput": "endpoint"
    }
  }
}

アプリの module が返す必要があるのは、deploy の事実だけです。

hcl

output "mcp_url" {
  value = "${cloudflare_worker_deployment.app.url}/mcp"
}

Interface の実体と認可は service-side の設定に置かれます。/api/v1/interfaces から直接作ることも、apply 成功後に InstallConfig.interfaceBlueprints から一度生成することもできます。app-owned launcher など plain Capsule の宣言案は、repository manifest v2 の interfaces[] から Takosumi が検証して同じ blueprint へ compile できます。repository manifest は実行権限ではなく、Output 名から Interface を推測する fallback もありません。 Resource-owned Interface や resource_output input は現行契約にはありません。InstallConfig.outputAllowlist は UI や install summary に公開する通常の Output を選ぶ別の設定で、Interface の宣言や lifecycle action の発見には使いません。

4. Input の解決

Interface の input には、次の 2 種類のいずれかの由来があります。

literal: service-side の設定にある non-secret な JSON
capsule_output: Capsule id、通常の root Output 名、任意の RFC 6901 JSON Pointer

resolver は解決した公開値を status.resolvedInputs に書き込み、input ごとの provenance を記録します。 Capsule の provenance には Output の id、digest、名前、pointer、利用可能な Run / StateVersion の id が含まれます。

参照元が存在しない、OpenTofu または明示的な mapping で sensitive とマークされている、pointer が無効、削除済み、その他利用できない場合、解決は安全側に停止します。普通の module に sensitive な state や Output があってもかまいません。それらは単に、この公開 runtime 層の対象外になるだけです。

5. ライフサイクル

Interface の状態は Capsule の apply 状態とは独立しています。

text

Pending -> Resolved
Pending/Resolved -> NotReady または Unknown
delete -> Terminating -> Retired

observedGeneration は、どの宣言の generation が評価されたかを利用者に伝えます。resolvedRevision は実効的な解決済み契約が変わると変化します。利用者は、その同じ revision を観測する binding を使う必要があります。

Output の変更は、その Output を明示的に mapping している Interface だけを再解決の対象にします。Workspace 内のすべての Capsule を plan / apply することはなく、runtime 利用者側の OpenTofu module を stale にもしません。 Interface input の参照元が変わる場合も同じ明示参照のルールに従います。

6. InterfaceBinding

InterfaceBinding は 1 つの対象を認可します。

Principal
ServiceAccount
Capsule

Binding には permission と delivery の記述があります。delivery は none、oauth2、workload_token のような開かれた capability token です。任意の credentialRef は参照であり、認証情報の値そのものではありません。 Binding が使えるのは、Ready であり、かつ Interface の現在の解決済み revision を観測しているときだけです。失効すると Binding は Revoked になります。

core は既定で認証不要の delivery を有効にしています。host が issuer を提供し、Interface の owner が認証情報なしの HTTPS resource の hostname を実際に所有していることを証明できる場合は、Principal oauth2 の delivery にも対応します。literal や Output の URL だけでは所有の証明になりません。workload-token と Secret を使う delivery は、host が明示的な実装を提供するまで NotReady のままです。

7. Takos の利用者 profile

Takos が現在読む 3 つの managed Interface profile の type / version、inputs、permissions、revision checks、URL rules、 display metadata は OpenTofu Output とランタイム Interface に集約しています。このページでは、その Interface を launcher、sidebar、file handler が直接読む projection の境界を説明します。

ランチャーの route、サイドバーの拡張、ファイルハンドラーの route は、認可された Interface を直接読みます。Takos 側の publication cache、読み込み resolver、Output Sync のフォールバックはありません。profile の条件を満たさない version、 delivery、URL、input、binding は安全側に停止して除外されます。

外部の MCP Connections は引き続き別の Takos 機能です。その直接 URL、registry discovery、OAuth token、ユーザーレビュー、tool policy は、OpenTofu Output に偽装されることなく Takos が保存・管理します。

8. 依存関係の境界

次の 2 つの関係は区別します。

text

Capsule Dependency / terraform_remote_state
  = 別の OpenTofu の plan や apply が必要とする値

InterfaceBinding
  = デプロイされた runtime を使う権限

Interface を変えても、インフラの依存関係を意味しません。Capsule Dependency を変えても、runtime へのアクセス権限を与えません。

9. セキュリティ上の不変条件

Interface の document、literal、解決済み input は non-secret です。
OpenTofu または明示的な mapping で sensitive とマークされた Output は Interface の input になれません。名前自体はそれ以外は opaque です。
token、パスワード、署名鍵、provider の認証情報は、Interface、Binding、解決済み input、ログ、audit の payload には入りません。
ProviderConnection は OpenTofu Run の認証であり、runtime Interface の認可ではありません。
discovery は呼び出し権限を意味しません。
未対応のプロトコル version と credential delivery は安全側に停止します。

10. 移行の経緯

pre-v1 の実装は service_exports、service_bindings、app_deployment を runtime の宣言として解釈し、 Workspace 全体の Output Sync の挙動も持っていました。そのプロトコルは廃止済みです。module がこれらの名前を返しても、現在は特別な runtime の意味を持たない普通の opaque な Output として扱われます。

移行では、明示的な service-side Interface を作り、必要な公開 Output 名だけを mapping し、InterfaceBinding を作り、以前公開されていた認証情報を rotate してから、古い宣言用の Output を削除します。廃止されたプロトコルへの runtime のフォールバックはありません。

11. 実装への参照

共有契約: takosumi/contract/interfaces.ts
Resolver とライフサイクル: takosumi/core/domains/interfaces/
HTTP API: takosumi/core/api/interface_routes.ts
Takos の Interface 読み取り: takos/src/worker/application/services/platform/runtime-interface-client.ts
Takos の profile 検証: takos/src/worker/application/services/platform/runtime-interface-profiles.ts
UI 拡張: takos/src/worker/application/services/platform/ui-extensions.ts
MCP tools: takos/src/worker/application/tools/mcp-tools.ts
ランチャー route: takos/src/worker/server/routes/apps/routes.ts
ファイルハンドラー route: takos/src/worker/server/routes/spaces/storage-management.ts

Capsule の runtime Interface ​

1. モデル ​

2. 所有権 ​

3. Interface の宣言 ​

MCP の例 ​

4. Input の解決 ​

5. ライフサイクル ​

6. InterfaceBinding ​

7. Takos の利用者 profile ​

8. 依存関係の境界 ​

9. セキュリティ上の不変条件 ​

10. 移行の経緯 ​

11. 実装への参照 ​

Capsule の runtime Interface

1. モデル

2. 所有権

3. Interface の宣言

MCP の例

4. Input の解決

5. ライフサイクル

6. InterfaceBinding

7. Takos の利用者 profile

8. 依存関係の境界

9. セキュリティ上の不変条件

10. 移行の経緯

11. 実装への参照