diplomail (Stage E): LibreTranslate client + async translation worker

Synchronous translation on read (Stage D) blocks the HTTP handler on
translator I/O. Stage E switches to "send moments-fast, deliver
when translated": recipients whose preferred_language differs from
the detected body_lang are inserted with available_at=NULL, and an
async worker turns them on once a LibreTranslate call materialises
the cache row (or fails terminally after 5 retries).

Schema delta on diplomail_recipients: available_at,
translation_attempts, next_translation_attempt_at, plus a snapshot
recipient_preferred_language so the worker queries do not need a
join. Read paths (ListInbox, GetMessage, UnreadCount) filter on
available_at IS NOT NULL. Push fan-out is moved from Service to the
worker so the recipient only sees the toast when the inbox row is
actually visible.

Translator backend is now a configurable choice: empty
BACKEND_DIPLOMAIL_TRANSLATOR_URL → noop (deliver original);
populated → LibreTranslate HTTP client. Per-attempt timeout, max
attempts, and worker interval all live in DiplomailConfig. The HTTP
client itself is unit-tested via httptest (happy path, BCP47
normalisation, unsupported pair, 5xx, identical src/dst, missing
URL); worker delivery + fallback paths are covered by the
testcontainers-backed e2e tests in diplomail_e2e_test.go.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/internal/diplomail/store.go

@@ -42,7 +42,8 @@ func recipientColumns() postgres.ColumnList {
 	r := table.DiplomailRecipients
 	return postgres.ColumnList{
 		r.RecipientID, r.MessageID, r.GameID, r.UserID,
-		r.RecipientUserName, r.RecipientRaceName,
+		r.RecipientUserName, r.RecipientRaceName, r.RecipientPreferredLanguage,
+		r.AvailableAt, r.TranslationAttempts, r.NextTranslationAttemptAt,
 		r.DeliveredAt, r.ReadAt, r.DeletedAt, r.NotifiedAt,
 	}
 }
@@ -65,14 +66,20 @@ type MessageInsert struct {
 	BroadcastScope string
 }
 
-// RecipientInsert carries the per-recipient snapshot.
+// RecipientInsert carries the per-recipient snapshot. AvailableAt
+// captures the async-delivery contract: when non-nil, the recipient
+// row is materialised already-delivered (no translation needed or
+// the language matches); when nil, the recipient is queued for the
+// translation worker.
 type RecipientInsert struct {
-	RecipientID       uuid.UUID
-	MessageID         uuid.UUID
-	GameID            uuid.UUID
-	UserID            uuid.UUID
-	RecipientUserName string
-	RecipientRaceName *string
+	RecipientID                uuid.UUID
+	MessageID                  uuid.UUID
+	GameID                     uuid.UUID
+	UserID                     uuid.UUID
+	RecipientUserName          string
+	RecipientRaceName          *string
+	RecipientPreferredLanguage string
+	AvailableAt                *time.Time
 }
 
 // InsertMessageWithRecipients persists a Message together with one or
@@ -120,6 +127,7 @@ func (s *Store) InsertMessageWithRecipients(ctx context.Context, msg MessageInse
 	rcptStmt := r.INSERT(
 		r.RecipientID, r.MessageID, r.GameID, r.UserID,
 		r.RecipientUserName, r.RecipientRaceName,
+		r.RecipientPreferredLanguage, r.AvailableAt,
 	)
 	for _, in := range recipients {
 		rcptStmt = rcptStmt.VALUES(
@@ -129,6 +137,8 @@ func (s *Store) InsertMessageWithRecipients(ctx context.Context, msg MessageInse
 			in.UserID,
 			in.RecipientUserName,
 			stringPtrArg(in.RecipientRaceName),
+			in.RecipientPreferredLanguage,
+			timePtrArg(in.AvailableAt),
 		)
 	}
 	rcptStmt = rcptStmt.RETURNING(recipientColumns())
@@ -198,7 +208,9 @@ func (s *Store) LoadInboxEntry(ctx context.Context, messageID, userID uuid.UUID)
 
 // ListInbox returns the recipient view of messages addressed to
 // userID in gameID, newest first. Soft-deleted rows
-// (`deleted_at IS NOT NULL`) are excluded.
+// (`deleted_at IS NOT NULL`) are excluded. Rows still waiting for
+// the async translation worker (`available_at IS NULL`) are also
+// excluded — they will appear once delivery is complete.
 func (s *Store) ListInbox(ctx context.Context, gameID, userID uuid.UUID) ([]InboxEntry, error) {
 	m := table.DiplomailMessages
 	r := table.DiplomailRecipients
@@ -208,7 +220,8 @@ func (s *Store) ListInbox(ctx context.Context, gameID, userID uuid.UUID) ([]Inbo
 		WHERE(
 			r.UserID.EQ(postgres.UUID(userID)).
 				AND(r.GameID.EQ(postgres.UUID(gameID))).
-				AND(r.DeletedAt.IS_NULL()),
+				AND(r.DeletedAt.IS_NULL()).
+				AND(r.AvailableAt.IS_NOT_NULL()),
 		).
 		ORDER_BY(m.CreatedAt.DESC(), m.MessageID.DESC())
 	var dest []struct {
@@ -336,9 +349,10 @@ func (s *Store) LoadRecipient(ctx context.Context, messageID, userID uuid.UUID)
 	return recipientFromModel(row), nil
 }
 
-// UnreadCountForUserGame returns the count of unread, non-deleted
-// messages addressed to userID in gameID. Backs the push payload
-// `unread_game` field.
+// UnreadCountForUserGame returns the count of unread, non-deleted,
+// delivered messages addressed to userID in gameID. Recipients
+// still waiting for translation (`available_at IS NULL`) are
+// excluded so the badge does not flicker.
 func (s *Store) UnreadCountForUserGame(ctx context.Context, gameID, userID uuid.UUID) (int, error) {
 	r := table.DiplomailRecipients
 	stmt := postgres.SELECT(postgres.COUNT(postgres.STAR).AS("count")).
@@ -347,7 +361,8 @@ func (s *Store) UnreadCountForUserGame(ctx context.Context, gameID, userID uuid.
 			r.UserID.EQ(postgres.UUID(userID)).
 				AND(r.GameID.EQ(postgres.UUID(gameID))).
 				AND(r.ReadAt.IS_NULL()).
-				AND(r.DeletedAt.IS_NULL()),
+				AND(r.DeletedAt.IS_NULL()).
+				AND(r.AvailableAt.IS_NOT_NULL()),
 		)
 	var dest struct {
 		Count int64 `alias:"count"`
@@ -358,6 +373,149 @@ func (s *Store) UnreadCountForUserGame(ctx context.Context, gameID, userID uuid.
 	return int(dest.Count), nil
 }
 
+// PendingTranslationPair carries one unit of work picked by the
+// translation worker. Multiple recipients of the same message that
+// share a preferred_language collapse into one pair, because the
+// translation is shared via the diplomail_translations cache.
+// CurrentAttempts is the highest `translation_attempts` value across
+// the matching recipient rows, so the worker can decide whether the
+// next attempt is the last one before falling back.
+type PendingTranslationPair struct {
+	MessageID       uuid.UUID
+	TargetLang      string
+	CurrentAttempts int32
+}
+
+// PickPendingTranslationPair returns one pair eligible for the
+// translation worker, or `ok == false` when the queue is empty. The
+// pair is the (message, target_lang) of any recipient where
+// `available_at IS NULL` and `next_translation_attempt_at` is either
+// unset or already due. The query intentionally drops the
+// `FOR UPDATE` clause — the worker is single-threaded per process,
+// and the optimistic UPDATE in `MarkPairDelivered` /
+// `MarkPairFallback` filters by `available_at IS NULL`, so a stale
+// pickup never delivers twice.
+func (s *Store) PickPendingTranslationPair(ctx context.Context, now time.Time) (PendingTranslationPair, bool, error) {
+	r := table.DiplomailRecipients
+	stmt := postgres.SELECT(
+		r.MessageID.AS("message_id"),
+		r.RecipientPreferredLanguage.AS("target_lang"),
+		postgres.MAX(r.TranslationAttempts).AS("attempts"),
+	).
+		FROM(r).
+		WHERE(
+			r.AvailableAt.IS_NULL().
+				AND(r.RecipientPreferredLanguage.NOT_EQ(postgres.String(""))).
+				AND(r.NextTranslationAttemptAt.IS_NULL().
+					OR(r.NextTranslationAttemptAt.LT_EQ(postgres.TimestampzT(now.UTC())))),
+		).
+		GROUP_BY(r.MessageID, r.RecipientPreferredLanguage).
+		ORDER_BY(r.MessageID.ASC(), r.RecipientPreferredLanguage.ASC()).
+		LIMIT(1)
+	var dest struct {
+		MessageID  uuid.UUID `alias:"message_id"`
+		TargetLang string    `alias:"target_lang"`
+		Attempts   int32     `alias:"attempts"`
+	}
+	if err := stmt.QueryContext(ctx, s.db, &dest); err != nil {
+		if errors.Is(err, qrm.ErrNoRows) {
+			return PendingTranslationPair{}, false, nil
+		}
+		return PendingTranslationPair{}, false, fmt.Errorf("diplomail store: pick pending pair: %w", err)
+	}
+	if dest.MessageID == (uuid.UUID{}) {
+		return PendingTranslationPair{}, false, nil
+	}
+	return PendingTranslationPair{
+		MessageID:       dest.MessageID,
+		TargetLang:      dest.TargetLang,
+		CurrentAttempts: dest.Attempts,
+	}, true, nil
+}
+
+// MarkPairDelivered flips every still-pending recipient of (messageID,
+// targetLang) to `available_at = at`, optionally persisting the
+// translation row alongside in the same transaction. Returns the
+// recipients that were just delivered (used by the worker to fan out
+// push events).
+func (s *Store) MarkPairDelivered(ctx context.Context, messageID uuid.UUID, targetLang string, translation *Translation, at time.Time) ([]Recipient, error) {
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return nil, fmt.Errorf("diplomail store: begin deliver tx: %w", err)
+	}
+	defer func() { _ = tx.Rollback() }()
+
+	if translation != nil {
+		t := table.DiplomailTranslations
+		ins := t.INSERT(
+			t.TranslationID, t.MessageID, t.TargetLang,
+			t.TranslatedSubject, t.TranslatedBody, t.Translator,
+		).VALUES(
+			translation.TranslationID, translation.MessageID, translation.TargetLang,
+			translation.TranslatedSubject, translation.TranslatedBody, translation.Translator,
+		).ON_CONFLICT(t.MessageID, t.TargetLang).DO_NOTHING()
+		if _, err := ins.ExecContext(ctx, tx); err != nil {
+			return nil, fmt.Errorf("diplomail store: upsert translation: %w", err)
+		}
+	}
+
+	r := table.DiplomailRecipients
+	upd := r.UPDATE(r.AvailableAt, r.NextTranslationAttemptAt).
+		SET(postgres.TimestampzT(at.UTC()), postgres.NULL).
+		WHERE(
+			r.MessageID.EQ(postgres.UUID(messageID)).
+				AND(r.RecipientPreferredLanguage.EQ(postgres.String(targetLang))).
+				AND(r.AvailableAt.IS_NULL()),
+		).
+		RETURNING(recipientColumns())
+
+	var rows []model.DiplomailRecipients
+	if err := upd.QueryContext(ctx, tx, &rows); err != nil {
+		return nil, fmt.Errorf("diplomail store: mark pair delivered: %w", err)
+	}
+	if err := tx.Commit(); err != nil {
+		return nil, fmt.Errorf("diplomail store: commit deliver: %w", err)
+	}
+	out := make([]Recipient, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, recipientFromModel(row))
+	}
+	return out, nil
+}
+
+// SchedulePairRetry bumps the attempt counter and schedules the next
+// translation attempt for `next`. The recipient rows stay in the
+// pending queue (`available_at IS NULL`). Returns the new attempt
+// counter so the worker can decide whether to fall back to the
+// original on the next pickup.
+func (s *Store) SchedulePairRetry(ctx context.Context, messageID uuid.UUID, targetLang string, next time.Time) (int32, error) {
+	r := table.DiplomailRecipients
+	upd := r.UPDATE(r.TranslationAttempts, r.NextTranslationAttemptAt).
+		SET(r.TranslationAttempts.ADD(postgres.Int(1)), postgres.TimestampzT(next.UTC())).
+		WHERE(
+			r.MessageID.EQ(postgres.UUID(messageID)).
+				AND(r.RecipientPreferredLanguage.EQ(postgres.String(targetLang))).
+				AND(r.AvailableAt.IS_NULL()),
+		).
+		RETURNING(r.TranslationAttempts)
+	var dest []struct {
+		TranslationAttempts int32 `alias:"diplomail_recipients.translation_attempts"`
+	}
+	if err := upd.QueryContext(ctx, s.db, &dest); err != nil {
+		return 0, fmt.Errorf("diplomail store: schedule pair retry: %w", err)
+	}
+	if len(dest) == 0 {
+		return 0, nil
+	}
+	max := dest[0].TranslationAttempts
+	for _, d := range dest[1:] {
+		if d.TranslationAttempts > max {
+			max = d.TranslationAttempts
+		}
+	}
+	return max, nil
+}
+
 // translationColumns is the canonical projection for
 // diplomail_translations reads.
 func translationColumns() postgres.ColumnList {
@@ -532,7 +690,8 @@ func (s *Store) UnreadCountsForUser(ctx context.Context, userID uuid.UUID) ([]Un
 		WHERE(
 			r.UserID.EQ(postgres.UUID(userID)).
 				AND(r.ReadAt.IS_NULL()).
-				AND(r.DeletedAt.IS_NULL()),
+				AND(r.DeletedAt.IS_NULL()).
+				AND(r.AvailableAt.IS_NOT_NULL()),
 		).
 		GROUP_BY(r.GameID).
 		ORDER_BY(postgres.MAX(m.GameName).ASC())
@@ -584,15 +743,19 @@ func messageFromModel(row model.DiplomailMessages) Message {
 // recipientFromModel converts a jet-generated row to the domain type.
 func recipientFromModel(row model.DiplomailRecipients) Recipient {
 	out := Recipient{
-		RecipientID:       row.RecipientID,
-		MessageID:         row.MessageID,
-		GameID:            row.GameID,
-		UserID:            row.UserID,
-		RecipientUserName: row.RecipientUserName,
-		DeliveredAt:       row.DeliveredAt,
-		ReadAt:            row.ReadAt,
-		DeletedAt:         row.DeletedAt,
-		NotifiedAt:        row.NotifiedAt,
+		RecipientID:                row.RecipientID,
+		MessageID:                  row.MessageID,
+		GameID:                     row.GameID,
+		UserID:                     row.UserID,
+		RecipientUserName:          row.RecipientUserName,
+		RecipientPreferredLanguage: row.RecipientPreferredLanguage,
+		AvailableAt:                row.AvailableAt,
+		TranslationAttempts:        row.TranslationAttempts,
+		NextTranslationAttemptAt:   row.NextTranslationAttemptAt,
+		DeliveredAt:                row.DeliveredAt,
+		ReadAt:                     row.ReadAt,
+		DeletedAt:                  row.DeletedAt,
+		NotifiedAt:                 row.NotifiedAt,
 	}
 	if row.RecipientRaceName != nil {
 		name := *row.RecipientRaceName
@@ -629,3 +792,12 @@ func stringPtrArg(v *string) postgres.Expression {
 	}
 	return postgres.String(*v)
 }
+
+// timePtrArg returns the jet argument expression for a nullable
+// timestamptz column.
+func timePtrArg(v *time.Time) postgres.Expression {
+	if v == nil {
+		return postgres.NULL
+	}
+	return postgres.TimestampzT(v.UTC())
+}