feat: add NFT usernames and bot verification (#22)

Implements collectible usernames, official verification workflows, and third-party bot verification after maintainer protocol and migration review. The composite activity/moderation rating remains an admin-only read model; Telegram Stars Rating wire fields stay unset pending a dedicated official-semantics implementation. Reviewed-Head: 2796345775ea0f908fb7734601e5e1dee4b653b9 Original-Head: fa082b892fd5180c9c9bc53c81c21cf5d250a75b Co-authored-by: Egor Egorov <business.egor.sg@gmail.com>
2026-07-27 20:18:00 +03:00 · 2026-07-27 20:18:00 +03:00 · fff8de783a
commit fff8de783a
parent b0fd3976f1
169 changed files with 55769 additions and 282 deletions
--- a/internal/app/rating/service.go
+++ b/internal/app/rating/service.go
@ -0,0 +1,453 @@
+// Package rating implements the composite account rating use cases: reading the
+// stored projection, recomputing it from the raw contribution signals, and
+// applying operator adjustments through the contribution ledger.
+//
+// This is an admin-only local model, not Telegram's Stars Rating protocol
+// surface. The service gathers signals, applies the configured weights and
+// pending-delay policy, and persists the result under optimistic concurrency.
+package rating
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"go.uber.org/zap"
+
+	"telesrv/internal/domain"
+	"telesrv/internal/store"
+)
+
+const (
+	// defaultPendingDelay parks a rating increase for a day, matching the
+	// shipped TELESRV_RATING_PENDING_DELAY default.
+	defaultPendingDelay = 24 * time.Hour
+	// defaultStaleAfter is the recompute horizon used when none is configured.
+	defaultStaleAfter = 6 * time.Hour
+	// defaultListLimit / maxListLimit bound one leaderboard page.
+	defaultListLimit = 50
+	maxListLimit     = 200
+	// defaultEventLimit / maxEventLimit bound one ledger page.
+	defaultEventLimit = 50
+	maxEventLimit     = 200
+	// defaultRecomputeBatch / maxRecomputeBatch bound one worker cycle.
+	defaultRecomputeBatch = 500
+	maxRecomputeBatch     = 10000
+)
+
+// ErrDisabled reports that the local composite rating feature is switched off.
+// Reads degrade to an empty admin projection; writes are refused so an operator
+// never believes an adjustment was recorded when it was not.
+var ErrDisabled = errors.New("account rating is disabled")
+
+// Service is the composite account rating use-case layer.
+type Service struct {
+	store        store.AccountRatingStore
+	weights      domain.AccountRatingWeights
+	pendingDelay time.Duration
+	staleAfter   time.Duration
+	enabled      bool
+
+	now func() time.Time
+	log *zap.Logger
+}
+
+// Option adjusts optional service dependencies.
+type Option func(*Service)
+
+// WithStore injects the rating read model and ledger store.
+func WithStore(st store.AccountRatingStore) Option {
+	return func(s *Service) { s.store = st }
+}
+
+// WithWeights installs the composite formula. An invalid set is rejected in
+// favour of the shipped defaults, so a misconfigured deployment produces a
+// conservative rating instead of an inconsistent one.
+func WithWeights(weights domain.AccountRatingWeights) Option {
+	return func(s *Service) {
+		if err := weights.Validate(); err != nil {
+			return
+		}
+		s.weights = weights
+	}
+}
+
+// WithPendingDelay configures how long a rating increase stays parked as
+// pending. Zero applies every change immediately.
+func WithPendingDelay(delay time.Duration) Option {
+	return func(s *Service) {
+		if delay >= 0 {
+			s.pendingDelay = delay
+		}
+	}
+}
+
+// WithStaleAfter configures the projection age after which the background
+// worker recomputes a user.
+func WithStaleAfter(staleAfter time.Duration) Option {
+	return func(s *Service) {
+		if staleAfter > 0 {
+			s.staleAfter = staleAfter
+		}
+	}
+}
+
+// WithEnabled toggles the feature.
+func WithEnabled(enabled bool) Option {
+	return func(s *Service) { s.enabled = enabled }
+}
+
+// WithClock injects the clock (tests).
+func WithClock(now func() time.Time) Option {
+	return func(s *Service) {
+		if now != nil {
+			s.now = now
+		}
+	}
+}
+
+// WithLogger injects the service logger.
+func WithLogger(log *zap.Logger) Option {
+	return func(s *Service) {
+		if log != nil {
+			s.log = log
+		}
+	}
+}
+
+// NewService creates the rating service. It is enabled by default so that the
+// only switch is the configuration flag, and it stays safe without a store:
+// reads answer empty and writes report a configuration error.
+func NewService(opts ...Option) *Service {
+	s := &Service{
+		weights:      domain.DefaultAccountRatingWeights(),
+		pendingDelay: defaultPendingDelay,
+		staleAfter:   defaultStaleAfter,
+		enabled:      true,
+		now:          time.Now,
+		log:          zap.NewNop(),
+	}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(s)
+		}
+	}
+	if s.now == nil {
+		s.now = time.Now
+	}
+	if s.log == nil {
+		s.log = zap.NewNop()
+	}
+	if s.pendingDelay < 0 {
+		s.pendingDelay = 0
+	}
+	if s.staleAfter <= 0 {
+		s.staleAfter = defaultStaleAfter
+	}
+	if err := s.weights.Validate(); err != nil {
+		s.weights = domain.DefaultAccountRatingWeights()
+	}
+	return s
+}
+
+// Enabled reports whether the feature is switched on.
+func (s *Service) Enabled() bool { return s != nil && s.enabled }
+
+// Ready reports whether the feature is on and backed by a store.
+func (s *Service) Ready() bool { return s.Enabled() && s.store != nil }
+
+// Weights returns the configured composite formula, so the admin panel can
+// explain a level with the same numbers that produced it.
+func (s *Service) Weights() domain.AccountRatingWeights {
+	if s == nil {
+		return domain.DefaultAccountRatingWeights()
+	}
+	return s.weights
+}
+
+func (s *Service) ratingStore() (store.AccountRatingStore, error) {
+	if s == nil || s.store == nil {
+		return nil, fmt.Errorf("account rating store is not configured")
+	}
+	return s.store, nil
+}
+
+// Rating returns the stored projection.
+//
+// domain.ErrAccountRatingNotFound is propagated rather than flattened to a zero
+// value so the admin API can distinguish "not computed" from a computed zero.
+// A missing store reports a configuration error an operator can diagnose.
+func (s *Service) Rating(ctx context.Context, userID int64) (domain.AccountRating, error) {
+	if s == nil || !s.enabled || userID <= 0 {
+		return domain.AccountRating{}, domain.ErrAccountRatingNotFound
+	}
+	st, err := s.ratingStore()
+	if err != nil {
+		return domain.AccountRating{}, err
+	}
+	return st.AccountRating(ctx, userID)
+}
+
+// RatingBatch resolves several users in one round trip. Users without a stored
+// projection are absent from the map, so a disabled feature and an unconfigured
+// store both read as "nobody has a rating" -- the batch shape already encodes
+// absence and needs no error to express it.
+func (s *Service) RatingBatch(ctx context.Context, userIDs []int64) (map[int64]domain.AccountRating, error) {
+	if s == nil || !s.enabled || s.store == nil {
+		return map[int64]domain.AccountRating{}, nil
+	}
+	unique := make([]int64, 0, len(userIDs))
+	seen := make(map[int64]struct{}, len(userIDs))
+	for _, userID := range userIDs {
+		if userID <= 0 {
+			continue
+		}
+		if _, ok := seen[userID]; ok {
+			continue
+		}
+		seen[userID] = struct{}{}
+		unique = append(unique, userID)
+	}
+	if len(unique) == 0 {
+		return map[int64]domain.AccountRating{}, nil
+	}
+	batch, err := s.store.AccountRatingBatch(ctx, unique)
+	if err != nil {
+		return nil, err
+	}
+	if batch == nil {
+		return map[int64]domain.AccountRating{}, nil
+	}
+	return batch, nil
+}
+
+// Recompute gathers the contribution signals, applies the configured weights
+// and the pending-delay policy relative to the stored value, and persists the
+// result.
+//
+// The save is guarded by the stored version. A concurrent writer (another
+// recompute, an adjustment, the worker) only invalidates the base the pending
+// policy was resolved against, so exactly one retry against the freshly
+// returned row is both sufficient and terminating.
+func (s *Service) Recompute(ctx context.Context, userID int64) (domain.AccountRating, error) {
+	if s == nil || !s.enabled {
+		return domain.AccountRating{}, ErrDisabled
+	}
+	st, err := s.ratingStore()
+	if err != nil {
+		return domain.AccountRating{}, err
+	}
+	if userID <= 0 {
+		return domain.AccountRating{}, domain.ErrAccountRatingAdjustmentInvalid
+	}
+	// The service accounts are infrastructure, not participants. Refusing here as
+	// well as in the seeding query means an operator cannot create a rating for one
+	// by hand either -- the platform account is not flagged is_bot, so nothing else
+	// would stop it.
+	if !domain.RatableAccount(userID, false) {
+		return domain.AccountRating{}, domain.ErrAccountRatingAdjustmentInvalid
+	}
+	signals, err := st.AccountRatingSignals(ctx, userID)
+	if err != nil {
+		return domain.AccountRating{}, err
+	}
+	signals.UserID = userID
+	prev, err := s.previous(ctx, st, userID)
+	if err != nil {
+		return domain.AccountRating{}, err
+	}
+	now := s.now().UTC()
+	computed := domain.ComputeAccountRating(signals, s.weights, now)
+	stored, changed, err := st.SaveAccountRating(ctx, domain.ResolveAccountRatingPending(prev, computed, s.pendingDelay, now))
+	if err != nil {
+		return domain.AccountRating{}, err
+	}
+	if changed {
+		return stored, nil
+	}
+	// One retry: `stored` is the row that won the race, so resolving the pending
+	// policy against it produces the correct next version.
+	stored, changed, err = st.SaveAccountRating(ctx, domain.ResolveAccountRatingPending(stored, computed, s.pendingDelay, now))
+	if err != nil {
+		return domain.AccountRating{}, err
+	}
+	if !changed {
+		return stored, fmt.Errorf("recompute account rating %d: concurrent version conflict", userID)
+	}
+	return stored, nil
+}
+
+// Adjust records an operator adjustment in the contribution ledger and
+// immediately recomputes the projection, so the manual component is visible
+// without waiting for the background worker. Replaying the same CommandKey
+// records nothing and reports applied=false; the current rating is still
+// returned so a retried admin command stays idempotent.
+func (s *Service) Adjust(ctx context.Context, req domain.AdjustAccountRatingRequest) (domain.AccountRating, bool, error) {
+	if s == nil || !s.enabled {
+		return domain.AccountRating{}, false, ErrDisabled
+	}
+	st, err := s.ratingStore()
+	if err != nil {
+		return domain.AccountRating{}, false, err
+	}
+	if err := req.Validate(); err != nil {
+		return domain.AccountRating{}, false, err
+	}
+	_, applied, err := st.AdjustAccountRating(ctx, req)
+	if err != nil {
+		return domain.AccountRating{}, false, err
+	}
+	rating, err := s.Recompute(ctx, req.UserID)
+	if err != nil {
+		return domain.AccountRating{}, applied, err
+	}
+	return rating, applied, nil
+}
+
+// List is the admin leaderboard query with a bounded page size.
+func (s *Service) List(ctx context.Context, filter domain.AccountRatingFilter) ([]domain.AccountRating, error) {
+	if s == nil || !s.enabled {
+		return nil, nil
+	}
+	st, err := s.ratingStore()
+	if err != nil {
+		return nil, err
+	}
+	if filter.MinLevel < 0 {
+		filter.MinLevel = 0
+	}
+	if filter.MinLevel > domain.MaxAccountRatingLevel {
+		filter.MinLevel = domain.MaxAccountRatingLevel
+	}
+	filter.Limit = clampLimit(filter.Limit, defaultListLimit, maxListLimit)
+	return st.ListAccountRatings(ctx, filter)
+}
+
+// Events returns one user's contribution ledger, newest first.
+func (s *Service) Events(ctx context.Context, userID int64, limit int) ([]domain.AccountRatingEvent, error) {
+	if s == nil || !s.enabled {
+		return nil, nil
+	}
+	st, err := s.ratingStore()
+	if err != nil {
+		return nil, err
+	}
+	if userID <= 0 {
+		return nil, domain.ErrAccountRatingAdjustmentInvalid
+	}
+	return st.AccountRatingEvents(ctx, userID, clampLimit(limit, defaultEventLimit, maxEventLimit))
+}
+
+// RunRecomputeCycle advances the read model by one bounded batch and returns how
+// many users it wrote. A single user's failure is logged and skipped: one poisoned
+// row must not stall the whole cycle.
+//
+// The cycle does two things, and the order matters. It first refreshes projections
+// that have gone stale, because those are rows somebody is already looking at.
+// Whatever batch budget is left it spends seeding accounts that have no projection
+// at all -- without that pass the read model can never populate itself, since
+// StaleAccountRatings walks account_rating and cannot return a user who is not in
+// it. Staleness keeps existing ratings honest; seeding is what makes them exist at
+// all, which is what makes the admin leaderboard populate without an operator
+// opening every account first.
+func (s *Service) RunRecomputeCycle(ctx context.Context, limit int) (int, error) {
+	if s == nil || !s.enabled {
+		return 0, nil
+	}
+	st, err := s.ratingStore()
+	if err != nil {
+		return 0, err
+	}
+	limit = clampLimit(limit, defaultRecomputeBatch, maxRecomputeBatch)
+	olderThan := s.now().UTC().Add(-s.staleAfter).Unix()
+	userIDs, err := st.StaleAccountRatings(ctx, olderThan, limit)
+	if err != nil {
+		return 0, err
+	}
+	processed, err := s.recomputeEach(ctx, userIDs, "recompute account rating failed")
+	if err != nil {
+		return processed, err
+	}
+	// The bound belongs to the cycle, not to each pass, so a backlog of stale rows
+	// can never turn one cycle into an unbounded amount of work.
+	remaining := limit - len(userIDs)
+	if remaining <= 0 {
+		return processed, nil
+	}
+	unrated, err := st.UnratedAccounts(ctx, remaining)
+	if err != nil {
+		// Seeding extends the cycle rather than being its purpose: a store that
+		// cannot enumerate accounts must not turn a successful stale pass into a
+		// failed cycle.
+		s.log.Warn("list unrated accounts failed", zap.Error(err))
+		return processed, nil
+	}
+	seeded, err := s.recomputeEach(ctx, unrated, "seed account rating failed")
+	return processed + seeded, err
+}
+
+// recomputeEach recomputes a list of users, skipping the ones that fail, and
+// giving up early only when the context is done.
+func (s *Service) recomputeEach(ctx context.Context, userIDs []int64, failureMessage string) (int, error) {
+	processed := 0
+	for _, userID := range userIDs {
+		if err := ctx.Err(); err != nil {
+			return processed, err
+		}
+		if userID <= 0 {
+			continue
+		}
+		if _, err := s.Recompute(ctx, userID); err != nil {
+			s.log.Warn(failureMessage,
+				zap.Int64("user_id", userID),
+				zap.Error(err))
+			continue
+		}
+		processed++
+	}
+	return processed, nil
+}
+
+// EnsureRating returns the stored local-admin projection, computing and storing
+// it first when an administrative caller needs an immediate value.
+//
+// The background cycle reaches every account eventually; callers that require a
+// local rating immediately use this bounded materialization path instead.
+func (s *Service) EnsureRating(ctx context.Context, userID int64) (domain.AccountRating, error) {
+	if s == nil || !s.enabled || userID <= 0 {
+		return domain.AccountRating{}, domain.ErrAccountRatingNotFound
+	}
+	rating, err := s.Rating(ctx, userID)
+	if err == nil {
+		return rating, nil
+	}
+	if !errors.Is(err, domain.ErrAccountRatingNotFound) {
+		return domain.AccountRating{}, err
+	}
+	return s.Recompute(ctx, userID)
+}
+
+// previous reads the stored projection the pending policy is resolved against.
+// A never-computed user yields the zero value, which domain.ResolveAccountRating
+// Pending treats as "apply immediately" -- a first rating is never parked.
+func (s *Service) previous(ctx context.Context, st store.AccountRatingStore, userID int64) (domain.AccountRating, error) {
+	prev, err := st.AccountRating(ctx, userID)
+	if err != nil {
+		if errors.Is(err, domain.ErrAccountRatingNotFound) {
+			return domain.AccountRating{}, nil
+		}
+		return domain.AccountRating{}, err
+	}
+	return prev, nil
+}
+
+func clampLimit(limit, fallback, maximum int) int {
+	if limit <= 0 {
+		return fallback
+	}
+	if limit > maximum {
+		return maximum
+	}
+	return limit
+}
--- a/internal/app/rating/service_test.go
+++ b/internal/app/rating/service_test.go
@ -0,0 +1,719 @@
+package rating
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"telesrv/internal/domain"
+)
+
+var testNow = time.Date(2026, 7, 26, 12, 0, 0, 0, time.UTC)
+
+// fakeRatingStore is an in-memory AccountRatingStore with the same optimistic
+// concurrency contract as PostgreSQL: a save whose version does not follow the
+// stored one reports changed=false and returns the row that won.
+type fakeRatingStore struct {
+	signals map[int64]domain.AccountRatingSignals
+	ratings map[int64]domain.AccountRating
+	manual  map[int64]int64
+	events  map[int64][]domain.AccountRatingEvent
+	keys    map[string]domain.AccountRatingEvent
+
+	stale          []int64
+	staleOlderThan int64
+	staleLimit     int
+
+	unrated      []int64
+	unratedLimit int
+	unratedCalls int
+	unratedErr   error
+
+	saves          []domain.AccountRating
+	forceConflicts int
+	signalsErr     error
+}
+
+func newFakeRatingStore() *fakeRatingStore {
+	return &fakeRatingStore{
+		signals: map[int64]domain.AccountRatingSignals{},
+		ratings: map[int64]domain.AccountRating{},
+		manual:  map[int64]int64{},
+		events:  map[int64][]domain.AccountRatingEvent{},
+		keys:    map[string]domain.AccountRatingEvent{},
+	}
+}
+
+func (f *fakeRatingStore) AccountRating(_ context.Context, userID int64) (domain.AccountRating, error) {
+	rating, ok := f.ratings[userID]
+	if !ok {
+		return domain.AccountRating{}, domain.ErrAccountRatingNotFound
+	}
+	return rating, nil
+}
+
+func (f *fakeRatingStore) AccountRatingBatch(_ context.Context, userIDs []int64) (map[int64]domain.AccountRating, error) {
+	out := make(map[int64]domain.AccountRating, len(userIDs))
+	for _, userID := range userIDs {
+		if rating, ok := f.ratings[userID]; ok {
+			out[userID] = rating
+		}
+	}
+	return out, nil
+}
+
+func (f *fakeRatingStore) SaveAccountRating(_ context.Context, rating domain.AccountRating) (domain.AccountRating, bool, error) {
+	f.saves = append(f.saves, rating)
+	current := f.ratings[rating.UserID]
+	if f.forceConflicts > 0 {
+		f.forceConflicts--
+		return current, false, nil
+	}
+	if rating.Version != current.Version+1 {
+		return current, false, nil
+	}
+	f.ratings[rating.UserID] = rating
+	return rating, true, nil
+}
+
+func (f *fakeRatingStore) AccountRatingSignals(_ context.Context, userID int64) (domain.AccountRatingSignals, error) {
+	if f.signalsErr != nil {
+		return domain.AccountRatingSignals{}, f.signalsErr
+	}
+	signals := f.signals[userID]
+	signals.UserID = userID
+	signals.Manual = f.manual[userID]
+	return signals, nil
+}
+
+func (f *fakeRatingStore) AdjustAccountRating(_ context.Context, req domain.AdjustAccountRatingRequest) (domain.AccountRatingEvent, bool, error) {
+	if req.CommandKey != "" {
+		if event, ok := f.keys[req.CommandKey]; ok {
+			return event, false, nil
+		}
+	}
+	event := domain.AccountRatingEvent{
+		ID: int64(len(f.events[req.UserID]) + 1), UserID: req.UserID, Kind: domain.AccountRatingEventManual,
+		Amount: req.Amount, Reason: req.Reason, Actor: req.Actor, CommandKey: req.CommandKey, CreatedAt: testNow,
+	}
+	f.events[req.UserID] = append(f.events[req.UserID], event)
+	f.manual[req.UserID] += req.Amount
+	if req.CommandKey != "" {
+		f.keys[req.CommandKey] = event
+	}
+	return event, true, nil
+}
+
+func (f *fakeRatingStore) ListAccountRatings(_ context.Context, filter domain.AccountRatingFilter) ([]domain.AccountRating, error) {
+	out := make([]domain.AccountRating, 0, len(f.ratings))
+	for _, rating := range f.ratings {
+		if rating.Level >= filter.MinLevel {
+			out = append(out, rating)
+		}
+		if len(out) >= filter.Limit {
+			break
+		}
+	}
+	return out, nil
+}
+
+func (f *fakeRatingStore) AccountRatingEvents(_ context.Context, userID int64, limit int) ([]domain.AccountRatingEvent, error) {
+	events := f.events[userID]
+	if len(events) > limit {
+		events = events[:limit]
+	}
+	return append([]domain.AccountRatingEvent(nil), events...), nil
+}
+
+func (f *fakeRatingStore) StaleAccountRatings(_ context.Context, olderThanUnix int64, limit int) ([]int64, error) {
+	f.staleOlderThan = olderThanUnix
+	f.staleLimit = limit
+	if len(f.stale) > limit {
+		return append([]int64(nil), f.stale[:limit]...), nil
+	}
+	return append([]int64(nil), f.stale...), nil
+}
+
+func (f *fakeRatingStore) UnratedAccounts(_ context.Context, limit int) ([]int64, error) {
+	f.unratedCalls++
+	f.unratedLimit = limit
+	if f.unratedErr != nil {
+		return nil, f.unratedErr
+	}
+	out := make([]int64, 0, len(f.unrated))
+	for _, userID := range f.unrated {
+		if _, rated := f.ratings[userID]; rated {
+			continue
+		}
+		out = append(out, userID)
+		if len(out) == limit {
+			break
+		}
+	}
+	return out, nil
+}
+
+func newTestService(st *fakeRatingStore, opts ...Option) *Service {
+	base := []Option{WithStore(st), WithClock(func() time.Time { return testNow })}
+	return NewService(append(base, opts...)...)
+}
+
+func TestRecomputeAppliesConfiguredWeights(t *testing.T) {
+	st := newFakeRatingStore()
+	st.signals[7] = domain.AccountRatingSignals{
+		StarsReceived: 1000, StarsSpent: 400, MessagesSent: 30, AccountAgeDays: 10,
+		GiftsReceived: 2, ModerationCases: 1,
+	}
+	service := newTestService(st)
+
+	rating, err := service.Recompute(context.Background(), 7)
+	if err != nil {
+		t.Fatalf("Recompute: %v", err)
+	}
+	weights := domain.DefaultAccountRatingWeights()
+	want := domain.ComputeAccountRating(domain.AccountRatingSignals{
+		UserID: 7, StarsReceived: 1000, StarsSpent: 400, MessagesSent: 30, AccountAgeDays: 10,
+		GiftsReceived: 2, ModerationCases: 1,
+	}, weights, testNow)
+	if rating.Stars != want.Stars || rating.Level != want.Level ||
+		rating.StarsComponent != want.StarsComponent || rating.ActivityComponent != want.ActivityComponent ||
+		rating.PenaltyComponent != want.PenaltyComponent {
+		t.Fatalf("rating = %#v, want the domain formula result %#v", rating, want)
+	}
+	if rating.Version != 1 {
+		t.Fatalf("first stored version = %d, want 1", rating.Version)
+	}
+	if !rating.ComputedAt.Equal(testNow) {
+		t.Fatalf("ComputedAt = %v, want the injected clock %v", rating.ComputedAt, testNow)
+	}
+}
+
+func TestRecomputePendingPolicy(t *testing.T) {
+	t.Run("increase is parked", func(t *testing.T) {
+		st := newFakeRatingStore()
+		st.ratings[7] = domain.AccountRating{UserID: 7, Stars: 100, Level: 1, Version: 4}
+		st.signals[7] = domain.AccountRatingSignals{StarsReceived: 500}
+		service := newTestService(st, WithPendingDelay(24*time.Hour))
+
+		rating, err := service.Recompute(context.Background(), 7)
+		if err != nil {
+			t.Fatalf("Recompute: %v", err)
+		}
+		if rating.Stars != 100 {
+			t.Fatalf("visible stars = %d, want the previous 100 while the increase is pending", rating.Stars)
+		}
+		if rating.PendingStars != 400 {
+			t.Fatalf("pending stars = %d, want 400", rating.PendingStars)
+		}
+		if want := testNow.Add(24 * time.Hour); !rating.PendingDate.Equal(want) {
+			t.Fatalf("pending date = %v, want %v", rating.PendingDate, want)
+		}
+		if rating.Version != 5 {
+			t.Fatalf("version = %d, want 5", rating.Version)
+		}
+	})
+
+	t.Run("decrease applies immediately", func(t *testing.T) {
+		st := newFakeRatingStore()
+		st.ratings[7] = domain.AccountRating{UserID: 7, Stars: 500, Level: 2, Version: 1}
+		st.signals[7] = domain.AccountRatingSignals{StarsReceived: 500, Scam: true}
+		service := newTestService(st, WithPendingDelay(24*time.Hour))
+
+		rating, err := service.Recompute(context.Background(), 7)
+		if err != nil {
+			t.Fatalf("Recompute: %v", err)
+		}
+		if rating.Stars != 0 || rating.PendingStars != 0 {
+			t.Fatalf("rating = %d stars / %d pending, want a penalty applied at once", rating.Stars, rating.PendingStars)
+		}
+		if rating.PenaltyComponent != domain.DefaultAccountRatingWeights().ScamPenalty {
+			t.Fatalf("penalty = %d, want the scam penalty", rating.PenaltyComponent)
+		}
+	})
+
+	t.Run("expired parking is folded into the visible rating", func(t *testing.T) {
+		st := newFakeRatingStore()
+		st.ratings[7] = domain.AccountRating{
+			UserID: 7, Stars: 100, Level: 1, Version: 2,
+			PendingStars: 400, PendingDate: testNow.Add(-time.Hour),
+		}
+		st.signals[7] = domain.AccountRatingSignals{StarsReceived: 500}
+		service := newTestService(st, WithPendingDelay(24*time.Hour))
+
+		rating, err := service.Recompute(context.Background(), 7)
+		if err != nil {
+			t.Fatalf("Recompute: %v", err)
+		}
+		if rating.Stars != 500 || rating.PendingStars != 0 || !rating.PendingDate.IsZero() {
+			t.Fatalf("rating = %#v, want the parked delta applied and cleared", rating)
+		}
+	})
+
+	t.Run("zero delay never parks", func(t *testing.T) {
+		st := newFakeRatingStore()
+		st.ratings[7] = domain.AccountRating{UserID: 7, Stars: 100, Version: 1}
+		st.signals[7] = domain.AccountRatingSignals{StarsReceived: 500}
+		service := newTestService(st, WithPendingDelay(0))
+
+		rating, err := service.Recompute(context.Background(), 7)
+		if err != nil {
+			t.Fatalf("Recompute: %v", err)
+		}
+		if rating.Stars != 500 || rating.PendingStars != 0 {
+			t.Fatalf("rating = %d stars / %d pending, want an immediate apply", rating.Stars, rating.PendingStars)
+		}
+	})
+}
+
+func TestRecomputeRetriesOnceOnVersionConflict(t *testing.T) {
+	st := newFakeRatingStore()
+	st.ratings[7] = domain.AccountRating{UserID: 7, Stars: 100, Version: 3}
+	st.signals[7] = domain.AccountRatingSignals{StarsReceived: 200}
+	st.forceConflicts = 1
+	service := newTestService(st, WithPendingDelay(0))
+
+	rating, err := service.Recompute(context.Background(), 7)
+	if err != nil {
+		t.Fatalf("Recompute: %v", err)
+	}
+	if len(st.saves) != 2 {
+		t.Fatalf("saves = %d, want exactly one retry", len(st.saves))
+	}
+	if rating.Version != 4 || rating.Stars != 200 {
+		t.Fatalf("rating = %#v, want version 4 with 200 stars", rating)
+	}
+}
+
+func TestRecomputeFailsAfterPersistentConflict(t *testing.T) {
+	st := newFakeRatingStore()
+	st.signals[7] = domain.AccountRatingSignals{StarsReceived: 200}
+	st.forceConflicts = 2
+	service := newTestService(st)
+
+	if _, err := service.Recompute(context.Background(), 7); err == nil {
+		t.Fatal("Recompute reported success while every save lost the version race")
+	}
+	if len(st.saves) != 2 {
+		t.Fatalf("saves = %d, want the bounded single retry", len(st.saves))
+	}
+}
+
+func TestAdjustRecordsLedgerAndRecomputes(t *testing.T) {
+	st := newFakeRatingStore()
+	st.signals[7] = domain.AccountRatingSignals{StarsReceived: 100}
+	service := newTestService(st, WithPendingDelay(0))
+
+	rating, applied, err := service.Adjust(context.Background(), domain.AdjustAccountRatingRequest{
+		UserID: 7, Amount: 300, Reason: "support compensation", Actor: "admin", CommandKey: "cmd-1",
+	})
+	if err != nil || !applied {
+		t.Fatalf("Adjust = %v, %v", applied, err)
+	}
+	if rating.ManualComponent != 300 || rating.Stars != 400 {
+		t.Fatalf("rating = %#v, want the manual component folded in", rating)
+	}
+	if len(st.events[7]) != 1 {
+		t.Fatalf("ledger rows = %d, want 1", len(st.events[7]))
+	}
+}
+
+func TestAdjustReplayByCommandKeyIsIdempotent(t *testing.T) {
+	st := newFakeRatingStore()
+	st.signals[7] = domain.AccountRatingSignals{StarsReceived: 100}
+	service := newTestService(st, WithPendingDelay(0))
+	req := domain.AdjustAccountRatingRequest{UserID: 7, Amount: 300, Actor: "admin", CommandKey: "cmd-1"}
+
+	first, applied, err := service.Adjust(context.Background(), req)
+	if err != nil || !applied {
+		t.Fatalf("first Adjust = %v, %v", applied, err)
+	}
+	second, applied, err := service.Adjust(context.Background(), req)
+	if err != nil {
+		t.Fatalf("replayed Adjust: %v", err)
+	}
+	if applied {
+		t.Fatal("replayed Adjust reported applied=true")
+	}
+	if len(st.events[7]) != 1 || st.manual[7] != 300 {
+		t.Fatalf("ledger = %d rows / manual %d, want the replay recorded nothing", len(st.events[7]), st.manual[7])
+	}
+	if second.Stars != first.Stars || second.ManualComponent != first.ManualComponent {
+		t.Fatalf("replayed rating = %#v, want the same score as %#v", second, first)
+	}
+}
+
+func TestAdjustValidatesRequest(t *testing.T) {
+	st := newFakeRatingStore()
+	service := newTestService(st)
+	tests := []domain.AdjustAccountRatingRequest{
+		{UserID: 0, Amount: 10},
+		{UserID: 7, Amount: 0},
+		{UserID: 7, Amount: 10, Reason: string(make([]byte, domain.MaxAccountRatingReasonLength+1))},
+	}
+	for _, req := range tests {
+		if _, _, err := service.Adjust(context.Background(), req); !errors.Is(err, domain.ErrAccountRatingAdjustmentInvalid) {
+			t.Fatalf("Adjust(%#v) error = %v, want ErrAccountRatingAdjustmentInvalid", req, err)
+		}
+	}
+	if len(st.events) != 0 || len(st.saves) != 0 {
+		t.Fatal("store was touched by an invalid adjustment")
+	}
+}
+
+func TestRunRecomputeCycleProcessesTheBatch(t *testing.T) {
+	st := newFakeRatingStore()
+	st.stale = []int64{1, 2, 3}
+	for _, userID := range st.stale {
+		st.signals[userID] = domain.AccountRatingSignals{StarsReceived: 100 * userID}
+	}
+	service := newTestService(st, WithStaleAfter(6*time.Hour))
+
+	processed, err := service.RunRecomputeCycle(context.Background(), 10)
+	if err != nil {
+		t.Fatalf("RunRecomputeCycle: %v", err)
+	}
+	if processed != 3 {
+		t.Fatalf("processed = %d, want 3", processed)
+	}
+	if st.staleLimit != 10 {
+		t.Fatalf("stale limit = %d, want the requested 10", st.staleLimit)
+	}
+	if want := testNow.Add(-6 * time.Hour).Unix(); st.staleOlderThan != want {
+		t.Fatalf("stale horizon = %d, want %d", st.staleOlderThan, want)
+	}
+	for _, userID := range st.stale {
+		if _, ok := st.ratings[userID]; !ok {
+			t.Fatalf("user %d was not recomputed", userID)
+		}
+	}
+}
+
+func TestRunRecomputeCycleSkipsFailingUsers(t *testing.T) {
+	st := newFakeRatingStore()
+	st.stale = []int64{1, 0, 2}
+	st.forceConflicts = 2 // both saves of the first user lose the race
+	service := newTestService(st)
+
+	processed, err := service.RunRecomputeCycle(context.Background(), 0)
+	if err != nil {
+		t.Fatalf("RunRecomputeCycle: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("processed = %d, want the surviving user only", processed)
+	}
+	if st.staleLimit != defaultRecomputeBatch {
+		t.Fatalf("stale limit = %d, want the default batch", st.staleLimit)
+	}
+}
+
+func TestReadPathsDegradeWhenDisabled(t *testing.T) {
+	st := newFakeRatingStore()
+	st.ratings[7] = domain.AccountRating{UserID: 7, Stars: 500, Level: 2, Version: 1}
+	service := newTestService(st, WithEnabled(false))
+
+	if service.Enabled() || service.Ready() {
+		t.Fatal("disabled service reported enabled/ready")
+	}
+	// The userFull projection omits both TL flags on this error, which is exactly
+	// the pre-rating wire shape.
+	if _, err := service.Rating(context.Background(), 7); !errors.Is(err, domain.ErrAccountRatingNotFound) {
+		t.Fatalf("Rating error = %v, want ErrAccountRatingNotFound", err)
+	}
+	batch, err := service.RatingBatch(context.Background(), []int64{7})
+	if err != nil || len(batch) != 0 {
+		t.Fatalf("RatingBatch = %#v, %v; want empty", batch, err)
+	}
+	if _, err := service.Recompute(context.Background(), 7); !errors.Is(err, ErrDisabled) {
+		t.Fatalf("Recompute error = %v, want ErrDisabled", err)
+	}
+	if _, _, err := service.Adjust(context.Background(), domain.AdjustAccountRatingRequest{UserID: 7, Amount: 5}); !errors.Is(err, ErrDisabled) {
+		t.Fatalf("Adjust error = %v, want ErrDisabled", err)
+	}
+	processed, err := service.RunRecomputeCycle(context.Background(), 10)
+	if err != nil || processed != 0 {
+		t.Fatalf("RunRecomputeCycle = %d, %v; want a no-op", processed, err)
+	}
+}
+
+func TestUnconfiguredStoreReportsConfiguration(t *testing.T) {
+	service := NewService()
+	if service.Ready() {
+		t.Fatal("Ready = true without a store")
+	}
+	if _, err := service.Rating(context.Background(), 7); err == nil {
+		t.Fatal("Rating accepted a missing store")
+	}
+	if _, err := service.Recompute(context.Background(), 7); err == nil {
+		t.Fatal("Recompute accepted a missing store")
+	}
+	if _, _, err := service.Adjust(context.Background(), domain.AdjustAccountRatingRequest{UserID: 7, Amount: 5}); err == nil {
+		t.Fatal("Adjust accepted a missing store")
+	}
+	if _, err := service.RunRecomputeCycle(context.Background(), 10); err == nil {
+		t.Fatal("RunRecomputeCycle accepted a missing store")
+	}
+}
+
+func TestNilServiceIsSafe(t *testing.T) {
+	var service *Service
+	if service.Enabled() || service.Ready() {
+		t.Fatal("nil service reported enabled/ready")
+	}
+	if got := service.Weights(); got != domain.DefaultAccountRatingWeights() {
+		t.Fatalf("nil service weights = %#v, want the defaults", got)
+	}
+	if _, err := service.Rating(context.Background(), 7); !errors.Is(err, domain.ErrAccountRatingNotFound) {
+		t.Fatalf("nil service Rating error = %v, want ErrAccountRatingNotFound", err)
+	}
+	if batch, err := service.RatingBatch(context.Background(), []int64{7}); err != nil || len(batch) != 0 {
+		t.Fatalf("nil service RatingBatch = %#v, %v; want empty", batch, err)
+	}
+	if _, err := service.Recompute(context.Background(), 7); !errors.Is(err, ErrDisabled) {
+		t.Fatalf("nil service Recompute error = %v, want ErrDisabled", err)
+	}
+	if processed, err := service.RunRecomputeCycle(context.Background(), 10); err != nil || processed != 0 {
+		t.Fatalf("nil service RunRecomputeCycle = %d, %v", processed, err)
+	}
+}
+
+func TestInvalidWeightsFallBackToDefaults(t *testing.T) {
+	st := newFakeRatingStore()
+	service := newTestService(st, WithWeights(domain.AccountRatingWeights{StarsReceivedPermille: -1}))
+	if got := service.Weights(); got != domain.DefaultAccountRatingWeights() {
+		t.Fatalf("weights = %#v, want the defaults after rejecting a negative set", got)
+	}
+}
+
+func TestListAndEventsBoundThePage(t *testing.T) {
+	st := newFakeRatingStore()
+	st.ratings[7] = domain.AccountRating{UserID: 7, Level: 3, Version: 1}
+	for i := range maxEventLimit + 10 {
+		st.events[7] = append(st.events[7], domain.AccountRatingEvent{ID: int64(i + 1), UserID: 7, Amount: 1})
+	}
+	service := newTestService(st)
+
+	list, err := service.List(context.Background(), domain.AccountRatingFilter{MinLevel: -5, Limit: 0})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(list) != 1 {
+		t.Fatalf("List = %d rows, want 1", len(list))
+	}
+	events, err := service.Events(context.Background(), 7, 100000)
+	if err != nil {
+		t.Fatalf("Events: %v", err)
+	}
+	if len(events) != maxEventLimit {
+		t.Fatalf("Events = %d rows, want the %d cap", len(events), maxEventLimit)
+	}
+	if _, err := service.Events(context.Background(), 0, 10); !errors.Is(err, domain.ErrAccountRatingAdjustmentInvalid) {
+		t.Fatalf("Events accepted a zero user id")
+	}
+}
+
+func TestRecomputeWorkerRunsAndStops(t *testing.T) {
+	st := newFakeRatingStore()
+	st.stale = []int64{1}
+	st.signals[1] = domain.AccountRatingSignals{StarsReceived: 100}
+	service := newTestService(st)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		NewRecomputeWorker(service, nil, time.Hour, 10).Run(ctx)
+	}()
+	// The first cycle runs before the ticker, so cancelling immediately still
+	// leaves exactly one recompute behind.
+	<-time.After(20 * time.Millisecond)
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("worker did not stop on context cancellation")
+	}
+	if _, ok := st.ratings[1]; !ok {
+		t.Fatal("worker did not recompute the stale user")
+	}
+}
+
+func TestRecomputeWorkerExitsWhenNotReady(t *testing.T) {
+	worker := NewRecomputeWorker(newTestService(newFakeRatingStore(), WithEnabled(false)), nil, time.Millisecond, 0)
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		worker.Run(context.Background())
+	}()
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("disabled worker kept running")
+	}
+	if worker.batch != defaultRecomputeBatch {
+		t.Fatalf("batch = %d, want the default fallback", worker.batch)
+	}
+}
+
+// TestRunRecomputeCycleSeedsAccountsWithNoProjection is the report "the ratings tab
+// is empty and no client shows a rating". StaleAccountRatings reads account_rating,
+// so it can only ever refresh rows that already exist; without a seeding pass the
+// very first row for a user has to come from an operator recomputing that user by
+// hand, and the read model stays permanently empty.
+func TestRunRecomputeCycleSeedsAccountsWithNoProjection(t *testing.T) {
+	st := newFakeRatingStore()
+	st.unrated = []int64{11, 12, 13}
+	for _, userID := range st.unrated {
+		st.signals[userID] = domain.AccountRatingSignals{StarsReceived: 100 * userID}
+	}
+	service := newTestService(st)
+
+	processed, err := service.RunRecomputeCycle(context.Background(), 10)
+	if err != nil {
+		t.Fatalf("RunRecomputeCycle: %v", err)
+	}
+	if processed != 3 {
+		t.Fatalf("processed = %d, want the three seeded accounts", processed)
+	}
+	for _, userID := range st.unrated {
+		if _, ok := st.ratings[userID]; !ok {
+			t.Fatalf("account %d was not seeded", userID)
+		}
+	}
+	// A second cycle has nothing left to seed, so seeding converges instead of
+	// rewriting the same rows every interval.
+	if processed, err := service.RunRecomputeCycle(context.Background(), 10); err != nil || processed != 0 {
+		t.Fatalf("second cycle = %d,%v, want 0,nil", processed, err)
+	}
+}
+
+// The batch bound belongs to the cycle, not to each pass: a backlog of stale rows
+// must not let one cycle do an unbounded amount of work.
+func TestRunRecomputeCycleSharesTheBatchBudget(t *testing.T) {
+	st := newFakeRatingStore()
+	st.stale = []int64{1, 2}
+	st.unrated = []int64{11, 12, 13, 14}
+	service := newTestService(st)
+
+	processed, err := service.RunRecomputeCycle(context.Background(), 3)
+	if err != nil {
+		t.Fatalf("RunRecomputeCycle: %v", err)
+	}
+	if processed != 3 {
+		t.Fatalf("processed = %d, want the batch bound of 3", processed)
+	}
+	if st.unratedLimit != 1 {
+		t.Fatalf("seeding limit = %d, want the 1 left after two stale rows", st.unratedLimit)
+	}
+
+	// A cycle whose stale pass already fills the batch does not query for seeds at
+	// all: refreshing rows somebody is looking at comes first.
+	full := newFakeRatingStore()
+	full.stale = []int64{1, 2, 3}
+	full.unrated = []int64{11}
+	if _, err := newTestService(full).RunRecomputeCycle(context.Background(), 3); err != nil {
+		t.Fatalf("RunRecomputeCycle: %v", err)
+	}
+	if full.unratedCalls != 0 {
+		t.Fatalf("seeding was queried %d times, want none when the batch is already full", full.unratedCalls)
+	}
+}
+
+// Seeding extends the cycle; it is not its purpose. A store that cannot enumerate
+// accounts must not turn a successful stale pass into a failed cycle.
+func TestRunRecomputeCycleSurvivesSeedingFailure(t *testing.T) {
+	st := newFakeRatingStore()
+	st.stale = []int64{1}
+	st.unratedErr = errors.New("no users table")
+	service := newTestService(st)
+
+	processed, err := service.RunRecomputeCycle(context.Background(), 10)
+	if err != nil {
+		t.Fatalf("RunRecomputeCycle = %v, want the stale pass to stand", err)
+	}
+	if processed != 1 {
+		t.Fatalf("processed = %d, want the one stale row", processed)
+	}
+}
+
+// TestEnsureRatingMaterializesOnce covers an administrative immediate-read path:
+// when the worker has not reached an account yet, the first read materializes the
+// local projection and the second read must not write again.
+func TestEnsureRatingMaterializesOnce(t *testing.T) {
+	st := newFakeRatingStore()
+	st.signals[7] = domain.AccountRatingSignals{StarsReceived: 900}
+	service := newTestService(st)
+
+	if _, err := service.Rating(context.Background(), 7); !errors.Is(err, domain.ErrAccountRatingNotFound) {
+		t.Fatalf("Rating before materialising = %v, want ErrAccountRatingNotFound", err)
+	}
+	rating, err := service.EnsureRating(context.Background(), 7)
+	if err != nil {
+		t.Fatalf("EnsureRating: %v", err)
+	}
+	if rating.UserID != 7 || rating.Stars == 0 {
+		t.Fatalf("materialised rating = %+v, want a computed rating for user 7", rating)
+	}
+	writes := len(st.saves)
+	again, err := service.EnsureRating(context.Background(), 7)
+	if err != nil {
+		t.Fatalf("second EnsureRating: %v", err)
+	}
+	if again.Version != rating.Version {
+		t.Fatalf("second EnsureRating rewrote the row: version %d then %d", rating.Version, again.Version)
+	}
+	if len(st.saves) != writes {
+		t.Fatalf("second EnsureRating issued %d extra saves, want none", len(st.saves)-writes)
+	}
+}
+
+// A disabled feature materialises nothing. Telegram wire fields remain unset
+// independently of this local feature flag.
+func TestEnsureRatingDisabledStaysEmpty(t *testing.T) {
+	st := newFakeRatingStore()
+	st.signals[7] = domain.AccountRatingSignals{StarsReceived: 900}
+	service := newTestService(st, WithEnabled(false))
+
+	if _, err := service.EnsureRating(context.Background(), 7); !errors.Is(err, domain.ErrAccountRatingNotFound) {
+		t.Fatalf("EnsureRating while disabled = %v, want ErrAccountRatingNotFound", err)
+	}
+	if len(st.saves) != 0 {
+		t.Fatalf("EnsureRating while disabled wrote %d rows, want none", len(st.saves))
+	}
+}
+
+// TestRecomputeRefusesServiceAccounts pins that the platform account and the
+// built-in bots carry no rating. The platform account is not flagged is_bot, so the
+// bot exclusion in the seeding query does not cover it -- which is how it acquired a
+// rating in the first place -- and an operator must not be able to create one by
+// hand either.
+func TestRecomputeRefusesServiceAccounts(t *testing.T) {
+	for _, userID := range domain.SystemUserIDs() {
+		st := newFakeRatingStore()
+		st.signals[userID] = domain.AccountRatingSignals{StarsReceived: 5000}
+		st.unrated = []int64{userID}
+		service := newTestService(st)
+
+		if _, err := service.Recompute(context.Background(), userID); !errors.Is(err, domain.ErrAccountRatingAdjustmentInvalid) {
+			t.Fatalf("Recompute(%d) = %v, want ErrAccountRatingAdjustmentInvalid", userID, err)
+		}
+		if _, err := service.EnsureRating(context.Background(), userID); err == nil {
+			t.Fatalf("EnsureRating(%d) succeeded, want a refusal", userID)
+		}
+		if len(st.ratings) != 0 {
+			t.Fatalf("service account %d ended up with a projection: %#v", userID, st.ratings)
+		}
+		// A seeding pass that is somehow handed one skips it rather than failing the
+		// whole cycle.
+		if processed, err := service.RunRecomputeCycle(context.Background(), 10); err != nil || processed != 0 {
+			t.Fatalf("cycle over service account %d = %d,%v, want 0,nil", userID, processed, err)
+		}
+	}
+
+	// An ordinary account is unaffected.
+	st := newFakeRatingStore()
+	st.signals[42] = domain.AccountRatingSignals{StarsReceived: 5000}
+	if _, err := newTestService(st).Recompute(context.Background(), 42); err != nil {
+		t.Fatalf("Recompute of an ordinary account: %v", err)
+	}
+}
--- a/internal/app/rating/worker.go
+++ b/internal/app/rating/worker.go
@ -0,0 +1,91 @@
+package rating
+
+import (
+	"context"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+const (
+	// defaultRecomputeInterval matches the shipped
+	// TELESRV_RATING_RECOMPUTE_INTERVAL default.
+	defaultRecomputeInterval = 15 * time.Minute
+)
+
+// RecomputeWorker keeps the rating read model fresh.
+//
+// The projection is derived from signals that change outside the rating write
+// path (Stars flow, message activity, moderation decisions, account age), so no
+// single writer can keep it current. This worker walks the stale projections in
+// bounded batches; it never recomputes the whole table in one pass, and a
+// cancelled context stops it between users rather than mid-write.
+type RecomputeWorker struct {
+	service  *Service
+	logger   *zap.Logger
+	interval time.Duration
+	batch    int
+}
+
+// NewRecomputeWorker creates the periodic recompute worker. Non-positive
+// interval/batch fall back to the shipped defaults, matching the retention
+// worker's contract.
+func NewRecomputeWorker(service *Service, logger *zap.Logger, interval time.Duration, batch int) *RecomputeWorker {
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+	if interval <= 0 {
+		interval = defaultRecomputeInterval
+	}
+	if batch <= 0 {
+		batch = defaultRecomputeBatch
+	}
+	return &RecomputeWorker{service: service, logger: logger, interval: interval, batch: batch}
+}
+
+// Run recomputes one batch immediately and then on every tick until ctx is
+// done. A disabled or store-less service exits immediately with one explicit
+// log line instead of ticking forever over a no-op.
+func (w *RecomputeWorker) Run(ctx context.Context) {
+	if w == nil {
+		return
+	}
+	if !w.service.Ready() {
+		w.logger.Info("account rating recompute worker disabled",
+			zap.Bool("enabled", w.service.Enabled()))
+		return
+	}
+	w.runOnce(ctx)
+	ticker := time.NewTicker(w.interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			w.runOnce(ctx)
+		}
+	}
+}
+
+func (w *RecomputeWorker) runOnce(ctx context.Context) {
+	if w == nil || w.service == nil {
+		return
+	}
+	processed, err := w.service.RunRecomputeCycle(ctx, w.batch)
+	if err != nil {
+		if ctx.Err() != nil {
+			return
+		}
+		w.logger.Warn("account rating recompute cycle failed",
+			zap.Int("processed", processed),
+			zap.Int("batch", w.batch),
+			zap.Error(err))
+		return
+	}
+	if processed > 0 {
+		w.logger.Info("account rating recompute cycle completed",
+			zap.Int("processed", processed),
+			zap.Int("batch", w.batch))
+	}
+}