feat: promote accepted proposals from API

server/api/service.go

@@ -63,6 +63,14 @@ type ProposalBackend interface {
 type ProposalMutationBackend interface {
 	Respond(context.Context, string, string, string, bool, uint64, time.Time) (domain.Proposal, error)
 }
+type ProposalPromoter interface {
+	Promote(context.Context, domain.Proposal, time.Time) error
+}
+type ProposalPromoterFunc func(context.Context, domain.Proposal, time.Time) error
+
+func (f ProposalPromoterFunc) Promote(ctx context.Context, proposal domain.Proposal, now time.Time) error {
+	return f(ctx, proposal, now)
+}
 
 type AssignmentView struct {
 	MatchID           string    `json:"match_id"`
@@ -83,29 +91,30 @@ type AssignmentView struct {
 type AssignmentProvider func(context.Context, string, string, time.Time) (AssignmentView, error)
 
 type Service struct {
-	Sessions        *domain.SessionStore
-	SessionBackend  SessionBackend
-	SessionIssuer   SessionIssuer
-	SteamLogin      SteamLoginProvider
-	Queue           *domain.Queue
-	Candidate       CandidateProvider
-	CandidateV2     CandidateProviderV2
-	QueueBackend    QueueBackend
-	CandidateIndex  CandidateIndex
-	Probe           ProbeProvider
-	ProbeRecorder   ProbeRecorder
-	WorkloadVerify  WorkloadVerifier
-	ResultSubmitter ResultSubmitter
-	Assignment      AssignmentProvider
-	Now             func() time.Time
-	Proposals       map[string]*domain.Proposal
-	ProposalBackend ProposalBackend
-	RankedProfiles  map[string]domain.RankedProfile
-	TierPolicy      domain.TierPolicy
-	RateLimiter     *RateLimiter
-	proposalMu      sync.Mutex
-	eventsMu        sync.Mutex
-	events          *eventHub
+	Sessions         *domain.SessionStore
+	SessionBackend   SessionBackend
+	SessionIssuer    SessionIssuer
+	SteamLogin       SteamLoginProvider
+	Queue            *domain.Queue
+	Candidate        CandidateProvider
+	CandidateV2      CandidateProviderV2
+	QueueBackend     QueueBackend
+	CandidateIndex   CandidateIndex
+	Probe            ProbeProvider
+	ProbeRecorder    ProbeRecorder
+	WorkloadVerify   WorkloadVerifier
+	ResultSubmitter  ResultSubmitter
+	Assignment       AssignmentProvider
+	Now              func() time.Time
+	Proposals        map[string]*domain.Proposal
+	ProposalBackend  ProposalBackend
+	ProposalPromoter ProposalPromoter
+	RankedProfiles   map[string]domain.RankedProfile
+	TierPolicy       domain.TierPolicy
+	RateLimiter      *RateLimiter
+	proposalMu       sync.Mutex
+	eventsMu         sync.Mutex
+	events           *eventHub
 }
 
 func (s *Service) Handler() http.Handler {
@@ -598,6 +607,12 @@ func (s *Service) proposalMutation(w http.ResponseWriter, r *http.Request) {
 		writeDomainError(w, err)
 		return
 	}
+	if updated.State == domain.Accepted && s.ProposalPromoter != nil {
+		if err := s.ProposalPromoter.Promote(r.Context(), updated, now); err != nil {
+			writeError(w, http.StatusServiceUnavailable, "match_promotion_unavailable")
+			return
+		}
+	}
 	s.publishProposalEvent(updated, now)
 	writeJSON(w, http.StatusOK, toProposalResponse(updated))
 }

server/api/service_test.go

@@ -41,6 +41,18 @@ type resultSubmitterSpy struct {
 	result domain.MatchResult
 }
 
+type proposalPromoterSpy struct {
+	calls    int
+	proposal domain.Proposal
+	err      error
+}
+
+func (p *proposalPromoterSpy) Promote(_ context.Context, proposal domain.Proposal, _ time.Time) error {
+	p.calls++
+	p.proposal = proposal
+	return p.err
+}
+
 func (r *resultSubmitterSpy) SubmitResult(_ context.Context, key string, result domain.MatchResult, _ domain.WorkloadBinding, _ []byte, _ time.Time) error {
 	r.calls++
 	r.key, r.result = key, result
@@ -409,6 +421,49 @@ func TestStateChangingAPIActionsPublishTargetedEvents(t *testing.T) {
 	}
 }
 
+func TestFinalProposalAcceptancePromotesDurableMatchAndFailsRetryably(t *testing.T) {
+	now := time.Unix(1000, 0).UTC()
+	proposal, err := domain.NewProposal("proposal-promote-123456", domain.Casual, []string{"player-1", "player-2"}, now)
+	if err != nil {
+		t.Fatal(err)
+	}
+	backend := &proposalBackendSpy{proposal: proposal}
+	promoter := &proposalPromoterSpy{}
+	sessions := domain.NewSessionStore()
+	session1, token1, err := sessions.Issue("player-1", time.Hour, now)
+	if err != nil {
+		t.Fatal(err)
+	}
+	session2, token2, err := sessions.Issue("player-2", time.Hour, now)
+	if err != nil {
+		t.Fatal(err)
+	}
+	service := &Service{Sessions: sessions, ProposalBackend: backend, ProposalPromoter: promoter, Now: func() time.Time { return now }}
+	respond := func(credential, key, revision string) int {
+		req := httptest.NewRequest(http.MethodPost, "/v1/proposals/"+proposal.ProposalID+"/accept", nil)
+		req.Header.Set("Authorization", "Bearer "+credential)
+		req.Header.Set("Idempotency-Key", key)
+		req.Header.Set("If-Match-Revision", revision)
+		recorder := httptest.NewRecorder()
+		service.proposalMutation(recorder, req)
+		return recorder.Code
+	}
+	credential1 := session1.SessionID + ":" + token1
+	credential2 := session2.SessionID + ":" + token2
+	if status := respond(credential1, "proposal-promote-first", "0"); status != http.StatusOK || promoter.calls != 0 {
+		t.Fatalf("first acceptance status/calls = %d/%d", status, promoter.calls)
+	}
+	if status := respond(credential2, "proposal-promote-final", "1"); status != http.StatusOK || promoter.calls != 1 || promoter.proposal.State != domain.Accepted {
+		t.Fatalf("final acceptance status/promoter = %d/%+v", status, promoter)
+	}
+	promoter.err = errors.New("database unavailable")
+	// A duplicate response is replayed by the durable proposal backend and
+	// retries promotion instead of asking the player to accept again.
+	if status := respond(credential2, "proposal-promote-final", "1"); status != http.StatusServiceUnavailable || promoter.calls != 2 {
+		t.Fatalf("promotion retry status/calls = %d/%d", status, promoter.calls)
+	}
+}
+
 func TestProposalRecoveryUsesDurableBackendAndRemainsParticipantScoped(t *testing.T) {
 	now := time.Unix(1000, 0).UTC()
 	proposal, err := domain.NewProposal("proposal-1234567890123456", domain.Casual, []string{"player-1", "player-2"}, now)

server/api/store_adapters.go

@@ -46,3 +46,15 @@ func (p postgresProposalBackend) Respond(ctx context.Context, playerID, proposal
 func ProposalProviderFromStore(db *sql.DB) ProposalBackend {
 	return postgresProposalBackend{db: db}
 }
+
+// ProposalPromoterFromStore turns a durably accepted proposal into its exact
+// matcher-selected ALLOCATING match. The store chooses a deterministic match
+// ID so an API retry after a transient failure cannot duplicate the match.
+func ProposalPromoterFromStore(db *sql.DB) ProposalPromoter {
+	return ProposalPromoterFunc(func(ctx context.Context, proposal domain.Proposal, now time.Time) error {
+		if proposal.State != domain.Accepted {
+			return domain.ErrIllegalTransition
+		}
+		return store.PromoteStoredAcceptedProposal(ctx, db, proposal.ProposalID, now)
+	})
+}

server/api/store_adapters_test.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"testing"
 	"time"
+
+	"github.com/cosmic-clash/cosmic-clash/server/domain"
 )
 
 func TestAssignmentProviderFromStorePreservesPlayerScopedRecoveryBoundary(t *testing.T) {
@@ -25,3 +27,14 @@ func TestProposalProviderFromStoreFailsClosedWithoutDatabase(t *testing.T) {
 		t.Fatal("nil store was treated as an available proposal source")
 	}
 }
+
+func TestProposalPromoterFromStoreFailsClosedWithoutDatabase(t *testing.T) {
+	promoter := ProposalPromoterFromStore(nil)
+	if promoter == nil {
+		t.Fatal("proposal promoter was not created")
+	}
+	proposal := domain.Proposal{ProposalID: "proposal-1", State: domain.Accepted}
+	if err := promoter.Promote(context.Background(), proposal, time.Unix(1000, 0)); err == nil {
+		t.Fatal("nil store was treated as an available proposal promoter")
+	}
+}

server/cmd/control-plane/main.go

@@ -81,13 +81,14 @@ func newAPIHandler(db *sql.DB, indexes ...api.CandidateIndex) http.Handler {
 		candidateIndex = indexes[0]
 	}
 	return (&api.Service{
-		SessionBackend:  store.PostgresSessions{DB: db},
-		QueueBackend:    store.PostgresQueue{DB: db},
-		ProposalBackend: api.ProposalProviderFromStore(db),
-		Assignment:      api.AssignmentProviderFromStore(db),
-		CandidateIndex:  candidateIndex,
-		ProbeRecorder:   store.PostgresQueue{DB: db},
-		Now:             func() time.Time { return time.Now().UTC() },
+		SessionBackend:   store.PostgresSessions{DB: db},
+		QueueBackend:     store.PostgresQueue{DB: db},
+		ProposalBackend:  api.ProposalProviderFromStore(db),
+		ProposalPromoter: api.ProposalPromoterFromStore(db),
+		Assignment:       api.AssignmentProviderFromStore(db),
+		CandidateIndex:   candidateIndex,
+		ProbeRecorder:    store.PostgresQueue{DB: db},
+		Now:              func() time.Time { return time.Now().UTC() },
 	}).Handler()
 }
 

server/domain/formation.go

@@ -2,6 +2,7 @@ package domain
 
 import (
 	"fmt"
+	"sort"
 	"time"
 )
 
@@ -68,5 +69,34 @@ func PrepareProposal(id string, playlist Playlist, formation MatchFormation, ran
 	if err != nil {
 		return PreparedProposal{}, err
 	}
+	if formation.Selection.Region == "" || len(formation.Selection.Players) == 0 || formation.Selection.Players[0].ProtocolVersion < 1 {
+		return PreparedProposal{}, fmt.Errorf("formed match metadata is incomplete")
+	}
+	proposal.Region = formation.Selection.Region
+	proposal.Protocol = formation.Selection.Players[0].ProtocolVersion
+	for _, player := range formation.Selection.Players {
+		if player.ProtocolVersion != proposal.Protocol {
+			return PreparedProposal{}, fmt.Errorf("formed match has mixed protocols")
+		}
+	}
+	assignProposalSlots(&proposal, formation.Teams)
 	return PreparedProposal{Proposal: proposal, CasualLineup: lineup}, nil
 }
+
+func assignProposalSlots(proposal *Proposal, teams Teams) {
+	assign := func(team int, players []Candidate) {
+		ordered := append([]Candidate(nil), players...)
+		sort.Slice(ordered, func(i, j int) bool { return ordered[i].PlayerID < ordered[j].PlayerID })
+		for index, player := range ordered {
+			for participant := range proposal.Participants {
+				if proposal.Participants[participant].PlayerID == player.PlayerID {
+					proposal.Participants[participant].Team = team
+					proposal.Participants[participant].Slot = team*3 + index
+					break
+				}
+			}
+		}
+	}
+	assign(0, teams.Team0)
+	assign(1, teams.Team1)
+}

server/domain/formation_test.go

@@ -10,7 +10,7 @@ func testFormation(t *testing.T, count int) MatchFormation {
 	now := time.Unix(1000, 0)
 	players := make([]Candidate, count)
 	for i := range players {
-		players[i] = Candidate{TicketID: string(rune('a' + i)), PlayerID: string(rune('p' + i)), Rating: 1500, EnqueuedAt: now, PredictedRTT: map[string]float64{"EU": 40}}
+		players[i] = Candidate{TicketID: string(rune('a' + i)), PlayerID: string(rune('p' + i)), ProtocolVersion: 1, Rating: 1500, EnqueuedAt: now, PredictedRTT: map[string]float64{"EU": 40}}
 	}
 	selection, err := SelectCandidates(players[0], players[1:], count, now)
 	if err != nil {
@@ -31,6 +31,9 @@ func TestPrepareProposalBuildsCasualLineupBeforeCreatingProposal(t *testing.T) {
 	if prepared.Proposal.Playlist != Casual || len(prepared.Proposal.Participants) != 2 || len(prepared.CasualLineup) != 6 {
 		t.Fatalf("prepared casual proposal = %+v", prepared)
 	}
+	if prepared.Proposal.Region != "EU" || prepared.Proposal.Protocol != 1 || prepared.Proposal.Participants[0].Slot == prepared.Proposal.Participants[1].Slot || prepared.Proposal.Participants[0].Team == prepared.Proposal.Participants[1].Team {
+		t.Fatalf("prepared proposal did not retain deterministic topology: %+v", prepared.Proposal)
+	}
 	humans := 0
 	teams := map[int]bool{}
 	for _, slot := range prepared.CasualLineup {

server/domain/proposal.go

@@ -34,11 +34,15 @@ const (
 type ProposalParticipant struct {
 	PlayerID string
 	Response Response
+	Team     int
+	Slot     int
 }
 
 type Proposal struct {
 	ProposalID   string
 	Playlist     Playlist
+	Region       string
+	Protocol     int
 	Participants []ProposalParticipant
 	State        State
 	Revision     uint64

server/matcher/worker_test.go

@@ -27,7 +27,7 @@ func candidates() []domain.Candidate {
 	now := time.Unix(1000, 0).UTC()
 	result := make([]domain.Candidate, 4)
 	for i := range result {
-		result[i] = domain.Candidate{TicketID: "ticket-" + string(rune('1'+i)), PlayerID: "player-" + string(rune('1'+i)), Playlist: domain.Casual, EnqueuedAt: now.Add(time.Duration(i) * time.Second), PredictedRTT: map[string]float64{"EU": 20}}
+		result[i] = domain.Candidate{TicketID: "ticket-" + string(rune('1'+i)), PlayerID: "player-" + string(rune('1'+i)), Playlist: domain.Casual, ProtocolVersion: 1, EnqueuedAt: now.Add(time.Duration(i) * time.Second), PredictedRTT: map[string]float64{"EU": 20}}
 	}
 	return result
 }

server/migrations/0005_proposal_match_plans.sql

@@ -0,0 +1,15 @@
+-- Preserve the matcher-selected topology through the proposal response window.
+-- These fields are nullable for already-created proposals during a rolling
+-- deployment; new matcher-created proposals always populate them before they
+-- can be promoted to an ALLOCATING match.
+ALTER TABLE proposals
+    ADD COLUMN match_region TEXT CHECK (match_region IN ('EU', 'NA')),
+    ADD COLUMN match_protocol INTEGER CHECK (match_protocol > 0);
+
+ALTER TABLE proposal_participants
+    ADD COLUMN team INTEGER CHECK (team IN (0, 1)),
+    ADD COLUMN slot INTEGER CHECK (slot BETWEEN 0 AND 5);
+
+CREATE UNIQUE INDEX proposal_participants_unique_slot
+    ON proposal_participants (proposal_id, slot)
+    WHERE slot IS NOT NULL;

server/store/match_sql.go

@@ -63,6 +63,44 @@ const AcceptedMatchParticipantInsertSQL = `INSERT INTO match_participants
     (match_id, player_id, ticket_id, slot, team)
 VALUES ($1, $2, $3, $4, $5)`
 
+const StoredProposalMatchPlanSQL = `SELECT match_region, match_protocol
+FROM proposals
+WHERE proposal_id = $1 AND state = 'ACCEPTED'`
+
+const StoredProposalMatchPlayersSQL = `SELECT player_id, team, slot
+FROM proposal_participants
+WHERE proposal_id = $1 AND response = 'ACCEPTED'
+ORDER BY player_id`
+
+// PromoteStoredAcceptedProposal materializes the exact topology persisted by
+// the matcher once every player has accepted. The deterministic match ID makes
+// a request retry converge after an API/worker interruption.
+func PromoteStoredAcceptedProposal(ctx context.Context, db *sql.DB, proposalID string, now time.Time) error {
+	if db == nil || proposalID == "" || now.IsZero() {
+		return fmt.Errorf("invalid stored proposal promotion arguments")
+	}
+	plan := AcceptedMatchPlan{MatchID: "match-" + proposalID, ProposalID: proposalID}
+	if err := db.QueryRowContext(ctx, StoredProposalMatchPlanSQL, proposalID).Scan(&plan.Region, &plan.Protocol); err != nil {
+		return err
+	}
+	rows, err := db.QueryContext(ctx, StoredProposalMatchPlayersSQL, proposalID)
+	if err != nil {
+		return err
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var player MatchPlayer
+		if err := rows.Scan(&player.PlayerID, &player.Team, &player.Slot); err != nil {
+			return err
+		}
+		plan.Players = append(plan.Players, player)
+	}
+	if err := rows.Err(); err != nil {
+		return err
+	}
+	return CreateMatchFromAcceptedProposal(ctx, db, plan, now)
+}
+
 // CreateMatchFromAcceptedProposal atomically promotes the exact accepted
 // roster into an ALLOCATING match. An existing match ID is an idempotent retry
 // only if every durable field and participant assignment matches the request.

server/store/proposal_sql.go

@@ -10,8 +10,8 @@ import (
 )
 
 const ProposalInsertSQL = `INSERT INTO proposals
-    (proposal_id, playlist, state, expires_at, revision)
-VALUES ($1, $2, 'OPEN', $3, 0)`
+    (proposal_id, playlist, state, expires_at, revision, match_region, match_protocol)
+VALUES ($1, $2, 'OPEN', $3, 0, NULLIF($4, ''), NULLIF($5, 0))`
 
 // CreateProposal atomically claims the queue tickets and creates the proposal.
 // Every statement runs inside the same SERIALIZABLE retry callback; callers
@@ -20,8 +20,11 @@ func CreateProposal(ctx context.Context, db *sql.DB, proposal domain.Proposal, t
 	if proposal.ProposalID == "" || len(proposal.Participants) == 0 {
 		return fmt.Errorf("invalid proposal transaction")
 	}
+	if !validProposalMatchPlan(proposal) {
+		return fmt.Errorf("invalid proposal match plan")
+	}
 	return RunSerializable(ctx, db, DefaultSerializableAttempts, func(ctx context.Context, tx *sql.Tx) error {
-		if _, err := tx.ExecContext(ctx, ProposalInsertSQL, proposal.ProposalID, proposal.Playlist, proposal.ExpiresAt); err != nil {
+		if _, err := tx.ExecContext(ctx, ProposalInsertSQL, proposal.ProposalID, proposal.Playlist, proposal.ExpiresAt, proposal.Region, proposal.Protocol); err != nil {
 			return err
 		}
 		for _, participant := range proposal.Participants {
@@ -29,7 +32,7 @@ func CreateProposal(ctx context.Context, db *sql.DB, proposal domain.Proposal, t
 			if participant.PlayerID == "" || ticketID == "" {
 				return fmt.Errorf("missing proposal ticket mapping")
 			}
-			if _, err := tx.ExecContext(ctx, ProposalParticipantInsertSQL, proposal.ProposalID, participant.PlayerID, ticketID); err != nil {
+			if _, err := tx.ExecContext(ctx, ProposalParticipantInsertSQL, proposal.ProposalID, participant.PlayerID, ticketID, nullablePlanField(proposal.Region != "", participant.Team), nullablePlanField(proposal.Region != "", participant.Slot)); err != nil {
 				return err
 			}
 			result, err := tx.ExecContext(ctx, QueueTicketProposeSQL, ticketID, participant.PlayerID, string(proposal.Playlist), now)
@@ -47,3 +50,32 @@ func CreateProposal(ctx context.Context, db *sql.DB, proposal domain.Proposal, t
 		return nil
 	})
 }
+
+func validProposalMatchPlan(proposal domain.Proposal) bool {
+	if proposal.Region == "" && proposal.Protocol == 0 {
+		return true // Legacy/direct callers have no matcher formation to persist.
+	}
+	if (proposal.Region != "EU" && proposal.Region != "NA") || proposal.Protocol < 1 {
+		return false
+	}
+	seenSlots := make(map[int]struct{}, len(proposal.Participants))
+	teams := [2]int{}
+	for _, participant := range proposal.Participants {
+		if participant.Team < 0 || participant.Team > 1 || participant.Slot < 0 || participant.Slot > 5 {
+			return false
+		}
+		if _, exists := seenSlots[participant.Slot]; exists {
+			return false
+		}
+		seenSlots[participant.Slot] = struct{}{}
+		teams[participant.Team]++
+	}
+	return teams[0] > 0 && teams[1] > 0
+}
+
+func nullablePlanField(enabled bool, value int) any {
+	if !enabled {
+		return nil
+	}
+	return value
+}

server/store/queue_sql_test.go

@@ -8,14 +8,16 @@ import (
 
 func TestQueueSQLUsesDurableIdempotencyAndOwnerScopedRecovery(t *testing.T) {
 	for query, fragments := range map[string][]string{
-		QueueIdempotencyInsertSQL:   {"idempotency_keys", "ON CONFLICT (scope, idempotency_key) DO NOTHING", "payload_digest"},
-		QueueIdempotencySelectSQL:   {"scope = $1", "idempotency_key = $2", "FOR UPDATE"},
-		QueueTicketSelectSQL:        {"ticket_id = $1", "player_id = $2"},
-		QueueTicketInsertSQL:        {"player_id", "playlist", "client_build", "protocol_version"},
-		QueueTicketHeartbeatSQL:     {"player_id = $2", "revision = $3", "expires_at > $4", "RETURNING"},
-		QueueTicketCancelSQL:        {"player_id = $2", "revision = $3", "state NOT IN", "RETURNING"},
-		QueueCandidateProjectionSQL: {"playlist = $1", "predicted_rtt", "expires_at > $2", "LIMIT $3"},
-		RankedParticipantSQL:        {"steam_id", "player_id = ANY($1)", "ORDER BY player_id"},
+		QueueIdempotencyInsertSQL:    {"idempotency_keys", "ON CONFLICT (scope, idempotency_key) DO NOTHING", "payload_digest"},
+		QueueIdempotencySelectSQL:    {"scope = $1", "idempotency_key = $2", "FOR UPDATE"},
+		QueueTicketSelectSQL:         {"ticket_id = $1", "player_id = $2"},
+		QueueTicketInsertSQL:         {"player_id", "playlist", "client_build", "protocol_version"},
+		QueueTicketHeartbeatSQL:      {"player_id = $2", "revision = $3", "expires_at > $4", "RETURNING"},
+		QueueTicketCancelSQL:         {"player_id = $2", "revision = $3", "state NOT IN", "RETURNING"},
+		QueueCandidateProjectionSQL:  {"playlist = $1", "predicted_rtt", "expires_at > $2", "LIMIT $3"},
+		RankedParticipantSQL:         {"steam_id", "player_id = ANY($1)", "ORDER BY player_id"},
+		ProposalInsertSQL:            {"match_region", "match_protocol", "NULLIF($4, '')"},
+		ProposalParticipantInsertSQL: {"team", "slot", "'PENDING'"},
 	} {
 		for _, fragment := range fragments {
 			if !contains(query, fragment) {

server/store/serializable.go

@@ -75,8 +75,8 @@ ORDER BY enqueued_at, ticket_id
 LIMIT $2
 FOR UPDATE SKIP LOCKED`
 
-	ProposalParticipantInsertSQL = `INSERT INTO proposal_participants (proposal_id, player_id, ticket_id, response)
-VALUES ($1, $2, $3, 'PENDING')`
+	ProposalParticipantInsertSQL = `INSERT INTO proposal_participants (proposal_id, player_id, ticket_id, response, team, slot)
+VALUES ($1, $2, $3, 'PENDING', $4, $5)`
 
 	QueueTicketProposeSQL = `UPDATE queue_tickets SET state = 'PROPOSED', revision = revision + 1
 WHERE ticket_id = $1 AND player_id = $2 AND playlist = $3 AND state = 'QUEUED' AND expires_at > $4`