feat: gamemaster

gamemaster/internal/ports/playermappingstore.go

@@ -0,0 +1,47 @@
+package ports
+
+import (
+	"context"
+
+	"galaxy/gamemaster/internal/domain/playermapping"
+)
+
+//go:generate go run go.uber.org/mock/mockgen -destination=../adapters/mocks/mock_playermappingstore.go -package=mocks galaxy/gamemaster/internal/ports PlayerMappingStore
+
+// PlayerMappingStore stores the (game_id, user_id) → race_name +
+// engine_player_uuid projection installed at register-runtime. Adapters
+// must preserve the storage-level invariants enforced by
+// `00001_init.sql`:
+//
+//   - composite primary key on `(game_id, user_id)`;
+//   - UNIQUE on `(game_id, race_name)` (one race per game).
+//
+// BulkInsert is the only ingestion path: register-runtime inserts every
+// row for a game in one batch. Per-row mutation is intentionally not
+// exposed; rosters are immutable for the lifetime of the runtime.
+type PlayerMappingStore interface {
+	// BulkInsert installs every mapping in records. Adapters validate
+	// each record through playermapping.PlayerMapping.Validate before
+	// touching the store. Adapters may use a single multi-row INSERT
+	// or one transaction with N rows; either way the operation is
+	// atomic.
+	BulkInsert(ctx context.Context, records []playermapping.PlayerMapping) error
+
+	// Get returns the mapping identified by (gameID, userID). Returns
+	// playermapping.ErrNotFound when no row exists.
+	Get(ctx context.Context, gameID, userID string) (playermapping.PlayerMapping, error)
+
+	// GetByRace returns the mapping identified by (gameID, raceName).
+	// Used by the admin banish flow (Stage 17) to resolve the engine
+	// player UUID for the engine /admin/race/banish call. Returns
+	// playermapping.ErrNotFound when no row exists.
+	GetByRace(ctx context.Context, gameID, raceName string) (playermapping.PlayerMapping, error)
+
+	// ListByGame returns every mapping owned by gameID. The order is
+	// adapter-defined; callers may reorder as needed.
+	ListByGame(ctx context.Context, gameID string) ([]playermapping.PlayerMapping, error)
+
+	// DeleteByGame removes every mapping owned by gameID. Returns nil
+	// even when no rows were deleted (idempotent).
+	DeleteByGame(ctx context.Context, gameID string) error
+}