# `Bee.Supervisor`
[🔗](https://github.com/fosferon/bee/blob/v0.3.0/lib/bee/supervisor.ex#L1)

The supervision tree for a Bee instance.

Add it to your application's supervision tree to get a fully managed Bee: a
single-writer Repo, a two-lane read-only connection pool, and a lock sweeper, all
over one SQLite database. Migrations run at boot, in order, before any children start.

    children = [
      {Bee.Supervisor, db_path: "priv/bee.db", prefix: "bee"}
    ]

See the README for the full option list and the concurrency model.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `start_link`

Starts the Bee supervision tree with `:rest_for_one` semantics.

## Boot sequence

1. **Migrate** — runs pending migrations synchronously in init/1 before
   any children start. This prevents race conditions between the Migrate
   task and the Repo both accessing the DB.
2. **Repo** (GenServer, traps exits) — writer + graph owner.
3. **Read.Pool** (Supervisor) — two-lane NimblePool for read-only connections.
4. **Sweeper** (GenServer) — releases expired locks.

## Shutdown guarantees

Three exit paths, each with a different guarantee:

| path           | when                          | terminate/2? | what runs                     |
| -------------- | ----------------------------- | ------------ | ----------------------------- |
| orderly        | supervisor asks to stop       | yes          | JSONL flush, WAL TRUNCATE     |
| trapped crash  | exit signal caught            | yes          | JSONL flush, WAL TRUNCATE     |
| brutal kill    | hard kill or timeout          | NO           | nothing; next boot recovers   |

On orderly/trapped: Repo stops its pool (if owned), TRUNCATE checkpoint
succeeds because no readers hold the WAL, then JSONL flush runs.

On brutal kill: terminate/2 does NOT run. The WAL may contain uncommitted
pages; the next boot's PASSIVE checkpoint timer (60s) recovers. The JSONL
trail may miss the last event window; it is recoverable by re-export since
JSONL is derived from the DB.

## :rest_for_one semantics

If Repo crashes    → restart Repo, Pool, Sweeper.
If Pool crashes    → restart Pool, Sweeper.
If Sweeper crashes → restart Sweeper only.

(Migrate runs in init/1, not as a supervised child — it cannot crash
independently. If it fails, the supervisor itself fails to start.)

---

*Consult [api-reference.md](api-reference.md) for complete listing*