#Upgrading

Upgrade the SDK, Module Federation packages, and host compatibility declaration as separate decisions. A dependency install that succeeds does not prove a package can activate on every supported host.

#0.5.3: Host-Managed Local Services

SDK 0.5.3 adds the optional desktop-only sdk.services.v1 API and the local.service manifest contribution. Existing miniapps do not need to change. A package that declares a local service must set compatibility.tapHost to a range that excludes hosts before 2.0.5, lock the complete target runtime, and request local-service.run with an exact service effect.

Production service execution is limited to Official packages and requires device-user approval for every release containing a service. Untrusted packages can exercise the same contract only in an explicitly enabled Live TAP Test Lab session. Mobile and older desktop hosts do not install sdk.services.v1, so feature-detect the capability before use.

The first pinned integration example is Baguette v0.1.85 on Apple Silicon macOS 15 with Xcode and CoreSimulator. It demonstrates package-owned native bytes under host-owned integrity verification, sandboxing, readiness, restart, and process-tree cleanup. It does not activate the Node target or add arbitrary command, environment, port, PID, Stop, or Kill APIs.

#0.3.0: Terminal Sessions

SDK 0.3.0 adds the optional desktop-only sdk.terminal.v1 API. Existing miniapps do not need to change. A miniapp that uses terminal sessions must feature-detect sdk.terminal?.v1, declare one fixed profile and the conversation VFS mount, and request the three persisted actions documented in the terminal API reference.

Capability discovery is authoritative. The initial host reports both workspace-shell and neovim unavailable while their sandbox and runtime prerequisites remain open. Treat an unavailable profile as a supported result. Do not fall back to an ambient shell, a PATH executable, or another profile.

After installing 0.3.0, rebuild every desktop target. The SDK emits the versioned guest runtime that validates terminal messages, applies bounded binary flow control, and closes owner-bound sessions during realm cleanup.

#Review the Public Contract

Read the SDK release notes and compare the API reference with the imports used by your package. Check:

• removed or renamed exports;
• new required fields or stricter validation in config-schema.json;
• changed peer dependency ranges;
• newly optional or newly required host capabilities; and
• target runtime or emitted-manifest changes.

#Upgrade in One Change

Update @theaiplatform/miniapp-sdk and keep all directly installed Module Federation packages on one exact supported version. Update the lockfile in the same change.

Do not widen compatibility.tapSdk or compatibility.tapHost until the new build has passed clean package and host validation.

#Rebuild from Clean Staging Roots

Remove old target staging output and rebuild every declared target. Then assemble a new immutable release and run the portability scan.

Compare the emitted descriptor and Federation manifests with the prior release. Expected changes should be explainable by the SDK or source update.

#Validate an Exact Release

Publish a new immutable Zephyr deployment while the current TAP Marketplace release remains unchanged. Import it as a new exact Marketplace release in a test workspace and verify:

• every target imports successfully;
• required and optional capabilities behave as documented;
• mounted surfaces clean up correctly;
• compatible state survives fresh-realm activation;
• a rollback restores the prior release; and
• a failed candidate does not displace the last known good release.

Publish the already tested immutable release through TAP Marketplace. Do not rebuild it during publication.

#Handle a Breaking Upgrade

For a breaking SDK or host contract:

1. publish a new package release with a narrow compatibility range;
2. migrate persisted data through an explicit versioned path;
3. retain only documented, time-bounded compatibility aliases;
4. test old and new supported host ranges separately; and
5. remove the old path only after supported installations have migrated.

Never use a display-name change to create a second package identity unintentionally.