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

Constraints — In-Browser Swactor Runtime

Threading Model

• wasm-threads is mandatory — the runtime uses SharedArrayBuffer + WebAssembly atomics for multi-worker parallelism. There is no single-threaded degraded mode for MVP.
• Browsers must serve pages with COOP/COEP headers:
  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Embedder-Policy: require-corp
• Build requires nightly Rust + -Z build-std=std,panic_abort + target features +atomics,+bulk-memory,+mutable-globals.

Architecture Rules

• Platform abstractions live in core swactor (src/), gated by #[cfg(target_arch = "wasm32")]. They do not belong in the wasm crate.
• Do not add new modules to src/ — modify existing files only (TASK.md style rule).
• Do not restructure existing module boundaries. The abstraction is a thin layer (type aliases, cfg-gated imports), not a trait-based HAL.
• The browser crate (crates/wasm-browser/ or evolved crates/wasm/) is a thin wasm-bindgen shell. All scheduling, routing, and actor logic stays in core Rust.

Actor Model

• Rust-only actors — actors are written in Rust and compiled to wasm. JavaScript does not define actor behavior.
• JS interacts through the wasm-bindgen API: create runtime, spawn actors (by registered type), send messages, receive results.
• Actor types are registered at compile time via Rust generics, not dynamically from JS.

Performance Priorities

• Maximize throughput: auto-scheduling via setTimeout(0) tight loop, not requestAnimationFrame (which caps at display refresh rate).
• Web Worker count defaults to navigator.hardwareConcurrency for full core utilization.
• Zero-copy where possible: SharedArrayBuffer eliminates serialization between workers.
• Minimize JS↔Wasm boundary crossings — batch operations where feasible.

Feature Scope

• All core features that compile for wasm32: spawn, send, receive, tick, actor lifecycle, watching, extensions.
• swactor-std features (naming, groups, monitoring) should work if they compile.
• Transport: WebSocket adapter for distributed clusters. STUN/TURN (WebRTC) deferred to later.
• Features that require OS primitives not available in wasm (filesystem, raw TCP) are excluded.

Testing

• Tests must pass on both native (cargo test) and wasm targets.
• Wasm tests use wasm-pack test --headless --chrome or Node.js with --experimental-wasm-threads.
• No test-only code paths that diverge native vs wasm behavior — if it works differently, it's a bug.
• Prefer scenario tests over structural tests (per project testing rules).

Dependencies

• web-time — drop-in replacement for std::time::Instant on wasm32
• wasm-bindgen + js-sys + web-sys — browser API bindings (in the wasm crate only, not core)
• gloo-timers — optional, for ergonomic setTimeout/setInterval
• No new dependencies in core swactor beyond web-time (which is no-op on native)

What We Don't Do

• No async/await runtime (tokio, async-std) — swactor is synchronous tick-based
• No Emscripten — target is wasm32-unknown-unknown only
• No WASI — browser environment, not server-side wasm
• No JS actor definitions — Rust only
• No polyfills for missing atomics — if SharedArrayBuffer isn't available, the runtime doesn't start