test: audit native unwinding and document missing guest traces

Author: matthargett

.github/workflows/shared_continuations.yml

@@ -68,3 +68,14 @@ jobs:
           toolchain: nightly
           components: miri
       - run: cargo miri test --locked -p tinywasm-c-api --features external-host-calls --lib
+
+  native-unwind:
+    name: Native unwind (GDB, C/C++/Rust)
+    runs-on: ubuntu-24.04
+    env:
+      WASM_EXT_TEST_ONLY: "1"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - run: sudo apt-get update && sudo apt-get install -y gdb
+      - run: python3 crates/c-api/tests/continuations/run.py --runtime tinywasm --root . --build build/native-unwind
+      - run: python3 crates/c-api/tests/continuations/debug/run.py --runtime tinywasm --include crates/c-api/include --library build/native-unwind/runtime/release/libtinywasm.a --build build/native-unwind/client --debugger gdb

crates/c-api/tests/continuations/FEATURE_COMPAT.md

@@ -105,3 +105,6 @@ fairness budget. AOT stack suspension, general reference-valued C calls, shared
 memory, arbitrary component graphs and watchOS deployment need separate work.
 All schedulers, component bindings, transport and fixtures remain consumer code
 intended for later out-of-tree extraction.
+
+See the [mixed-stack audit](debug/README.md) for native debugger/crash-report
+coverage and the remaining guest-frame and async-ancestry requirements.

crates/c-api/tests/continuations/README.md

@@ -91,3 +91,6 @@ to match the runtime. WAMR fast-interpreter SIMD is unavailable on Windows.
 Regenerate the portable fixtures with `wasm-tools parse gc.wat -o gc.wasm`
 and `wasm-tools parse simd.wat -o simd.wasm`.
 See [FEATURE_COMPAT.md](FEATURE_COMPAT.md) for results and remaining boundaries.
+
+See the [mixed-stack audit](debug/README.md) for native debugger/crash-report
+coverage and the remaining guest-frame and async-ancestry requirements.

crates/c-api/tests/continuations/debug/README.md

@@ -0,0 +1,115 @@
+# Mixed native and guest stack audit
+
+Full mixed guest/native crash reporting is a readiness requirement for this RFC,
+not a capability established by the continuation and HTTP tests.
+
+The fixture calls Wasm `root -> middle -> leaf -> example:native.call`, then C,
+C++, Rust and optionally Swift. It stops inside the native provider, parks the
+continuation, and traps after resumption. An early-trap case checks failure
+before the first yield. The ordinary-call mode also accepts a WAMR AOT module.
+Provider functions use `noinline` so this test can assert native ABI unwind order;
+this is not a requirement to disable inlining or tail dispatch in the runtime.
+
+## Observed behavior
+
+On macOS arm64, optimized builds recover the native C/C++/Rust/Swift chain in
+LLDB and actual Apple `.ips` reports. Matching dSYM UUIDs are checked. After
+yield, the native backtrace contains the scheduler/driver: the guest continuation
+has no native stack. A physical backtrace must not invent the old frames.
+
+WAMR previously returned an empty C trap trace for continuation failures even
+with `WAMR_BUILD_DUMP_CALL_STACK=1`. The initial error path discarded the trace;
+the resumed error path also released frames before capturing them. Both now
+reuse the ordinary trap mechanism. Tests require all three guest function
+indices for initial, resumed and ordinary failures. This requires the existing
+opt-in call-stack feature; the shared C header has not changed.
+
+TinyWasm still returns an empty `wasm_trap_trace`. Its optimized C adapter invokes
+external callbacks after returning from the interpreter, so the native backtrace
+does not contain an active interpreter frame either. The fixture records this
+limitation, not a successful guest-stack qualification.
+
+WAMR ordinary AOT calls preserve native unwinding and the opt-in logical trap
+trace, but the tested default AOT build shows an unnamed generated-code address
+in LLDB. It does not provide named guest source frames. The separate experimental
+`WAMR_BUILD_DEBUG_AOT` compiler configuration requires LLDB development libraries,
+which were unavailable in the local LLVM 21 installation. Its DWARF registration
+path remains unqualified by this audit.
+
+The fast interpreter's reported offsets are internal compiled-bytecode offsets;
+module offsets may be zero. They must not be presented to a Wasm DWARF symbolizer
+as original Wasm instruction offsets. Function identity is useful; full source
+locations require a retained mapping to the exact original module.
+
+The [recorded observations](observed.json) include native backtraces, minimal
+Apple crash receipts, source hashes and the unchanged disabled artifacts.
+
+## Required out-of-tree diagnostic contract
+
+1. Associate each loaded module with its content hash, component/instance identity,
+   original Wasm/debug sidecar, and native image UUID or build ID. Preserve the
+   component linker's mapping from lowered core functions to original modules.
+2. Provide a bounded, versioned, read-only guest-frame snapshot at host-call and
+   suspension boundaries, with explicit offset coordinate systems and truncation.
+   TinyWasm needs a public capture seam; its current `guest-debug` by-index APIs
+   are insufficient. WAMR's allocating trap-trace API is not a fatal-signal API.
+3. Keep async ancestry in the external scheduler: task/call generation, parent,
+   import identity, and active/pending/completed/cancelled state. Distinguish
+   concurrent streams and reused slots. Show an explicit async boundary rather
+   than treating a resumed callback as a continuous native stack.
+4. Capture no borrowed guest/native pointers across a yield. Publish immutable
+   or coherently versioned records for debugger/crash readers; invalidate them on
+   cancellation and teardown. Do not allocate, acquire runtime locks, invoke
+   callbacks, format strings or re-enter the engine from a fatal-signal handler.
+5. Preserve native unwind metadata and archive matching dSYMs/ELF debug files.
+   Keep inline/tail-call semantics honest. C++ exceptions, Rust panics and Swift
+   errors must be caught/translated before crossing the C ABI; stack inspection
+   does not authorize exception propagation through it.
+6. Compile diagnostic state and capture work out of embedded builds. Use existing
+   runtime frames rather than a second stack updated on every instruction. Bound
+   enabled memory and measure capture cost at native-call boundaries, including
+   high-frequency GPU/audio imports. Disabling diagnostics must retain the LTO
+   binary/RSS/native-call baseline; don't sacrifice tail dispatch for prettier
+   native traces.
+
+Native Apple reports alone do not automatically include interpreter/async
+records. An out-of-tree reporting integration must attach or reconstruct them.
+Apple's [CrashReportExtension](https://developer.apple.com/documentation/crashreportextension)
+can inspect a crashed process out of process on its supported platforms; its
+documented availability is iOS/iPadOS/macOS 27, not watchOS. It must not become a
+runtime dependency or the only diagnostic path. GDB/LLDB readers and an external
+crash-context attachment remain necessary for other targets.
+
+These requirements are intentionally not a new public diagnostics ABI in this
+patch. Named guest frames, source mappings and async ancestry remain gates before
+claiming a complete `Wasm -> component/module -> native provider` crash stack.
+
+## Reproduce
+
+Build the shared runtime fixture with `run.py --runtime wamr --root /path/to/wamr
+--build /tmp/runtime --call-stacks`, or the equivalent TinyWasm command without
+`--call-stacks`. Use one compiler family for native LTO objects and the final
+linker. For WAMR source-level runtime debugging, additionally build its archive
+with `RelWithDebInfo` and `-fno-omit-frame-pointer`. The default build flags stay
+unchanged.
+
+Run this directory's `run.py` with `--runtime`, `--include`, `--library`,
+`--build` and `--debugger lldb` or `--debugger gdb`. WAMR's include directory must
+contain its C API header under the shared name `wasm.h`, as the parent runner
+arranges. Add `--swift` on macOS. Without it, a C bridge connects Rust to the
+checkpoint; this is the Linux GDB CI configuration.
+
+`--apple-crash` deliberately traps the standalone fixture, checks a new Apple
+`.ips` report for the native frame order and matching dSYM UUID, and symbolicates
+its image addresses with `atos`. Run it only when intentionally producing a test
+crash. The script records a minimal receipt, not the report's machine identifiers.
+`--ordinary --guest /path/to/guest.aot` checks ordinary AOT calls; compile
+`guest.wasm` with `--enable-dump-call-stack` and matching GC/bounds-check settings.
+
+The runner writes `debugger.txt`, `guest_trace.txt`, and `receipt.json`; Apple
+crash tests also write `apple_symbolicated.txt`. It explicitly records
+`full_mixed_guest_stack_qualified: false`, even when native unwinding passes.
+
+References: [Apple symbolication](https://developer.apple.com/documentation/xcode/adding-identifiable-symbol-names-to-a-crash-report),
+[GDB JIT interface](https://sourceware.org/gdb/current/onlinedocs/gdb.html/JIT-Interface.html),
+[LLVM debugging generated code](https://llvm.org/docs/DebuggingJITedCode.html).

crates/c-api/tests/continuations/debug/bridge.c

@@ -0,0 +1,9 @@
+/* Copyright (C) 2026 Matt Hargett. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception */
+extern int
+native_checkpoint(int);
+__attribute__((noinline)) int
+native_bridge(int value)
+{
+    return native_checkpoint(value) + 1;
+}

crates/c-api/tests/continuations/debug/guest.wasm

@@ -0,0 +1,9 @@
+;; Copyright (C) 2026 Matt Hargett. All rights reserved.
+;; SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+(module $stack_audit
+  (import "example:native" "call" (func $native_call (param i32) (result i32)))
+  (func $leaf (param i32) (result i32)
+    local.get 0 i32.eqz if unreachable end
+    local.get 0 call $native_call drop unreachable)
+  (func $middle (param i32) (result i32) local.get 0 call $leaf i32.const 1 i32.add)
+  (func $root (export "run") (param i32) (result i32) local.get 0 call $middle i32.const 1 i32.add))

crates/c-api/tests/continuations/debug/guest.wat

@@ -0,0 +1,149 @@
+/* Copyright (C) 2026 Matt Hargett. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception */
+#include "wasm.h"
+#include "wasm_ext.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#ifdef _MSC_VER
+#include <intrin.h>
+#define NOINLINE __declspec(noinline)
+#define CRASH() __debugbreak()
+#else
+#define NOINLINE __attribute__((noinline))
+#define CRASH() __builtin_trap()
+#endif
+#define CHECK(x)                                 \
+    do {                                         \
+        if (!(x)) {                              \
+            fprintf(stderr, "failed: %s\n", #x); \
+            exit(1);                             \
+        }                                        \
+    } while (0)
+#ifdef STACK_AUDIT_NATIVE
+extern int
+native_cpp(int value);
+#else
+static int
+native_cpp(int value)
+{
+    return value + 4;
+}
+#endif
+static int crash_enabled;
+NOINLINE int
+native_checkpoint(int value)
+{
+    if (crash_enabled)
+        CRASH();
+    return value + 1;
+}
+NOINLINE void
+parked_checkpoint(void)
+{
+    static volatile unsigned visits;
+    visits++;
+}
+static NOINLINE wasm_ext_status_t
+native_import(void *env, const wasm_val_vec_t *args, wasm_val_vec_t *results,
+              wasm_trap_t **trap)
+{
+    (void)env;
+    (void)results;
+    (void)trap;
+    CHECK(native_cpp(args->data[0].of.i32) == args->data[0].of.i32 + 4);
+    return WASM_EXT_PENDING;
+}
+static NOINLINE wasm_trap_t *
+sync_import(void *env, const wasm_val_vec_t *args, wasm_val_vec_t *results)
+{
+    (void)env;
+    results->data[0].kind = WASM_I32;
+    results->data[0].of.i32 = native_cpp(args->data[0].of.i32);
+    return NULL;
+}
+int
+main(int argc, char **argv)
+{
+    CHECK(argc >= 2);
+    crash_enabled = argc > 2 && !strcmp(argv[2], "crash");
+    int ordinary = argc > 2 && !strcmp(argv[2], "ordinary");
+    int early = argc > 2 && !strcmp(argv[2], "early");
+    wasm_engine_t *engine = wasm_engine_new();
+    CHECK(engine);
+    wasm_store_t *store = wasm_store_new(engine);
+    CHECK(store);
+    FILE *f = fopen(argv[1], "rb");
+    CHECK(f);
+    CHECK(!fseek(f, 0, SEEK_END));
+    long n = ftell(f);
+    CHECK(n > 0);
+    rewind(f);
+    wasm_byte_vec_t bytes;
+    wasm_byte_vec_new_uninitialized(&bytes, (size_t)n);
+    CHECK(fread(bytes.data, 1, bytes.size, f) == bytes.size);
+    fclose(f);
+    wasm_module_t *module = wasm_module_new(store, &bytes);
+    CHECK(module);
+    wasm_byte_vec_delete(&bytes);
+    wasm_functype_t *type =
+        wasm_functype_new_1_1(wasm_valtype_new_i32(), wasm_valtype_new_i32());
+    wasm_func_t *host =
+        ordinary ? wasm_func_new_with_env(store, type, sync_import, NULL, NULL)
+                 : wasm_ext_func_new(store, type, native_import, NULL, NULL);
+    CHECK(host);
+    wasm_functype_delete(type);
+    wasm_extern_t *items[] = { wasm_func_as_extern(host) };
+    wasm_extern_vec_t imports = WASM_ARRAY_VEC(items);
+    wasm_trap_t *trap = NULL;
+    wasm_instance_t *instance =
+        wasm_instance_new(store, module, &imports, &trap);
+    CHECK(instance && !trap);
+    wasm_extern_vec_t exports;
+    wasm_instance_exports(instance, &exports);
+    wasm_val_t in[] = { WASM_I32_VAL(20) }, out[] = { WASM_I32_VAL(0) };
+    wasm_val_vec_t args = WASM_ARRAY_VEC(in), results = WASM_ARRAY_VEC(out);
+    wasm_ext_call_t *call = NULL;
+    if (ordinary) {
+        trap = wasm_func_call(wasm_extern_as_func(exports.data[0]), &args,
+                              &results);
+        CHECK(trap);
+    }
+    else {
+        if (early)
+            in[0].of.i32 = 0;
+        call = wasm_ext_call_new(wasm_extern_as_func(exports.data[0]), &args);
+        CHECK(call);
+        int status = wasm_ext_call_resume(call, NULL, &results, &trap);
+        if (!early) {
+            CHECK(status == WASM_EXT_PENDING);
+            parked_checkpoint();
+            status = wasm_ext_call_resume(call, &args, &results, &trap);
+        }
+        CHECK(status == WASM_EXT_ERROR && trap);
+    }
+    wasm_frame_vec_t frames;
+    wasm_trap_trace(trap, &frames);
+    printf("guest_trace_count=%zu\n", frames.size);
+#ifdef EXPECT_GUEST_TRACE
+    CHECK(frames.size == 3);
+    for (size_t i = 0; i < 3; i++)
+        CHECK(wasm_frame_func_index(frames.data[i]) == i + 1);
+#endif
+    for (size_t i = 0; i < frames.size; i++)
+        printf("guest_frame index=%u function_offset=%zu module_offset=%zu\n",
+               wasm_frame_func_index(frames.data[i]),
+               wasm_frame_func_offset(frames.data[i]),
+               wasm_frame_module_offset(frames.data[i]));
+    wasm_frame_vec_delete(&frames);
+    wasm_trap_delete(trap);
+    if (call)
+        wasm_ext_call_delete(call);
+    wasm_extern_vec_delete(&exports);
+    wasm_instance_delete(instance);
+    wasm_func_delete(host);
+    wasm_module_delete(module);
+    wasm_store_delete(store);
+    wasm_engine_delete(engine);
+    return 0;
+}

crates/c-api/tests/continuations/debug/native.c

@@ -0,0 +1,10 @@
+/* Copyright (C) 2026 Matt Hargett. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception */
+extern "C" int
+native_rust(int);
+extern "C" __attribute__((noinline)) int
+native_cpp(int value)
+{
+    volatile int result = native_rust(value);
+    return result + 1;
+}

crates/c-api/tests/continuations/debug/native.cpp

@@ -0,0 +1,10 @@
+// Copyright (C) 2026 Matt Hargett. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+unsafe extern "C" {
+    fn native_bridge(value: i32) -> i32;
+}
+#[unsafe(no_mangle)]
+#[inline(never)]
+pub extern "C" fn native_rust(value: i32) -> i32 {
+    std::hint::black_box(unsafe { native_bridge(value) }) + 1
+}