同期、Hot Reload、外部連携

目標とする開発ループ

User: "Make a BLE scanner"
          |
          v
COS edits Apsule Project
          |
          v
Conductor Apsule capability
          |
          v
Relay
          |
          v
iPhone Host receives delta
          |
          v
JSON view re-render / JS reload
          |
          v
Native SwiftUI on device

通常のiteration loopではIPA生成を必要としません。IPA/build/sign/installは、Host自体を変更する場合、まだ存在しないnative Host functionalityを追加する場合、または通常のstandalone iOS appを作る場合に限定します。

Transport

推奨architecture:

• RelayとiPhone Host間のpersistent WebSocket connection。
• 初回install/recovery用のproject-level full sync。
• 通常編集用のfile-level patch/update。
• run/stop/reloadなどのruntime command。
• console log、JavaScript error、Host API error、runtime inspectionを返すreverse channel。

このarchitectureにApsule cloud/serverは必須ではありません。user自身のPCがdevelopment sourceを保持し、Relay経由でiPhoneへ接続できます。PCがdevelopment source of truthで、iPhoneは最後に正常installされた完全なprojectをローカルに保持します。そのproject自身がoffline execution可能なら、PC/Relayなしでも実行できます。

logical messageの例（wire formatは未確定）:

project.install
project.patch
project.delete
runtime.run
runtime.stop
runtime.reload
runtime.inspect
runtime.log
runtime.error

実行可能なRelay sliceはauthenticated WebSocket path /api/v1/apsule/socketを使います。Hostはdevice.helloとruntime discoveryで自身を識別します。PC-to-device commandは、完全なpack済みproject.install、file-level project.patch、project list/get/delete、runtime run/stop/status/reload/schema operationに対応します。commandはrequestIdを持て、Hostは対応するcommand.resultを返します。これによりConductorはtransport acceptanceだけでなく実際のread/write resultを公開できます。Patch fileはBase64 payload（deleteの場合はnull）で、base revision guardを含められ、atomic replacement前にstage/validateされます。

ConductorはAI/COS caller向けのorchestration boundaryです。Apsule adapterは%LOCALAPPDATA%\\Relay\\apsule-control.jsonからloopback-onlyのApsule-control Relay credentialを検出します。このcredentialはconnected-device discoveryとApsule command deliveryに制限されます。apsule.project.pushはHostの現在のfile hash/revisionとlocal projectを比較します。projectが存在しない場合は完全packageとしてinstallし、既存projectの場合は現在のrevisionをpatch baseとしてchanged/deleted fileだけを送ります。

Offline / background delivery

Relayは登録済みApsule deviceとbounded pending-command queueを永続化します。deviceがonlineならConductorは既存request/result WebSocket pathを使い、revision-guarded patchを計算できます。deviceがofflineの場合、apsule.project.pushは検証済み完全project.install packageへfallbackし、device_not_connectedで失敗する代わりにRelayがdurableに保存します。次回Apsuleがforegroundでlaunch/activateされたとき、Hostはpending commandを自動取得し、ProjectStore経由でinstall/patch/deleteをatomicに適用し、acknowledgeし、通常のpermission check後に要求されたprojectを実行します。

RelayにはoptionalなAPNs wake pathもあります。インストール済みHostがPush Notifications entitlement付きでsignされ、RelayにAPNs credentialがある場合、queued commandからsilent background wakeを送ってHostの取得を早められます。APNs deliveryをdurableまたはguaranteedとは扱いません。Relay queueがsource of truthであり、次回foreground activationでは必ずretryします。personal/free sideload signingではAPNs entitlementを利用できないため、durable queue + next-launch sync pathがdefault development behaviorです。

すでに実行中のprojectをpatchまたはexplicit runtime reloadする場合、HostはJavaScript contextを置き換える前にJSON-serializableなstateとglobalをsnapshotします。新project scriptがdefaultをinitializeした後、同じproject IDについて以前の値をoverlayします。native Host API object/subscriptionは保持せず再生成します。通常のmanual/project runは引き続き新しいtransient stateから始まります。

Hot Reload

views/home.jsonを変更した場合:

1. 可能ならPCはchanged fileだけを含むrevisionを送る。
2. Hostはactive projectとは別の場所に完全な変更をstageする。
3. Hostはstaged revisionのschema、compatibility、permission、referenced fileをvalidateする。
4. 変更全体がvalidな場合だけrevisionをatomic commitする。
5. 可能な範囲でRendererは影響するview treeだけを再構築する。
6. SwiftUIがnative diff/renderingを行う。
7. validation/runtime errorをPCへ返す。updateに失敗した場合は以前のknown-good revisionをactiveのまま残す。

JavaScript変更では該当script contextのresetが必要になる場合があります。runtimeはdeterministicに実現できる場合だけstateを保持します。

各revisionはstable revision ID、必要に応じたparent revision、timestamp、content identity/hashを持ちます。submittedByなどのprovenanceは、確立できる場合、authenticated Apsule sync/tooling boundaryで付加します。project生成toolの自己申告によるauthorshipは信頼しません。

ツールに依存しない開発

sync contractはCOSに依存してはいけません。COS、Codex、Apsule Builder、他のIDE、人間のいずれも同じApsule Projectを生成できます。validation、packing、revision creation、submission identityはApsule tooling/protocol boundaryに属し、開発環境が変わってもbehaviorを一貫させます。

Conductor

COSはRelayへ直接ではなくConductorへ接続します。Conductorがadapter/providerを解決し、正規化されたoperationをvalidateします。

暫定Apsule capabilityはarchitecture.mdに記載しています。

将来のWindows Builder

Apsule BuilderはCOS/AIと同じproject fileを編集します。

                 Apsule Project
                 /            \
                /              \
       Visual Builder        COS / AI
                \              /
                 \            /
                    JSON + JS
                       |
                    iPhone

これにより次が可能になります。

• drag/drop mock UI -> JSON。
• userが望むbehaviorを説明する。
• AIがactionをbindしてJavaScriptを生成する。
• AIによるJSON変更がvisual editorへ再表示される。
• offline/mock design用device preview data。
• connected iPhoneへのone-click/live pushで、本物のnative SwiftUI/Liquid Glass renderingを確認する。

Builderのmock rendererがpixel-perfectなLiquid Glass emulationを行う必要はありません。iPhone Hostがauthoritative native previewです。