feat: add durable outbox dispatcher

multiplayer-todo.md

@@ -1202,7 +1202,7 @@ the local/CI/community transport, not a silent production fallback.
 | 8.22 `[D:8.21]` | **IN PROGRESS.** Pure Go ranked profile exposes the first ten games as provisional, derives tiers only through validated backend-owned rating bands, and keeps casual ratings outside the API; authenticated HTTP now returns the authoritative ranked view | `server/domain/rating.go`, `tier_test.go` and `server/api/service.go` cover provisional override, exact band boundaries, malformed policy rejection, session authentication and ranked-only response fields; persisted tier policy, client UI and reconnect transport remain |
 | 8.23 `[D:8.21]` | **IN PROGRESS.** Pure Go ranked-only season policy compresses 25% toward 1500, clamps RD to 200–350, preserves volatility/history, is idempotent by season ID, and defines exact 12-week windows/due detection; migration and Go store now persist a per-player/per-season marker and rating update atomically | `server/domain/rating.go`, `season_test.go`, `server/migrations/0001_initial.sql` and `server/store/season_sql.go` cover compression, floor/cap, duplicate replay, window boundary, completed-season idempotence, row locking and conflict-safe rollover markers; live PostgreSQL execution and maintenance scheduler remain |
 | 8.24 `[D:8.9,8.20,8.21]` | **IN PROGRESS.** Pure Go ranked connection policy binds match/server/player/team/slot/protocol, supports 60 s reclaim with server-owned generations, fences old connections, and applies the rolling 7-day 5 m/15 m/1 h/24 h abandon ladder; canonical signed authorisation issuance/verification now gates admission | `server/domain/reconnect.go`, `join_auth.go` and adversarial fixtures cover repeated backend-independent reclaim, all signed claim binding, tampering, failed verification, old-generation fencing, grace boundary and deterministic cooldown audit ordering; persistent lease fencing, join transport and full match/result integration remain |
-| 8.25 `[D:8.10,8.24]` | **IN PROGRESS.** Pure Go result policy binds match/server/workload identity, hashes canonical payloads, makes identical retries idempotent, leaves conflicts inert, separates integrity eligibility, classifies roster/simulation/result/fairness evidence, validates annotation signatures/digests, and exposes 5 m alert/30 m review delivery thresholds; Go store SQL now executes the receipt → match lock → completion → receipt acknowledgment → outbox boundary atomically, and exposes bounded ordered outbox reads plus publish acknowledgements for replayable fan-out | `server/domain/result.go`, `workload.go`, `server/store/result_sql.go` and `outbox.go` plus adversarial fixtures cover credential binding, duplicate/conflict, annotation forgery, delivery-outage-versus-integrity classification, commit ordering, idempotent SQL reconciliation and unpublished-event replay/ack boundaries; production credential verification, Agones annotation persistence/reconciliation, rating-lock integration, live PostgreSQL execution and integrity evidence adapters remain |
+| 8.25 `[D:8.10,8.24]` | **IN PROGRESS.** Pure Go result policy binds match/server/workload identity, hashes canonical payloads, makes identical retries idempotent, leaves conflicts inert, separates integrity eligibility, classifies roster/simulation/result/fairness evidence, validates annotation signatures/digests, and exposes 5 m alert/30 m review delivery thresholds; Go store SQL now executes the receipt → match lock → completion → receipt acknowledgment → outbox boundary atomically, and exposes bounded ordered outbox reads plus publish acknowledgements for replayable fan-out; `OutboxDispatcher` now delivers in order and acknowledges only after successful fan-out | `server/domain/result.go`, `workload.go`, `server/store/result_sql.go` and `outbox.go` plus adversarial fixtures cover credential binding, duplicate/conflict, annotation forgery, delivery-outage-versus-integrity classification, commit ordering, idempotent SQL reconciliation, unpublished-event replay/ack boundaries and delivery-before-ack failure ordering; production credential verification, Agones annotation persistence/reconciliation, rating-lock integration, live PostgreSQL execution and integrity evidence adapters remain |
 
 #### 8D — Agones, allocation and regional scaling
 
@@ -1227,7 +1227,7 @@ the local/CI/community transport, not a silent production fallback.
 | # | Task | Acceptance |
 |---|---|---|
 | 8.39 `[D:8.3,8.14,8.17]` | **IN PROGRESS.** `MatchmakingState` now projects queue → proposal → allocation/process-ready/assignment-ready/connect/live plus terminal failure states; autoload `ControlPlaneClient` provides authenticated queue create/recovery/heartbeat/cancel and proposal response requests with idempotency/revision headers; `matchmaking.tscn`/`matchmaking.gd` expose the state and authoritative actions from the main menu; authenticated proposal recovery now reconciles missed proposal events and expires them at read time; the Go API publishes targeted authenticated revisioned queue/proposal/assignment events and the Godot client consumes state/proposal/assignment events, fetching the authoritative assignment after assignment readiness; the API can now use the durable participant-scoped proposal provider for both recovery and accept/decline mutations | `test_matchmaking_state.gd`, `test_control_plane_client.gd`, `test_matchmaking_ui.gd`, `TestProposalRecoveryIsParticipantScopedAndExpiresAtReadBoundary`, `TestAuthenticatedWebSocketDeliversOnlyTargetedRevisionedEvents`, `TestStateChangingAPIActionsPublishTargetedEvents`, `TestProposalRecoveryUsesDurableBackendAndRemainsParticipantScoped` and store proposal SQL tests reject stale/gapped/conflicting updates, validate endpoint/token/payload normalization, preserve idempotent duplicates, and guarantee visible phase/terminal copy; wiring durable allocation events into the outbox, wait/latency explanations and Godot runtime verification remain |
-| 8.40 `[D:8.3,8.14]` | **IN PROGRESS.** Pure Go revisioned replica reducer rejects gaps for REST resync, makes duplicate/out-of-order events idempotent, and resumes from the authoritative snapshot revision; authenticated queue-ticket recovery now has an owner-checked REST read; Godot client projection persists non-secret ticket/proposal state, forces authoritative recovery after restart, and can replay a lost queue-create response with the original ticket/idempotency key; the Go API now exposes an authenticated `/v1/events` WebSocket with bounded per-player queues, strict upgrade/vocabulary validation and REST-resync-safe slow-client failure; Godot `ControlPlaneClient` can connect to the stream, consume validated events, automatically reconnect with bounded backoff, and trigger REST recovery on projection gaps and stream return | `server/domain/sync.go`, `server/api/events.go`, `server/api/service.go`, `service_test.go`, `matchmaking_state.gd` and `control_plane_client.gd` cover gap, snapshot, replay, same-revision conflict, owner-only ticket recovery, expired-ticket terminal handling, malformed restart snapshots, API-level duplicate-create replay/conflict, authenticated handshake/key rejection, targeted event delivery, exactly-once slow-subscriber closure and invalid-event rejection; durable outbox fan-out and live Godot verification remain |
+| 8.40 `[D:8.3,8.14]` | **IN PROGRESS.** Pure Go revisioned replica reducer rejects gaps for REST resync, makes duplicate/out-of-order events idempotent, and resumes from the authoritative snapshot revision; authenticated queue-ticket recovery now has an owner-checked REST read; Godot client projection persists non-secret ticket/proposal state, forces authoritative recovery after restart, and can replay a lost queue-create response with the original ticket/idempotency key; the Go API now exposes an authenticated `/v1/events` WebSocket with bounded per-player queues, strict upgrade/vocabulary validation and REST-resync-safe slow-client failure; Godot `ControlPlaneClient` can connect to the stream, consume validated events, automatically reconnect with bounded backoff, and trigger REST recovery on projection gaps and stream return; `OutboxDispatcher` now provides ordered at-least-once delivery after durable commit | `server/domain/sync.go`, `server/api/events.go`, `server/api/service.go`, `server/store/outbox.go`, `service_test.go`, `outbox_test.go`, `matchmaking_state.gd` and `control_plane_client.gd` cover gap, snapshot, replay, same-revision conflict, owner-only ticket recovery, expired-ticket terminal handling, malformed restart snapshots, API-level duplicate-create replay/conflict, authenticated handshake/key rejection, targeted event delivery, exactly-once slow-subscriber closure, invalid-event rejection and delivery-before-ack failure ordering; wiring the dispatcher to a production WebSocket/Redis worker and live Godot verification remain |
 | 8.41 `[D:7.8,8.9,8.31,8.40]` | **IN PROGRESS.** Authenticated `GET /v1/assignments/{matchId}` now exposes only a validated, player-scoped assignment view; Godot `AssignmentState`/`ControlPlaneClient.fetch_assignment()` bind the response to the authenticated player, recheck expiry, preserve explicit transport/slot/join authorisation and do not connect before assignment-ready; migration 0002 and the Go store adapter now persist/recover the complete player-scoped assignment projection with conflict-safe identical replay; `AssignmentProviderFromStore` wires that durable projection into the API injection point; `SaveAssignments` publishes a complete signed roster atomically instead of allowing partial player visibility; `SaveVerifiedAssignmentRoster` rechecks signed claims before deriving player rows | `server/api/service.go`, `store_adapters.go`, `service_test.go`, `assignment_state.gd`, `test_assignment_state.gd`, `server/migrations/0002_assignments.sql` and `server/store/assignment_sql.go` cover participant/identity/expiry/shape/transport boundaries, player-scoped schema keys, expiry-filtered reads, assignment upsert conflict handling, atomic batch validation and signed-claim binding; direct API caller wiring, SDR relay-ticket installation, `hello` join-authorisation wiring, fencing integration and live Godot/PostgreSQL verification remain |
 | 8.42 `[D:8.22,8.23,8.24,8.40]` | **IN PROGRESS.** `RankedProfileState` and `ControlPlaneClient.fetch_ranked_profile()` expose the backend-authoritative rating/RD/volatility/games/tier/provisional/season view; matchmaking UI displays provisional/tier status without client-side rating math | `test_control_plane_client.gd` validates profile shape, numeric safety and provisional display; ranked profile fetch/display, committed revision after reconnect, abandon status and season countdown remain dependent on live auth/backend events and Godot runtime verification |
 | 8.43 `[D:8.39,8.40,8.41]` | **IN PROGRESS.** Matchmaking client now distinguishes expired queue recovery, session expiry, missing records and retryable control-plane outages; a 401 clears the in-memory token, emits `session_expired` and disables retry until a new session is configured; terminal messages remain visible and active searches are not falsely failed on transient errors | `MatchmakingState` and `ControlPlaneClient` tests cover explicit expiry and the existing terminal/retry-safe state paths; decline, version mismatch, regional outage retry UI, failed reconnect, duplicate-action recovery and live Godot verification remain |

server/store/outbox.go

@@ -34,6 +34,57 @@ WHERE event_id = $1 AND published_at IS NULL`
 
 var ErrOutboxEventNotFound = fmt.Errorf("outbox event not found or already published")
 
+type OutboxDelivery func(context.Context, OutboxEvent) error
+
+// OutboxDispatcher is the durable-to-transient bridge. Read and Ack are
+// injectable so ordering can be tested without a live PostgreSQL instance.
+// Delivery is at-least-once: a crash after delivery and before acknowledgement
+// leaves the event replayable, while a delivery failure stops the batch.
+type OutboxDispatcher struct {
+	Read    func(context.Context, int) ([]OutboxEvent, error)
+	Ack     func(context.Context, string, time.Time) error
+	Deliver OutboxDelivery
+}
+
+func NewOutboxDispatcher(db *sql.DB, deliver OutboxDelivery) *OutboxDispatcher {
+	return &OutboxDispatcher{
+		Read: func(ctx context.Context, limit int) ([]OutboxEvent, error) {
+			return ReadUnpublishedOutbox(ctx, db, limit)
+		},
+		Ack: func(ctx context.Context, eventID string, publishedAt time.Time) error {
+			return MarkOutboxPublished(ctx, db, eventID, publishedAt)
+		},
+		Deliver: deliver,
+	}
+}
+
+// Dispatch publishes at most limit events in the store's stable order and
+// returns the number acknowledged. A successful delivery followed by an ack
+// error intentionally leaves that event replayable.
+func (d *OutboxDispatcher) Dispatch(ctx context.Context, limit int, publishedAt time.Time) (int, error) {
+	if d == nil || d.Read == nil || d.Ack == nil || d.Deliver == nil || limit < 1 || limit > 1000 || publishedAt.IsZero() {
+		return 0, fmt.Errorf("invalid outbox dispatcher")
+	}
+	events, err := d.Read(ctx, limit)
+	if err != nil {
+		return 0, err
+	}
+	acknowledged := 0
+	for _, event := range events {
+		if event.EventID == "" {
+			return acknowledged, fmt.Errorf("outbox event has no ID")
+		}
+		if err := d.Deliver(ctx, event); err != nil {
+			return acknowledged, err
+		}
+		if err := d.Ack(ctx, event.EventID, publishedAt); err != nil {
+			return acknowledged, err
+		}
+		acknowledged++
+	}
+	return acknowledged, nil
+}
+
 // ReadUnpublishedOutbox returns a bounded, stable ordered batch. It does not
 // mark rows before delivery: a worker crash therefore leaves events replayable.
 func ReadUnpublishedOutbox(ctx context.Context, db *sql.DB, limit int) ([]OutboxEvent, error) {

server/store/outbox_test.go

@@ -1,6 +1,9 @@
 package store
 
 import (
+	"context"
+	"errors"
+	"reflect"
 	"testing"
 	"time"
 )
@@ -18,6 +21,38 @@ func TestOutboxSQLPreservesReplayableOrderedReadAndPublishAck(t *testing.T) {
 	}
 }
 
+func TestOutboxDispatcherAcknowledgesOnlyAfterDelivery(t *testing.T) {
+	events := []OutboxEvent{{EventID: "event-1"}, {EventID: "event-2"}}
+	var delivered, acknowledged []string
+	dispatcher := &OutboxDispatcher{
+		Read: func(context.Context, int) ([]OutboxEvent, error) { return events, nil },
+		Deliver: func(_ context.Context, event OutboxEvent) error {
+			delivered = append(delivered, event.EventID)
+			if event.EventID == "event-2" {
+				return errors.New("transient fan-out failure")
+			}
+			return nil
+		},
+		Ack: func(_ context.Context, eventID string, _ time.Time) error {
+			acknowledged = append(acknowledged, eventID)
+			return nil
+		},
+	}
+	count, err := dispatcher.Dispatch(context.Background(), 10, time.Unix(1000, 0))
+	if err == nil || count != 1 {
+		t.Fatalf("dispatch = (%d, %v), want one acknowledged event and an error", count, err)
+	}
+	if !reflect.DeepEqual(delivered, []string{"event-1", "event-2"}) || !reflect.DeepEqual(acknowledged, []string{"event-1"}) {
+		t.Fatalf("delivery/ack order = %v/%v", delivered, acknowledged)
+	}
+}
+
+func TestOutboxDispatcherRejectsInvalidConfiguration(t *testing.T) {
+	if count, err := (*OutboxDispatcher)(nil).Dispatch(context.Background(), 1, time.Unix(1000, 0)); err == nil || count != 0 {
+		t.Fatal("nil dispatcher accepted")
+	}
+}
+
 func TestOutboxAdaptersRejectUnsafeArgumentsWithoutDatabase(t *testing.T) {
 	if _, err := ReadUnpublishedOutbox(nil, nil, 1); err == nil {
 		t.Fatal("nil database accepted")