AXP-Resurection/docs/009-sideload-system-updates.md

009 — Sideload system package updates (FR-019)

Owner cadence: refresh bundled system / privileged packages about every 2–3 months without a full ROM reflash. No AXP OTA / external repos.

Status: documented — commands and signing gates below define the intended refresh path. The owner has also verified full-ROM upgrades over existing userdata without a wipe. A real individual-APK refresh drill can wait for the final ROM candidate; packaging of the shipping image MUST preserve update eligibility.

Full ROM updates (new LOS base + rebacon) are a different path: recovery sideload of the project zip. See 009-upstream-rebase-ota.md.

In scope

Component	Intended update path	Signing constraint
microG GmsCore / companions	adb install -r / recovery sideload of upstream APK	PRESIGNED / same signer as shipped
Magisk	Magisk app self-update and/or documented boot re-patch	Manager + boot image must stay matched
Project Phonesky	Sideload project-signed APK	Same project key across releases
Other bundled system apps	Sideload matching-signer APK (or recovery zip if priv-app needs it)	Same identity as image

Out of scope

• Network OTA / AXP update servers
• Full bacon + clean flash for routine APK bumps (still OK for kernel / framework / Magisk boot changes when required)

Checklist before claiming FR-019 done

• Each row above has a concrete command/runbook step
• pm install / PackageManager does not reject for signature mismatch
• Privileged permissions still grant after update (or re-flash privapp XML noted)
• Magisk version after update matches kernel/boot expectation
• Record new versions in docs/009-version-pins.md

Preparation and safety

1. Keep the last known-good full ROM zip and its SHA-256. APK refreshes do not replace a boot/kernel rollback path.
2. Download the new APK from the upstream/project source into a host-only staging directory. Never put it in Git or paste its bytes into evidence.
3. Verify the APK before connecting the phone:

apksigner verify --verbose --print-certs NEW.apk
sha256sum NEW.apk

4. Compare the signer with the installed package. For a system app, first record adb shell pm path PACKAGE and the installed version. Do not use -d for routine refreshes and do not accept a signer mismatch.

microG / GSF Proxy

For a compatible same-signer update on a test device:

adb install -r GmsCore.apk
adb install -r GsfProxy.apk
adb shell pm path com.google.android.gms
adb shell dumpsys package com.google.android.gms | grep -E 'versionName=|versionCode='
adb shell dumpsys package com.google.android.gsf | grep -E 'versionName=|versionCode='

Then run microG Self-Check, open Phonesky, and verify one ordinary app update. If a package is privileged or its signer/permissions change, stop and rebuild the image or provide a recovery package with the matching privapp XML; do not paper over the rejection with a weaker permission policy.

Project Phonesky

Phonesky must remain the project-signed artifact and must retain the same package identity and signer as the image:

adb install -r Phonesky.apk
adb shell pm path com.android.vending
adb shell dumpsys package com.android.vending | grep -E 'versionName=|versionCode='
adb shell monkey -p com.android.vending 1

Verify an ordinary install/update through Phonesky. A signature mismatch, privileged-permission loss, or broken microG path is a failed refresh; restore the previous APK or the known-good ROM rather than accepting the update.

Other bundled system apps

Aurora, Droidify, Fossify Gallery, Jelly and OpenEUICC may be refreshed only with an APK matching the shipped package identity and signing policy:

adb install -r APP.apk
adb shell pm path PACKAGE
adb shell dumpsys package PACKAGE | grep -E 'versionName=|versionCode='

For an app whose update must retain system/privileged permissions, verify its normal function and the relevant permissions after install. If PackageManager places the update under /data/app/, that is expected only when the signer and permission model remain valid; record the path change and any required XML handling in the version pin record.

Magisk

Magisk manager APK updates and boot-preroot updates are separate:

• Manager-only update: use the manager's normal update path, then verify magisk -v, Zygisk/DenyList behavior, and the test package before banking experiments.
• Boot/runtime update: patch and test a new boot image with the matching Magisk version. This is not an APK-only refresh and must use the full build and LAB-only flash procedure; never mix a new Magisk manager with an older preroot boot image casually.

Post-update evidence

Record the following under the relevant host artifact or release note:

adb shell getprop ro.lineage.version
adb shell pm path PACKAGE
adb shell dumpsys package PACKAGE
adb shell logcat -d -t 500 | grep -E 'PackageManager|avc: denied|FATAL EXCEPTION'

Reboot once after privileged/system-package changes and repeat the package path, permissions, microG Self-Check, Phonesky install, and WebView checks. Record versions and SHA-256 values in docs/009-version-pins.md.