From ac28c2bb6068432faf3fef52567cb183c1c2b4fa Mon Sep 17 00:00:00 2001
From: Niels Mokkenstorm <niels@mokkenstorm.dev>
Date: Tue, 11 Aug 2026 10:07:19 +0200
Subject: [PATCH] docs: cut every readiness comment to one line without losing
 the why

---
 server/src/crate_server/readiness.gleam | 30 ++++++++-----------------
 1 file changed, 9 insertions(+), 21 deletions(-)

diff --git a/server/src/crate_server/readiness.gleam b/server/src/crate_server/readiness.gleam
index 0ba6204..7f1e70a 100644
--- a/server/src/crate_server/readiness.gleam
+++ b/server/src/crate_server/readiness.gleam
@@ -69,8 +69,7 @@ pub type Check {
 type State {
   State(
     last: Option(#(Readiness, Int)),
-    // Generation and start time of the refresh in flight; the generation keeps
-    // a late reply from an abandoned attempt out of the current one.
+    // Generation keeps a late reply from an abandoned attempt out of this one.
     in_flight: Option(#(Int, Int)),
     next_generation: Int,
     reported: Readiness,
@@ -83,23 +82,16 @@ type Msg {
   ProbeResult(Int, Readiness)
 }
 
-// How long the actor waits on a fresh result before answering from cache.
-// Under `call_budget_ms` and the healthcheck timeouts, so a slow-but-healthy
-// probe still answers inside one health check.
+// Bounded so a slow-but-healthy probe still answers inside one health check.
 const local_wait_ms = 500
 
-// Above the docker healthcheck's --timeout=3s, below Caddy's health_timeout:
-// headroom for scheduling, since the actor never blocks past `local_wait_ms`.
+// Scheduling headroom only: the actor never blocks past `local_wait_ms`.
 const call_budget_ms = 4000
 
-// One full Caddy health_interval (deploy/Caddyfile). Past that the refresh has
-// plainly overrun, or its worker died without replying; either way it must not
-// wedge probing for the actor's lifetime.
+// One Caddy health_interval: past it the refresh has plainly overrun or died.
 const refresh_overrun_seconds = 10
 
-// Three Caddy poll cycles, the docker healthcheck interval. Without a ceiling
-// a database that hangs rather than errors would serve the last known-good
-// answer forever, silently.
+// A database that hangs rather than errors must stop counting as evidence.
 const max_staleness_seconds = 30
 
 const never_probed = "no probe has completed yet"
@@ -112,8 +104,7 @@ pub fn postgres(conn: pog.Connection) -> Check {
   cached(fn() { probe_schema(conn) }, clock.now_seconds)
 }
 
-// Zero rows is proof the schema is unusable; an error is only ever an absence
-// of proof.
+// Zero rows proves the schema unusable; an error is only absence of proof.
 fn probe_schema(conn: pog.Connection) -> Readiness {
   let row = decode.success(Nil)
   case
@@ -182,8 +173,7 @@ fn describe(current: Readiness) -> String {
   }
 }
 
-// Every answer funnels through here, so a flapping gate logs its transitions
-// rather than one line per probe.
+// Every answer funnels through here: transitions log, repeat answers do not.
 fn note(state: State, current: Readiness) -> State {
   case transition_line(state.reported, current) {
     None -> state
@@ -214,8 +204,7 @@ fn handle(
   }
 }
 
-// A reply from an attempt already abandoned to overrun must not overwrite the
-// current one.
+// A reply from an attempt abandoned to overrun must not overwrite this one.
 fn accept(
   state: State,
   generation: Int,
@@ -255,8 +244,7 @@ fn needs_refresh(last: Option(#(Readiness, Int)), now: fn() -> Int) -> Bool {
   }
 }
 
-// The best answer available without waiting on the database, vouching for
-// nothing older than `max_staleness_seconds`.
+// The best answer available without waiting on the database.
 fn fallback(last: Option(#(Readiness, Int)), now: fn() -> Int) -> Readiness {
   case last {
     Some(#(current, checked_at)) ->
-- 
2.51.2