Runtime GenServer for Orkestra projection subsystem.

Subscribes to the event store from the persisted checkpoint position, applies pushed events strictly sequentially (one per handle_info — OTP mailbox guarantees in-order, single-consumer processing — PROJ-04), commits the read-model write and the checkpoint upsert atomically in a single Ecto.Multi transaction (STORE-03), retries failed events with exponential backoff via Process.send_after, and parks exhausted events to dead-letter while staying alive in an idle halted state (ERR-04).

Start Configuration

Pass a map with the following keys when starting the GenServer:

%{
  repo:             MyApp.OrderProjection.Repo,   # per-projection Ecto.Repo
  projector_name:   "MyApp.OrderProjection",      # unique string identifier
  storage_adapter:  Orkestra.Projection.Storage.Postgres,  # Storage behaviour
  event_store:      Orkestra.EventStore.InMemory,  # EventStore behaviour
  lifecycle_config: %{max_retries: 5, backoff_base_ms: 500, backoff_cap_ms: 30_000},
  adapter_opts:     [handler: &my_handler/3]       # forwarded to storage_adapter.write/4
}

An optional :name key sets the GenServer registered name.

Deferred Init

init/1 does not call the Repo directly. Instead it enqueues a :load_checkpoint message so callers (e.g., tests) can call Ecto.Adapters.SQL.Sandbox.allow/3 after start_supervised!/1 returns but before the GenServer processes its first mailbox message (RESEARCH Pitfall 1).

Halt Behaviour

A halted projector discards incoming events and stays alive — it never returns a stop tuple from handle_info. This avoids supervisor restart loops and keeps the halted status observable via the persisted projection_checkpoints row.

Step Name Convention

The GenServer's checkpoint Multi steps are named :checkpoint, :halted_checkpoint, and :dead_letter. The injected storage adapter must use :read_model_-prefixed step names to prevent Ecto.Multi.append/2 name clashes (RESEARCH Pitfall 2).