# 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.**
  ```dart
  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.

## Code Style

- **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.

## Content Types

- 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.