feat(game): race exit warnings in the turn report (#12)

Surface the inactivity-removal countdown the rules promise but the
engine never reported. A race within five turns of being auto-removed
for inactivity gets a personal warning in its own report; every race
within three turns is listed publicly to all participants.

- model: Report.PersonalExitWarning + RacesLeavingSoon ([]RaceExitNotice)
- fbs: RaceExitNotice table + Report.personal_exit_warning /
  races_leaving_soon (regenerated Go + TS bindings)
- transcoder: encode/decode both fields
- engine: ReportExitWarnings fills the recipient's TTL (1..5) and lists
  other non-extinct races with TTL 1..3, excluding the recipient itself
- ui: danger-styled personal banner + "races leaving soon" section
  (hidden when empty), wired into the report view, EN/RU i18n
- docs: rules.txt report-section list, FUNCTIONAL.md 6.4 + RU mirror

Voluntary quit and idle timeout share the TTL countdown and are not
distinguished, per the agreed scope.

pkg/model/report/report.go

@@ -47,6 +47,13 @@ type Report struct {
 	OtherGroup         []OtherGroup         `json:"otherGroup,omitempty"`
 	UnidentifiedGroup  []UnidentifiedGroup  `json:"unidentifiedGroup,omitempty"`
 
+	// Race exit warnings. PersonalExitWarning is the recipient race's own
+	// number of turns remaining before auto-removal for inactivity (set when
+	// it is 1..5, otherwise 0). RacesLeavingSoon lists other races within 3
+	// turns of removal and is shown to every recipient.
+	PersonalExitWarning uint             `json:"personalExitWarning,omitempty"`
+	RacesLeavingSoon    []RaceExitNotice `json:"racesLeavingSoon,omitempty"`
+
 	OnPlanetGroupCache     map[uint][]int           `json:"-"`
 	InSpaceGroupRangeCache map[int]map[uint]float64 `json:"-"`
 }
@@ -71,6 +78,13 @@ type Player struct {
 	Extinct    bool      `json:"extinct"`
 }
 
+// RaceExitNotice is a public notice that a race is within a few turns of being
+// auto-removed for inactivity; TurnsLeft is the number of turns until removal.
+type RaceExitNotice struct {
+	Race      string `json:"race"`
+	TurnsLeft uint   `json:"turnsLeft"`
+}
+
 func (r Report) MarshalBinary() (data []byte, err error) {
 	return json.Marshal(&r)
 }

pkg/schema/fbs/report.fbs

@@ -209,6 +209,13 @@ table BattleSummary {
   shots:uint64;
 }
 
+// RaceExitNotice is a public notice that a race is within a few turns of being
+// auto-removed for inactivity; turns_left is the number of turns until removal.
+table RaceExitNotice {
+  race:string;
+  turns_left:uint32;
+}
+
 table Report {
   version:uint64;
   turn:uint64;
@@ -236,6 +243,8 @@ table Report {
   local_group:[LocalGroup];
   other_group:[OtherGroup];
   unidentified_group:[UnidentifiedGroup];
+  personal_exit_warning:uint32 = 0;
+  races_leaving_soon:[RaceExitNotice];
 }
 
 // GameReportRequest is the signed-gRPC request payload for

pkg/schema/fbs/report/RaceExitNotice.go

@@ -0,0 +1,75 @@
+// Code generated by the FlatBuffers compiler. DO NOT EDIT.
+
+package report
+
+import (
+	flatbuffers "github.com/google/flatbuffers/go"
+)
+
+type RaceExitNotice struct {
+	_tab flatbuffers.Table
+}
+
+func GetRootAsRaceExitNotice(buf []byte, offset flatbuffers.UOffsetT) *RaceExitNotice {
+	n := flatbuffers.GetUOffsetT(buf[offset:])
+	x := &RaceExitNotice{}
+	x.Init(buf, n+offset)
+	return x
+}
+
+func FinishRaceExitNoticeBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.Finish(offset)
+}
+
+func GetSizePrefixedRootAsRaceExitNotice(buf []byte, offset flatbuffers.UOffsetT) *RaceExitNotice {
+	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
+	x := &RaceExitNotice{}
+	x.Init(buf, n+offset+flatbuffers.SizeUint32)
+	return x
+}
+
+func FinishSizePrefixedRaceExitNoticeBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.FinishSizePrefixed(offset)
+}
+
+func (rcv *RaceExitNotice) Init(buf []byte, i flatbuffers.UOffsetT) {
+	rcv._tab.Bytes = buf
+	rcv._tab.Pos = i
+}
+
+func (rcv *RaceExitNotice) Table() flatbuffers.Table {
+	return rcv._tab
+}
+
+func (rcv *RaceExitNotice) Race() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func (rcv *RaceExitNotice) TurnsLeft() uint32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.GetUint32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *RaceExitNotice) MutateTurnsLeft(n uint32) bool {
+	return rcv._tab.MutateUint32Slot(6, n)
+}
+
+func RaceExitNoticeStart(builder *flatbuffers.Builder) {
+	builder.StartObject(2)
+}
+func RaceExitNoticeAddRace(builder *flatbuffers.Builder, race flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(race), 0)
+}
+func RaceExitNoticeAddTurnsLeft(builder *flatbuffers.Builder, turnsLeft uint32) {
+	builder.PrependUint32Slot(1, turnsLeft, 0)
+}
+func RaceExitNoticeEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
+	return builder.EndObject()
+}

pkg/schema/fbs/report/Report.go

@@ -489,8 +489,40 @@ func (rcv *Report) UnidentifiedGroupLength() int {
 	return 0
 }
 
+func (rcv *Report) PersonalExitWarning() uint32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(56))
+	if o != 0 {
+		return rcv._tab.GetUint32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *Report) MutatePersonalExitWarning(n uint32) bool {
+	return rcv._tab.MutateUint32Slot(56, n)
+}
+
+func (rcv *Report) RacesLeavingSoon(obj *RaceExitNotice, j int) bool {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(58))
+	if o != 0 {
+		x := rcv._tab.Vector(o)
+		x += flatbuffers.UOffsetT(j) * 4
+		x = rcv._tab.Indirect(x)
+		obj.Init(rcv._tab.Bytes, x)
+		return true
+	}
+	return false
+}
+
+func (rcv *Report) RacesLeavingSoonLength() int {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(58))
+	if o != 0 {
+		return rcv._tab.VectorLen(o)
+	}
+	return 0
+}
+
 func ReportStart(builder *flatbuffers.Builder) {
-	builder.StartObject(26)
+	builder.StartObject(28)
 }
 func ReportAddVersion(builder *flatbuffers.Builder, version uint64) {
 	builder.PrependUint64Slot(0, version, 0)
@@ -624,6 +656,15 @@ func ReportAddUnidentifiedGroup(builder *flatbuffers.Builder, unidentifiedGroup
 func ReportStartUnidentifiedGroupVector(builder *flatbuffers.Builder, numElems int) flatbuffers.UOffsetT {
 	return builder.StartVector(4, numElems, 4)
 }
+func ReportAddPersonalExitWarning(builder *flatbuffers.Builder, personalExitWarning uint32) {
+	builder.PrependUint32Slot(26, personalExitWarning, 0)
+}
+func ReportAddRacesLeavingSoon(builder *flatbuffers.Builder, racesLeavingSoon flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(27, flatbuffers.UOffsetT(racesLeavingSoon), 0)
+}
+func ReportStartRacesLeavingSoonVector(builder *flatbuffers.Builder, numElems int) flatbuffers.UOffsetT {
+	return builder.StartVector(4, numElems, 4)
+}
 func ReportEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/transcoder/report.go

@@ -114,6 +114,11 @@ func ReportToPayload(report *model.Report) ([]byte, error) {
 		unidentifiedGroupOffsets[i] = encodeReportUnidentifiedGroup(builder, &report.UnidentifiedGroup[i])
 	}
 
+	racesLeavingSoonOffsets := make([]flatbuffers.UOffsetT, len(report.RacesLeavingSoon))
+	for i := range report.RacesLeavingSoon {
+		racesLeavingSoonOffsets[i] = encodeReportRaceExitNotice(builder, &report.RacesLeavingSoon[i])
+	}
+
 	playerVector := encodeReportOffsetVector(builder, len(playerOffsets), fbs.ReportStartPlayerVector, playerOffsets)
 	localScienceVector := encodeReportOffsetVector(builder, len(localScienceOffsets), fbs.ReportStartLocalScienceVector, localScienceOffsets)
 	otherScienceVector := encodeReportOffsetVector(builder, len(otherScienceOffsets), fbs.ReportStartOtherScienceVector, otherScienceOffsets)
@@ -132,6 +137,7 @@ func ReportToPayload(report *model.Report) ([]byte, error) {
 	localGroupVector := encodeReportOffsetVector(builder, len(localGroupOffsets), fbs.ReportStartLocalGroupVector, localGroupOffsets)
 	otherGroupVector := encodeReportOffsetVector(builder, len(otherGroupOffsets), fbs.ReportStartOtherGroupVector, otherGroupOffsets)
 	unidentifiedGroupVector := encodeReportOffsetVector(builder, len(unidentifiedGroupOffsets), fbs.ReportStartUnidentifiedGroupVector, unidentifiedGroupOffsets)
+	racesLeavingSoonVector := encodeReportOffsetVector(builder, len(racesLeavingSoonOffsets), fbs.ReportStartRacesLeavingSoonVector, racesLeavingSoonOffsets)
 
 	fbs.ReportStart(builder)
 	fbs.ReportAddVersion(builder, uint64(report.Version))
@@ -196,6 +202,10 @@ func ReportToPayload(report *model.Report) ([]byte, error) {
 	if len(unidentifiedGroupOffsets) > 0 {
 		fbs.ReportAddUnidentifiedGroup(builder, unidentifiedGroupVector)
 	}
+	fbs.ReportAddPersonalExitWarning(builder, uint32(report.PersonalExitWarning))
+	if len(racesLeavingSoonOffsets) > 0 {
+		fbs.ReportAddRacesLeavingSoon(builder, racesLeavingSoonVector)
+	}
 
 	reportOffset := fbs.ReportEnd(builder)
 	fbs.FinishReportBuffer(builder, reportOffset)
@@ -238,6 +248,8 @@ func PayloadToReport(data []byte) (result *model.Report, err error) {
 		Race:        string(flatReport.Race()),
 		Votes:       reportFloatFromFBS(flatReport.Votes()),
 		VoteFor:     string(flatReport.VoteFor()),
+
+		PersonalExitWarning: uint(flatReport.PersonalExitWarning()),
 	}
 
 	if err := decodeReportPlayerVector(flatReport, result); err != nil {
@@ -294,6 +306,9 @@ func PayloadToReport(data []byte) (result *model.Report, err error) {
 	if err := decodeReportUnidentifiedGroupVector(flatReport, result); err != nil {
 		return nil, err
 	}
+	if err := decodeReportRacesLeavingSoonVector(flatReport, result); err != nil {
+		return nil, err
+	}
 
 	return result, nil
 }
@@ -583,6 +598,14 @@ func encodeReportUnidentifiedGroup(builder *flatbuffers.Builder, group *model.Un
 	return fbs.UnidentifiedGroupEnd(builder)
 }
 
+func encodeReportRaceExitNotice(builder *flatbuffers.Builder, notice *model.RaceExitNotice) flatbuffers.UOffsetT {
+	race := builder.CreateString(notice.Race)
+	fbs.RaceExitNoticeStart(builder)
+	fbs.RaceExitNoticeAddRace(builder, race)
+	fbs.RaceExitNoticeAddTurnsLeft(builder, uint32(notice.TurnsLeft))
+	return fbs.RaceExitNoticeEnd(builder)
+}
+
 func decodeReportPlayerVector(flatReport *fbs.Report, result *model.Report) error {
 	length := flatReport.PlayerLength()
 	if length == 0 {
@@ -1244,6 +1267,33 @@ func decodeReportUnidentifiedGroupVector(flatReport *fbs.Report, result *model.R
 	return nil
 }
 
+func decodeReportRacesLeavingSoonVector(flatReport *fbs.Report, result *model.Report) error {
+	length := flatReport.RacesLeavingSoonLength()
+	if length == 0 {
+		return nil
+	}
+
+	result.RacesLeavingSoon = make([]model.RaceExitNotice, length)
+	item := new(fbs.RaceExitNotice)
+	for i := 0; i < length; i++ {
+		if !flatReport.RacesLeavingSoon(item, i) {
+			return fmt.Errorf("decode report races leaving soon %d: notice is missing", i)
+		}
+
+		turnsLeft, err := uint64ToUint(uint64(item.TurnsLeft()), "turnsLeft")
+		if err != nil {
+			return fmt.Errorf("decode report races leaving soon %d: %w", i, err)
+		}
+
+		result.RacesLeavingSoon[i] = model.RaceExitNotice{
+			Race:      string(item.Race()),
+			TurnsLeft: turnsLeft,
+		}
+	}
+
+	return nil
+}
+
 func decodeReportRouteMap(flatRoute *fbs.Route, routeIndex int) (map[uint]string, error) {
 	length := flatRoute.RouteLength()
 	if length == 0 {

pkg/transcoder/report_test.go

@@ -365,6 +365,11 @@ func sampleReport() *model.Report {
 		UnidentifiedGroup: []model.UnidentifiedGroup{
 			{X: model.Float(10.0), Y: model.Float(11.0)},
 		},
+		PersonalExitWarning: 4,
+		RacesLeavingSoon: []model.RaceExitNotice{
+			{Race: "Martians", TurnsLeft: 2},
+			{Race: "Klingons", TurnsLeft: 1},
+		},
 		OnPlanetGroupCache: map[uint][]int{
 			1: {2, 3},
 		},