docs: cross-isolate message API — feasibility + design (not yet built)

The fourth spec-todo roadmap item (§20.2-3) has no runtime foundation: the runtime
is strictly single-isolate (one cooperative-task heap; the channel is an explicit
single-isolate Rc<RefCell> MPSC), so "managed handles never cross isolates" has no
boundary to enforce yet — exactly why the spec gates it on "the isolate model
maturing first." Rather than fake a heap-sharing cooperative-task channel as a
"cross-isolate" boundary, record the smallest sound implementation plan
(cross-isolate-design.md): a static is_cross_isolate_safe(T) payload rule plus a
distinct Mailbox<T> surface over the cooperative scheduler. spec-todo.md updated to
mark it blocked-on-foundation with the plan; linked from the docs index.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: olwang

docs/README.md

@@ -15,6 +15,7 @@ LLMs); everything else lives here.
 | [DEVELOPMENT.md](DEVELOPMENT.md) | Local verification flow and development discipline. |
 | [DOCKER.md](DOCKER.md) | Containerized, cross-platform dev environment (Docker / VS Code / Codespaces). |
 | [spec-todo.md](spec-todo.md) | Prioritized list of unimplemented spec surface (the §3.2 / §20.1 superset). |
+| [cross-isolate-design.md](cross-isolate-design.md) | Feasibility + smallest-sound-slice plan for the cross-isolate message API (§20.2-3, not yet built). |
 
 ## Implementation-planning specs (not yet normative)
 

docs/cross-isolate-design.md

@@ -0,0 +1,75 @@
+# Cross-isolate message API — design & feasibility (spec §20.1-B / §20.2-3)
+
+Status: **not implemented — blocked on foundational runtime work** (the spec gates
+it on "the isolate model maturing first"). This note records the investigation and
+the smallest sound implementation plan so the work can be picked up directly.
+
+## Goal (from the spec)
+
+Typed send/receive channels **between isolates**: payloads are owned/Copy data or
+values moved with `take`; **managed handles never cross**; single ownership is
+enforced statically (not by runtime convention); `take`-based move is the
+no-shared-alias transfer path (zero-copy when representation permits).
+
+## Why it isn't a small change today
+
+The runtime is **strictly single-isolate**. Concurrency is cooperative tasks on
+one thread sharing **one heap**:
+
+- `crates/runtime/src/channel.rs` is an explicit "single-isolate MPSC" using
+  `Rc<RefCell<ChannelState<T>>>` (no `Send`/`Sync`, no `Arc<Mutex>`).
+- The reg-VM scheduler (`reg_vm/mod.rs`: `tasks`, `ready_queue`, `Wait`,
+  `satisfy_waiters`) drives many tasks, but they share the same `Rc` pool —
+  `task_group` children are isolate-**local**.
+- There is no construct that creates a second execution context with its own heap;
+  a "second isolate" would still alias the same managed `Rc`s.
+
+So "managed handles never cross isolates" has no boundary to be enforced *at*
+today — there is only one heap.
+
+## Smallest sound slice (recommended, ~1–2 weeks; holds VM↔compiled parity)
+
+Reuse the cooperative scheduler; make the isolate boundary a **static + runtime
+value-transfer contract** rather than a separate OS thread/heap. Soundness comes
+from restricting payloads so a value transfer is a genuine deep copy with no
+shared `Rc`.
+
+1. **Type classification — `is_cross_isolate_safe(T)`** (`checks/local.rs`).
+   Allowed: Copy scalars, and owned `struct`/`sum` values whose fields are all
+   cross-isolate-safe. Denied: `List`/`Map`/`Set`, closures, any managed handle,
+   resources, views, generic `T`. This is the reviewable essence: no `Rc` can
+   cross, so a clone/move is alias-free.
+
+2. **Surface** — a distinct mailbox API (e.g. `Mailbox<T>` + `Mailbox.pair()`,
+   `Outbox.send(value: take T)`, `Inbox.recv()`), feature-gated, with
+   `send` requiring `take` of a cross-isolate-safe `T`. Kept separate from the
+   in-isolate `Channel<T>` so existing channel semantics are unchanged.
+
+3. **Static enforcement** — at `Outbox.send`, infer the payload type and reject
+   non-cross-isolate-safe `T` with a stable diagnostic (mirrors `take`
+   validation). This is the primary defense and is fully testable without
+   multi-threading.
+
+4. **Execution** — run the two endpoints as cooperative tasks; transfer reuses the
+   existing channel value-move (VM clones `VmValue`, Rust moves `T`). Because the
+   payload has no `Rc`, this is alias-free on the shared heap — sound for the
+   "single ownership / no shared managed handle" guarantee. Add a defensive
+   runtime scan rejecting any `Rc`-bearing value (safety net for edge cases).
+
+5. **Parity + tests** — `tests/vm_eval_parity/async_concurrency.rs`: Copy payloads
+   cross; managed payloads rejected at check time; ordering preserved; mixing with
+   in-isolate channels.
+
+## Larger, deferred option
+
+True multi-thread / multi-heap isolates (`Arc<Mutex>`, `Send + Sync`, a
+thread-multiplexing scheduler) is a multi-quarter refactor that intentionally
+breaks the single-thread-simplicity design. Out of scope; the slice above delivers
+the spec's *static* guarantee without it.
+
+## Decision
+
+Recorded, not built. The static contract (step 1+3) is the high-value, sound,
+bounded core; steps 2/4/5 add the executable surface. Pick up when the mailbox
+surface is prioritized; until then the single-isolate model stands and managed
+handles simply cannot be sent anywhere.

docs/spec-todo.md

@@ -46,10 +46,19 @@ model without reversing a review-first tenet. Ordered by readiness/value.
   review map already flags dynamic dispatch (`has_dynamic_protocol_dispatch`).
 
 - [ ] **Cross-isolate message API (zero-copy transfer)** (§20.1-B, §20.2-3) —
-  _large._ Typed send/receive channels between isolates; payloads are Copy/owned data
-  or values moved with `take`; managed handles never cross. Single ownership enforced
-  statically. Depends on the isolate model maturing first. _Touches:_ async/isolate
-  runtime, type/effect checking for `take`-across-boundary, lowering + reg-VM.
+  _blocked on foundational runtime work; design recorded._ Unlike the other three
+  roadmap items (which were largely already built), this has **no foundation**: the
+  runtime is strictly single-isolate (one cooperative-task heap; the channel is an
+  explicit single-isolate `Rc<RefCell>` MPSC), so "managed handles never cross
+  isolates" has no boundary to be enforced at yet — exactly why the spec gates it on
+  "the isolate model maturing first." Faking it (cooperative tasks sharing a heap)
+  would not be a real isolate boundary, so it is **not** implemented here.
+  The smallest *sound* slice and the full feasibility analysis are recorded in
+  [cross-isolate-design.md](cross-isolate-design.md): a static
+  `is_cross_isolate_safe(T)` payload rule (Copy/owned, no managed handles) + a
+  distinct `Mailbox<T>` surface over the cooperative scheduler (~1–2 weeks, holds
+  parity). True multi-thread/multi-heap isolates are a separate multi-quarter
+  refactor. Pick up when the mailbox surface is prioritized.
 
 ## Removed — non-goals (not deferred; deleted from the roadmap)