From 78fc4be1b4fa6ce0fdf785063ca8394ca2441276 Mon Sep 17 00:00:00 2001
From: Malte Ubl <malte@vercel.com>
Date: Tue, 27 Oct 2026 19:39:16 -0700
Subject: [PATCH] Document the event-order limitation between native code and
 islands

Native timers and an island's Node timers run on the hosted libuv loop but are not merged into one order, so callbacks from the two sides can run in a different order than in Node and the order can vary between runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/content/docs/limitations.mdx                              | 2 ++
 .../event-order-across-native-code-and-islands.mdx             | 3 +++
 2 files changed, 5 insertions(+)
 create mode 100644 docs/content/limitations/runtime-differences-from-node-js/event-order-across-native-code-and-islands.mdx

diff --git a/docs/content/docs/limitations.mdx b/docs/content/docs/limitations.mdx
index 88b2ca5fc..cf6114037 100644
--- a/docs/content/docs/limitations.mdx
+++ b/docs/content/docs/limitations.mdx
@@ -172,6 +172,8 @@ title: "Limitations"
 
 <include>../limitations/runtime-differences-from-node-js.mdx</include>
 
+<include>../limitations/runtime-differences-from-node-js/event-order-across-native-code-and-islands.mdx</include>
+
 ### Array bounds and runtime errors
 
 <include>../limitations/array-bounds-and-runtime-errors.mdx</include>
diff --git a/docs/content/limitations/runtime-differences-from-node-js/event-order-across-native-code-and-islands.mdx b/docs/content/limitations/runtime-differences-from-node-js/event-order-across-native-code-and-islands.mdx
new file mode 100644
index 000000000..49b748f65
--- /dev/null
+++ b/docs/content/limitations/runtime-differences-from-node-js/event-order-across-native-code-and-islands.mdx
@@ -0,0 +1,3 @@
+- **Event order across native code and islands:** Timers, worker output, and other macrotasks from the program and from JavaScript it runs in a Node island share one event loop under Node.js, so their order is fixed.
+  A compiled program runs both on the event loop it hosts for Node.js, but it does not merge them into one order, so callbacks from the two sides can run in a different order than under Node.js, and the order can vary between runs.
+  Only programs that depend on the ordering between native and island callbacks are affected.