rotation

func ApplyDisplayRotation ¶

func ApplyDisplayRotation(row *domain.UserGoalProgress, goal *domain.Goal, now time.Time) (progress int, status domain.GoalStatus, rotated bool)

ApplyDisplayRotation returns display-adjusted values for API responses without mutating the row.

This is the read-only counterpart to ApplyRotationReset. It detects rotation in-memory and returns what the user should see, without writing to the database.

Returns:

• progress: displayed progress value
• status: displayed goal status
• rotated: whether a rotation boundary has been crossed

func ApplyRotationReset ¶

func ApplyRotationReset(row *domain.UserGoalProgress, goal *domain.Goal, now time.Time) bool

ApplyRotationReset mutates the row for the new rotation period. Returns true if reset was applied.

Behavior matrix:

| Status       | reset_progress=true              | reset_progress=false |
|--------------|----------------------------------|----------------------|
| not_started  | Reset baseline/status            | Update expiry only   |
| in_progress  | Reset to not_started             | Update expiry only   |
| completed    | Reset to not_started             | Update expiry only   |
| claimed      | Reset if allow_reselection=true  | Skip (return false)  |

func CalculateDisplayedProgress ¶

func CalculateDisplayedProgress(row *domain.UserGoalProgress, goal *domain.Goal) int

CalculateDisplayedProgress computes the progress value shown to users.

For absolute mode: returns raw progress as-is. For relative mode: returns progress minus baseline (delta since rotation start). Returns 0 if baseline is not yet set (relative mode, first event pending).

func CalculateLastRotationBoundary ¶

func CalculateLastRotationBoundary(schedule domain.RotationSchedule, now time.Time) time.Time

CalculateLastRotationBoundary returns the start of the current rotation period. Daily: today 00:00 UTC. Weekly: last Monday 00:00 UTC. Monthly: 1st of month 00:00 UTC. Returns zero time for invalid schedules.

func CalculateNextExpiresAt ¶

func CalculateNextExpiresAt(goal *domain.Goal, now time.Time) *time.Time

CalculateNextExpiresAt returns *time.Time for the goal's next expiry. Returns nil if goal is nil, rotation is nil, or rotation is disabled.

func CalculateNextRotationBoundary ¶

func CalculateNextRotationBoundary(schedule domain.RotationSchedule, now time.Time) time.Time

CalculateNextRotationBoundary returns when the current period ends (= start of next period). Returns zero time for invalid schedules.

func HasRotationOccurred ¶

func HasRotationOccurred(row *domain.UserGoalProgress, goal *domain.Goal, now time.Time) bool

HasRotationOccurred returns true if a rotation boundary has passed since the row was last updated. Read-only; does not modify the row. Returns false for nil inputs or disabled rotation.