Time every automation run the same way: offsets and a duration, and no fixed moments

[Flix6x]

Description

Closes #2550.

An automation runs again and again on the server clock, so a moment fixed in its parameters goes stale:
a fixed start or end has every run compute the same period, and a fixed prior has every run ignore the data recorded since then.
Until now, each automation type handled its timing differently. Forecast automations accepted all three. Schedule automations warned about a fixed start. Report automations (#2297) refused a fixed start or end, and were the only type that could describe a window relative to the run.
This makes the three types agree.

Fixed moments are refused for every type. A start, end or prior in an automation's parameters is refused when the automation is created, with one message and one exception (RecurringAutomationFixesAMoment, renamed from RecurringScheduleFixesAMoment), so the API answers 422 and the CLI a usage error.
A forecast automation can still fix train-start, which belongs to the forecaster's config.
Simulations are not affected: play mode leaves the server clock alone, and a simulation stepping through simulated time triggers each step through the API or CLI with an explicit start and prior.

Every type describes its window the same way. Any automation's parameters take two of start-offset, end-offset and duration, with offsets as the offset chains flexmeasures add report --start-offset already uses (Pandas offsets, plus DB and HB).
The offsets apply to the cron occurrence the run was claimed for, on the automation's own clock, so a run delayed past midnight still covers the day it was due for.
They resolve into what each data generator takes: a start and a duration for a schedule, a start and an end or duration for a forecast, a start and an end for a report.
That makes "every day at noon, schedule tomorrow" expressible, which it was not for schedules and forecasts:

start-offset: "1D,DB"
duration: "P1D"

A start-offset alone gives a forecast or schedule its default duration, and has a report end at the run time. An end-offset alone is for reports only: they continue from the last successful report, and before the first one, cover the cron period ending at that offset. A report with nothing new to cover (e.g. an hourly report up to midnight, after its first run of the day) queues no job, since not every reporter can compute an empty window, and a failed job would never record coverage.
All three fields at once, and combinations a run could not resolve, are refused on creation.

Defaults without offsets are unchanged. Forecasts and schedules still start at the run time, rounded down, rather than at the claimed occurrence, so a caught-up run stays current as the docs promise. Reports still continue from the last successful report.

Two things worth a look:

• A forecast with an explicit start is believed at that start unless it gets a prior, so a resolved window also carries the run time as prior. Otherwise a day-ahead forecast would be stamped as believed tomorrow.
• Window arithmetic uses pd.Timestamp: two datetimes sharing a ZoneInfo subtract in wall-clock time, which made the day the clocks go forward last 24 hours instead of 23.

Report parameters name their belief time prior, as schedule and forecast parameters do. belief_time shipped in v1.0 and is still accepted.
The report schema carries its own alias rather than SupportsLegacyFieldAliases, because prior has to win where both names appear: DataGenerator.compute merges a new run's parameters into those it loaded for its previous run, so a loaded belief_time can meet a new prior. The aggregator tests that compute twice on one reporter caught this.

The first two commits are the schedule refusals first made in #2297, which that PR has since reverted, so they could be done together with forecasts here.

• Added changelog item in documentation/changelog.rst

How to test

pytest \
  flexmeasures/data/tests/test_automation_window.py \
  flexmeasures/data/tests/test_automations_fresh_db.py \
  flexmeasures/cli/tests/test_automations.py \
  flexmeasures/data/schemas/tests/test_reporting.py

New tests cover each window combination for each type, including the day the clocks go forward. They also cover a delayed run that must still cover the day it was due for, a forecast's belief time, the refused combinations, the refused fixed moments per type, train-start staying allowed, the prior data key with its legacy alias and precedence, and day-ahead schedule and forecast runs end to end.
Each new check was verified to fail without the code it covers.

Related items

Tracked in #2550, under the Automations v1 story (#2334). Stacked on #2297, from which the schedule refusals moved here.
Anchoring runs on the claimed occurrence is also the direction for #2537 (a retried run re-resolving its timings), which can build on this once durable runs (#2457) land.

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or another incompatible license.

🤖 Generated with Claude Code

https://claude.ai/code/session_0129WrXeJ5gia2pctFH93BqC

[Copilot]

🔵 Needs a closer look

It changes core timing semantics across all automation types (including DST-sensitive window arithmetic), so it needs careful final human validation despite the strong test coverage.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 1
• Review effort level: Lite

[BelhsanHmida]

Reviewed this one and tested it locally. The design holds up, so I pushed six commits.

Two of them I'd like you to look at properly:

A report could still resolve an inverted window, and fixing it needed a decision. Offsets that fix both ends are checked against each other, but a start carried over from the last successful report is not, since the automation does not fix it. An end-offset alone combines the two: it takes that carried-over start and an end a backward offset can place before it. The run then reported on an inverted window, which a reporter reads as neither the empty window it means nor an error.

I made such a run report on nothing and log why, naming both moments. The alternative — refusing the run — leaves the automation stuck, because the start it cannot resolve is the one it did not choose. If you would rather refuse, it is a three-line change.

resolve_schedule_generator was resolving a wider gap than I first thought. It was the one caller left on the old signature, so it passed neither the automation's timezone nor the run's scheduled_at. I wrote the test expecting an eight-hour drift between the platform clock and an Amsterdam one; the red run showed the generator was actually resolved for today's date, six months from the schedule it describes. Nothing breaks today, since a scheduler's data source records the flex config alone and #2444 keeps moment-fixing values out of it. The two calls now simply agree.

The rest:

• resolve_automation_window indexed "duration" directly on a path that creation refuses, so a stored automation from before that check made the dispatcher report failed to queue jobs: 'duration'. It now names the missing field.
• A calendar duration is built as a pd.DateOffset field by field, and the build took days and seconds but not microseconds, so P1MT0.5S landed half a second early.
• The CLI now explains the offsets and the refusal well, but the create endpoint's description said nothing about either, so an API user met the rule only as a 422 — and the UI's parameters field, a free-form JSON box, is the only place its form explains what belongs in it. Both now say it, and the endpoint gains a day-ahead example. The description also names reporting, which it had missed since #2297.
• Three corrections to wording already on the branch: the comment on the Timestamp arithmetic hung its "so the day the clocks go forward lasts 23 hours" off the datetime clause; the docs said a duration counts real time, which holds for P1D but not for the calendar-aware P1M; and the changelog read as though every belief time in report parameters was renamed, where the one inside an input entry keeps its name.

[Copilot]

🟡 Changes recommended

A newly added wrapped OpenAPI example description breaks mid-phrase and should be reflowed to match the repo’s line-break-after-punctuation documentation convention.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It changes core automation timing semantics across all automation types (including DST-sensitive window arithmetic) and merits final human review despite no specific defects found in the reviewed diffs.

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 0 new
• Review effort level: Lite