Dart owner-isolate checks do not match the C API's owner-thread checks

[sargunv-bot]

NativeHandleState records Isolate.current.hashCode and validates against it (bindings/dart/lib/src/internal/lifecycle/lifecycle.dart:66,113). The C API validates std::thread::id. These are not equivalent: a Dart isolate migrates between OS threads while its hash stays constant.

Measured with pthread_self through dart:ffi, one isolate, awaiting file I/O in a loop:

isolate=970152377 initial os=135237815236288
MIGRATED at iteration 11: os 135237815236288 -> 135237808420544 (isolate hash unchanged: 970152377)
MIGRATED at iteration 19: os 135237808420544 -> 135237815236288 (isolate hash unchanged: 970152377)
MIGRATED at iteration 29: os 135237815236288 -> 135237808420544 (isolate hash unchanged: 970152377)

It reproduces on the main isolate, Isolate.run, and Isolate.spawn. Future.delayed alone did not move it; awaiting I/O did, so the isolate appears to resume on whichever VM thread completed the I/O.

The consequence, through the public binding:

final runtime = RuntimeHandle.create();
runtime.pump();                                  // OK
while (!migrated) {                              // any awaited I/O
  await File('/proc/self/stat').readAsString();
  migrated = osThread() != start;
}
runtime.pump();   // wrongThread (-3): runtime call must be made on its owner thread
runtime.close();  // wrongThread (-3): runtime must be destroyed on its owner thread

Both fail. Because close fails too, the runtime becomes undestroyable and mln_runtime_destroy refuses for the rest of the process, so the runtime, its run loop, and everything under it leak.

This affects any thread-affine handle (runtime, map, projection, render session) held across an awaited I/O operation, which is ordinary Dart code.

The existing test suite does not catch it because tests do their native calls without awaiting I/O in between.

I do not have a fix to propose that fits inside the current design. Options seem to be pinning native calls to a thread the binding owns and routing them there, or documenting a hard constraint that no thread-affine handle may be held across an await. Flagging it rather than guessing.

[sargunv-bot]

Worth recording that this is not Dart-specific. The same mismatch appears wherever a host's unit of execution is not pinned to an OS thread, and the C API validates std::thread::id:

• Go — goroutines migrate at any scheduling point. Go is the case that already works, because runtime.LockOSThread() exists and the binding delegates to it (bindings/go/maplibre.go:6, README, every test).
• Swift — a GCD serial DispatchQueue guarantees serialization but not thread affinity, so actors and Task are unusable for an owner thread.
• .NET — Task.Run and the thread pool likewise.
• Kotlin — coroutine dispatchers likewise.

The example specification already forbids all of those and requires a dedicated thread, which is the same rule stated per-ecosystem.

Dart is the case with no escape hatch: nothing in dart:isolate or dart:ffi pins an isolate to an OS thread, so the Go answer cannot be ported.

That suggests the general fix is one mechanism rather than four: something below the binding that owns a real thread and runs submitted work, with the host blocking on it. include/maplibre_native_c/callback_adapter.h already exists for the same class of host — one that "has no native compilation unit of its own, because it consumes the shared library through a pure foreign-function interface" — but for the callback direction. An execution adapter would be that idea applied to the calling direction, and it would let Swift use an actor and .NET use async rather than each host being told to spawn a dedicated thread.

Not proposing to build that here. Recording it so the eventual fix is scoped as a shared capability rather than a Dart workaround.

[sargunv-bot]

Confirmed this wedges CI, not just user code. On target / windows-arm64-wgl the //bindings/dart:test step hangs until the job timeout, with every earlier suite in that job passing. #418 quarantines it there.

[sargunv]

Concrete downstream confirmation from flutter-maplibre-gl's experimental FFI backend: after moving the engine to a worker isolate, awaited I/O caused 25 owner-thread migrations across 7 OS threads during one 60-second Android gesture session. The integration carries 0002-runtime-rebind-thread.patch plus the explicitly throwaway 0009-lifecycle-rebind-owner-thread.patch because the Dart lifecycle guard otherwise prevents reaching the rebind that would heal the mismatch. This is field evidence that the issue is structural under sustained Flutter worker-isolate load, not just the small repro above. The executor design in #433 would retire both workarounds.