@mentra/crust 3.3.0-dev.598 → 3.3.0-dev.600

package/android/src/main/java/com/mentra/crust/CrustModule.kt

@@ -308,7 +308,8 @@ class CrustModule : Module() {
                       ?: appContext.currentActivity
                               ?: throw IllegalStateException("MentraJS: no context")
       val json = org.json.JSONObject(envelope as Map<*, *>).toString()
-      JSCRuntime.shared(ctx).dispatchToJs(packageName, json)
+      val deliveryId = (envelope["deliveryId"] as? Number)?.toLong()?.takeIf { it > 0 }
+      JSCRuntime.shared(ctx).dispatchToJs(packageName, json, deliveryId)
     }.runOnQueue(mentraJsQueue)
 
     AsyncFunction("mentraJsSetManifest") { packageName: String, permissions: List<String> ->

package/android/src/main/java/com/mentra/crust/jsc/JSCRuntime.kt

@@ -1,6 +1,7 @@
 package com.mentra.crust.jsc
 
 import android.content.Context
+import android.os.SystemClock
 import android.util.Log
 import com.dokar.quickjs.QuickJs
 import com.dokar.quickjs.binding.function
@@ -11,6 +12,7 @@ import java.util.concurrent.Executors
 import java.util.concurrent.ScheduledExecutorService
 import java.util.concurrent.ScheduledFuture
 import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicLong
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.runBlocking
 
@@ -133,6 +135,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
     val dispatcher: JSCDispatcher = JSCDispatcher(appContext)
 
     private val contexts = ConcurrentHashMap<String, ContextRecord>()
+    private val nextContextId = AtomicLong()
     private val polyfillBundle: String by lazy { loadPolyfillBundle() }
 
     // Schedule pool for timers; per-context the executor is the same as the
@@ -146,6 +149,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
         val packageName: String,
         val qjs: QuickJs,
         val executor: ExecutorService,
+        val contextId: Long,
         val pendingTimers: MutableMap<Int, ScheduledFuture<*>> = ConcurrentHashMap(),
         @Volatile var readyAcked: Boolean = false,
         @Volatile var readyNackTimer: ScheduledFuture<*>? = null,
@@ -273,6 +277,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
             packageName = packageName,
             qjs = qjs,
             executor = executor,
+            contextId = nextContextId.incrementAndGet(),
         )
         contexts[packageName] = record
 
@@ -457,10 +462,23 @@ class JSCRuntime private constructor(private val appContext: Context) {
      * Push a `{kind: "event"|"response", …}` envelope into the named
      * context's globalThis.__deliver. Hops onto the per-context executor.
      */
-    fun dispatchToJs(packageName: String, envelopeJson: String) {
-        val record = contexts[packageName] ?: return
+    fun dispatchToJs(packageName: String, envelopeJson: String, deliveryId: Long? = null) {
+        val record = contexts[packageName]
+        // Only host-generated PINGs carry this ID. Ordinary media/event deliveries stay quiet.
+        val diagnostic = deliveryId?.let {
+            JSDeliveryDiagnostics(it, record?.contextId, SystemClock::elapsedRealtime) { metadata ->
+                reportDeliveryDiagnostic(packageName, metadata)
+            }
+        }
+        diagnostic?.entry()
+        if (record == null) {
+            diagnostic?.dropped("context-missing")
+            return
+        }
+        diagnostic?.queued()
         try {
             record.executor.submit {
+                diagnostic?.started()
                 // Arm only once evaluate is about to run. Queue wait during a
                 // long previous turn (WHIP start, etc.) must not count — that
                 // was firing ready_nack while the context was merely busy.
@@ -489,14 +507,26 @@ class JSCRuntime private constructor(private val appContext: Context) {
                     kill(packageName)
                 }, WATCHDOG_KILL_MS, TimeUnit.MILLISECONDS)
                 record.watchdogTimer = killTimer
+                var failure: Throwable? = null
                 try {
                     val source = "globalThis.__deliver(${jsStringLiteral(envelopeJson)});"
                     runBlocking {
                         record.qjs.evaluate<Any?>(source, filename = "mentrajs:deliver.js")
                     }
                 } catch (e: Throwable) {
+                    failure = e
                     Log.w(TAG, "dispatchToJs threw in $packageName: ${e.message}", e)
+                    if (diagnostic == null) {
+                        reportDeliveryDiagnostic(packageName, mapOf(
+                            "event" to "native-delivery-failed",
+                            "contextId" to record.contextId,
+                            "phase" to "evaluate-failed",
+                            "errorClass" to e.javaClass.simpleName,
+                            "causeClass" to e.cause?.javaClass?.simpleName,
+                        ))
+                    }
                 } finally {
+                    diagnostic?.finished(failure)
                     // Success or throw: the host observed the turn end.
                     record.readyNackTimer?.cancel(false)
                     record.readyNackTimer = null
@@ -505,8 +535,26 @@ class JSCRuntime private constructor(private val appContext: Context) {
                     if (record.watchdogTimer === killTimer) record.watchdogTimer = null
                 }
             }
-        } catch (_: java.util.concurrent.RejectedExecutionException) {
-            // Context killed mid-flight — drop. dispatchToJs is best-effort.
+        } catch (e: java.util.concurrent.RejectedExecutionException) {
+            diagnostic?.dropped("executor-rejected", e)
+            Log.w(TAG, "dispatchToJs rejected for $packageName", e)
+        }
+    }
+
+    private fun reportDeliveryDiagnostic(packageName: String, metadata: Map<String, Any?>) {
+        val line = org.json.JSONObject(metadata as Map<*, *>).toString()
+        Log.i(TAG, line)
+        // Use the existing miniapp log route so console interception includes this in reports.
+        try {
+            deliverOrDrop(OutboundMessage(packageName, mapOf(
+                "packageName" to packageName,
+                "iface" to "__log",
+                "method" to if (metadata["errorClass"] == null) "log" else "warn",
+                "argsJson" to org.json.JSONArray().put(org.json.JSONObject(metadata as Map<*, *>)).toString(),
+            )))
+        } catch (e: Throwable) {
+            // Observability cannot change delivery or hide its original failure.
+            Log.w(TAG, "delivery diagnostic forwarding failed: ${e.javaClass.simpleName}")
         }
     }
 

package/android/src/main/java/com/mentra/crust/jsc/JSDeliveryDiagnostics.kt

@@ -0,0 +1,44 @@
+package com.mentra.crust.jsc
+
+/** Metadata for one host PING. Never retains the envelope or exception message. */
+internal class JSDeliveryDiagnostics(
+    private val deliveryId: Long,
+    private val contextId: Long?,
+    private val clockMs: () -> Long,
+    private val emit: (Map<String, Any?>) -> Unit,
+) {
+    private val enteredAtMs = clockMs()
+    private var queuedAtMs: Long? = null
+    private var startedAtMs: Long? = null
+
+    fun entry() = report("native-entry")
+
+    fun queued() {
+        queuedAtMs = clockMs()
+        report("queued")
+    }
+
+    fun started() {
+        startedAtMs = clockMs()
+        report("started")
+    }
+
+    fun finished(error: Throwable? = null) = report(if (error == null) "finished" else "evaluate-failed", error)
+
+    fun dropped(reason: String, error: Throwable? = null) = report(reason, error)
+
+    private fun report(phase: String, error: Throwable? = null) {
+        val now = clockMs()
+        emit(mapOf(
+            "event" to "native-ping-delivery",
+            "deliveryId" to deliveryId,
+            "contextId" to contextId,
+            "phase" to phase,
+            "elapsedMs" to now - enteredAtMs,
+            "queueWaitMs" to queuedAtMs?.let { (startedAtMs ?: now) - it },
+            "evaluateMs" to startedAtMs?.let { now - it },
+            "errorClass" to error?.javaClass?.simpleName,
+            "causeClass" to error?.cause?.javaClass?.simpleName,
+        ))
+    }
+}

package/android/src/test/java/com/mentra/crust/jsc/JSDeliveryDiagnosticsTest.kt

@@ -0,0 +1,54 @@
+package com.mentra.crust.jsc
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class JSDeliveryDiagnosticsTest {
+    @Test fun `queue wait and evaluate duration are distinct`() {
+        var now = 100L
+        val events = mutableListOf<Map<String, Any?>>()
+        val diagnostic = JSDeliveryDiagnostics(7, 2, { now }, { events += it })
+        diagnostic.entry()
+        now = 110
+        diagnostic.queued()
+        now = 310
+        diagnostic.started()
+        now = 350
+        diagnostic.finished()
+
+        assertEquals(listOf("native-entry", "queued", "started", "finished"), events.map { it["phase"] })
+        assertEquals(200L, events.last()["queueWaitMs"])
+        assertEquals(40L, events.last()["evaluateMs"])
+        assertEquals(250L, events.last()["elapsedMs"])
+        assertEquals(7L, events.last()["deliveryId"])
+        assertEquals(2L, events.last()["contextId"])
+    }
+
+    @Test fun `failure includes exception identity without payload or message`() {
+        val events = mutableListOf<Map<String, Any?>>()
+        val diagnostic = JSDeliveryDiagnostics(1, 4, { 0L }, { events += it })
+        val error = IllegalStateException("private-token user transcript", IllegalArgumentException("private-source"))
+        diagnostic.entry()
+        diagnostic.queued()
+        diagnostic.started()
+        diagnostic.finished(error)
+
+        assertEquals("evaluate-failed", events.last()["phase"])
+        assertEquals("IllegalStateException", events.last()["errorClass"])
+        assertEquals("IllegalArgumentException", events.last()["causeClass"])
+        assertFalse(events.toString().contains("private-"))
+        assertFalse(events.toString().contains("transcript"))
+    }
+
+    @Test fun `missing context and rejected executor have explicit terminal events`() {
+        for (reason in listOf("context-missing", "executor-rejected")) {
+            val events = mutableListOf<Map<String, Any?>>()
+            val diagnostic = JSDeliveryDiagnostics(9, null, { 0L }, { events += it })
+            diagnostic.entry()
+            diagnostic.dropped(reason)
+            assertEquals(reason, events.last()["phase"])
+            assertNull(events.last()["contextId"])
+            assertNull(events.last()["evaluateMs"])
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/crust",
-  "version": "3.3.0-dev.598",
+  "version": "3.3.0-dev.600",
   "description": "Mentra Native Module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -35,7 +35,7 @@
   "license": "Apache-2.0",
   "homepage": "https://github.com/Mentra-Community/MentraOS/tree/dev/mobile/modules/crust#readme",
   "dependencies": {
-    "@mentra/jspolyfill": "3.3.0-dev.598"
+    "@mentra/jspolyfill": "3.3.0-dev.600"
   },
   "devDependencies": {
     "@expo/config-plugins": ">=8.0.0",