swactor/docs/development_history/cfuzz/CFUZZ_OVERVIEW.md

cfuzz Branch — Development History Overview

19 improvement cycles on the cfuzz branch. Research-driven methodology: study competitors → identify gap → implement → test → benchmark. Grew test suite from 42 → 148 passing tests.

---

Methodology

Each cycle followed a consistent pattern:

1. Research — Study how competitors (Erlang/OTP, Tokio, Akka, Ractor, Actix, Kameo) handle the problem
2. Identify gap — Find a specific deficiency in swactor
3. Implement — Fix the gap with minimal, targeted changes
4. Test — Write behavioral tests (Given/When/Then) from the consumer's perspective
5. Benchmark — Measure impact where applicable

Constraints

• src/ structure is frozen — no new files or modules, only modify existing files in-place
• No new dependencies on the root crate
• Behavioral tests only — no white-box/structural tests
• All cargo test must pass before each commit
• Never delete tests for active code

---

Baseline Benchmarks (Pre-Improvement)

Benchmark	Time	Throughput
spawn	1.28 µs	—
message_roundtrip	2.24 µs	—
send_fire_and_forget	1.50 µs	—
single_actor/1000	57.5 µs	17.4 Melem/s
multi_actor/100x100	610.6 µs	16.4 Melem/s
ring/100	99.9 µs	1.01 Melem/s

---

Cycle Summary

Cycle	Commit	Topic	Tests Added	Cumulative Tests
1	ef87f7e	Fairness (message budget)	3	45
2	10cb078	Stress tests + benchmarks	6	51
3	acacc1b	Thread parking	1	52
4	cf61619	Shutdown fix + bug-inspired tests	5	57
5	7d00e65	Load-aware placement	3	60
6	265992c	Mailbox backpressure	4	64
7	1779ad6	Actor recovery	4	68
8	0213938	Dead actor cleanup	2 (+2 updated)	70
9	e28aca0	Lifecycle hooks + graceful stop	12	82
10	d58a999	Actor timers	6	88
11	9b1518b	Property-based testing	7	95
12	66a8523	Named actor registry	11	106
13	8782638	Actor monitoring	7	113
14	4d18874	Actor groups	9	122
15	902471b	Ask pattern	5	127
16	0ef6df9	Registry benchmarks	0	127
17	a70bd86	Supervision trees	10	138
18	771c38c	OneForAll + RestForOne	3	141
19	c688f0a	Router	7	148

---

Thematic Groupings

Scheduling & Performance (Cycles 1–5)

Foundation work: fairness guarantees, stress testing, thread parking, shutdown reliability, and load-aware actor placement. Research thread: BEAM reductions → tokio coop budget → Kameo/Actix mailboxes → tokio parker → work stealing survey.

Resilience & Lifecycle (Cycles 6–10)

Production hardening: backpressure, crash recovery, memory leak fix, lifecycle hooks, and deterministic timers. Narrative arc: from "actors crash permanently" to "actors have a fully managed lifecycle."

Testing & Service Discovery (Cycles 11–16)

Property-based testing for invariant verification, plus four registry features (names, monitoring, groups, ask pattern) and benchmarks to validate them. Research shifted from scheduling to service discovery patterns.

Supervision (Cycles 17–19)

Capstone features built on everything preceding: supervision trees with configurable restart strategies, and routers for actor pool management. Directly modeled on Erlang/OTP supervision trees.

---

Frameworks Studied

Framework	Language	Key Lessons
Erlang/OTP BEAM	Erlang	4000-reduction budget, supervision trees, pg groups, gen_server:call
Tokio	Rust	128-op coop budget, work-stealing, parker state machine
Akka	Scala/Java	SupervisorStrategy, Router actors, PoisonPill
Ractor	Rust	String-based registry, SupervisionEvent, bug history
Actix	Rust	Vyukov MPSC queue, 256-message guard, ctx.stop()
Kameo	Rust	Dual mailbox (bounded/unbounded), on_panic hook, ActorPool
Linux CFS/EEVDF	C	vruntime fairness, NO_HZ adaptive ticks
libuv/Node.js	C	Phase-based event loop, round-robin handlers