Sync, Hot Reload and external integration

Target development loop

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

The normal iteration loop should not require IPA generation. IPA/build/sign/install is reserved for changing the Host itself, adding native Host functionality that is not already present, or producing a conventional standalone iOS app.

Transport

Preferred architecture:

• persistent WebSocket connection between Relay and iPhone Host;
• project-level full sync for initial install/recovery;
• file-level patch/update for normal edits;
• runtime commands such as run/stop/reload;
• reverse channel for console logs, JavaScript errors, Host API errors and runtime inspection.

The architecture does not require an Apsule cloud/server. A user's own PC may host the development source and connect to the iPhone through Relay. The PC is the development source of truth; the iPhone keeps the last successfully installed complete project locally so installed projects can run without the PC/Relay when their own functionality permits offline execution.

Example logical messages (wire format TBD):

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

The executable Relay slice uses the authenticated WebSocket path /api/v1/apsule/socket. A Host identifies itself with device.hello plus runtime discovery. PC-to-device commands support a full packed project.install, file-level project.patch, project list/get/delete, and runtime run/stop/status/reload/schema operations. Commands may carry a requestId; the Host replies with a correlated command.result so Conductor can expose real read/write results rather than only transport acceptance. Patch files are Base64 payloads (or null for deletion), may include a base revision guard, and are staged/validated before atomic replacement.

Conductor is the orchestration boundary for AI/COS callers. Its Apsule adapter discovers a loopback-only, Apsule-control Relay credential from %LOCALAPPDATA%\\Relay\\apsule-control.json. The credential is restricted to connected-device discovery and Apsule command delivery. apsule.project.push compares the Host's current file hashes/revision with the local project: a missing project is installed as a complete package, while an existing project receives only changed/deleted files with the current revision as the patch base.

Offline / background delivery

Relay persists registered Apsule devices and a bounded pending-command queue. When a device is online, Conductor keeps the existing request/result WebSocket path and can compute revision-guarded patches. When the device is offline, apsule.project.push falls back to a complete validated project.install package and Relay stores it durably instead of failing with device_not_connected. On the next Apsule foreground launch/activation, the Host automatically fetches pending commands, applies install/patch/delete operations atomically through ProjectStore, acknowledges them, and runs a requested project after normal permission checks.

Relay also has an optional APNs wake path. If the installed Host is signed with the Push Notifications entitlement and Relay has APNs credentials, a queued command can send a silent background wake so the Host may fetch sooner. APNs delivery is not treated as durable or guaranteed: the Relay queue remains the source of truth and the next foreground activation always retries. Personal/free sideload signing does not provide the APNs entitlement, so the durable queue + next-launch sync path is the default development behavior.

When a patch or explicit runtime reload targets the project that is already running, the Host replaces the JavaScript context but snapshots JSON-serializable state and global values first. After the new project script initializes its defaults, the previous values are overlaid for the same project ID. Native Host API objects/subscriptions are recreated rather than preserved. A normal manual/project run still starts from a fresh transient state.

Hot Reload

For a change to views/home.json:

1. PC sends a revision containing only changed files where possible.
2. Host stages the complete change away from the active project.
3. Host validates schema, compatibility, permissions and referenced files for the staged revision.
4. Host atomically commits the revision only after the whole change validates.
5. Renderer rebuilds only the affected view tree where practical.
6. SwiftUI performs native diff/rendering.
7. Validation/runtime errors are returned to PC; a failed update leaves the previous known-good revision active.

JavaScript changes may require resetting the relevant script context; the runtime should preserve state only when it can do so deterministically.

Each revision has a stable revision ID, parent revision where applicable, timestamp and content identity/hash. Provenance such as submittedBy is attached by the authenticated Apsule sync/tooling boundary when it can be established. Project-generating tools are not trusted to self-report authorship.

Tool-neutral development

The sync contract must not depend on COS. COS, Codex, Apsule Builder, another IDE or a human may all produce the same Apsule Project. Validation, packing, revision creation and submission identity belong to Apsule tooling/protocol boundaries so behavior remains consistent across development environments.

Conductor

COS should talk to Conductor, not directly to Relay. Conductor resolves the adapter/provider and validates normalized operations.

Provisional Apsule capabilities are documented in architecture.md.

Future Windows Builder

Apsule Builder edits the same project files as COS/AI.

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

This enables:

• drag/drop mock UI -> JSON;
• user describes desired behavior;
• AI binds actions and generates JavaScript;
• JSON changes made by AI reappear in the visual editor;
• device preview data for offline/mock design;
• one-click/live push to a connected iPhone for real native SwiftUI/Liquid Glass rendering.

The Builder's mock renderer does not need pixel-perfect Liquid Glass emulation. The iPhone Host remains the authoritative native preview.