swarm — Project Guidelines

Actor Model Conventions

One sealed hierarchy per actor. Define a sealed class FooMessage for commands and a sealed class FooResult for responses. Every concrete variant is a final class.
Handler mixin, not extension. Actors implement Handler<M, A> via with, never via extends or implements.
Factory tear-off for construction.
```
final actor = Actor.create(FooActor.new);
```
Never pass an already-constructed handler instance across isolate boundaries.
Skip init() and close() when there is nothing to initialise or release. Override them only when the actor holds persistent resources (sockets, database handles, etc.).
Errors propagate as exceptions. Throw inside handle(); the actors runtime wraps isolate errors in RemoteErrorException on the caller side. Result-type error variants are only justified across network/serialisation boundaries.

Comment only when intent is not obvious. Skip doc comments on self-explanatory members (final String path, const FileSaved(), etc.).
Prefer const constructors and declarations wherever the linter suggests.
No public_member_api_docs lint rule. Forced doc comments on every public member produce noise, not signal.
prefer_final_fields, avoid_print, sort_pub_dependencies are enabled.

Actors deal in plain Dart types (String, int, Map, …) or simple value objects. Binary data (Uint8List) warrants a separate actor rather than overloading an existing one.