screen-locker/stronglift_replacement/workout_app/lib/models/gap_deload.dart
Krzysztof kuhy Rudnicki bc4e590822 workout_app: deload after a training gap at load
The old break rule ran at finish after the session was saved, so
daysSince was always 0 and it never fired. Now the gap deload cuts
by tier (7-13d 1 step, 14-20d 2, +1/week, 40% cap) when the workout
loads, stamps last_deloaded_at (shared with manual deload, synced),
logs progression_events, and shows the old target struck through.
One-time backfill with pre-cut export + restore script.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 00:11:54 +01:00

135 lines
4.6 KiB
Dart

/// The gap deload: how far a training break cuts an exercise's target.
///
/// Applied when the workout loads, not when it finishes. The old rule lived
/// in `applyProgression` and could never fire: finishing saves the session
/// first, so "days since the last workout" was always 0. It also only ever
/// took one step, so a two-week break started from the pre-gap max.
///
/// Pure on purpose: the storage layer decides *whether* an exercise is due
/// (stamp, history) and these functions decide *how much*.
library;
import 'package:workout_app/models/progression.dart';
/// Shortest break, in calendar days, that costs a step.
const int kGapDeloadMinDays = 7;
/// Every further week of break costs one more step.
const int kGapDeloadDaysPerStep = 7;
/// The most a gap deload may take off the pre-gap weight (or reps, in reps
/// mode): a hard cap, however long the break.
const double kGapDeloadMaxLoss = 0.4;
/// `progression_events.kind` of a deload a training gap caused at load.
const String kGapDeloadKind = 'gap_deload';
/// `progression_events.kind` of the one-time repair of existing data.
const String kBackfillDeloadKind = 'backfill_deload';
/// Calendar days from [from] to [to]: 23:00 to 01:00 next day is one day.
///
/// Built from UTC dates so a DST change inside the gap cannot shave an hour
/// off and turn 7 days into 6.
int gapCalendarDays(DateTime from, DateTime to) => DateTime.utc(
to.year,
to.month,
to.day,
).difference(DateTime.utc(from.year, from.month, from.day)).inDays;
/// Regression steps a break of [gapDays] calendar days costs: under 7 none,
/// 7-13 one, 14-20 two, then one more per extra week.
int gapDeloadSteps(int gapDays) => gapDays < kGapDeloadMinDays
? 0
: 1 + (gapDays - kGapDeloadMinDays) ~/ kGapDeloadDaysPerStep;
/// [s]'s target after [steps] regression steps, each one
/// [targetAfterFailure], stopping before any step that would take more than
/// [kGapDeloadMaxLoss] off [s]'s weight (or, in reps mode, its reps).
///
/// A step that alone breaks the cap is not taken: 5 kg -> 2.5 kg is a 50%
/// loss, so a 5 kg exercise keeps 5 kg. Double progression caps on weight
/// only; its rep drops within one weight are the small steps of the ladder.
ProgressionTarget gapDeloadTarget(ProgressionInputs s, int steps) {
final weightFloor = s.weight * (1 - kGapDeloadMaxLoss);
final repsFloor = (s.reps * (1 - kGapDeloadMaxLoss)).ceil();
var cur = s;
for (var i = 0; i < steps; i++) {
final t = targetAfterFailure(cur);
if (t.weight == cur.weight && t.reps == cur.reps) break;
// A tiny epsilon: 0.6 * 12.5 is 7.499999... in binary.
if (t.weight < weightFloor - 1e-9) break;
if (s.mode == ProgressionMode.reps && t.reps < repsFloor) break;
cur = _Step(s, t);
}
return ProgressionTarget(cur.weight, cur.reps);
}
/// One finished session of one exercise: when it ended and its target.
class SessionMark {
/// Creates a [SessionMark].
const SessionMark({
required this.endedAt,
required this.weight,
required this.reps,
});
/// When the session ended (local time).
final DateTime endedAt;
/// The target weight the session was done at, in kg.
final double weight;
/// The target reps the session was done at.
final int reps;
}
/// Steps the history still owes: the replay (part c) of the backfill.
///
/// Replays [marks] (oldest first) with the new rule. Each gap of a week or
/// more between two sessions should have cut the next one's target; when the
/// next session ran at the SAME target, that cut never happened and its
/// steps are owed. Any target change afterwards (a fail-streak deload, a
/// success step, a hand edit) re-anchors the replay on what was really
/// lifted, so the debt clears. That is kuhy's case: failed after a 7-day
/// break at the pre-gap weight, then a second break on top.
int missedGapSteps(List<SessionMark> marks) {
var owed = 0;
for (var i = 1; i < marks.length; i++) {
final prev = marks[i - 1];
final cur = marks[i];
if (cur.weight != prev.weight || cur.reps != prev.reps) {
owed = 0;
continue;
}
owed += gapDeloadSteps(gapCalendarDays(prev.endedAt, cur.endedAt));
}
return owed;
}
/// [ProgressionInputs] of [base] with [t]'s weight and reps: one step down.
class _Step implements ProgressionInputs {
_Step(this._base, this._t);
final ProgressionInputs _base;
final ProgressionTarget _t;
@override
double get weight => _t.weight;
@override
int get reps => _t.reps;
@override
double get maxWeight => _base.maxWeight;
@override
ProgressionMode get mode => _base.mode;
@override
int get repsHigh => _base.repsHigh;
@override
int get repsLow => _base.repsLow;
}