Thermostat Scheduler: Wrap-Around Bugs, Holds and Zones

Thermostat Scheduler: Wrap-Around Bugs, Holds and Zones

You've joined the comfort-platform team that owns the scheduling core of a smart thermostat. The household sets a weekly schedule; the thermostat decides what temperature to aim for at any minute. Customer support has escalated wrong-temperature reports, and two features are queued behind the fix. Temperatures are integer tenths of a degree Celsius (215 means 21.5 C).

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh thermostat and returns one result per operation. Every operation is [name, ts, ...args].

• ts is a moment: "Mon 07:30" (day Mon..Sun, 24-hour time) in week 0, or "w2 Mon 07:30" for week 2 (w0, w1, ... with no leading zeros). ts never decreases from one operation to the next. The weekly schedule repeats every week; week 0 starts on Monday 00:00.
• Errors are returned as "error: <code>" strings, never raised. An unknown operation name returns "error: unknown operation"; a wrong number of arguments, an unparsable ts, or an argument of the wrong type returns "error: invalid arguments".
• A setpoint is an integer (not true/false) from 50 to 300 inclusive; otherwise "error: setpoint out of range" (a non-integer is invalid arguments).
• A period is ["HH:MM", setpoint] ("00:00".."23:59", two digits each).

• set_schedule replaces that weekday's list (an empty list clears the day). The list may be given in any order. All structure (list shape, day name, HH:MM text, integer setpoints) is checked first, then every setpoint's range, then duplicate start times in the list. A failed call changes nothing.
• status reports the setpoint in force at ts and its source, which is "schedule" in Part 1. If no weekday has any period, it returns "error: no schedule".

Worked example

[["set_schedule", "Mon 00:00", "Mon", [["06:30", 210], ["22:00", 170]]],
 ["status", "Mon 06:30"],
 ["status", "Mon 22:00"],
 ["status", "Tue 03:00"]]

returns

[true, {"setpoint": 210, "source": "schedule"}, {"setpoint": 170, "source": "schedule"}, {"setpoint": 170, "source": "schedule"}]

Part 1 — Fix the wrong scheduled setpoints (SUP-5108)

Goal: make status return the setpoint the household actually scheduled.

Support tickets:

1. "My heating drops at 22:00 on Friday, but at 06:30 sharp on Saturday morning it still isn't back up until 06:31." (the period that starts exactly at the queried minute is not applied)
2. "I only set Wednesday. On Monday the thermostat says *no schedule* instead of carrying on with last Wednesday's evening setpoint."
3. "I entered my evening period before my morning one and the temperatures came out swapped."

Rules

1. A period is in force from its start minute, inclusive, until the next period starts. The period starting exactly at the queried minute is the one in force.
2. The schedule repeats weekly. Before the first period of the week, the last period of the previous week is still in force — even if several days in between have no periods. A week with a single period in total keeps that setpoint all week.
3. Periods may be supplied in any order, on any day.

tests/test_schedule.py and tests/test_api.py contain failing tests for the first two tickets.

Part 2 — Holds and away mode (FEAT-912)

Goal: let people override the schedule from the wall dial and the app, and add an away mode.

Rules

1. Precedence, highest first: away mode, then the active hold, then the schedule. status returns source "away", "hold" or "schedule" accordingly. In away mode status works even when there is no schedule.
2. hold is temporary: it lasts until the first period start strictly after ts, counting across days and weeks (a period start is a start on any weekday). That moment is returned. A hold set exactly at a period start therefore lasts until the *following* start; with a single period in the whole week it lasts until that period starts again a week later ("w1 Mon 06:30"). The expiry is fixed when the hold is made — later set_schedule calls do not move it. At the expiry minute itself the hold is over and the schedule applies.
3. hold_permanent lasts until cancel_hold. It works with no schedule at all (status then reports the hold; without a hold or schedule it reports no schedule).
4. A new hold replaces the current one. Nothing underneath comes back later.
5. cancel_hold ends the active hold; if there is none — never set, already cancelled, or a temporary hold that has already ended — it returns no hold.
6. Away mode is a single switch for the whole home, with its own setpoint (default 160; set_away changes it at any time, even while away, and takes effect immediately). While away, hold, hold_permanent and cancel_hold are rejected with away mode. Existing holds are not touched: when away_off is called, the state is exactly what the clock says it should be — a permanent hold is back, a temporary hold is back only if its expiry has not passed yet.

Example (Mon-Fri schedule 06:30 210 and 22:00 170 already set)

[["hold", "Mon 12:00", 235],
 ["status", "Mon 21:59"],
 ["hold", "Mon 22:00", 190],
 ["away_on", "Tue 01:00"],
 ["status", "Tue 01:00"],
 ["away_off", "Tue 07:00"],
 ["status", "Tue 07:00"]]

returns

["Mon 22:00", {"setpoint": 235, "source": "hold"}, "Tue 06:30", true,
 {"setpoint": 160, "source": "away"}, true, {"setpoint": 210, "source": "schedule"}]

(The 190 hold made at 22:00 would have ended at Tue 06:30, which passed while away.)

Part 3 — Rooms (zones) (FEAT-955)

Goal: the product is moving to per-room zones. Each zone has its own schedule and its own hold; the household can also hold the whole home at once. Part 1 and 2 behaviour must still work.

New operation and extended operations (zone is a zone id; every zone-aware operation takes it as an optional last argument, defaulting to "main", which exists from the start):

Rules

1. A zone id is 1-20 characters: a lowercase letter followed by lowercase letters, digits or -. add_zone with anything else is invalid arguments. A new zone has an empty schedule and no hold. A zone argument that is not a string is invalid arguments; a valid string naming no zone is zone not found.
2. Zones are independent: schedule, holds and no schedule are all per zone. A temporary hold ends at the next period start of that zone's own schedule.
3. hold_home applies a temporary hold to every zone that currently has at least one period, each ending at its own zone's next start; it returns the expiries for exactly those zones (no schedule if no zone qualifies). hold_home_permanent applies a permanent hold to every existing zone. A zone added later is not affected by an earlier home hold.
4. The later hold wins, by order of operations (not by ts; two holds at the same minute are ordered by which came first). A zone hold made after a home hold replaces it for that zone only; a home hold made after a zone hold replaces that zone's hold. Per Part 2 rule 4, nothing underneath comes back when a hold ends or is replaced.
5. cancel_hold with a zone ends only that zone's active hold, whether it came from the zone or from a home hold. There is no cancel_hold_home.
6. Away mode stays a whole-home switch: it covers every zone, including zones added while away, and away_off restores each zone exactly as its own clock says (Part 2 rule 6).

Example

[["add_zone", "Mon 00:00", "bedroom"],
 ["set_schedule", "Mon 00:00", "Mon", [["06:30", 210], ["22:00", 170]]],
 ["set_schedule", "Mon 00:00", "Mon", [["07:00", 190], ["23:00", 160]], "bedroom"],
 ["hold_home", "Mon 12:00", 230],
 ["hold", "Mon 12:30", 250, "bedroom"],
 ["status", "Mon 13:00"],
 ["status", "Mon 13:00", "bedroom"],
 ["status", "Mon 22:00"],
 ["status", "Mon 22:00", "bedroom"]]

returns

[true, true, true, {"bedroom": "Mon 23:00", "main": "Mon 22:00"}, "Mon 23:00",
 {"setpoint": 230, "source": "hold"}, {"setpoint": 250, "source": "hold"},
 {"setpoint": 170, "source": "schedule"}, {"setpoint": 250, "source": "hold"}]

Notes

• clock.py and validation.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.