Make Android native deploys update-only and target-frozen

AGENTS.md

@@ -123,11 +123,46 @@ A few helpers are public specifically to enable testing (the parsing and
 narrowing functions). Don't make them private:
 
 - `Discovery.Android.parse_devices_output/1`
-- `Discovery.IOS.parse_simctl_json/1`, `parse_simctl_text/1`, `parse_runtime_version/1`
+- `Discovery.IOS.parse_simctl_json/1`, `parse_simctl_text/1`, `parse_runtime_version/1`,
+  `build_simctl_launch_args/2`, `restart_app_physical/3`, and
+  `build_devicectl_launch_args/2`
 - `OtpDownloader.valid_otp_dir?/2`, `ios_device_extras_present?/1`
 - `PythonAppleSupport.valid_dir?/1`
 - `NativeBuild.narrow_platforms_for_device/2`, `ios_toolchain_available?/0`, `read_sdk_dir/1`, `fallback_entitlements_plist/3`
 - `NativeBuild.pythonx_in_project?/1`, `python_apple_support_env/2`
+- `NativeBuild.build_all_with_outcome/1`, `build_outcome/1`, `build_outcome/2`,
+  `ios_phase_decision/3`, `resolve_android_update_targets/2`,
+  `install_android_updates/3`, `install_and_deliver_android/4`, and
+  `install_and_deliver_android_runtime/8`, `release_android_deploy_lock/2`,
+  `interpret_adb_update/2`, `android_otp_dir_from_abi_probe/4`,
+  `android_package_listed?/2`, `deliver_android_otp_release/7`, and
+  `push_otp_runas/6` (typed sequencing and update-only Android safety seams;
+  the deprecated direct mutators intentionally fail closed)
+- `AndroidDeployLock.valid?/2`, `acquire/4`, `verify_owner/3`, `transition/4`,
+  `release/2`, `status/3`, and `cleanup_committed_tombstone/3` (the shared,
+  exact-target Android mutation lease and its bounded recovery surface)
+- `HotPush.prepare/1`, `push_prepared/2`, `push_prepared/3`,
+  `validate_prepared_snapshot/1`, and `push_prepared_fenced/3` (immutable BEAM
+  snapshot and lease-fenced RPC seams; raw Android pushes intentionally reject)
+- `Mix.Tasks.Mob.DeployLock.inspect_or_cleanup/4` (hermetic task decision seam;
+  production still requires an explicit exact `--device`)
+- `Deployer.collect_android_beam_dirs/0`, `prepare_android_payload/2`,
+  `valid_android_payload?/2`, `cleanup_android_payload/1`, and
+  `deploy_all_with_lease/1`, `execute_ios_restart/1`, and
+  `interpret_ios_restart_result/1`, `restart_ios_simulator/4`, and
+  `restart_ios_physical/4` (immutable final-pass payload, shared-lease
+  integration, and authoritative iOS restart seams)
+- `Deployer.select_canonical_android_devices/2`,
+  `classify_android_package_probe/2`, `deploy_android_device/4`,
+  `ensure_erts_on_device/3`, `verify_elixir_runtime_version_android/5`,
+  `setup_exqlite_android_runas/4`, `push_beams_android_runas/3`, and
+  `restart_android/3` (exact-target and per-mutation fencing seams; ordinary
+  `--device` matching remains user-friendly)
+- `Mix.Tasks.Mob.Deploy.run/2`, `resolve_target_platforms!/4`, `execute_native_deploy!/6`,
+  `deploy_after_native_build!/3`, `deploy_after_native_build!/4`,
+  `deploy_after_native_build!/5`, `deploy_after_native_build!/6`,
+  `ensure_deploy_succeeded!/1`, and `report_deploy_result!/2` (typed
+  orchestration/result seams)
 - `NativeBuild.__prune_plugin_artifacts__/2` (the plugin-removal prune; ledger-tracked per merge concern)
 - `Enable.inject_pythonx_dep/1`, `inject_pythonx_uv_init_gate/2`, `python_paths_module_template/1`
 - `Emulators.parse_simctl_json/1`, `find_emulator_binary/1`
@@ -164,9 +199,38 @@ needing the same fan-out behavior. Pin the headline guarantee in
 each task's tests — "personal iPhone + dev emulators + `--all-devices`
 must leave the iPhone alone."
 
-**TODO:** apply this pattern to `mix mob.deploy` (today's `--all-devices`
-deploy can push BEAMs to a personal phone). When that fan-out exists
-or grows, factor `select_devices/3` plus the flag plumbing into a
+Android **native** deploys resolve a non-empty connected serial set (narrowed
+by `--device <id>` when supplied) and run only the data-preserving
+`adb -s <serial> install -r <apk>` update path. They never force-stop first,
+uninstall, or fall back to a clean install. A failed update must prevent the
+final `MobDev.Deployer` pass. Before the first device mutation, freeze and hash
+the APK, OTP archives, BEAM/priv payload, optional exqlite payload, restart
+arguments, and exact canonical serial set. One phase-bound
+`AndroidDeployLock` covers that complete set across native install/OTP work and
+the final BEAM/restart pass. Prove the entire set immediately before every
+mutation, halt later targets on the first failure, and retain the exact lease
+on any ambiguous reply. Only a fully successful final pass may advance to a
+committed phase and release it. Build-only APIs must remain artifact-only and
+must never acquire a device lease or install an APK.
+
+For a mixed native Android+iOS deploy, complete, commit, release, and clean the
+entire Android transaction before beginning the iOS build or install. An exact
+typed `:not_attempted` Android disposition may proceed to iOS; any malformed,
+failed, retained, or ambiguous Android outcome suppresses iOS and fails closed.
+
+Never recover by clearing app data, uninstalling, deleting an active lock, or
+blindly retrying. `mix mob.deploy_lock --device <exact-serial>` is read-only;
+`--cleanup-committed` may remove only one exact record-only tombstone already
+in a committed phase and must prove the final clear state.
+
+Fast Android BEAM deploys use an exact-set shared lease. Distribution is used
+only when every frozen target is already connected; otherwise the entire set
+uses the fenced filesystem/restart path rather than splitting authority.
+
+**TODO:** apply the full physical-device *selection* pattern to the fast
+`mix mob.deploy` BEAM fan-out. Its mutations are now exact-set fenced, but the
+broad selector can still include a personal phone. When that fan-out grows,
+factor `select_devices/3` plus the flag plumbing into a
 shared `MobDev.TaskTargets` (or similar) module so the rules don't
 drift between tasks.
 

README.md

@@ -25,6 +25,7 @@ end
 | `mix mob.install` | First-run setup: download OTP runtime, generate icons, write `mob.exs` |
 | `mix mob.deploy` | Compile and push BEAMs to all connected devices |
 | `mix mob.deploy --native` | Also build and install the native APK/iOS app |
+| `mix mob.deploy_lock --device ID` | Inspect one exact Android deploy lease; optionally clean only a verified committed tombstone |
 | `mix mob.deploy --slim` | Same, but with the App Store strip pass applied (slow, lets you verify a slim build before TestFlight — see [`guides/slim_release.md`](guides/slim_release.md)) |
 | `mix mob.release` | Build a signed `.ipa` / `.aab` for App Store / TestFlight / Play Store (slim by default) |
 | `mix mob.release --security-gate` | Same, but runs `mix mob.security_scan` first and aborts on any critical/high/medium finding ([details](guides/security_scan.md)) |
@@ -89,10 +90,51 @@ Pushing 14 BEAM file(s) to 2 device(s)...
   iPhone 15 Pro   →  pushing... ✓ (dist, no restart)
 ```
 
-If dist is not reachable (first deploy, app not running), it falls back to `adb push` + restart. Mixed deploys work — one device can hot-push while another restarts.
+If every frozen Android target is already reachable over distribution, the
+whole exact set hot-pushes. Otherwise the whole Android set uses the fenced
+`adb push` + restart path; Mob never splits one Android transaction across two
+authorities. A mixed iOS/Android command handles each platform in its own
+ordered, committed phase.
 
 **Requirements:** The app must call `Mob.Dist.ensure_started/1` at startup, and the cookie must match the one in `mob.exs` (default `:mob_secret`).
 
+### Android native updates preserve app data
+
+`mix mob.deploy --native --android` is deliberately update-only. Every selected
+device must already contain the configured package, and Mob uses only the
+serial-scoped equivalent of `adb install -r`. It never clears app data,
+uninstalls the package, or turns a rejected update into a fresh install.
+
+Before the first device write, Mob snapshots and verifies the exact APK, OTP,
+BEAM, `priv`, and optional exqlite payloads. A phase-bound lease covers the
+sorted canonical device set so a concurrent deploy or hot push cannot change a
+subset mid-transaction. The lease advances only after the native payload and
+then the final authoritative BEAM/restart pass have each completed on every
+target. Replayed, widened, stale, or wrong-phase work fails closed.
+
+For a mixed Android+iOS native command, Android is deliberately serialized
+first: it must commit, release its exact-set lease, and clean its immutable
+staging before iOS build/install begins. A typed result that proves Android was
+not attempted may continue to iOS; every failed, retained, malformed, or
+ambiguous Android result suppresses iOS. Fast Android BEAM deploys are also
+exact-set transactions.
+
+If transport authority becomes ambiguous after a write, Mob intentionally
+retains the device-side lease or release tombstone and stops later targets. Do
+not recover by uninstalling the app or deleting its data. Inspect the bounded
+lease status, resolve the interrupted operation, and remove only a verified
+committed release tombstone; an active or malformed lease requires manual
+diagnosis.
+
+```sh
+mix mob.deploy_lock --device <exact-adb-serial>
+mix mob.deploy_lock --device <exact-adb-serial> --cleanup-committed
+```
+
+The first command is read-only. The second refuses every state except one exact,
+record-only tombstone that already carries a committed phase, and proves the
+device returned to a clear state after the single cleanup attempt.
+
 ## `mix mob.enable <feature>`
 
 Wires up an optional Mob feature in one command — platform-manifest