README: rewrite overview, add limitations, roadmap, and contribution notes

Expands the intro into an overview/limitations structure, documents
preemption, tracing/causal profiling, URUS, and adds a 'Coming up' and
'A note on open source' section.

README.md

@@ -1,35 +1,38 @@
 # smarm
 
-> SMARM — Smarm, Marks Actor Runtime Machinery. A proof-of-concept green-thread actor runtime for Rust.
+> SMARM: Smarm, Marks Actor Runtime Machinery. A proof-of-concept green-thread actor runtime for Rust.
 
-Implements the core ideas in [`Achitecture.md`](.docs/Architecture.md): green-thread actors on a
-shared heap, scheduled cooperatively, communicating only by `Send` messages.
-Erlang's isolation model without Erlang's copying GC, Rust's zero-copy
-ownership transfers without async's function colouring.
+SMARM is my attempt to implement the erlang/OTP philosophy in the Rust programming language. This has yielded a fault-tolerant, fast, and scalable runtime. This runtime allows the creation of asynchronous applications in Rust without the function coloring associated with the async/await system. It encourages the writing of simple, synchronous code, and largely elides the need for lifetime annotations. 
 
-The scheduler is multi-threaded — one OS thread per available CPU, all drawing
-from a shared run queue. The single-threaded `run()` entry point is kept as a
-convenience wrapper around `runtime::init(Config::exact(1)).run(f)`.
 
-## What's here
+## Overview
+
+SMARM implements green-thread actors on a shared heap, communicating only by `Send` messages. By sharing the heap, SMARM avoids the copying overhead of Erlang, which is safe to do due to Rust's borrow checker. 
+
+On top of the core runtime mechanics, SMARM also provides a library of primitives for making applications closely inspired by erlang/OTP. This includes generic servers (gen_servers), generic state machines (gen_statem), and supervision trees.
+
+Supervision trees are the core primitive to allow your application to survive an unexpected panic. Supervisors are processes dedicated to monitoring other processes, which can restart these should they fail. This means that when set up properly an application may 'self-heal' when encountering unforeseen circumstances. 
+
+SMARM is not cooperatively scheduled; it uses preemption. This means a heavy task will not starve out other lighter tasks. Everything will make steady progress, which translates to very beneficial behaviour under (over)load: average latency goes up, but tail latency does not blow up.
+
+To help diagnose these unforeseen circumstances, smarm may be compiled with its `tracing` feature, which emits a full trace using [Perfetto](https://perfetto.dev/). 
+
+Should you want to optimize your application, SMARM is unusually well poised to help. As the runtime functionally controls time, SMARM comes with a built in causal profiler, under the `causal` feature.
+
+I also built a Phoenix-Framework inspired HTTP 1.1 library on top of SMARM called [URUS](https://git.kalsbeek.dev/Markk116/urus), which implements Pub/Sub, Channels, and basic amenities like Websockets and Server Sent Events. 
+
+## Limitations
+
+This runtime requires naked assembly to function, and has thus far only been implemented for x86-64 assembly. It expects an operating system that supports virtual address space, and is therefore not (yet) suited for embedded targets. The IO implementation is currently based around the Linux kernel's `epoll` mechanism, meaning it requires a (GNU+)Linux distribution to run. 
+
+The preemption mechanism works by wrapping the memory allocator and checking how many CPU cycles you have used compared to your timeslice budget. This allows preemption to fire in most normal code, but tight zero-allocation loops do not get caught and require manual insertion of `check!()` if you want preemption to function. 
+
+This library is still in its early stages, and while I try my best with loom and tests, stable operation cannot be guaranteed. Therefore it is not (yet) recommended for production use. 
+
+At this moment, stack memory for each green thread is capped. Uncapping this may lead to performance benefits for deeply recursive algorithms that in a traditional async runtime might require pointer-chases through the heap. This is as yet unrealised.
+
+At this stage, the codebase is largely LLM-generated, which is obvious if you start to read through the internals. While I did the design, and I keep the LLM under tight rein, the codebase is not in a state that I am very happy with. This also goes for the documentation.
 
-| Module       | What it does                                                           |
-|--------------|------------------------------------------------------------------------|
-| `stack`      | `mmap`'d growable stack with guard page; SIGSEGV on overflow           |
-| `context`    | `#[naked]` x86-64 context-switch shims, callee-saved regs only         |
-| `preempt`    | Allocator-driven preemption; `check!()` macro for no-alloc loops       |
-| `pid`        | `(index, generation)` PIDs; stale handles are detectable, not silent   |
-| `actor`      | Trampoline + `catch_unwind` boundary at the actor entry point          |
-| `scheduler`  | Run queue, slot table, spawn/join, parking, idle path                  |
-| `channel`    | Unbounded MPSC channel; `recv` parks the actor; `recv_timeout` bounds it; `select`/`select_timeout` park on many receivers at once (ready-index, priority order) |
-| `mutex`      | `Mutex<T>` with mandatory timeout; FIFO waiters; parks the green thread |
-| `timer`      | Min-heap of `(deadline, reason)`; `Sleep` and `WaitTimeout` reasons    |
-| `io`         | `block_on_io` for blocking work; `wait_readable`/`wait_writable` + `read`/`write` via epoll |
-| `supervisor` | `Signal::Exit`/`Panic`/`Stopped` funnelled to a parent; `OneForOne`/`OneForAll`/`RestForOne` strategies + restart-intensity cap |
-| `monitor`    | `monitor(pid)` → `Monitor { id, target, rx }`; one-shot `Down` via `rx`; `demonitor(&m)` tears one registration down; unidirectional death notice |
-| `link`       | bidirectional `link`/`unlink`; abnormal death propagates (cooperative stop, or an `ExitSignal` message under `trap_exit`) |
-| `gen_server` | `call`/`call_timeout` (sync request-reply) / `cast` (async) over one inbox; `handle_info` over static info arms + `handle_down` via `Watcher`-fed monitors, selected ahead of the inbox; `ServerRef`/`ServerBuilder` + `init`/`terminate` hooks; server-down via channel closure |
-| `registry`   | `register`/`whereis`/`name_of`: name ↔ pid bimap; lazy generation-checked cleanup |
 
 ## Quick taste
 
@@ -67,12 +70,9 @@ benches/
 
 ## Building and running
 
-Standard Cargo. Requires Rust 1.95 or newer (the `#[naked]` attribute went stable
-in 1.88; we use a few unrelated post-1.88 features). `master` is x86-64 Linux
-only. An experimental, **untested** aarch64 context-switch backend lives on the
-`arm-port` branch (extracted into a `target_arch`-gated `src/arch/`); it has not
-been validated on hardware yet. macOS remains on the deferred list because of the
-epoll dependency.
+Standard Cargo. Requires Rust 1.95 or newer (the `#[naked]` attribute went stable in 1.88; we use a few unrelated post-1.88 features). I have worked hard to keep this library as dependency-free as possible. `master` is x86-64 Linux only. An experimental, **untested** aarch64 context-switch backend lives on the `arm-port` branch (extracted into a `target_arch`-gated `src/arch/`); it has not been validated on hardware yet. macOS remains on the deferred list because of the epoll dependency.
+
+
 
 ```sh
 cargo test                # all tests
@@ -80,26 +80,29 @@ cargo test --test mutex   # one module
 cargo bench               # primes benchmark vs tokio
 ```
 
-## What's not here
-
-See the **Defer** section of `Architecture.md`. 
-`join!` for handle groups, stack growth via remap,
-hierarchical timer wheel, fd-wait timeouts, `Signal::Timeout`. Each is
-mechanism we know how to add; none belongs in this iteration.
-
 ## Docs
 
 | Document | What it covers |
 |---|---|
 | [`Architecture.md`](./docs/Architecture.md) | Design intent, runtime model, and deferred work |
-| [`smarm - Deep Dive.html`](./docs/smarm%20-%20Deep%20Dive.html) | Generated walkthrough of the system; good starting point |
+| [`smarm - Deep Dive.html`](./docs/smarm%20-%20Deep%20Dive.html) | Generated walkthrough of the system; good starting point if you want to learn about the internals |
 | [`BENCHMARKS_AND_TUNING.md`](./docs/BENCHMARKS_AND_TUNING.md) | Where smarm wins and loses vs tokio, preemption knob recommendations |
 | [`benchmarks.md`](./docs/benchmarks.md) | Raw benchmark results, methodology, and tuning experiment log |
 
+## Coming up 
+
+Clustering: clustering multiple SMARM nodes together is in the pipeline. 
+SMARM-BEAM Interop: Running SMARM as a supervised node under the BEAM via a Rustler NIF works, including message passing and supervision trees that span the runtimes. However, this library is still too unstable to release. 
+SMARM is an interesting platform for implementing a 'dataflow' library, but work on this has not yet started. 
+
+
 ## Contributing
 
-This is a personal proof-of-concept. There's no PR workflow. If you fork it and do something interesting, just send me an email. If it's nice, I'll upstream the changes. 
+This started as a personal proof-of-concept, but it is starting to outgrow that name. If you want to contribute, please get in contact to discuss what you want to work on. Code without prior communication is not welcome.  
+
+
+## A note on open source
+
+An open source project is a gift, and by giving it, it is no longer mine. I highly enourage you to fork it, to make it your own. This repository, however, is still mine. 
 
 ---
-
-