The boot reads the log

Portal.Engine is a single process that holds the Portal’s folded state in memory, and it rebuilds that state on every start by replaying the event log from the beginning. The replay is the first thing the process does, and it does it synchronously, before init/1 returns. The path is short and exact: init(:ok), do: {:ok, load()} calls load/0, which reads the whole stream through Portal.EventStore.adapter().read_stream(@stream) — the adapter/0 indirection that resolves to whichever store the release ships with. Under prod that store is Portal.EventStore.Postgres, so the read is a real query.

Portal.EventStore.Postgres.read_stream/1 answers with a single Repo.all(from e in Event, where: e.stream == ^stream, order_by: e.seq) — a SELECT … FROM events ordered by :seq, run through Portal.Repo over the connection pool. Because init/1 blocks on the result, the pool’s queue_timeout — the 4‑second window a checkout waits for a free connection — is the clock the whole boot runs against. If a connection cannot be had in that window, the read does not return; it raises, and a raise in init/1 means the process never starts.

Step the chain below to read what each call does, and to confirm that every link is synchronous — the boot is waiting on the SELECT, under the 4‑second queue_timeout, the entire time.

Because the boot blocks on that one read, two different database faults end the same way — the process fails to start. An unreachable database (the F7.2 reachability faults, left unresolved — a name that does not resolve, a port that does not answer) means the checkout never completes inside the queue_timeout; the read times out, init/1 raises, the supervisor reports failed to start child Portal.Engine, and the node exits non‑zero. Fly restarts the machine, the same read fails again, and after ten such restarts the platform suspends the machine. This is the floor under the gotcha‑2/3 crash stack: the same symptom family, reached through the same synchronous read.

A reachable‑but‑empty database — the trap this module names — fails one step later. The connection succeeds, so the queue_timeout never fires; but the SELECT … FROM events runs against a schema with no events table, and Postgrex surfaces relation "events" does not exist. The connection is fine; the table is not there. init/1 raises the same way, and the crash loop is the same.

So the precondition the boot demands is stacked, not single: the database must be reachable (the F7.2 half — a host that resolves and answers) and migrated (this module’s half — the schema applied release‑native, the F7.3.1 dive) before read_stream/1 can return a result. Either half missing, and the boot does not complete.

The obvious fix is to stop coupling the boot to the database. A lazy or retried replay would let init/1 return immediately and fold the log a moment later — or retry the read a few times before giving up — so a momentary database blip during a deploy would no longer take the whole release down. That is a real and reasonable hardening, and it is the right shape. It is also not built in F7.3.

The reason is a boundary, not an oversight. A lazy or retried replay changes how Portal.Engine starts and folds its state — it edits the engine, which sits below the facade, beneath the deploy layer’s mandate. The deploy chapter’s rule is to ship the release and document what it depends on, not to reshape the domain underneath it; the engine is left untouched (F6.8.2-INV7). So this dive does what the deploy layer is allowed to do: it observes the coupling, names the fix, and stops there. No engine code changes in F7.3.

Until the hardening is built, the coupling stands, and so does the operational rule it implies: bring the database up and migrate it before the release boots. The interactive below contrasts the two behaviours — the synchronous coupling as built, and the lazy/retried replay that is carried — and badges the second clearly as not built.