# `Capstan.Supervisor`
[🔗](https://github.com/baselabs/capstan/blob/v1.3.1/lib/capstan/supervisor.ex#L1)

The pipeline supervisor: it owns one pipeline's
checkpoint store, `Capstan.AssemblerServer`, and `Capstan.Connection`, wired so the
`Connection`'s `:receiver` is the `AssemblerServer` PID.

## Fail-closed halts do not take down the host

Every child is `restart: :temporary`. A fail-closed halt exits
`{:shutdown, {:halt, reason}}` — which is **not** a crash — so a halted child is
removed and **never restarted into a livelock**, and this supervisor (the host) stays
up. A `:temporary` child never restarts, so the `AssemblerServer` PID baked into the
`Connection`'s `:receiver` is stable for the pipeline's life; a send to a
terminated `AssemblerServer` is a silent no-op, never a raise that could resurrect a
fail-closed pipeline.

The strategy is `:one_for_one`: the children coordinate their own fail-closed halts
(the `Connection` forwards `{:capstan_halt, reason}` to the `AssemblerServer` before it
stops), so no cross-restart coupling is needed, and none is wanted — a restart of a
halted child is exactly the livelock the fail-closed design forbids.

Children start in dependency order — store, then `AssemblerServer` (reads the store,
takes its `{impl, handle}`), then `Connection` (takes the `AssemblerServer` PID) — via
`Supervisor.start_child/2`, because the `Connection`'s receiver PID is only known once
the `AssemblerServer` is running.

# `start_link`

```elixir
@spec start_link(keyword()) :: {:ok, pid()} | {:error, term()}
```

Start a supervised, lib-owned pipeline from an already-validated wiring keyword
(`:sink`, `:checkpoint_store`, `:connection`, `:server_id`, `:max_command_retries`,
`:start_position`, `:tables`, and the validated streaming-liveness trio
`:reconnect_backoff` / `:heartbeat_period_ms` / `:stream_timeout_ms`; plus an optional
`:connect_fun` test seam that fails closed to the real connect when absent).

Returns `{:ok, supervisor_pid}`, or `{:error, reason}` — a value-free store-read or
start-position refusal — after tearing the partially-started tree back down.

---

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