アーキテクチャ

概要

User
  |
  v
COS / AI -------------------- Future Windows Apsule Builder
  |                                      |
  | edits the same Apsule Project        |
  +------------------+-------------------+
                     |
                     v
              Apsule Project
          JSON UI + JS + assets
                     |
                     v
                 Conductor
          (orchestration layer)
                     |
                     v
                   Relay
        (auth / transport / sessions)
                     |
                     v
              iPhone Apsule Host
        +---------------------------+
        | Project Manager           |
        | JSON -> SwiftUI Renderer  |
        | JavaScript Runtime        |
        | Reactive State Store      |
        | Host API Bridge           |
        +-------------+-------------+
                      |
          +-----------+-----------+
          | iOS frameworks        |
          | URLSession, MapKit,    |
          | CoreLocation, BLE ...  |
          +-----------------------+

責務

COS / AI

• Apsule Projectのファイルを作成・編集する。
• 任意のSwiftUIを生成するのではなく、文書化されたschemaを利用する。
• プロジェクト生成前に、接続中runtimeが対応する機能を問い合わせてもよい。
• Relay固有のURLやtransportの知識を必要としない。

COSは対応する開発クライアントの1つであり、project formatそのものの一部ではありません。Codex、その他のagent、公式Builder、サードパーティーツール、ファイルを直接編集する人間も同じcontractを対象にできる必要があります。

Conductor

ConductorはCOSに公開されるorchestration boundaryです。Apsule関連操作は、最終的に次のような正規化されたConductor Capabilityとして扱います。

• apsule.device.list
• apsule.project.list
• apsule.project.push
• apsule.project.get
• apsule.project.delete
• apsule.project.run
• apsule.project.stop
• apsule.runtime.status
• apsule.runtime.reload
• apsule.runtime.schema

実装が確定するまでは名前が変更される可能性があります。これらはConductor Capabilityであり、Host APIではありません。

Relay

Relayはtransportに集中させます。

• endpointを認証する。
• 接続中のiPhone Hostを追跡する。
• project file/deltaとcommandを転送する。
• runtime log/error/state inspectionをPC/COS側へ返す。
• WebSocket sessionを維持する。

RelayはApsule UIを解釈したり、JavaScriptを実行したり、アプリ固有のロジックを持ったりしません。

iPhone Host

Hostは次を担当します。

• Apsule Projectを保存する。
• project/runtime互換性を検証する。
• JSON UIをネイティブSwiftUIとして描画する。
• 制御されたruntime内でproject JavaScriptを実行する。
• reactive stateをSwiftUIと同期する。
• 承認されたネイティブ機能をHost APIとして公開する。
• project permissionを強制する。
• project patchを受信し、影響するviewをHot Reloadする。
• logとruntime errorを報告する。
• 設定されたshake gestureで、実行中ApsuleからProject Managerへ戻る。

Host API設計では、安全に実現できる場合は安定した高レベルwrapper + 範囲を限定したraw/provider primitiveを優先します。目的は、サービス側に新しいendpointが増えるたびにApsule本体を再ビルドしなくてもProject JavaScriptから利用できるようにすることです。raw/provider primitiveもApsuleのpermission、credential isolation、destination/method restriction、runtime discoveryの境界を維持しなければならず、Hostのsecurity modelを回避する手段にはしません。新しいentitlement、Info.plist declaration、extension、コンパイル済みnative supportが必要な機能にはHost更新が必要です。

初期段階では、同時にactiveとなるproject runtimeは1つで構いません。停止時には一時的なruntime実行を破棄しますが、project単位の永続データや、すでにschedule済みのlocal notificationのようにOSが明示的に管理している処理は保持します。

Hostは最後に正常インストールできたproject revisionをローカルに保持します。インストール済みprojectの実行が、開発PC、Relay、COS、Apsule運営のcloud serviceに本質的に依存してはいけません。

Development kitとecosystemの境界

Apsuleのdevelopment contractは公式Builderがなくても利用できるようにします。

• Apsule SDK / Spec: schema、project/runtime contract、再利用可能なtooling interface。
• Apsule CLI: 実装に応じたcreate/validate/pack/sync/run系workflow。
• Starter templates: 通常のeditorやagentでも扱える有効なproject。
• Apsule Skill: skill対応agent向けの任意ガイダンス。正しさやsecurityの境界にはしない。
• Apsule Builder: 同じ標準project formatを読み書きする公式visual GUI。

Builder専用project formatやCOS専用metadataは禁止します。信頼できるidentity、revision、permission enforcementはApsuleが管理するtooling/Host境界に置きます。

基本境界

Conductor Capability: apsule.project.push
        |
        v
Relay transport
        |
        v
iPhone Host
        |
        +-- JSON -> native SwiftUI
        |
        +-- JavaScript -> host.bluetooth.scan()
                         ^ Host API

この2つのAPI familyを混同しないでください。