Releases and Patches Management

The binary lifecycle in TkushPatch is built around two core domain entities:

1. Base Release (Release): The compiled native binary (application binary on Android or App.framework on iOS) shipped to the Google Play Store or Apple App Store. Once registered, a Release is immutable and locked by its baseSha256Hash.
2. OTA Patch (Patch): The compressed binary diff (compressed binary diff, .vmcode file) computed by the server between the Day-1 base Release and the newly compiled Dart binary, signed with digital signature (SHA256withRSA).

---

1. Master Registry (/releases) vs Application View (/apps/[appId]/releases)

The console provides two complementary views:

• Master Registry (/releases, src/app/releases/page.tsx): Cross-application view allowing Release, Security, and SRE teams to oversee all releases and patches across the tenant, register a new base Release (POST /api/admin/v1/releases), or submit a new Patch (POST /api/admin/v1/patches).
• Application View (/apps/[appId]/releases, src/app/apps/[appId]/releases/page.tsx): Application-scoped view featuring multi-ABI consolidation.

Multi-ABI Consolidation

When tk-ota-push release android runs against an Android App Bundle (.aab), the CLI automatically uploads reference binaries for every CPU architecture (aarch64, arm, x86_64). The /apps/[appId]/releases page consolidates these records into a single logical (releaseVersion, platform) row displaying ABI coverage badges (aarch64, armv7, x86_64), Store status, and total attached patches.

---

2. Release Detail View (/apps/[appId]/releases/[version])

Clicking a version in /apps/[appId]/releases opens the version workspace (src/app/apps/[appId]/releases/[version]/layout.tsx), organized into 6 sub-tabs:

Sub-tab	Route	Content and Actions
1. Overview	/apps/[appId]/releases/[version]	Patch timeline (#1, #2...), status (STAGED, APPROVED_AND_SIGNED, ROLLED_BACK), channel, rollout %, country filters, and quick actions
2. Insights	/apps/[appId]/insights	Telemetry scoped to this version: successful installs, failures, and stability rate
3. Size	/apps/[appId]/releases/[version]/size	Size comparison: base binary size vs .vmcode patch diff sizes and bandwidth savings (%)
4. Artifacts	/apps/[appId]/releases/[version]/artifacts	Physical artifacts per ABI (aarch64, arm, x86_64), SHA-256 hashes (base, pubspec.lock, assets, nativeCodeHash), and .symbols downloads
5. Notes	/apps/[appId]/releases/[version]/notes	Release notes / changelog editor persisted per version (localStorage tks_release_notes_<appId>_<version>)
6. Settings	/apps/[appId]/releases/[version]/settings	Store lifecycle status toggle (LIVE_ON_STORE, IN_STORE_REVIEW, DEPRECATED) via PATCH /api/admin/v1/releases/{id}/status

---

3. Operator Actions on Releases and Patches

All critical operations are protected by RoleGuard and recorded in the immutable audit trail:

Patch Operational Statuses

• STAGED: Submitted patch quarantined in review. Inaccessible to end users.
• APPROVED_AND_SIGNED: Peer-reviewed and digitally signed for production rollout.
• ROLLED_BACK: Revoked due to defects. Mobile devices immediately fall back to the safe base release.

Available Actions Reference

Action	Backend Endpoint	Allowed Roles (roles.ts)	Technical Effect
Register Base Release	POST /api/admin/v1/releases	ROLE_ADMIN, ROLE_RELEASE_DEVELOPER	Enforces Anti-Bomb quota (maxReleaseSizeMb), computes SHA-256, stores base binary and .symbols
Submit Patch	POST /api/admin/v1/patches	ROLE_ADMIN, ROLE_RELEASE_DEVELOPER	Computes compressed binary diff diff, checks maxPatchSizeMb, places patch in STAGED (or APPROVED_AND_SIGNED if auto-signed without Four-Eyes)
Approve and Sign	POST /api/admin/v1/patches/{id}/approve	ROLE_ADMIN, ROLE_SECURITY_OFFICER	Enforces Four-Eyes rule, signs the 64-character ASCII targetSha256Hash with digital signature, transitions to APPROVED_AND_SIGNED
Update Rollout %	PATCH /api/admin/v1/patches/{id}/rollout	ROLE_ADMIN, ROLE_SRE_ADMIN	Updates Canary percentage (0% to 100%) and evicts L1/L2 cache
Promote Channel	POST /api/admin/v1/patches/{id}/promote	ROLE_ADMIN, ROLE_SECURITY_OFFICER	Clones an APPROVED_AND_SIGNED patch to a target channel (staging, stable) with zero recompilation
Kill-Switch / Rollback	POST /api/admin/v1/patches/{id}/rollback	ROLE_ADMIN, ROLE_SRE_ADMIN	Sets status to ROLLED_BACK, forces rolloutPercentage = 0, and appends patch number to rolled_back_patch_numbers
Update Release Status	PATCH /api/admin/v1/releases/{id}/status	ROLE_ADMIN, ROLE_RELEASE_DEVELOPER, ROLE_SRE_ADMIN	Switches between LIVE_ON_STORE, IN_STORE_REVIEW (blocks stable patches), and DEPRECATED (eligible for Day-2 purge)
Download .symbols	GET /api/admin/v1/releases/{id}/symbols or /patches/{id}/symbols	ROLE_ADMIN, ROLE_RELEASE_DEVELOPER, ROLE_SRE_ADMIN	Downloads the architecture-specific DWARF .symbols file and logs an audit entry