Skip to content

Workflow status is tracked in GitHub: https://github.com/emulebb/emulebb-rust/issues/226. This local document owns the durable engineering contract.

RUST-FEAT-056 - Deliver supported Android and Fire OS APKs with device harnesses

Distribution Intake Acceptance

This is explicitly optional environment expansion with its existing phase; unfinished APK/device work does not independently hold the core Client gate. Every selected nightly Android compile/ELF check remains mandatory.

  • [ ] Keep experimental native daemon bundles distinct from the separately authorized APK/JNI/foreground-service/signing implementation.
  • [ ] Bind both ABI archives, manifests, tool inputs and ELF/compile proofs to the actual accepted nightly/source. Never relabel binaries or claim target execution from cross-compilation or linked-but-unexecuted tests.
  • [ ] Require device/emulator lifecycle, storage, networking and default-route evidence before any Android/Fire OS runtime support claim. Remote browser control of another host proves no local daemon/device support.

Summary

Deliver eMuleBB Rust as a signed, installable Android and Fire OS APK backed by the existing Rust daemon and browser operations console. Add deterministic emulator and physical-device harnesses that prove installation, foreground lifecycle, authenticated WebUI operation, managed storage, local transfer, restart, clean shutdown, and release provenance.

The Android product remains the same headless bounded monolith. Android owns a minimal application shell and foreground service; it does not introduce a second client implementation or a native recreation of the desktop UI.

Authorized Experimental Nightly Slice

The operator selected experimental native daemon bundles for arm64-v8a and x86_64 as the initial Android nightly deliverable. The operator subsequently authorized APK/JNI/service/signing implementation on 2026-11-13; publishing developer archives does not close this APK feature or add a supported Android-platform claim.

Build fresh ELFs with the actual nightly version/channel and immutable source identity through the pinned non-root NDK recipe. Publish bounded developer archives, manifests, checksums, SPDX and compile/ELF evidence through the GitHub-owned nightly pipeline. Do not relabel prior development binaries or present compile checks as target test execution. Keep archive compile receipts distinct from the bounded APK/device evidence below; Termux execution and representative-device routing remain unqualified. The existing Windows/Linux/macOS, musl and OCI proof remains mandatory; the Beta3 release and long-soak holds remain in effect.

The parent coordinates one workstream with separate Build and Rust checkout owners. Run complete applicable hooks and hosted qualification under the current Delivery Policy; explicit heavy local proof remains serialized through the shared lock. Preserve inherited workspace/output/Cargo state rather than restoring obsolete storage assumptions.

Acceptance for this slice is new, source-bound published nightly assets for both Android ABIs with honest experimental status. Current compile-only CI reports and source code for a producer are not publication proof. The full APK and device acceptance criteria below remain open.

Mobile WebUI Addition

On 2026-11-14 the operator added the supplied mobile WebUI and dark-mode plan to this delivery chunk. Keep the existing 14 views, Tabler components and desktop layout. Below 640 px, collapse the existing navigation into an accessible Menu; fit controls at 320 px and retain wide semantic tables inside labeled local scrolling wrappers. Do not add dependencies, a second navigation tree or cards replacing table columns.

Add System / Light / Dark appearance with Tabler's root theme attribute, applying the resolved appearance before rendering. Persist the browser preference under emulebb.webui.theme independently of authentication; storage failures retain an in-memory selection. Validate live device-theme changes and readable controls.

Diagnostics capture, crash testing and shutdown use direct buttons without typed phrases or confirmation dialogs. Keep authentication and required API request fields; mocked tests must not crash or stop an operator daemon. Validate displayed values and action payloads against actual response contracts, including the private raw diagnostic bundle. Do not describe that bundle as sanitized or safe for public sharing. This supersedes the earlier acknowledgement proposal in RUST-BUG-178.

Acceptance includes realistic mocked data for all views at phone, tablet and desktop widths; theme persistence and unavailable storage; keyboard/menu/focus behavior; forms, row actions and local table scrolling; Chromium coverage and a mobile WebKit smoke. Retain synthetic light/dark screenshots below the configured output root. Use the existing supported WebUI owner for unit, type, production build and browser checks, followed by fresh combined-source release qualification.

Local qualification of 54a5f22042a2131ba6706cc4a7f3206ff30b4a4f passed 52 WebUI unit tests, 32 Chromium/WebKit browser tests, TypeScript and the production build. All 14 views were checked at 320, 390, 768 and 1280 px. Phone-width checks also measure readable folder/hashing path columns, local scrolling and reachable row actions; page overflow alone did not catch the original collapsed path columns. The selected Builder passed 83 scoped tests, retained below EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/builder-unit/1d13026f37ab/. Synthetic reference PNGs are retained below EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/webui-mobile/54a5f220/. These are mocked browser proofs, not physical-phone execution or APK publication evidence.

Hosted Linux qualification exposed two regressions missed by the initial local pass: deferred Preact unmount cleanup accessed a disposed global window, and Escape dismissal could miss focused controls. The shared table listener now captures its owning window; suite teardown and its regression flush passive effects with act. The menu installs an owning-document capture listener synchronously, with focus restoration checked from controls, links and body.

PR #335 merged the mobile overflow and keyboard-focus fixes to Rust main at 0840e9005fd2ab28e9cbe262054dd692262e5698. The 52 WebUI unit tests and 32 browser tests passed across the supported widths and Chromium/WebKit engines. This WebUI update did not produce a new APK or nightly; the published APK and its producer/evidence remain the PR #333 release recorded below.

Current State

  • PR #333 merged to Rust main at source 23e685b87bb76db21489c9b1cc725dd0da4241c1. Published nightly 0.1.0-beta.2.nightly.20261115.g23e685b8 went public at 03:02:52 UTC on 2026-11-15. Run 43666596381 published 85 assets with the release marked non-draft. Its producer identities are Builder 43515795e85beceeb73b1bbbd77e5ab167ef13b6, Harness 281ccbcdf9f4c9960c5efda4705df966418b6bb2, Tooling f88a8ce608bc75a619aea6909f54a9cdecdddb6e, and tool image ID prefix c94812.

All seven normal Android API 31–37 APK runtime jobs passed on x86_64 KVM emulators. The same APK, manifest and source passed 13, 13, 15, 15, 15, 15 and 16 cases respectively, including local transfer and file links. API 31–36 used 4096-byte pages; API 37 used 16384-byte pages. Screen-off observations were bounded and do not establish 24-hour endurance. All six native package lifecycle checks and native image checks for musl, Ubuntu and Alpine passed. The aggregate Android APK lifecycle evidence SHA-256 is cf4e53654139b21acfd19c46d8d87013bcaebbd9f5cf1d60845138135f39bdff.

The universal APK is versionCode 216871926, minimum API 31, target API 37, with ARM64 and x86_64 payloads. Its SHA-256 is 7437540651dd54f30e9c3210c2b75f146e52c8c4d180e47d0c8b2dcb13b3750d; the manifest SHA-256 is 36919479a73655b99ceddbc021c7c3666223a505fa70172a49493257db933123, and the signer certificate SHA-256 is 9edc742d7230a714a0149c20eb2afb235b8ad5237166090f10e7ac69e2bb359f. Published native archive SHA-256 values: android-arm64-v8a.tar.zst, cc4639b024e353564a97a2969bc77e79543b4514da5eebb72304ceabd942dabc; android-x86_64.tar.zst, c0f9f435b5ababc689f1029a947a161ab870758b007bedb6095b56744fd36c75. A separate TLS repair execution is auxiliary evidence and does not replace the producer identities above. - The operator deferred automatic boot resume on 2026-11-14. Current source 42bffd971c77cd856e361c00e3a318c85304a859 requires manual Start after reboot and removes the boot receiver, permission and resume setting. Continuous foreground-service operation, wake lock, explicit Stop and ordinary process recovery remain in scope. Builder ce89ba75c722b49f29791fe8be1d75728c147289 passed release Kotlin, strict runtime inventory and lint for that source. Receipt: EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-apk/1796a7ee388f4937a725c14ce3e72a3e/build.json, SHA-256 cb00784f8f5e3e8bd6e487b6e3b71a8baadfcf070f54471480e1b5443a90f011. This is not APK runtime qualification. Exact-source CI, CodeQL and optional-platform checks passed. Its nightly candidate 43593021660 produced the signed universal APK and both native archives, but remains unpublished. One failed-job rerun resolved the unrelated Linux ARM64 package admission failure. APK qualification still failed on all four guests: API 34 repeatedly failed during local transfer; API 35 failed initial startup first and local transfer on rerun. API 36 repeatedly failed an ADB operation during screen-off/Doze; API 37 passed transfer and file-link confirmation on the rerun, then failed screen-off/Doze. These initial receipts did not distinguish product defects from test-driver failures. Isolated diagnostic replays use the original APK, independently pinned diagnostic executors and sanitized typed failures; their results cannot satisfy publication qualification. - Failure-only transfer observations now identify the API 34/35 blocker. API 34 replay and API 35 replay both reported 262,144 of 262,144 bytes downloaded, state completing, no delivered path and atomic-no-replace-unsupported. AOSP's shared-storage FUSE implementation rejects nonzero rename flags on Android 14 and Android 15; Android 16 permits RENAME_NOREPLACE. Timeout increases cannot repair that limitation. The operator explicitly expanded storage implementation rather than raising the minimum version, then selected Android 12+ on 2026-11-14. The delivery contract below preserves atomic rename where supported and adds an exclusive copy path for filesystems that reject atomic no-replace rename. Both native archives remain required public assets alongside the APK. - The API 36/37 screen-off failure was separately identified as successful dumpsys power output exceeding the harness's 65,536-byte bound. Harness 0cd8b6bcc7f3ec2298b86dc27fe33c60ab5887db filters the dump on-device into a closed wakefulness result, preserving command errors, the output/time bounds, Home/activity-closed proof, actual deep idle and repeated authentication. The focused lifecycle suite passed 230 tests without skips, including real shell filter execution. It also includes the reviewed bounded state-wait repair for transiently absent UI controls. API 36 replay passed all 15 cases against the original signed APK: the activity was closed, deep-idle/screen-off observation lasted 60.067 seconds, and three authenticated samples passed. Its curated receipt is EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/github-actions/43604043307/diagnostic/bcfd4a24789546e19bf20b473e178770/validation.json, SHA-256 b6d95a654b1b7d37d4e8f352bc69e1da305fa95e09f5bd133a9cc153d3cab000. The receipt explicitly remains scope: apk-diagnostic-replay, applicationQualification: not-run and publicationEligible: false. API 37 then exposed a source-format mismatch: its unindented numeric power-group fields must not count as the two-space global wakefulness field. Harness b522c218b4a93ee842b99b68471664a700700ebc repairs that parser, with 235 passing lifecycle tests and no skips; its targeted API 37 replay subsequently failed while locating Start in the file-link case, before the power check. That navigation failure is being investigated separately. None of these bounded proofs establishes 24-hour endurance or qualifies publication. - The exact GitHub-built manual-start 42bffd97 APK passed two bounded 12-case physical-device campaigns on API 36, ARM64, 4096-byte pages. Its APK SHA-256 is 7da937988aedf6fce35863f164e57c89964dae5f5adabb6ce2fcf796dfb9e714. Fresh installation proved Incoming/Shared defaults, visible version/insets, authenticated source-bound readiness, system day/night switching with the original theme restored, resource diagnostics and the diagnostics chooser without selecting a recipient. Receipt: EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-apk-device/phone-github-42b-fresh-20261114122844/physical-device.json, SHA-256 d42b6067199d1a11e9f97859ab512f7f186728864ddc26dc7a8971ae8811b96f. The second campaign proved rendered WebUI content, a real 256 KiB transfer against the same-source ARM64 peer, collision-preserving final delivery, and completion history/shared catalog across restart with duplicate rejection. Receipt: EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-apk-device/phone-github-42b-transfer-20261114123417/physical-device.json, SHA-256 bbb53126e29687b1660b7076bf50a4a725b2863ba572767fb10db4cf2eb6c975. Owned peer endpoints and fixtures were cleaned up; the app was left stopped. This same-device P2P proof does not establish Wi-Fi/NAT data-plane behavior, Termux execution, Fire OS, emulator qualification or 24-hour endurance. - The prior 54a5f22042a2131ba6706cc4a7f3206ff30b4a4f source passed its CI, CodeQL and optional-platform prerequisites. Its nightly candidate 43583500231 produced the signed APK and both native archives, but failed all four APK runtime qualification jobs; no release was published. Phone evidence for these exact APK bytes below does not qualify the later manual-start source. - The 2026-11-13 operator authorization lifts the APK/signing hold for this workstream and selects the lean Android shell contract below. Implementation, package qualification and publication remain separate acceptance steps. - The Android completed-file move accidentally selected the unsupported-target stub because Android has a distinct Rust target_os from Linux. The source repair uses the existing rustix atomic no-replace rename on both Linux and Android, preserving collision handling, native file identity and durability barriers. There is no check-then-rename or overwrite fallback. - Process resource diagnostics expose daemon resident memory and interval CPU usage through diagnostics, status, snapshot and diagnostic bundles, with readable WebUI cards. Native counters avoid Android's restricted global process inventory, honor runtime page sizes including 16 KiB, and run outside the async executor. CPU 100% means one occupied core; unavailable counters are null and displayed as n/a. The OpenAPI contract owns the field semantics. - The 2026-11-13 source checkpoint passed 1,307 Windows transfer tests, 150 REST tests, 35 WebUI unit tests, 17 browser tests, WebUI type/build checks and both Android ABI Clippy, diagnostics, workspace test-link, release-link and ELF checks. Android evidence is retained under EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/rust-android/dd5439c6d32841fe9685328ecacc1ed1/validation.json and records runtimeExecution: not-run. These local checks do not execute file delivery or resource sampling on Android, qualify a device, or verify a newly published archive. Later bounded phone evidence is recorded below. - Experimental native daemon archives for both ABIs were published by nightly run 43242135692. Publication and compile/ELF proof do not establish Android runtime support. - The reported Samsung Galaxy S24+ Termux launch exposed a JVM-dependent TLS panic. The bounded native CLI repair now has accepted actual-source emulator evidence: API 37/x86_64/16 KiB, source-built release-mode daemon on the development channel, six TLS cases, fresh EXE-directory profile, authenticated REST and graceful shutdown. This does not execute a published Android archive. The physical S24+ Termux retest and separate Android unavailable/degraded-network execution are explicitly unproved and remain with this open owner under the operator's choice to use GitHub emulators for now. Six TLS cases are not a separate unavailable-network run. - The supported platform contract includes Windows, Linux, and macOS only. - The workstream now has checksum-pinned SDK/NDK, Java, Gradle, ADB and Android CLI inputs, a non-root offline Docker toolchain probe, and Android Rust validation shared by local WSL/Docker and required GitHub CI. - arm64-v8a and x86_64 pass canonical Clippy/diagnostics checks, workspace test linking, release executable linking, and ELF CPU/Bionic/16KB audits. These archive-specific receipts are compile checks; the separate x86_64 emulator proof above executed only the six selected TLS cases. - The Android shell and JNI implementation are committed on the active branch. Nightly 43509368144 produced the universal production-signed APK for Rust source 257cf6fe4e44a9446f56ed8c80cbacb9ab9c293c, version 0.1.0-beta.2.nightly.20261113.g257cf6fe, code 216767888. Production passed strict Gradle verification, release Kotlin/lint, both JNI ABI builds, ELF/export/dependency audits, certificate verification, 16 KiB ZIP alignment, SDK/ABI inventory, SPDX and checksums. The APK SHA-256 is 0c2a532f3036a1fba444af473697c92cb6e1b7ec585255f796c7a26a063920bc; its certificate SHA-256 is 9edc742d7230a714a0149c20eb2afb235b8ad5237166090f10e7ac69e2bb359f. This is an Actions candidate artifact, not a published release: all four API 34-37 application-qualification jobs failed and publication remained gated. - The exact GitHub-built 54a5f220 APK passed all 13 physical-device cases on API 36, ARM64, 4096-byte pages. Its APK SHA-256 is 1c5587f886e546770473d652f1ed46d59189e907021875c548e38c971fcc2a3e. Execution proved visible version/insets, authenticated source-bound readiness, bundled WebUI serving, rendered browser content, CPU/RSS sampling, fresh Incoming/Shared defaults, a real 256 KiB P2P transfer, collision-safe final delivery, and restart/catalog/completion-history preservation with duplicate rejection. The standard Android diagnostics chooser was verified and dismissed without selecting a recipient. Normal Stop closed the listener and cleared foreground-service state; the phone was left stopped. Owned transfer fixtures were removed and prior settings preserved. The receipt is EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-apk-device/phone-github-54a5-transfer-20261114105915/physical-device.json, SHA-256 b3111f3f24b35d47e97e57649b8d4dcaac02fe7e0fdfc7ac17783824c51fb1f8. The peer used matching GitHub-built ARM64 source. Traffic was same-device P2P; this proves neither a Wi-Fi/NAT data plane nor endurance. The foreground observation was 30 seconds; the 24-hour campaign remains open. - A separate 11-case physical-device smoke of the same signed APK passed Android system day/night theme switching and readable native controls/system bars. Receipt: EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-apk-device/phone-github-54a5-theme-20261114105137/physical-device.json, SHA-256 4fd796f40d22df1f901994d02e3c5512091df45f1d3f977b1f12fdcfe295aa08. The diagnostic driver was selected independently of the original APK producer harness; these bounded foreground proofs do not establish Termux UID/runtime, Fire OS, full API 34-37 lifecycle or continuous-operation qualification. - A fresh, initially empty Gradle home exposed four missing strict dependency metadata entries that warm-cache checks had hidden. The independently verified Maven Central hashes were added without weakening verification. A second empty-home production Kotlin/inventory/lint run passed; its receipt is EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-apk/88ab941af5974a62b6574c8f233fe1fc/build.json, SHA-256 bd012b2b44609b7239b2a226e18b6a32e4d23f8b1de3aeb58567b4ef5c54c98f. Source-bound CI, CodeQL and optional-platform checks all passed for 257cf6fe. - The later candidate run 43524927475 passed exact-source CI, CodeQL and optional-platform prerequisites for 170e3005a7c0f985f72fd579cf7c2ba18eb21ed2, then passed native packaging, packaged lifecycle and container-image gates. Its production APK is version 0.1.0-beta.2.nightly.20261113.g170e3005, code 216774585, SHA-256 8fb078f326c281667c44c6a85158ea4da8e319da521cfeedce27e6689b4f6d98. The manifest SHA-256 is 6e7bb7a67539943e9ae0f190af0ba00fadb730ef9dd3395830c380bd82e46f72. An independent byte audit passed both JNI libraries, 16 KiB ELF/ZIP alignment, packaged notices and SPDX binding. The review is retained below EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-apk-release/43524927475/static-review/. All four application-qualification jobs failed; no APK release was published. Only release workflow source changed between this candidate and the exact phone-tested 257cf6fe build. This establishes unchanged product source, not physical execution of the later APK bytes. - Actual API 35-37 diagnostic replays passed fresh setup, authenticated readiness, bundled WebUI, clean Stop, notification-denied startup and all-files denial/revocation, then failed enabled reboot authentication. Both observed the primary user unlocked, the package not stopped, storage access and notification grants present, and the Doze whitelist retained. The daemon service was absent and every post-reboot REST attempt failed to connect. A subsequent observation also resolved the installed boot receiver and, only after recording the failed automatic startup, opened the normal application without pressing Start. The bound service reported Failed with boot resume still enabled. The source-owned error category is network-default-route-missing on all three versions: default IPv4 route selection failed during automatic startup. The successful explicit Start and authenticated readiness immediately before reboot durably removed the earlier permission-test error. The API 36 receipt is retained below EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-apk-diagnostic/43546179420/, SHA-256 96002982c4acb23e70d8411ca47a97656425ce262d7c07d6afdd3a7343418bdb. API 37 also passed its local-network denial/revocation case before this boot failure. API 34 instead reached Failed during initial startup, before authenticated readiness; its exact error was not observed, so the same cause is not established there. These are failed qualification receipts, not release or continuous-operation proof. - The existing Nightly workflow now has an optional read-only diagnostic replay mode. It independently admits a completed official producer run's successful signed APK and matching peer artifacts, original source-owned provider pins, whole-artifact digests, caller-selected manifest hash, version and signer. It records original producer authority separately from the current diagnostic executor. Any diagnostic input closes the normal publication path; incomplete inputs or publish=true fail before checkout. Diagnostics use a separate concurrency group and read-only Actions/content permissions, with no signing secret. Their receipts have scope: apk-diagnostic-replay and publicationEligible: false; they cannot qualify a release. Normal source, same-run artifact, native and full API 34-37 publication gates remain required. Retained failures contain only source-owned stages/codes and bounded closed navigation, permission, service and post-failure UI facts, never raw UI, configuration, keys, guest logs or private AVD data. - Harness repair 763fb610 prevents stale UI hierarchies from authorizing taps. AOSP's dump command can return success after a null-root or idle failure without replacing its output; the driver now invalidates only its owned UUID dump before each inspection. Regression cases cover zero-exit/no-write, partial-write, failed invalidation and fresh-success behavior. This is a demonstrated driver defect, not proof that it caused every earlier emulator failure. Boot resume is now deferred; final manual-start APK qualification/publication remain open. - The daemon exposes its behavior through a reusable library, loopback REST, and the browser WebUI. Its run_hosted entrypoint accepts application-owned readiness and shutdown without installing process signal handlers. - The selected API 37/x86_64 guest proved the conservative route hint and authenticated loopback REST startup. Representative-device routing, P2P socket/VPN confinement, broader storage recovery, background execution, multicast and NAT behavior remain unqualified.

Intended Shape

  • Kotlin application sources live in emulebb-rust/android/; native lifecycle integration lives in the same Rust repository. There is no separate app repo.
  • The accepted APK minimum is Android 12 (API 31), targeting API 37. Qualify APIs 31, 32, 33, 34, 35, 36 and 37 separately, including Android 12L/API 32. This is the expanded delivery target; the older candidate proofs above do not establish execution on the newly selected APIs. Native CLI archives keep their separate API 28 compile floor and experimental runtime status.
  • A minimal Kotlin application owns one foreground service and invokes the Rust daemon through a narrow JNI library boundary.
  • The native shell follows the device's light/dark setting through qualified Android theme resources, including matching system-bar icon contrast. It has no separate appearance preference. Native widgets, system insets and FLAG_SECURE remain in effect. Release Kotlin compilation and lint, including both resource variants, passed on the current manual-start source above. The earlier 54a5f220 signed APK additionally passed the bounded physical day/night theme smoke recorded above.
  • The service supplies app-owned profile, database, log, transfer, and WebUI paths and defaults the authenticated listener to 0.0.0.0:20017, matching every other product platform and package. Browser connections on the same device use loopback; the wildcard is a listen address.
  • The packaged SPA remains the complete operations surface, opened in the system browser. There is no WebView or parallel native transfer/settings UI.
  • The shell provides Start/Stop, actual lifecycle status, Open WebUI, REST bootstrap settings and a visible API key with Copy and Regenerate controls. TOML edits require a stopped service and use Rust's authoritative parser. Generate a random first-run key; never pass it in browser URLs or logs.
  • Respect status-bar, display-cutout and navigation insets so the version and controls remain visible on modern edge-to-edge Android displays. Provide user-initiated Share diagnostics through Android's share sheet, including bounded recent logs and app/service/platform metadata. Exclude private configuration and credentials; scrub private operational identifiers or omit records that cannot be safely projected. Share only temporary read-only access to the generated support archive.
  • Register browsable ed2k:// file links with Android. Validate a bounded link through the canonical Rust parser, retain at most one pending link, and open the WebUI with its transfer form prefilled. Receiving a link must not start the service or queue a transfer. Preserve the handoff through authentication; require explicit Add confirmation and support cancellation and repeat intents.
  • A persistent notification exposes running state and a clean stop action.
  • A dedicated foreground-service process owns the Rust runtime. On API 34+ use specialUse with an explicit continuous eD2K/Kad peer-hosting subtype; use the supported foreground-service invocation on APIs 31-33 without that type. starting, readiness, shutdown and failure remain observable independently of the shell/browser lifecycle. Repeated Start cannot create duplicate runtimes.
  • Private app storage owns metadata, TOML, credentials and logs. App-specific external storage owns incomplete payloads by default; completed delivery defaults to Download/eMuleBB/Incoming under shared internal storage. Create the adjacent visible Download/eMuleBB/Shared folder as the initial explicit shared root; incoming remains implicitly shared. Seed these defaults in the canonical database only for a fresh profile, preserving later WebUI edits and removals across restarts. Show the actual paths to users. The user grants all-files access, then uses ordinary filesystem paths through the WebUI. Do not add document-provider adapters or import/export copy workflows.
  • Guide notification, all-files and battery-optimization permissions explicitly. All-files access is required to start. Denied notification visibility or battery exemption remains visible without preventing startup. Hold a partial wake lock while continuous service operation is enabled and release it on every stop/failure path. Permission revocation must preserve existing data.
  • Start is an explicit user action; after reboot the user opens the app and presses Start again. Automatic boot resume is deferred. Explicit Stop, including REST shutdown, clears desired-running state. Force-stop remains authoritative; recover ordinary system termination with bounded backoff and expose persistent startup failures.
  • Android private preferences own only desired service intent and bounded recovery state; TOML/SQLite remain the existing daemon configuration authorities.
  • One universal release APK contains arm64-v8a and x86_64. The same signed artifact receives emulator and physical-device qualification.
  • Fire OS support must not depend on Google Play Services.

Collision-safe Shared-storage Delivery

The operator expanded this delivery slice on 2026-11-14 to retain Android 12+ and the visible Incoming folder. Keep the existing atomic no-replace rename on filesystems that support it. Check the destination name first, then let the atomic operation resolve any race. Try the original name, _01 through _99, then _001 through _999, widening the number group again when exhausted. Insert the suffix before the extension, for example abc_01.mp3.

Only a typed unsupported result from the rename itself selects exclusive-copy publication. Persist a sharing exclusion before creating the final candidate with create_new/O_EXCL; an existing occupant causes the next candidate to be tried. Copy through the exclusively created handle, verify the complete size and hash, and sync the file and parent directory before committing publication. Never replace or truncate another file, and retain the original download until completion. A sync failure after a successful rename must not select this path.

An exclusive copy can be visible to other file managers while incomplete. Scans, directory monitoring, direct sharing and metadata admission must keep it out of the shared catalog. Interrupted or ambiguous outputs stay preserved and excluded across daemon restarts and transfer deletion; retries choose another name. Normalize parent-path aliases before applying exclusions. This is a current-schema storage change, requiring a fresh beta profile, without migration or automatic profile reset.

The approved campaign library was copied into the owned test location: 221 original files across 19 directories, totaling 1,301,166,929 bytes. Three files were excluded by normal intake rules; 218 eligible shared entries remained. The public-network campaign ended as failed after 74 minutes and 140 observations. It recorded zero public peer requests and zero public peer bytes. A generic RuntimeError was not classified, and the harness stop was confirmed. Do not describe the library as uncopied or the campaign as ongoing, and do not claim that eligible entries were served. Later observer fixes merged in Harness PR #113 at 17438846c1a62fa8228c821071cc79e7cf56145b; all four main workflows passed and the mapping/closed-failure-phase repairs were unit-tested. This improves future observability but does not retroactively classify that error or establish a public upload. Exact private inventory, filenames, paths and user-media hashes remain only in local output evidence.

Latest API 31 Phone Smoke

A signed local APK (versionCode 44) built from Rust source 20a07429bf41ec58649725bc56e58b0e7855839f passed 13 fresh physical-device smoke cases on an ARM64 phone running API 31 (Android 12) with Linux 4.14.186. The cases covered permissions, themes/version, fresh defaults, authenticated REST and rendered WebUI, CPU/RAM diagnostics, graceful service stop and the diagnostic share chooser. Both arm64-v8a and x86_64 APK payloads were built. The tested APK signing certificate SHA-256 is 9edc742d7230a714a0149c20eb2afb235b8ad5237166090f10e7ac69e2bb359f. The receipt is EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-apk-device/phone-api31-route20-fresh-20261114/physical-device.json, SHA-256 199a05cc30487b618ec7f419757fe16f8a9ba99e0e5688b51110f3801a3c9742. This is bounded local-APK evidence, not hosted full-matrix, release, or broad Android qualification.

The tested automatic direct-routing repair applies only when the original IP and interface are unset and VPN Guard is off. It selects a detected local IPv4 address and lets the operating system route traffic with that source address. Explicit IP, interface and VPN Guard choices remain strict and do not fall back. The public-network campaign result is recorded above; it produced no observed public peer requests or bytes and does not establish successful public serving or 24-hour endurance. Manual Start after reboot remains the accepted workflow. Both experimental native archives retain their API 28 compile target, which does not qualify Termux or Fire OS runtime.

Distribution Boundary

  • The initial supported distribution is a signed APK published with GitHub release assets. Google Play, Amazon Appstore, and Android App Bundle delivery require separate decisions.
  • The operator explicitly selected MANAGE_EXTERNAL_STORAGE for the lean direct-path shell, superseding the original picker/import/export boundary.
  • The operator resumed completion of Android packaging and additive GitHub release integration on 2026-11-13, including visible Incoming/Shared defaults, insets and support sharing. Keep the current branch, granular commits and pushes; no pull request is authorized yet. Qualify branch candidates through existing dispatchable CI and unpublished nightly execution before publication.
  • Automatic resume after unlock on reboot is deferred by the 2026-11-14 operator decision. Manual Start is the selected release behavior; recovery after Android force-stop is not authorized. The operating system remains authoritative.
  • Keep both native arm64-v8a and x86_64 tar/zstd archives as public nightly assets alongside the universal APK, with manifests, SPDX and honest compile/ELF evidence. The download guide owns APK and experimental Termux user instructions. No new packaging format or Termux testing framework is required by this distribution addition.
  • Add the universal signed APK to existing nightly qualification/publication without weakening existing gates. A dedicated long-lived APK signing key comes from GitHub secrets; missing signing input fails publication without debug-key fallback. Initial APKs remain experimental pending device proof.
  • No 32-bit Android ABI is required.

Android 12-17 Permission Contract

The operator requested an explicit permission review for every supported version. The accepted APK target is API 37 with a minimum of API 31. This source review is not emulator or physical-device execution evidence.

  • All seven versions use normal INTERNET, ACCESS_NETWORK_STATE, FOREGROUND_SERVICE and WAKE_LOCK permissions for the actual socket and service APIs. The special-use service type/permission applies on API 34+. The manual-start APK has no boot receiver or RECEIVE_BOOT_COMPLETED permission.
  • APIs 33-37 request POST_NOTIFICATIONS; APIs 31-32 use Android's application notification settings without requesting that nonexistent runtime permission. Denial does not prevent a foreground service, but the shell must show reduced notification visibility. See Android notification permission.
  • All seven require the user-granted MANAGE_EXTERNAL_STORAGE special access before starting native shared-path operations. Denial blocks Start and revocation stops active operation without deleting data. See all-files access.
  • All seven declare REQUEST_IGNORE_BATTERY_OPTIMIZATIONS and guide the user through the separate exemption setting. Exemption is recommended, not a prerequisite to starting. Show ActivityManager.isBackgroundRestricted() independently: unrestricted battery use and Doze exemption are different controls. See background optimization and Doze.
  • Runtime API 37 additionally requires ACCESS_LOCAL_NETWORK before Start, including native TCP/UDP and SSDP operations. Monitor revocation. APIs 31-36 must not request that newer runtime permission. See local network permission.
  • No legacy storage/media, location, Bluetooth, nearby-Wi-Fi, overlay, exact alarm, package enumeration or APK installation permission is needed by the current implementation. Active MiniUPnP M-SEARCH receives unicast replies; the current PCP/NAT-PMP paths use directed gateway traffic. There is no passive multicast group subscription requiring a Wi-Fi multicast lock.
  • Android 15 data-sync timeouts do not classify the selected special-use service. Android 16 job quotas apply to scheduling APIs, not the hosted Tokio runtime, which does not use those APIs. See foreground service changes.
  • Android 13+ Task Manager Stop kills the application without lifecycle callbacks. Own daemon process exit history must prevent treating explicit user termination as an ordinary recoverable crash; stale exits preceding a later explicit Start must not disable that new session. See user-initiated service stopping.

The intended qualification contract covers each API 31-37 separately: notification denial/grant/revocation on API 33+; all-files denial/grant/running revocation; Doze with and without exemption and actual idle-state assertions; manual Start; explicit Stop and force-stop everywhere, plus Task Manager Stop on API 33+. API 37 adds local-network denial/grant/revocation; earlier versions verify absence of that prompt. These are required coverage targets, not a statement that every case has passed. The current mandatory harness selects manual Start, clean Stop, Home/background continuity and measured Doze continuity; it contains no reboot scenario. Restricted battery mode must never be presented as qualified continuous operation. Boot-resume qualification is deferred with that feature.

Earlier in this workstream, the operator authorized physical-phone testing over Wi-Fi and limited resets to the app-owned test profile. Those historical authorizations do not schedule another phone run. The current operator testing preference is to use emulators for all future Android execution tests; this is a workstream preference, not a product support limitation. Preserve the operator's ADB server and unrelated application data in historical evidence. Confine test fixtures to owned synthetic files. Phone results on one Android API do not substitute for the full API 31-37 matrix or 24-hour endurance evidence.

Release signing material is retained in the operator's normal application-data directory: %LOCALAPPDATA%/eMuleBB/signing/android on Windows, or ~/.local/share/emulebb/signing/android on Linux. It is outside workspace cleanup ownership. Preserve its encrypted keystore, private credentials and public identity together in an operator-controlled backup. GitHub secrets are not a substitute for retaining the update signing identity. The operator authorized generation and GitHub secret configuration on 2026-11-13; the retained signing identity has been generated and all four Android signing secrets are configured. Directory ACL customization is not a prerequisite; use ordinary per-user storage and the encrypted keystore.

Compile Foundation Evidence

The 2026-11-09 compile foundation is now part of the merged and published experimental native-bundle baseline. Its original Build orchestration bb0e542 owns the reviewed inputs and both local/hosted entrypoints: python -m emule_workspace validate-rust-android locally and validate-rust-android-ci on explicit hosted checkouts. Both retain source identities and explicitly record runtimeExecution: not-run.

Rust 3ddf47ac passed the full local pre-push gate and required GitHub CI, including both Android ABIs on fresh AMD64 runners. Its CodeQL run also passed. Local compile receipts remain below EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/rust-android.

Harness e99192f adds the universal-APK native-payload audit with 12 passing regression tests. It checks both ABI payloads, bounded ZIP inventory, 16KB alignment, CRC and hashes, and delegates ELF validation to the packaging owner. It has not yet audited a produced eMuleBB APK and does not establish signing or runtime proof.

The local Android target directory contains accumulated debug and incremental output across builds. Reducing that footprint is follow-up CI hardening; both fresh hosted compile jobs passed, so this measurement is not a demonstrated runner-capacity blocker. Keep complete checks when changing build profiles.

Build 1c70c15 adds separately pinned emulator/API-28/current-16KB inputs and the local prepare-rust-android-emulator software probe. Real WSL Docker execution passed as a non-root user with networking disabled, a read-only root, dropped capabilities and the exact image content ID. Both installed guest-image metadata sets passed API/revision/ABI/variant checks. The probe caught and fixed owner-only modes in the old AOSP archive and now uses the intended headless emulator mode. Owner changes require the tools-only probe before push, without implicitly downloading guest images. Receipts below EMULEBB_WORKSPACE_OUTPUT_ROOT/reports/android-emulator record runtimeExecution: not-run; that tool-only check did not boot guests or qualify an APK.

The shared guest-boot owner uses native non-root Docker with KVM, no networking, and a fresh writable run directory. probe-rust-android-guest --image min or --image current runs it locally where KVM is available; the GitHub adapter uses the same owner and harness. This WSL host has no /dev/kvm, so software installation/version/metadata checks run locally and accelerated boots run on GitHub. Emulator preparation now needs only the emulator, the existing shared ADB pin and the selected guest image; it no longer prepares compiler inputs. Public evidence excludes private AVDs and emulator runtime logs and explicitly records applicationQualification: not-run.

Build bea48fd and harness 0b878d7 passed both hosted KVM guest boots: stable API 28 with 4096-byte pages and stable API 37 with 16384-byte pages, both native x86_64. The minimum guest exposed an unavailable getconf PAGE_SIZE query; the shared harness now reads the kernel's ELF64 AT_PAGESZ entry over binary-preserving ADB, without publishing auxiliary-vector process addresses. Local evidence includes the complete harness suite plus 36 focused boot/parser tests and the offline WSL Docker runtime-tool probe. APK production, signing, application lifecycle and release integration remain open.

The operator has reported a Samsung Galaxy S24+ Termux failure; the exact Android/Termux versions and artifact hash remain unknown, and no Android device was connected to ADB at the 2026-11-12 intake. Android ARM64, Fire OS and ChromeOS device qualification remains pending; emulator or compile success must not satisfy those acceptance criteria.

Networking And Safety Constraints

  • Direct routing is the initial supported public-network mode. Mobile carrier NAT is not expected to provide inbound HighID reachability.
  • Android must never silently reinterpret or weaken VPN Guard. Unsupported interface or VPN selections fail closed before public P2P traffic is emitted.
  • Wi-Fi UPnP/NAT-PMP must either be runtime-proven or explicitly rejected by the Android settings surface; configuration must not appear successful while doing nothing.
  • Background execution, Doze, network transitions, multicast requirements, and process termination receive explicit evidence.

Acceptance Criteria

  • [ ] Pinned Rust, Android SDK, NDK, and Gradle inputs build arm64-v8a release and x86_64 emulator artifacts reproducibly.
  • [ ] MiniUPnPc, libpcpnatpmp, SQLite, TLS, interface enumeration, and every native dependency have explicit Android compile and runtime dispositions.
  • [ ] Canonical orchestration produces the signed APK, bundled WebUI, manifest, checksums, SBOM, and provenance below the workspace output root.
  • [ ] The foreground service starts one Rust runtime with an app-private profile and an authenticated WebUI listening on 0.0.0.0:20017 by default.
  • [ ] Notification stop, REST shutdown, application stop, restart, and ordinary process termination leave SQLite and transfer state recoverable.
  • [ ] Backgrounding the UI does not stop an active transfer while the service remains authorized to run.
  • [ ] Direct shared-storage delivery and sharing preserve exact size and SHA-256; interruption, low-space, revoked-access, and collision paths recover.
  • [ ] Manual Start, explicit Stop, REST shutdown and force-stop preserve the selected service intent and never create duplicate daemon ownership.
  • [ ] A physical ARM64 screen-off run exceeding 24 hours proves the continuous service claim, including Doze and network transitions.
  • [ ] An emulator smoke proves install, REST/OpenAPI, WebUI assets, SQLite, local transfer, restart/resume, and shutdown.
  • [ ] An ARM64 physical-device smoke proves the same lifecycle against a local workspace-owned peer.
  • [ ] A bounded physical-device Wi-Fi campaign records direct-mode eD2K/Kad startup, route selection, network transitions, and teardown.
  • [ ] Fire OS installation, foreground lifecycle, WebUI, storage exchange, and transfer behavior pass without Google Play Services.
  • [ ] Existing Windows, Linux, macOS, container, quality, and supply-chain gates remain green.

Automatic boot resume is deferred, including its optional setting, receiver, permission and resume-on/off qualification. Revisit it only as a separately selected follow-up; it is not an acceptance condition for the manual-start APK. The physical 24-hour, Fire OS and remaining runtime criteria above stay open.

Validation

  • Android cross-compilation and Android-specific Rust tests.
  • Gradle lint and release assembly from pinned inputs.
  • Deterministic Python ADB/emulator package smoke with retained provenance.
  • ARM64 Android and representative Fire OS physical-device smokes.
  • Storage, low-space, restart, update, background, network-transition, and unsupported-VPN tests.
  • Existing full Rust quality and native release matrices.

Delivery Slices

  1. NDK compile-and-launch spike using an ADB-controlled standalone daemon.
  2. Deterministic emulator harness and two-peer local transfer.
  3. Foreground-service APK with JNI lifecycle and bundled WebUI.
  4. Shared-storage permissions, direct delivery and interruption recovery.
  5. Android and Fire OS physical-device evidence.
  6. Signed release integration and supported-platform policy update.

Dependencies

repos/emulebb-rust owns runtime and application behavior, repos/emulebb-build owns build/signing/release orchestration, and repos/emulebb-build-tests owns the persisted device harness. Coordinate the storage boundary with RUST-REF-009 rather than adding an Android-only transfer implementation.

Audit Release Placement

This remains parallel follow-up work and does not independently block Beta 3. Its existing Client, Indexer, or Arr phase ownership remains unchanged; non-gating Beta 3 placement does not bypass the separate whole-phase gates.

Audit Reconciliation (2026-11-09)

The complete audit collection was reconciled against current source and owning issues. The following are retained findings, corrected assumptions, or required evidence for this owner; inspection does not replace runtime proof.

  • emulebb-rust-prompt_audit_findings_secure-ident.md section 5 / 7 (existing): Weak stock RSA/SHA1 is an accepted interoperability boundary. Key pinning has a closed owner; native-target build/runtime and cross-client proof have existing owners.
  • emulebb-rust-prompt_audit_findings_reachability.md section 2.4 / 4.2-3 (existing): ABI verification and native-target compile/runtime proof belong to existing FFI and platform items. Android is parallel and non-gating for Beta 3; do not replace proven C libraries with a narrower pure-Rust fallback to avoid qualification.
  • emulebb-rust-prompt_audit_findings_multi-platform.md section portable-delivery (existing): The unsupported-platform arm still rejects completed delivery. Android/FreeBSD/other Unix issues already own platform viability. Do not adopt the audit's check-then-rename suggestion: it can race and clobber data.
  • emulebb-rust-prompt_audit_findings_multi-platform.md section android-route-inventory (existing): The original intake found an empty Android default-route inventory. PR #329 repaired it with a conservative Android-only kernel route hint, covered by the narrow guest startup proof above. Representative-device/network acceptance stays open here; APK/signing implementation is separately authorized above.
  • emulebb-rust-prompt_audit_findings_multi-platform.md section extended-lanes (existing): The audit's no-musl/no-Android-CI claim is stale: both musl architectures and Android compile/ELF lanes now exist. Keep the owning feature issues open for their remaining runtime/package evidence; cross-compilation is not complete platform certification.

Scoped Follow-up Acceptance

  • [ ] Do not replace on-wire primitives locally.
  • [ ] Retain key pin/restart/credit preservation proof.
  • [ ] Keep Android evidence non-gating for Beta 3.
  • [ ] Mechanical C/Rust layout proof uses exact vendored headers.
  • [ ] Keep musl and Android compile proof distinct from runtime/device NAT proof.
  • [ ] Choose a platform primitive preserving no-replace and crash/durability guarantees.
  • [ ] Prove destination collision and concurrent publication without clobbering.
  • [ ] Record unsupported filesystems explicitly rather than silently weakening safety.
  • [ ] Prove representative device route discovery or document explicit-bind constraints.
  • [ ] Never infer VPN confinement from a missing route inventory.
  • [ ] Reuse current lanes and identify missing runtime/device proof only.
  • [ ] Track optional platform failures visibly without gating Beta 3.