fix: single report under "throw" policy, pre-dispatch stackTrace (iOS parity)

Parity round with NativeScript/ios#409's claim-slot commit, closing the
review's cross-platform divergences:

- Single report per failure under uncaughtErrorPolicy: "throw": the full
  report (cancelable event -> hook -> log) now runs at the decision
  point BEFORE the native throw, for both the sync boundary and the
  rejection drain, and the thrown com.tns.NativeScriptException is
  marked reportedToJs (isolate-private brand carried to a Java field by
  ReThrowToJava; set directly for the rejection looper throw) so
  NativeScriptUncaughtExceptionHandler skips the post-mortem
  re-report. Previously a "throw"-policy rejection fired
  unhandledrejection AND a second post-mortem error event. The public
  NativeScriptException.isReportedToJs() lets custom
  Thread.UncaughtExceptionHandler implementations honor the same
  contract.
- preventDefault() now beats the "throw" policy at the sync boundary
  too: the event dispatches before the propagation decision, so a
  prevented error is fully contained with the app alive (iOS behavior).
  The deprecated discard flag disables the throw, matching iOS.
- error.stackTrace / reason.stackTrace (the combined legacy stack, a
  NativeScript extension) are populated BEFORE the error /
  unhandledrejection events dispatch - including the worker branch of
  the rejection drain - so listeners see the same shape the hooks do;
  pinned by new spec assertions mirroring the iOS ones.
- Docs: unified "throw" sequencing and the cross-platform catchability
  note (Android sync at the method boundary; iOS sync only at
  own-frame-reporting boundaries, deferred for block/method callbacks
  and loop-originated errors; escapeException is the portable per-call
  interception tool), plus the Android-only native-crash event
  asymmetry and the interop feature-detection note.

Full suite green on an API 35 arm64 emulator: 604 specs, 0 failures.

Author: edusperoni

docs/error-handling.md

@@ -120,6 +120,7 @@ throw interop.escapeException(new java.io.IOException("x"));
 - Otherwise a `com.tns.NativeScriptException` is thrown as usual, but with its stack trace replaced by frames synthesized from the JS stack, so crash reporters group it by where it actually happened in JS.
 - The `escapeException()` call site's stack is recorded too — for non-Error values (`escapeException("boom")`) it is the only stack available.
 - Branded escapes bypass `discardUncaughtJsExceptions` (an explicit forward request must reach the caller).
+- The `interop` global is new in this release with `escapeException` as its only member — shared code targeting older runtimes should feature-detect: `global.interop?.escapeException`.
 
 ## Native (Java) API
 
@@ -174,7 +175,7 @@ One policy key in the app's `package.json` (root level) governs what happens to
 | `uncaughtErrorPolicy` | Effect |
 |---|---|
 | `"report"` (default) | Report (event → hook → log) and continue. Never crashes. |
-| `"throw"` | After the (cancelable) event, the error is thrown to the native layer as a real Java exception — `com.tns.NativeScriptException` with the JS frames as its stack trace — and reported through the thread's uncaught-exception path. This typically ends the process (the pre-9.1 default), though a native catch or a custom `UncaughtExceptionHandler` above the boundary can still intercept it, which is why the policy names the mechanism, not a guaranteed crash. Unhandled rejections are thrown from a clean frame on the runtime's looper. |
+| `"throw"` | The full report runs first, at the decision point — cancelable event (`preventDefault()` still fully contains the error, same as iOS), then hook and log — and the error is *then* thrown to the native layer as a real Java exception: `com.tns.NativeScriptException` with the JS frames as its stack trace, marked `isReportedToJs()` so the uncaught-exception path does not report the same failure twice. This typically ends the process (the pre-9.1 default), though the policy names the mechanism, not a guaranteed crash. Unhandled rejections are thrown from a clean frame on the runtime's looper. **Cross-platform note:** on Android the sync throw unwinds through the native caller at the method boundary, so a Java `try/catch` above it can intercept; on iOS the rethrow is synchronous (catchable) only at boundaries that report within their own frame (property accessors, adapter reads) — block/overridden-method callbacks and loop-originated errors fall back to a deferred clean-frame throw. Portable code that needs a native-interceptable exception for a *specific* call should use `interop.escapeException`, which behaves identically on both platforms at every boundary; the policy governs unprevented, already-reported errors only. |
 
 Deprecated (kept for the transition, both emit a logcat warning):
 
@@ -189,8 +190,9 @@ Terminal-path decision table:
 |---|---|---|
 | uncaught error, default (`"report"`) | `__onUncaughtError` | no |
 | uncaught error, `"report"` + `discardUncaughtJsExceptions: true` | `__onDiscardedError` | no |
-| uncaught error, listener called `preventDefault()` | none | no |
-| uncaught error / unhandled rejection, `"throw"`, unprevented | `__onUncaughtError` (via the uncaught-exception path) | yes, normally |
+| uncaught error, listener called `preventDefault()` (either policy) | none | no |
+| uncaught error / unhandled rejection, `"throw"`, unprevented | `__onUncaughtError` (at the decision point, before the throw) | yes, normally |
+| uncaught error / unhandled rejection, `"throw"` + `discardUncaughtJsExceptions: true` | `__onDiscardedError` | no (discard disables the throw, matching iOS) |
 | unhandled rejection / `reportError`, `"report"`, unprevented | `__onUncaughtError` | no |
 | unhandled rejection / `reportError`, `preventDefault()` | none | no |
 
@@ -220,7 +222,9 @@ Java side — for exceptions that never pass through the JS event layer (escaped
 
 - **Containment is boundary-outermost.** The runtime tracks the depth of in-flight JS→Java calls; a throw with JS frames waiting below the boundary propagates (so `try { javaApi.call(cb) } catch` works, with the original JS error object restored across the crossing), and is contained only at an outermost native-initiated entry. `interop.escapeException` and `uncaughtErrorPolicy: "throw"` are the two ways an error crosses that outermost boundary.
 - **Contained callbacks return type defaults.** A throwing overridden method hands its Java caller `null` for reference types and `0`/`false` for primitives (the runtime substitutes the default before unboxing, so no `NullPointerException` from the binding). The error is loudly reported *before* the caller resumes, so logcat shows the real failure ahead of any downstream symptom. If the Java contract genuinely needs the exception, use `interop.escapeException`.
-- Every error is reported exactly once: either the containment point, the rejection drain (once per looper turn, scheduled on the runtime's `ALooper`), `reportError`, or — under `"throw"` — the thread's uncaught-exception path. Never two of them for the same error.
+- Every error is reported exactly once, at its decision point: the containment boundary, the rejection drain (once per looper turn, scheduled on the runtime's `ALooper`), or `reportError`. Under `"throw"` the report still happens at the decision point and the thrown `NativeScriptException` carries `isReportedToJs()`, which the uncaught-exception handler honors by not reporting again — one event per failure on both platforms.
+- The legacy `stackTrace` property (combined JS + Java frames, a NativeScript extension) is set on the error/reason **before** the event dispatches, so listeners and hooks see the same shape. The standard `e.error.stack` is always there for spec-shaped code.
 - A rejection that gets a handler before the end-of-turn drain is never reported (and produces no `rejectionhandled` either).
+- **Android-only asymmetry:** the `error` event also fires for *pure-native* Java uncaught exceptions — the app-level `NativeScriptUncaughtExceptionHandler` reports any crashing `Throwable` through `passUncaughtExceptionToJs`, with no iOS analogue. `preventDefault()` there suppresses the error activity and the default (killing) handler, but the throwing thread has already unwound — on the main thread the looper is gone, so realistic recovery is limited to background threads.
 - Module/script evaluation (`runModule`/`runScript`, app bootstrap) is not contained — an app whose main module fails to load still fails loudly.
 - Worker isolates run the same machinery: each worker has its own tracker, drain, event layer and containment.

test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js

@@ -73,6 +73,10 @@ describe("uncaughtErrorPolicy (default: report)", function () {
             expect(received).not.toBeNull();
             // The event carries the actual thrown value.
             expect(received.error).toBe(reason);
+            // The combined `stackTrace` string is populated BEFORE dispatch,
+            // so listeners can read it (not only e.error.stack).
+            expect(typeof received.error.stackTrace).toBe("string");
+            expect(received.error.stackTrace.length).toBeGreaterThan(0);
             // Unprevented, so the legacy hook fired too.
             expect(uncaughtSeen(reason)).toBe(true);
             // And the app is still running.

test-app/app/src/main/assets/app/tests/testUnhandledRejections.js

@@ -132,6 +132,10 @@ describe("unhandled promise rejections", function () {
             expect(received.type).toBe("unhandledrejection");
             expect(received.reason).toBe(reason);
             expect(typeof received.promise.then).toBe("function");
+            // The drain sets a combined `stackTrace` on the (object) reason
+            // BEFORE dispatching the event, so a listener sees it.
+            expect(typeof received.reason.stackTrace).toBe("string");
+            expect(received.reason.stackTrace.length).toBeGreaterThan(0);
             afterQuietTurns(function () {
                 expect(reportedSeen(reason)).toBe(false);
                 done();

test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java

@@ -24,7 +24,12 @@ public void uncaughtException(Thread thread, Throwable ex) {
 
         boolean handledByJs = false;
 
-        if (Runtime.isInitialized()) {
+        // An uncaughtErrorPolicy: "throw" exception was already fully reported
+        // to JS (event + hook + log) at the throw decision point - reporting
+        // it again here would double-dispatch the same failure.
+        boolean alreadyReportedToJs = ex instanceof NativeScriptException && ((NativeScriptException) ex).isReportedToJs();
+
+        if (Runtime.isInitialized() && !alreadyReportedToJs) {
             try {
                 if (Util.isDebuggableApp(context)) {
                     System.err.println(errorMessage);

test-app/runtime/src/main/cpp/NativeScriptException.cpp

@@ -18,6 +18,10 @@ using namespace std;
 using namespace tns;
 using namespace v8;
 
+/* Defined below, next to ContainUncaughtCallbackException. */
+static void MarkReportedToJs(Isolate* isolate, Local<Value> error);
+static bool IsMarkedReportedToJs(Isolate* isolate, Local<Value> error);
+
 NativeScriptException::NativeScriptException(JEnv& env)
     : m_javascriptException(nullptr) {
   m_javaException = JniLocalRef(env.ExceptionOccurred());
@@ -157,6 +161,16 @@ void NativeScriptException::ReThrowToJava() {
           env.GetFieldID(NATIVESCRIPTEXCEPTION_CLASS, "escapedFromJs", "Z");
       env.SetBooleanField(ex, escapedFromJsField, JNI_TRUE);
     }
+
+    // A `uncaughtErrorPolicy: "throw"` propagation whose report already ran
+    // at the boundary: carry the mark so the post-mortem uncaught path does
+    // not report the same failure a second time. `ex` is always a
+    // com.tns.NativeScriptException at this point.
+    if (ex != nullptr && IsMarkedReportedToJs(isolate, errObj)) {
+      static jfieldID reportedToJsField =
+          env.GetFieldID(NATIVESCRIPTEXCEPTION_CLASS, "reportedToJs", "Z");
+      env.SetBooleanField(ex, reportedToJsField, JNI_TRUE);
+    }
   } else if (!m_message.empty()) {
     JniLocalRef msg(env.NewStringUTF(m_message.c_str()));
     JniLocalRef stackTrace(env.NewStringUTF(m_stackTrace.c_str()));
@@ -324,27 +338,37 @@ void NativeScriptException::ReportUnhandledRejection(Isolate* isolate,
                                                      Local<Promise> promise,
                                                      Local<Value> reason,
                                                      const string& stackTrace) {
+  // Populate the legacy `stackTrace` property before dispatch so event
+  // listeners see the same shape the hooks do (matches the sync path).
+  if (reason->IsObject() && !stackTrace.empty()) {
+    auto context = isolate->GetCurrentContext();
+    reason.As<Object>()
+        ->Set(context, V8StringConstants::GetStackTrace(isolate),
+              ArgConverter::ConvertToV8String(isolate, stackTrace))
+        .FromMaybe(false);
+  }
+
   if (ErrorEvents::DispatchUnhandledRejection(isolate, promise, reason)) {
     return;
   }
 
   auto runtime = GetRuntimeOrNull(isolate);
-  if (runtime != nullptr &&
+  bool discard =
+      runtime != nullptr && runtime->GetDiscardUncaughtJsExceptions();
+  ReportFatalTail(isolate, reason, stackTrace, "Unhandled promise rejection:",
+                  discard ? JNI_TRUE : JNI_FALSE);
+
+  // The report is complete (event + hook + log, exactly once). Under the
+  // "throw" policy the rejection is additionally handed to the native layer;
+  // the thrown exception is marked reported-to-JS so the post-mortem
+  // uncaught path does not report it a second time. The deprecated discard
+  // flag disables the throw, matching iOS.
+  if (runtime != nullptr && !discard &&
       runtime->GetUncaughtErrorPolicy() == Runtime::UncaughtErrorPolicy::Throw) {
-    // Hand the rejection to the native layer; the post-mortem uncaught path
-    // performs the (single) report, exactly as for a sync uncaught error.
     string message =
         "Unhandled promise rejection: " + ToDetailString(isolate, reason);
     ThrowUncaughtJsErrorToJava(message, stackTrace);
-    return;
   }
-
-  jboolean isDiscarded =
-      (runtime != nullptr && runtime->GetDiscardUncaughtJsExceptions())
-          ? JNI_TRUE
-          : JNI_FALSE;
-  ReportFatalTail(isolate, reason, stackTrace, "Unhandled promise rejection:",
-                  isDiscarded);
 }
 
 void NativeScriptException::ReportFatalTail(Isolate* isolate,
@@ -389,6 +413,38 @@ void NativeScriptException::ReportFatalTail(Isolate* isolate,
   }
 }
 
+/*
+ * Marks a JS error value whose report already ran (event + hook + log), via
+ * an isolate-private symbol. ReThrowToJava carries the mark over to the Java
+ * com.tns.NativeScriptException so the post-mortem uncaught-exception path
+ * does not report the same failure a second time.
+ */
+static Local<Private> GetReportedToJsBrand(Isolate* isolate) {
+  return Private::ForApi(
+      isolate, ArgConverter::ConvertToV8String(isolate, "tns::reportedToJs"));
+}
+
+static void MarkReportedToJs(Isolate* isolate, Local<Value> error) {
+  if (!error->IsObject()) {
+    return;
+  }
+  auto context = isolate->GetCurrentContext();
+  error.As<Object>()
+      ->SetPrivate(context, GetReportedToJsBrand(isolate),
+                   v8::True(isolate))
+      .FromMaybe(false);
+}
+
+static bool IsMarkedReportedToJs(Isolate* isolate, Local<Value> error) {
+  if (!error->IsObject()) {
+    return false;
+  }
+  auto context = isolate->GetCurrentContext();
+  return error.As<Object>()
+      ->HasPrivate(context, GetReportedToJsBrand(isolate))
+      .FromMaybe(false);
+}
+
 bool NativeScriptException::ContainUncaughtCallbackException(Isolate* isolate,
                                                              v8::TryCatch& tc) {
   auto runtime = GetRuntimeOrNull(isolate);
@@ -409,7 +465,7 @@ bool NativeScriptException::ContainUncaughtCallbackException(Isolate* isolate,
   }
 
   // Branded interop.escapeException: an explicit forward to the native
-  // caller - never contained.
+  // caller - never contained, never reported here.
   if (error->IsObject()) {
     JEnv env;
     Interop::EscapedExceptionInfo escapeInfo;
@@ -421,14 +477,10 @@ bool NativeScriptException::ContainUncaughtCallbackException(Isolate* isolate,
     }
   }
 
-  if (runtime->GetUncaughtErrorPolicy() == Runtime::UncaughtErrorPolicy::Throw) {
-    // Pre-9.1 semantics: the exception is thrown to the Java caller and the
-    // post-mortem uncaught-exception path performs the (single) report.
-    return false;
-  }
-
-  // Contain: report through the WHATWG pipeline (`error` event -> legacy
-  // hook -> log) and let the caller resume with a default value.
+  // Report through the WHATWG pipeline at the decision point, for both
+  // policies (same sequence as iOS): `error` event first - preventDefault()
+  // fully contains the error even under the "throw" policy - then the legacy
+  // hook and log.
   string errorMessage;
   string stackTrace;
   auto message = tc.Message();
@@ -440,20 +492,42 @@ bool NativeScriptException::ContainUncaughtCallbackException(Isolate* isolate,
     stackTrace = GetStackTraceOfValue(isolate, error);
   }
 
+  // Populate the legacy `stackTrace` property before dispatch so event
+  // listeners see the same shape the hooks do.
+  if (error->IsObject() && !stackTrace.empty()) {
+    auto context = isolate->GetCurrentContext();
+    error.As<Object>()
+        ->Set(context, V8StringConstants::GetStackTrace(isolate),
+              ArgConverter::ConvertToV8String(isolate, stackTrace))
+        .FromMaybe(false);
+  }
+
+  bool discard = runtime->GetDiscardUncaughtJsExceptions();
   {
     // A throwing listener or hook must not escape into the caller.
     v8::TryCatch reportTc(isolate);
-    if (!ErrorEvents::DispatchError(isolate, error, errorMessage, stackTrace)) {
-      jboolean isDiscarded =
-          runtime->GetDiscardUncaughtJsExceptions() ? JNI_TRUE : JNI_FALSE;
-      ReportFatalTail(isolate, error, stackTrace, "", isDiscarded);
+    if (ErrorEvents::DispatchError(isolate, error, errorMessage, stackTrace)) {
+      tc.Reset();
+      return true;
     }
+    ReportFatalTail(isolate, error, stackTrace, "",
+                    discard ? JNI_TRUE : JNI_FALSE);
     if (reportTc.HasCaught()) {
       DEBUG_WRITE_FORCE(
           "ContainUncaughtCallbackException: exception while reporting");
     }
   }
 
+  // The report is complete (exactly once). Under the "throw" policy the
+  // exception is additionally propagated to the Java caller, marked so the
+  // post-mortem uncaught path skips re-reporting. The deprecated discard
+  // flag disables the throw, matching iOS.
+  if (!discard &&
+      runtime->GetUncaughtErrorPolicy() == Runtime::UncaughtErrorPolicy::Throw) {
+    MarkReportedToJs(isolate, error);
+    return false;
+  }
+
   tc.Reset();
   return true;
 }
@@ -637,6 +711,16 @@ void PromiseRejectionTracker::Drain() {
 
       string stackTrace = GetStackTraceOfValue(isolate, reason);
 
+      // Populate the legacy `stackTrace` property before dispatch so event
+      // listeners see it - covers both the worker and main branches below
+      // (ReportUnhandledRejection's own set is idempotent).
+      if (reason->IsObject() && !stackTrace.empty()) {
+        reason.As<Object>()
+            ->Set(context, V8StringConstants::GetStackTrace(isolate),
+                  ArgConverter::ConvertToV8String(isolate, stackTrace))
+            .FromMaybe(false);
+      }
+
       if (workerWrapper != nullptr) {
         // Dispatch the rejection event on the worker's own global first;
         // preventDefault() there fully handles it. Only when unprevented fall

test-app/runtime/src/main/java/com/tns/NativeScriptException.java

@@ -12,11 +12,28 @@ public class NativeScriptException extends RuntimeException {
      * discardUncaughtJsExceptions handling.
      */
     private boolean escapedFromJs = false;
+    /*
+     * Set (natively or by the runtime) when this exception's failure was
+     * already reported to JS (error/unhandledrejection event, hooks, log) at
+     * the uncaughtErrorPolicy: "throw" decision point. Custom
+     * Thread.UncaughtExceptionHandler implementations should skip
+     * Runtime.passUncaughtExceptionToJs for such exceptions so the failure
+     * is not reported twice.
+     */
+    private boolean reportedToJs = false;
 
     boolean isEscapedFromJs() {
         return escapedFromJs;
     }
 
+    void markReportedToJs() {
+        reportedToJs = true;
+    }
+
+    public boolean isReportedToJs() {
+        return reportedToJs;
+    }
+
     public NativeScriptException() {
         super();
     }

test-app/runtime/src/main/java/com/tns/Runtime.java

@@ -1375,6 +1375,10 @@ private static Object defaultPrimitiveValue(Class<?> type) {
     private static void throwUncaughtJsErrorOnCurrentThread(String message, String stackTrace) {
         final NativeScriptException ex = new NativeScriptException(message, stackTrace, 0);
         JavaScriptStackTrace.applyFrames(ex, stackTrace, null);
+        // The failure was already reported (event + hook + log) at the throw
+        // decision point - the uncaught-exception handler must not report it
+        // a second time.
+        ex.markReportedToJs();
         android.os.Looper looper = android.os.Looper.myLooper();
         if (looper == null) {
             throw ex;