Habit Tracker: Streaks, Freezes and Backfills

Habit Tracker: Streaks, Freezes and Backfills

You've joined the team behind Streak, a habit-tracking app. Users create habits ("run", "read 20 pages"), check in when they do them, and watch their streak grow. Support has three open bugs against the streak counter, and product wants two features on top of it: streak freezes and backfilled check-ins. Plan for about 45 minutes; the three parts build on each other.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh tracker and returns one result per operation. Every operation is [name, ts, ...args]. ts is an integer epoch second in UTC and never decreases from one operation to the next. Errors are returned as strings ("error: <code>"), never raised.

• An unknown operation name returns "error: unknown operation". A wrong number of arguments, a non-integer ts (true/false are not integers), or an empty or non-string user_id/habit_id returns "error: invalid arguments" (before any other check).
• A UTC offset is an integer number of minutes from -720 to 840 inclusive, fixed per user.
• Ids are case-sensitive. A habit is identified by (user_id, habit_id); two users may each have a habit called "run".
• Local day. Everything a user sees is on *their* calendar: the local day of ts is the UTC calendar day of ts + offset_minutes * 60. A habit's start day is the local day it was added; there is no history before it.
• A habit can be checked in at most once per local day.
• Schedules (exact strings): "daily"; a comma-separated list of distinct weekday names from Mon Tue Wed Thu Fri Sat Sun with no spaces, in any order ("Mon,Wed,Fri"); or "Nx/week" with N from 1 to 7 ("3x/week"). Anything else is invalid schedule. Weeks start on Monday.

Part 1 — Fix the streak counter (HAB-412, HAB-437, HAB-450)

Goal: make streak follow the rules below. A *period* is one unit of a streak; the current streak is the number of consecutive completed periods ending at the user's current local day.

Reports from support:

1. "I check in around 8pm Pacific and the app files it under tomorrow, and my streak is wrong in the evening." (HAB-412)
2. "My daily streak shows 0 every morning until I check in again." (HAB-437)
3. "I did my 3x/week habit Friday, Saturday and Sunday and that week doesn't count." (HAB-450)

Rules

1. *Daily and weekday schedules.* Each scheduled day from the start day up to today is a period; it is completed if the habit was checked in that local day. Days that are not scheduled are not periods: they neither extend nor break a streak. A check-in on an unscheduled day is accepted and recorded (and blocks a second check-in that day) but never counts toward a streak.
2. *Today is still in progress.* If today is a scheduled day and not checked in yet, it is left out (it does not break the streak). If it is checked in, it counts. Any earlier scheduled day without a check-in breaks the streak: the streak is the run of completed periods after it.
3. *"N times per week".* Each Monday-to-Sunday week from the habit's start week to the current week is a period, completed when it has check-ins on at least N different days. A finished week that is not completed breaks the streak. The current week counts if already completed and is otherwise left out. The start week (the week containing the start day) is optional: it counts if completed, and is simply left out if not, so a habit added on a Thursday is not already failing.
4. A streak of 0 is returned when no period qualifies.

Worked example (Mia is at UTC-08:00, so her days start at 08:00 UTC)

[["add_user", 1709510400, "mia", -480],
 ["add_habit", 1709510400, "mia", "run", "daily"],
 ["check_in", 1709532000, "mia", "run"],
 ["check_in", 1709607600, "mia", "run"],
 ["streak", 1709618400, "mia", "run"],
 ["streak", 1709632800, "mia", "run"],
 ["streak", 1709726400, "mia", "run"]]

returns [true, true, "2024-03-03", "2024-03-04", 2, 2, 0]. (1709510400 is 2024-03-04 00:00 UTC = Mia's local 2024-03-03 16:00, so that is her start day. Her local March 5 is unfinished at the first streak query and fully missed at the last.)

tests/test_streaks.py has a failing test for the first report.

Part 2 — Streak freezes (HAB-461)

Goal: a missed period should not instantly destroy a long streak. Users earn freezes that are spent automatically to cover a miss. Add two operations and change what streak returns.

Freezes belong to a habit, not to a user. Replay the habit's periods oldest first (the same periods as Part 1), starting with a streak of 0 and 0 freezes:

Rules

1. *Completed period:* the streak goes up by 1. If it is now a multiple of 7 and fewer than 2 freezes are held, one freeze is earned; at the cap of 2 the freeze is lost.
2. *Missed period* (it has ended, was not completed, and is not the optional start week): if a freeze is held, one is spent and the streak is unchanged (the period is *frozen*: it neither counts nor breaks). With no freeze the streak resets to 0.
3. A period that is still open (today's scheduled day, the current week) or optional never spends a freeze. Today's check-in does count the moment it is made, including earning a freeze.
4. Because frozen periods do not count, the next freeze is earned on the 7th, 14th, 21st, ... *completed* period, not on the 7th calendar period.
5. frozen labels a period by its date: the scheduled day ("2024-03-11") or, for Nx/week, the Monday of the week.
6. A spent freeze is not given back in this part.
7. streak is the streak after the replay (everything in Part 1 still applies).

Worked example (Ana is at UTC; 1709510400 = Mon 2024-03-04 00:00, and every check-in is at noon)

[["add_user", 1709510400, "ana", 0],
 ["add_habit", 1709510400, "ana", "read", "daily"],
 ["check_in", 1709553600, "ana", "read"], ["check_in", 1709640000, "ana", "read"],
 ["check_in", 1709726400, "ana", "read"], ["check_in", 1709812800, "ana", "read"],
 ["check_in", 1709899200, "ana", "read"], ["check_in", 1709985600, "ana", "read"],
 ["check_in", 1710072000, "ana", "read"],
 ["streak", 1710100800, "ana", "read"],
 ["freezes", 1710100800, "ana", "read"],
 ["check_in", 1710244800, "ana", "read"],
 ["streak", 1710273600, "ana", "read"],
 ["freezes", 1710273600, "ana", "read"],
 ["frozen", 1710273600, "ana", "read"]]

returns [true, true, "2024-03-04", "2024-03-05", "2024-03-06", "2024-03-07", "2024-03-08", "2024-03-09", "2024-03-10", 7, 1, "2024-03-12", 8, 0, ["2024-03-11"]]. Ana checks in on Mar 4-10 (streak 7, one freeze earned), skips Mar 11 (the freeze is spent, streak stays 7) and checks in on Mar 12 (streak 8, no freezes left).

Part 3 — Backfilled check-ins (HAB-479)

Goal: people forget to log. Let them record a check-in for a past day, and make the streak and freezes come out exactly as if they had logged it on time. This changes Part 2's rule 6.

Rules

1. date is a strict YYYY-MM-DD string naming a real calendar date, otherwise invalid date ("2024-3-4", "20240304", "2024-02-30", and non-strings are all invalid).
2. Let *today* be the user's local day at ts. The date must be 1 or 2 days before today (not today, not older), otherwise outside backfill window. Today is logged with check_in.
3. The date must not be before the habit's start day (before habit start); the start day itself is fine, even when the rest of its week is not. It must not already be checked in (already checked in), whether that was on time or backfilled.
4. A backfill is accepted for unscheduled days too (it is recorded and counts for nothing).
5. After a backfill, streak, freezes and frozen are what they would be had the check-in been made on that day. In particular a freeze that was spent covering that period is back, a backfill can complete a week for Nx/week, and everything after the backfilled day is evaluated again from scratch: a day that the old history had to freeze or break on may now be covered differently, freeze earning dates can shift, and the cap of 2 still applies.
6. Part 2's rule 6 ("never given back") no longer holds; everything else does.

Worked example (Ana, UTC; Mar 4-9 and Mar 11 are checked in at noon, Mar 10 was forgotten)

[["add_user", 1709510400, "ana", 0],
 ["add_habit", 1709510400, "ana", "read", "daily"],
 ["check_in", 1709553600, "ana", "read"], ["check_in", 1709640000, "ana", "read"],
 ["check_in", 1709726400, "ana", "read"], ["check_in", 1709812800, "ana", "read"],
 ["check_in", 1709899200, "ana", "read"], ["check_in", 1709985600, "ana", "read"],
 ["check_in", 1710158400, "ana", "read"],
 ["streak", 1710237600, "ana", "read"],
 ["freezes", 1710237600, "ana", "read"],
 ["backfill", 1710237600, "ana", "read", "2024-03-10"],
 ["streak", 1710237600, "ana", "read"],
 ["freezes", 1710237600, "ana", "read"]]

returns [true, true, "2024-03-04", "2024-03-05", "2024-03-06", "2024-03-07", "2024-03-08", "2024-03-09", "2024-03-11", 1, 0, "2024-03-10", 8, 1]. On Mar 12 at 10:00 the missed Mar 10 (no freeze held) had reset the streak, so it was 1. The backfill reconnects Mar 4-11 into eight completed days, which earns a freeze at the seventh.

Notes

• schedule.py, registry.py, checkins.py and models.py are known-good.
• You may use the AI assistant freely; you are expected to verify what it produces.
• Later parts must not break earlier ones; hidden tests re-check earlier behaviour after each part.