feat: game lobby service

lobby/internal/ports/evaluationguardstore.go

@@ -0,0 +1,34 @@
+package ports
+
+import (
+	"context"
+
+	"galaxy/lobby/internal/domain/common"
+)
+
+// EvaluationGuardStore stores the per-game «already evaluated» marker used
+// by capability evaluation to make replayed `game_finished` events
+// idempotent. reads the marker before any RND mutation: a marker
+// observed before mutation means the prior pass committed in full and the
+// current pass can return without side effects. A marker absent before
+// mutation means either a first attempt or a retry of an interrupted prior
+// attempt; in both cases the evaluator re-runs the idempotent mutations
+// and writes the marker only after every mutation, the stats cleanup, and
+// the post-commit work succeed.
+//
+// The two methods exist to express that read-then-write order: IsEvaluated
+// is a non-mutating check used early in the pass, and MarkEvaluated commits
+// the marker once the pass is fully complete. Implementations must persist
+// the marker durably; an in-process implementation is acceptable only for
+// tests because process restarts must observe the same marker state.
+type EvaluationGuardStore interface {
+	// IsEvaluated reports whether gameID is already marked. The method
+	// must not mutate state and must distinguish a missing marker from a
+	// transport error.
+	IsEvaluated(ctx context.Context, gameID common.GameID) (bool, error)
+
+	// MarkEvaluated records gameID as evaluated. Calling MarkEvaluated
+	// twice for the same gameID is safe; the second call leaves the
+	// marker untouched.
+	MarkEvaluated(ctx context.Context, gameID common.GameID) error
+}