Prune commentary and stale Rust port notes

app-rust/src/shell/jcall.rs

@@ -1,46 +1,3 @@
-//! Thin wrappers around the five `Env` calls this crate makes constantly
-//! (a class name, a method name and a signature, all as plain `&str`).
-//!
-//! `jni` 0.22 wants a class or method *name* as `AsRef<JNIStr>` (its own
-//! modified-UTF-8 type; `JNIString::new` is the runtime conversion, used
-//! here uniformly rather than switching to the compile-time `jni_str!`
-//! literal macro call by call -- these are a handful of short, one-off
-//! lookups, not a hot loop, so the difference is not worth two code paths
-//! for the same thing) and a *signature* as a parsed `MethodSignature`/
-//! `FieldSignature`, which is why those go through
-//! `RuntimeMethodSignature`/`RuntimeFieldSignature::from_str` instead: the
-//! parsed form is what lets these calls skip re-validating the signature
-//! against the arguments on every call, which is the whole reason `jni`
-//! moved to it.
-//!
-//! **The classloader gotcha, found by testing (2026-09-05).** A class
-//! lookup by name (`find_class`, `new_object`, `call_static_method`,
-//! `get_static_field` -- anything that resolves a *class*, as opposed to
-//! `call_method` on an object it already has, which needs no such lookup)
-//! defaults to `FindClass`'s ordinary search when it cannot find the
-//! calling thread a classloader through `Thread.getContextClassLoader()`.
-//! That default is fine on a thread the JVM itself started -- an
-//! `onCreate`/`onStartCommand` callback -- but every one of these calls
-//! from `android-shell`'s own background thread (the notification
-//! follow-loop, the share upload) is running on a thread *Rust* spawned
-//! and attached with `JavaVM::attach_current_thread`, which the platform
-//! never gave an app classloader. Framework classes
-//! (`android.app.Notification$Builder`, ...) still resolve, because they
-//! are reachable from the bootstrap loader `FindClass` falls back to --
-//! `androidx.core.app.NotificationManagerCompat` is not, since it is
-//! packaged inside this app's own APK. The failure was
-//! `Error::NoClassDefFound`, logged by `notify::show`'s `LogErrorAndDefault`
-//! as "failed to resolve Java class ... (class not found or linkage
-//! error)" -- on a real device this reads as "the notification silently
-//! never arrives," since the whole call is inside the follow loop and the
-//! ongoing foreground notification (built on the main thread, in
-//! `try_start`, before the background thread exists) posts fine either
-//! way. `remember_class_loader` caches the app's own `ClassLoader` the
-//! first time any entry point has a `Context` to ask, and every class
-//! lookup below goes through it explicitly via `LoaderContext::Loader`
-//! rather than the thread-dependent default -- so it is correct on the
-//! main thread and on this crate's own background threads alike.
-
 use jni::Env;
 use jni::errors::Result;
 use jni::objects::{JClass, JClassLoader, JObject, JValue, JValueOwned};
@@ -51,17 +8,10 @@ use std::sync::OnceLock;
 
 static CLASS_LOADER: OnceLock<Global<JClassLoader<'static>>> = OnceLock::new();
 
-/// Caches `context`'s own `ClassLoader`, the first time this is called.
-/// Cheap to call from every entry point that has a `Context` on hand
-/// (`MainActivity`'s and `NotificationService`'s all do): later calls are
-/// a `OnceLock::get` and nothing else.
 pub fn remember_class_loader(env: &mut Env, context: &JObject) -> Result<()> {
     if CLASS_LOADER.get().is_some() {
         return Ok(());
     }
-    // context.getClass().getClassLoader() -- resolved via `call_method` on
-    // real objects throughout, so this needs no class-name lookup of its
-    // own and has nothing to bootstrap.
     let class_obj = call_method(env, context, "getClass", "()Ljava/lang/Class;", &[])?.l()?;
     let loader_obj = call_method(
         env,
@@ -99,9 +49,6 @@ pub fn find_class<'local>(env: &mut Env<'local>, name: &str) -> Result<JClass<'l
     resolve_class(env, name)
 }
 
-/// A new Java string as a plain `JObject` -- what every call site here
-/// wants it as (`JValue::Object` takes `&JObject`, not `&JString`, and
-/// `JString: Into<JObject>` is the documented way across).
 pub fn jstr_obj<'local>(env: &mut Env<'local>, text: impl AsRef<str>) -> Result<JObject<'local>> {
     Ok(env.new_string(text)?.into())
 }

app-rust/src/shell/mod.rs

@@ -1,23 +1,3 @@
-//! The JNI bridge behind E3's two Java stub classes. See `Cargo.toml`'s
-//! package comment for what this crate is and RUST.md's E3 entry for the
-//! design decisions.
-//!
-//! Each native method is declared with `jni`'s [`native_method!`] macro
-//! rather than a hand-written `#[no_mangle] extern "system" fn Java_...`:
-//! the macro derives the mangled export name and the JNI signature from the
-//! Rust function itself, so the two cannot drift apart the way a
-//! hand-typed name string and a hand-typed `"(Landroid/...;)V"` signature
-//! routinely do. `error_policy = LogErrorAndDefault` matches
-//! `Notifications.kt`'s own posture: a failure here (a lost connection, a
-//! JNI call that threw) is reported to logcat, not thrown back into Java
-//! as an exception that would crash the app over something recoverable.
-//!
-//! Each `const _: NativeMethod = native_method! { ... };` binding is
-//! otherwise unused by name -- `_` is the idiomatic way to keep a
-//! side-effecting const (here, generating the `#[export_name]`d function
-//! the JVM resolves by the JNI naming convention) without a `dead_code`
-//! warning for a binding nothing reads.
-
 mod jcall;
 mod notify;
 mod settings;
@@ -28,15 +8,6 @@ use jni::objects::{JClass, JObject};
 use jni::sys::jint;
 use jni::{Env, NativeMethod, native_method};
 
-/// Installs the `log` backend that routes to logcat, once per process.
-/// Without it, `LogErrorAndDefault` (every native method below) and any
-/// `log::error!` inside `jni` itself (e.g. `JString`'s `Display` fallback)
-/// call into the `log` facade's default no-op logger, and a real failure
-/// vanishes with nothing on logcat to say so -- silently *more* wrong than
-/// crashing, since nothing on screen or in the log says a notification was
-/// dropped. Called from every entry point below rather than a Java-side
-/// `Application.onCreate`, since this crate deliberately has no such class
-/// to hook (see RUST.md's E3 entry on the two-Java-classes floor).
 fn ensure_logger() {
     static ONCE: std::sync::Once = std::sync::Once::new();
     ONCE.call_once(|| {
@@ -65,8 +36,6 @@ const _: NativeMethod = native_method! {
     error_policy = LogErrorAndDefault,
 };
 
-/// `MainActivity.nativeHandleIntent` -- called from `onCreate` and
-/// `onNewIntent`. See `share::handle_intent` for what an intent can mean.
 fn native_handle_intent<'local>(
     env: &mut Env<'local>,
     _class: JClass<'local>,
@@ -84,9 +53,6 @@ const _: NativeMethod = native_method! {
     error_policy = LogErrorAndDefault,
 };
 
-/// `NotificationService.nativeSync` -- called both from `MainActivity` (an
-/// enrollment may have just landed) and from `NotificationService.sync`
-/// itself. See `notify::sync`.
 fn native_sync<'local>(
     env: &mut Env<'local>,
     _class: JClass<'local>,
@@ -103,7 +69,6 @@ const _: NativeMethod = native_method! {
     error_policy = LogErrorAndDefault,
 };
 
-/// `NotificationService.nativeOnStartCommand`. See `notify::on_start_command`.
 fn native_on_start_command<'local>(
     env: &mut Env<'local>,
     _class: JClass<'local>,
@@ -120,7 +85,6 @@ const _: NativeMethod = native_method! {
     error_policy = LogErrorAndDefault,
 };
 
-/// `NotificationService.nativeOnDestroy`. See `notify::on_destroy`.
 fn native_on_destroy<'local>(
     _env: &mut Env<'local>,
     _class: JClass<'local>,

app-rust/src/shell/notify.rs

@@ -25,7 +25,6 @@ const ALERT_CHANNEL: &str = "sessions";
 const ONGOING_CHANNEL: &str = "connection";
 const ONGOING_ID: i32 = 1;
 const ALERT_ID: i32 = 2;
-/// Same backoff as `Notifications.kt`'s `RECONNECT_DELAY_MS`.
 const RECONNECT_DELAY: Duration = Duration::from_millis(5_000);
 
 /// Whether the follow-loop thread is already running. **A deviation from
@@ -45,17 +44,6 @@ const RECONNECT_DELAY: Duration = Duration::from_millis(5_000);
 /// same guard back to `Notifications.kt` separately.
 static RUNNING: AtomicBool = AtomicBool::new(false);
 
-/// Set by `nativeOnDestroy`, checked by the follow loop between
-/// reconnects. **Known gap, recorded rather than hidden**: unlike
-/// `HttpURLConnection.disconnect()` in the Kotlin original, nothing here
-/// can interrupt a `ureq` read already blocked inside one connection --
-/// `Transport::stream` hands back a plain `Read` with no cancellation
-/// handle. So a stop lands at the next reconnect, not mid-read. `/notifications`
-/// is idle between events (a keep-alive, per `server/src/routes.rs`), so in
-/// practice this is a bounded wait rather than a hang; closing that gap
-/// for real means adding a cancellation point to `crate::client::Transport`,
-/// which is a decision affecting every caller of that trait, not just this
-/// one -- left for whoever next depends on prompt shutdown.
 static STOPPING: AtomicBool = AtomicBool::new(false);
 
 fn static_int(env: &mut Env, class: &str, field: &str) -> Result<i32> {
@@ -328,11 +316,6 @@ pub fn sync(env: &mut Env, context: &JObject) -> Result<()> {
     Ok(())
 }
 
-/// The `Service.onStartCommand` body -- loads settings, starts the
-/// foreground notification, and spawns the follow-loop thread. Answers the
-/// platform's `START_STICKY`/`START_NOT_STICKY` constant, read from the
-/// framework rather than hardcoded so a wrong guess at their values cannot
-/// silently pick the other behaviour.
 pub fn on_start_command(env: &mut Env, service: JObject) -> jint {
     match try_start(env, &service) {
         Ok(true) => static_int(env, "android/app/Service", "START_STICKY").unwrap_or(1),
@@ -381,9 +364,6 @@ fn try_start(env: &mut Env, service: &JObject) -> Result<bool> {
     std::thread::Builder::new()
         .name("ai-app-notifications".to_string())
         .spawn(move || {
-            // Requests a *permanent* attachment (detached only when this thread
-            // exits), matching the Kotlin original's `thread(isDaemon = true)`:
-            // this is the long-lived follow loop, not a one-shot callback.
             let _: jni::errors::Result<()> = vm.attach_current_thread(|env| {
                 follow_loop(env, &context, settings, &ca);
                 Ok(())
@@ -393,12 +373,6 @@ fn try_start(env: &mut Env, service: &JObject) -> Result<bool> {
     Ok(true)
 }
 
-/// Follows the backend's notification stream, reconnecting until stopped
-/// -- mirrors `Notifications.kt`'s `follow`. A dropped connection is the
-/// ordinary case, so it retries quietly and forever; nothing is shown when
-/// it cannot connect, for the same reason as the Kotlin original: a
-/// notification saying "I could not tell you whether anything happened" is
-/// noise about a condition nobody can act on.
 fn follow_loop(env: &mut Env, context: &JObject, settings: ServerSettings, ca: &[u8]) {
     while !STOPPING.load(Ordering::SeqCst) {
         if let Ok(transport) = UreqTransport::new(settings.base_url(), settings.token.clone(), ca) {
@@ -416,9 +390,6 @@ fn follow_loop(env: &mut Env, context: &JObject, settings: ServerSettings, ca: &
     }
 }
 
-/// One notification per session, replacing that session's previous one --
-/// mirrors `Notifications.kt`'s `show`, minus the on-screen/banner
-/// branches this module's doc comment explains.
 fn show(env: &mut Env, context: &JObject, notification: &SessionNotification) -> Result<()> {
     let manager = notification_manager(env, context)?;
     let sdk = static_int(env, "android/os/Build$VERSION", "SDK_INT")?;
@@ -534,8 +505,6 @@ fn show(env: &mut Env, context: &JObject, notification: &SessionNotification) ->
     Ok(())
 }
 
-/// Ends the follow loop -- mirrors `Notifications.kt`'s `onDestroy`, with
-/// the gap this module's `STOPPING` doc explains.
 pub fn on_destroy() {
     STOPPING.store(true, Ordering::SeqCst);
     // `RUNNING`'s path out. Same race as `STOPPING` itself (this doc's own

app-rust/src/shell/settings.rs

@@ -28,11 +28,6 @@ impl ServerSettings {
     }
 }
 
-/// This experiment's own scheme and Keystore alias -- distinct from the
-/// production app's (`aiapp` / `aiapp-token-key`) so the two can be
-/// installed side by side on the same development device without
-/// colliding over which one a scanned QR or a deep link resolves to. See
-/// RUST.md's E3 entry for why they are not the same value.
 pub(crate) const SCHEME: &str = "aiappshell";
 const KEY_ALIAS: &str = "aiapp-shell-token-key";
 const STORE_CLASS: &str = "com/example/wgapplink/ServerStore";
@@ -81,7 +76,6 @@ pub fn load(env: &mut Env, context: &JObject) -> Result<Option<ServerSettings>>
     Ok(Some(read_settings(env, &settings_obj)?))
 }
 
-/// Seals and stores `settings` -- mirrors `ServerConfig.kt`'s `saveServerSettings`.
 pub fn save(env: &mut Env, context: &JObject, settings: &ServerSettings) -> Result<()> {
     let store = new_store(env)?;
     let host = crate::shell::jcall::jstr_obj(env, &settings.host)?;
@@ -106,9 +100,6 @@ pub fn save(env: &mut Env, context: &JObject, settings: &ServerSettings) -> Resu
     Ok(())
 }
 
-/// Parses an `aiappshell://enroll?...` URI -- mirrors `ServerConfig.kt`'s
-/// `parseEnrollmentUri`, asking the same Kotlin code that already owns the
-/// query-parameter rules rather than re-deriving them here.
 pub fn parse_enrollment_uri(env: &mut Env, uri: &JObject) -> Result<Option<ServerSettings>> {
     let store = new_store(env)?;
     let settings_obj = crate::shell::jcall::call_method(

app-rust/src/shell/share.rs

@@ -1,23 +1,3 @@
-//! Deep links and the share sheet -- ported from `MainActivity.kt`'s
-//! `handleIntent`/`onNewIntent` and `Share.kt`'s `sharedContent`.
-//!
-//! **Scope cut, recorded rather than silent**: only shared *text*
-//! (`Intent.EXTRA_TEXT`) is attached to a session. `Attachments.kt`'s
-//! upload path -- `ContentResolver` reads of a shared file/photo URI,
-//! bitmap downscaling, EXIF rotation -- is real work of its own and is not
-//! ported here, because `client-core`'s `ApiClient` does not have the
-//! `/sessions/{id}/attachments` route yet either (see `CLIENT_CORE.md`'s
-//! "not covered" list). So `ACTION_SEND`/`ACTION_SEND_MULTIPLE` with a
-//! `content://` stream and no text falls through to a toast saying so,
-//! rather than silently doing nothing. Closing this gap is the same
-//! `client-core` work whichever caller needs it next.
-//!
-//! **Which session a share lands in** is also a placeholder: with no
-//! screen drawn yet (E4's job), there is no picker to ask, so this attaches
-//! to whichever session has the latest `last_activity` -- the one most
-//! likely to be what somebody meant. Worth revisiting once a real screen
-//! exists to ask instead of guessing.
-
 use crate::client::api::{ApiClient, UreqTransport};
 use jni::Env;
 use jni::errors::Result;
@@ -53,8 +33,6 @@ fn toast(env: &mut Env, context: &JObject, message: &str) -> Result<()> {
     Ok(())
 }
 
-/// The one place an incoming intent is sorted into what it means -- mirrors
-/// `MainActivity.kt`'s `handleIntent`.
 pub fn handle_intent(env: &mut Env, activity: &JObject, intent: &JObject) -> Result<()> {
     let action = get_string_method(env, intent, "getAction")?;
     if matches!(
@@ -86,9 +64,6 @@ fn handle_session_open(env: &mut Env, activity: &JObject, uri: &JObject) -> Resu
     let Some(session_id) = get_string_method(env, uri, "getLastPathSegment")? else {
         return Ok(());
     };
-    // There is no session screen yet (E4's job); the toast is this
-    // experiment's stand-in proof that the tap was routed to the right
-    // session id.
     toast(env, activity, &format!("Opened session {session_id}"))
 }
 
@@ -107,9 +82,6 @@ fn handle_enrollment(env: &mut Env, activity: &JObject, uri: &JObject) -> Result
     }
 }
 
-/// The share sheet -- mirrors `Share.kt`'s `sharedContent` for what counts
-/// as a share, and `AttachmentButton`'s upload-then-message pattern for
-/// what happens to it, minus attachments per this module's doc comment.
 fn handle_share(env: &mut Env, activity: &JObject, intent: &JObject) -> Result<()> {
     let extra_text = crate::shell::jcall::jstr_obj(env, EXTRA_TEXT)?;
     let text = crate::shell::jcall::call_method(