feat(coordinator): worker registry, API contract, logging & DB retry

Align the coordinator with the master PLAN.md (CTX-00, CTX-04) and harden
process startup.

- CTX-00: freeze docs/api-contract.md as the v1 source of truth for the
  Go coordinator and Python worker.
- CTX-04: worker registry — workers table (migration 0002), domain.Worker,
  RegisterWorker use case, WorkerRepository, and POST /workers/register.
- Contract alignment: claim uses `capabilities` (was `workloads`),
  COORDINATOR_TOKEN env (WORKER_AUTH_TOKEN kept as fallback), and
  GET /health now reports database readiness (503 when the DB is down).
- Logging: logs are teed to stdout and an optional rotated file (LOG_FILE)
  via lumberjack, so they survive a container rebuild.
- Startup resilience: the initial DB connection is retried with backoff,
  so the coordinator waits for Postgres to boot instead of crash-looping.

coordinator/internal/infra/config.go

@@ -23,13 +23,23 @@ type Config struct {
 	// PostgreSQL connection string (pgx format / libpq URL).
 	DatabaseURL string
 	// Shared bearer token workers must present. Empty disables auth (dev only).
-	WorkerAuthToken string
+	Token string
+
+	// Minimum log level: debug, info, warn, error.
+	LogLevel string
+	// Path to a rotated log file. Empty logs to stdout only.
+	LogFile string
 
 	// Connection pool upper bound.
 	DBMaxConns int32
+	// How long to keep retrying the initial database connection at startup
+	// before giving up. Covers a Postgres container that is still booting.
+	DBConnectTimeout time.Duration
 	// Per-request context timeout applied to handlers and DB calls.
 	RequestTimeout time.Duration
 
+	// Suggested heartbeat cadence returned to workers on registration.
+	HeartbeatInterval time.Duration
 	// Default lease length handed out on claim.
 	LeaseDuration time.Duration
 	// Default attempt ceiling for newly created tasks.
@@ -43,7 +53,7 @@ type Config struct {
 //
 // A .env file (path overridable via ENV_FILE) is loaded first as a local-dev
 // convenience. It only fills variables the environment does not already define.
-func Load() (Config, error) {
+func LoadConfig() (Config, error) {
 	envFile := os.Getenv("ENV_FILE")
 	if envFile == "" {
 		envFile = defaultEnvFile
@@ -56,11 +66,17 @@ func Load() (Config, error) {
 	}
 
 	cfg := Config{
-		Addr:               getEnv("COORDINATOR_ADDR", ":8080"),
-		DatabaseURL:        os.Getenv("DATABASE_URL"),
-		WorkerAuthToken:    os.Getenv("WORKER_AUTH_TOKEN"),
+		Addr:        getEnv("COORDINATOR_ADDR", ":8080"),
+		DatabaseURL: os.Getenv("DATABASE_URL"),
+		// COORDINATOR_TOKEN is the contract name; WORKER_AUTH_TOKEN is the
+		// former name, still honoured so existing .env files keep working.
+		Token:              getEnv("COORDINATOR_TOKEN", os.Getenv("WORKER_AUTH_TOKEN")),
+		LogLevel:           getEnv("LOG_LEVEL", "info"),
+		LogFile:            os.Getenv("LOG_FILE"),
 		DBMaxConns:         10,
+		DBConnectTimeout:   30 * time.Second,
 		RequestTimeout:     15 * time.Second,
+		HeartbeatInterval:  15 * time.Second,
 		LeaseDuration:      2 * time.Minute,
 		DefaultMaxAttempts: 3,
 		ReaperInterval:     30 * time.Second,
@@ -74,9 +90,15 @@ func Load() (Config, error) {
 	if cfg.DBMaxConns, err = getEnvInt32("DB_MAX_CONNS", cfg.DBMaxConns); err != nil {
 		return Config{}, err
 	}
+	if cfg.DBConnectTimeout, err = getEnvDuration("DB_CONNECT_TIMEOUT", cfg.DBConnectTimeout); err != nil {
+		return Config{}, err
+	}
 	if cfg.RequestTimeout, err = getEnvDuration("REQUEST_TIMEOUT", cfg.RequestTimeout); err != nil {
 		return Config{}, err
 	}
+	if cfg.HeartbeatInterval, err = getEnvDuration("HEARTBEAT_INTERVAL", cfg.HeartbeatInterval); err != nil {
+		return Config{}, err
+	}
 	if cfg.LeaseDuration, err = getEnvDuration("LEASE_DURATION", cfg.LeaseDuration); err != nil {
 		return Config{}, err
 	}

coordinator/internal/infra/db.go

@@ -3,13 +3,16 @@ package infra
 
 import (
 	"context"
+	"log/slog"
+	"time"
 
+	"github.com/cenkalti/backoff/v4"
 	"github.com/jackc/pgx/v5/pgxpool"
 )
 
 // NewPool builds the single shared pool. The caller owns its lifetime and must
 // Close() it on shutdown.
-func NewPool(ctx context.Context, cfg Config) (*pgxpool.Pool, error) {
+func NewPool(ctx context.Context, cfg Config, log *slog.Logger) (*pgxpool.Pool, error) {
 	poolCfg, err := pgxpool.ParseConfig(cfg.DatabaseURL)
 	if err != nil {
 		return nil, err
@@ -20,11 +23,43 @@ func NewPool(ctx context.Context, cfg Config) (*pgxpool.Pool, error) {
 	if err != nil {
 		return nil, err
 	}
-	// pgxpool.New is lazy, so without this ping a bad DATABASE_URL would only
-	// surface on the first request instead of at startup.
-	if err := pool.Ping(ctx); err != nil {
+	// pgxpool.New is lazy, so a ping is needed to actually reach the server.
+	// It is retried because at startup — especially under docker-compose, where
+	// the coordinator can boot before Postgres is accepting connections — a
+	// service should wait for its database rather than crash-loop.
+	if err := pingWithRetry(ctx, pool, cfg.DBConnectTimeout, log); err != nil {
 		pool.Close()
 		return nil, err
 	}
 	return pool, nil
 }
+
+// pingWithRetry waits for the database to accept connections, backing off
+// between attempts until the budget elapses or ctx is cancelled.
+//
+// Unlike the transaction retry in storage/postgres, this retries *any* ping
+// error: at startup a "connection refused" is the expected, retryable state,
+// not an anomaly.
+func pingWithRetry(ctx context.Context, pool *pgxpool.Pool, budget time.Duration, log *slog.Logger) error {
+	b := backoff.NewExponentialBackOff()
+	b.InitialInterval = 200 * time.Millisecond
+	b.MaxInterval = 3 * time.Second
+	b.MaxElapsedTime = budget
+
+	attempt := 0
+	return backoff.RetryNotify(
+		func() error {
+			// A bounded per-attempt timeout so one hung dial cannot eat the
+			// whole budget in a single try.
+			pingCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
+			defer cancel()
+			return pool.Ping(pingCtx)
+		},
+		backoff.WithContext(b, ctx),
+		func(err error, next time.Duration) {
+			attempt++
+			log.Warn("database not ready, retrying",
+				"attempt", attempt, "retry_in", next.String(), "err", err)
+		},
+	)
+}

coordinator/internal/infra/doc.go

@@ -1,7 +0,0 @@
-// Package infra holds the outermost layer: frameworks, drivers, and process
-// wiring. It reads configuration, opens the database pool, supplies the real
-// clock, and runs the HTTP server and background reaper.
-//
-// Nothing inward depends on this package — it is the last thing constructed and
-// the first thing that would be swapped when the runtime environment changes.
-package infra

coordinator/internal/infra/logging.go

@@ -0,0 +1,65 @@
+package infra
+
+import (
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gopkg.in/natefinch/lumberjack.v2"
+)
+
+// NewLogger builds the process logger.
+//
+// It always writes JSON to stdout, so `docker logs` and any 12-factor log
+// collector keep working. When LogFile is set it *also* writes to a
+// size-rotated file, so logs survive a container rebuild instead of vanishing
+// with the previous stdout stream. Rotation is delegated to lumberjack rather
+// than hand-rolled.
+//
+// The returned Closer flushes and closes the file; call it on shutdown.
+func NewLogger(cfg Config) (*slog.Logger, io.Closer, error) {
+	opts := &slog.HandlerOptions{Level: parseLevel(cfg.LogLevel)}
+
+	var (
+		out    io.Writer = os.Stdout
+		closer io.Closer = noopCloser{}
+	)
+
+	if cfg.LogFile != "" {
+		if err := os.MkdirAll(filepath.Dir(cfg.LogFile), 0o755); err != nil {
+			return nil, nil, fmt.Errorf("create log directory: %w", err)
+		}
+		rotator := &lumberjack.Logger{
+			Filename:   cfg.LogFile,
+			MaxSize:    50, // megabytes before a rotation
+			MaxBackups: 5,  // keep this many rotated files
+			MaxAge:     30, // days
+			Compress:   true,
+		}
+		// Tee to both: the console stays live while the file is the durable copy.
+		out = io.MultiWriter(os.Stdout, rotator)
+		closer = rotator
+	}
+
+	return slog.New(slog.NewJSONHandler(out, opts)), closer, nil
+}
+
+func parseLevel(s string) slog.Level {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "debug":
+		return slog.LevelDebug
+	case "warn", "warning":
+		return slog.LevelWarn
+	case "error":
+		return slog.LevelError
+	default:
+		return slog.LevelInfo
+	}
+}
+
+type noopCloser struct{}
+
+func (noopCloser) Close() error { return nil }