swactor/big-feature-phase/notes/research_synthesis.md

# Research Synthesis — In-Browser Swactor Runtime

## Ecosystem Landscape

No established Rust actor framework runs natively in browsers. The closest projects:

- **Lunatic** — Erlang-inspired Wasm actor runtime using wasmtime (server-side, not browser). Uses preemptive scheduling and work-stealing. Not applicable to browser constraints.
- **wasmCloud** — CNCF distributed actor platform. Single-threaded actors, NATS-backed lattice. Cloud/edge focus, no browser target.
- **Actix** — Tokio-dependent, network stack doesn't compile for wasm32. Community attempts to port failed due to `net2`/tokio dependencies.

**Implication**: swactor would be the first Rust actor runtime with true multi-threaded browser execution via wasm-threads. This is a differentiated position.

## Existing Work in This Codebase

| Component | Status | Notes |
|-----------|--------|-------|
| `crates/wasm/` | Basic PoC | Hardcoded Counter/Relay actors, manual tick, u32-only messages |
| `no_random` feature | Working | Deterministic address generation without `getrandom` |
| `tick()` method | Working | Single-threaded tick for manual driving |
| Actor watching | In core | `ExitReason`, `ActorExited`, `on_actor_exit`, `WatchRegistry` |
| swactor-std | Complete | StdExtension, naming, groups, monitoring, supervisor |

## Platform Dependencies Analysis

### Works as-is with wasm-threads
- `crossbeam-queue` (ArrayQueue, SegQueue) — uses `core::sync::atomic`
- `std::sync::{Mutex, RwLock}` — stdlib uses futex on wasm with atomics
- `std::sync::atomic::*` — maps to wasm atomic instructions
- `Arc<T>` — works with atomics
- `std::sync::OnceLock` — works with atomics

### Requires platform abstraction (4 items)
1. `std::thread::spawn` → Web Worker via `web-sys::Worker`
2. `thread::park_timeout` / `Thread::unpark` → `Atomics.wait` / `Atomics.notify`
3. `thread::yield_now` → no-op (or `Atomics.wait(0)` as hint)
4. `std::time::Instant` → `web_time::Instant` (drop-in crate)

## Priority Ranking

### P0 — Must Have (enables everything else)

1. **Platform abstraction layer** — cfg-gated replacements for thread spawn, park/unpark, yield, Instant. Core swactor compiles for wasm32 with atomics.
2. **Single-worker browser runtime** — Prove the runtime works in a browser. One Web Worker, auto-scheduled tick loop, generic JS API for spawn/send/recv.
3. **Multi-worker parallelism** — N Web Workers sharing runtime state via SharedArrayBuffer. Full utilization of browser CPU cores.

### P1 — Should Have (full actor system)

4. **Actor watching in browser** — Death notifications, exit reasons. Already in core, just needs to compile and pass wasm tests.
5. **swactor-std in browser** — Naming, groups, monitoring extensions. Compile and test for wasm32.
6. **Stats and introspection** — Runtime stats accessible from JS. Worker info, actor counts, message throughput.

### P2 — Important (distributed peer)

7. **WebSocket transport** — Adapter implementing swactor's transport traits over WebSocket. Browser node joins a distributed cluster.
8. **Browser-to-browser transport foundation** — WebRTC DataChannel scaffolding for future STUN/TURN.

### P3 — Nice to Have (developer experience)

9. **TypeScript type generation** — Derive TS interfaces from Rust actor message types.
10. **Build tooling** — wasm-pack wrapper script, example project template, CI configuration.
11. **Browser dev tools** — Actor inspector, message flow visualization, performance profiling.

### P4 — Future (out of scope for this feature phase)

12. **STUN/TURN integration** — Full NAT traversal for peer-to-peer browser connections.
13. **Hot code reload** — Swap actor implementations without restarting the runtime.
14. **Wasm component model** — Migrate from wasm-bindgen to component model when stabilized.

## Key Design Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Threading model | SharedArrayBuffer + wasm-threads | swactor's shared-memory architecture (Arc, crossbeam queues, atomics) maps directly. postMessage isolation would require a rewrite. |
| Scheduling | `setTimeout(0)` tight loop | `requestAnimationFrame` caps at 60Hz. setTimeout(0) gives ~4ms resolution, sufficient for actor ticks. For rendering-coupled actors, RAF can be opt-in. |
| Actor definition | Rust only | Keeps the type system intact. JS actors would require dynamic dispatch and lose compile-time guarantees. |
| Platform abstraction approach | cfg-gated type aliases + inline functions | Minimal invasion. No trait-based HAL, no new modules. Just swap `std::time::Instant` → `web_time::Instant` etc. |
| Browser crate location | New `crates/wasm-browser/` | Clean separation from the existing PoC. The old `crates/wasm/` can be deprecated or kept as a minimal example. |

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| crossbeam-queue doesn't compile for wasm32+atomics | Low | High | Test early in Stage 1. Fallback: thin wrapper over `VecDeque` behind cfg. |
| COOP/COEP headers break third-party integrations | Medium | Medium | Document clearly. This is the standard trade-off for SharedArrayBuffer apps. |
| Nightly Rust + build-std is unstable | Medium | Medium | Pin to a known-good nightly. Revisit when wasm-threads stabilizes. |
| Web Worker spawn latency | Low | Low | Spawn workers eagerly at runtime init, not per-actor. |
| Browser compatibility gaps | Low | Medium | Target Chrome/Firefox/Safari latest. All support SharedArrayBuffer since 2021. |