Set fx.StopTimeout inside the container stop grace (closes #134)

fx defaults the stop timeout to 15s and the Dockerfile sets no
STOPSIGNAL or grace override, so Docker's 10s default SIGKILLs the
process five seconds before the bound can fire. Everything gated on
it — including the "shutdown timed out, goroutines still running"
error log that tells an operator a component is wedged — was
unreachable in the image this repo produces.

Set fx.StopTimeout to 5s: inside the grace with headroom for signal
delivery and process exit, and equal to the HTTP server's own drain
budget so the first hook can spend its whole budget without the
sequence bound truncating it. The option set moves into newApp() so
a test can read (*fx.App).StopTimeout() back and pin it against
drift; dropping the option makes that test report fx's 15s default.

Also fix a latent coin flip in the shared stop-hook waiter. It
selected on the drained channel against ctx.Done() with no
preamble, and select picks uniformly among ready cases, so a
component that drained against an already-expired context reported
a timeout about half the time. Not reachable through fx, which
re-checks ctx.Err() before each hook, but the helper is shared and
a direct caller can reach it. waitDone now settles the drained case
in a non-blocking preamble first; the test drives it over 1000
passes, so a restored coin flip cannot pass by luck.

README records the timeout and its relationship to the container
stop grace: that lowering the grace below it puts SIGKILL back in
front of the bound, and that an expired stop context makes fx skip
its remaining hooks, so a wedge in the first-stopped component
means the database close never runs. Adds the missing
internal/lifecycle/ entry to the Package Layout tree.

internal/lifecycle/export_test.go

@@ -0,0 +1,21 @@
+package lifecycle
+
+import (
+	"context"
+	"log/slog"
+)
+
+// WaitDone exposes waitDone to the external test package. Only the
+// unexported waiter can be handed a channel that is already closed
+// before the call, which is the state the preamble exists for;
+// through WaitForShutdown the waiter goroutine may or may not have
+// closed the channel yet, so the case is not reachable
+// deterministically from outside.
+func WaitDone(
+	ctx context.Context,
+	log *slog.Logger,
+	component string,
+	done <-chan struct{},
+) error {
+	return waitDone(ctx, log, component, done)
+}

internal/lifecycle/lifecycle.go

@@ -38,6 +38,29 @@ func WaitForShutdown(
 		wg.Wait()
 	}()
 
+	return waitDone(ctx, log, component, done)
+}
+
+// waitDone waits for done to close, bounded by ctx.
+//
+// The non-blocking preamble is load-bearing. When the component has
+// already drained and ctx has already expired, both cases of the
+// bounded select are ready and Go picks between them uniformly at
+// random, so a clean shutdown would be reported as a timeout about
+// half the time. Draining wins: the goroutines are gone, and there
+// is nothing left for the operator to act on.
+func waitDone(
+	ctx context.Context,
+	log *slog.Logger,
+	component string,
+	done <-chan struct{},
+) error {
+	select {
+	case <-done:
+		return nil
+	default:
+	}
+
 	select {
 	case <-done:
 		return nil

internal/lifecycle/lifecycle_test.go

@@ -37,6 +37,57 @@ func TestWaitForShutdown_DrainedGroup(t *testing.T) {
 	)
 }
 
+// racePasses is how many times the both-cases-ready race is run.
+// Without the preamble each pass is an independent coin flip, so
+// the probability of the whole loop passing by luck is 2^-N: at
+// this N the test is deterministic in practice, and it involves no
+// wall-clock waiting at all.
+const racePasses = 1000
+
+// TestWaitDone_DrainedBeforeExpiredContext covers the case where a
+// component drained cleanly but the stop context had already
+// expired. Both select cases are ready, and Go chooses among ready
+// cases uniformly at random, so the drained case must be settled by
+// the preamble before the bounded select ever runs.
+func TestWaitDone_DrainedBeforeExpiredContext(t *testing.T) {
+	t.Parallel()
+
+	done := make(chan struct{})
+	close(done)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	for pass := range racePasses {
+		require.NoErrorf(
+			t,
+			lifecycle.WaitDone(
+				ctx, discardLogger(), "test component", done,
+			),
+			"pass %d reported a timeout for a drained component",
+			pass,
+		)
+	}
+}
+
+// TestWaitDone_ExpiredContext pins the other side of the preamble:
+// an expired context with a component that has not drained is still
+// a timeout.
+func TestWaitDone_ExpiredContext(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	err := lifecycle.WaitDone(
+		ctx, discardLogger(), "test component",
+		make(chan struct{}),
+	)
+
+	require.ErrorIs(t, err, context.Canceled)
+	require.ErrorContains(t, err, "test component")
+}
+
 func TestWaitForShutdown_ContextExpires(t *testing.T) {
 	t.Parallel()