feat(schedule): activate manual calibration and time changes next day

gabogg commented

2026-09-25 18:22:55 +00:00

Owner

Split out of #113 (2026-09-25). Design settled by maintainer triage below; original alternatives retained for context.

daily_reset_time decides where every business day starts and ends. It is a single current value, so changing it (e.g. 04:00 → 05:00) re-cuts all past business days: events near the old boundary move to a different day, and every past daily, weekly and monthly figure can change.

#113 deliberately does not record a reset per day: if each day kept its own reset, adjacent days could overlap or leave a gap when the setting changes, and every query that splits time into business days would need to handle that.

Options to decide:

Keep one reset and document that changing it re-cuts history (current behaviour; #113 documents it).
Reset with effective dates: a change applies from a chosen day onward; the transition day is one business day that is longer or shorter than usual.
Forbid changing the reset once counted data exists, except via an explicit migration.

Resets change rarely; this does not block the statistics deck.

🤖 Generated with Claude Code

Maintainer triage — 2026-09-27

Maintainer decision: manual modifications relating to calibration or times apply from the next day onward, preserving prior behavior/history. The user must see both a note explaining delayed activation and a warning/confirmation that the change has been saved and will take effect the next day, explicitly naming that date. Pending settings must survive restart and remain distinguishable from active settings. Expand this issue beyond daily_reset_time to inventory affected manual calibration/time changes and document the agent-facing policy with the implementation. The accepted activation, transition and historical-correction rules below resolve these questions. This triage specifies future implementation; it does not change running settings.

Accepted design and implementation acceptance

The maintainer accepted all recommendations in Q9–Q11.

Next day: the following civil date in facility time, at that date's business-cycle reset, not midnight and not merely the next reset encountered. Saving a change before today's reset still targets tomorrow. Display the effective date, clock time and timezone. If saving on 2026-09-27 in facility time, the notice names 2026-09-28; calculate this dynamically rather than hard-coding it.
Prospective changes: manually changed calibration/time settings stay pending until that boundary. Inventory every affected write surface (configuration, schedules/exceptions, multipliers, offsets and reset actions) and apply the policy consistently through UI and direct API calls. Keep active and pending values distinguishable and persist pending changes across restarts. Do not silently apply them mid-cycle.
Historical corrections: record corrections to historical trust/audit evidence immediately against the original cycle, retaining audit provenance. Their effect on live operational calibration is deferred until tomorrow's boundary. Historical evidence can change through an explicit correction; an ordinary settings change must not re-cut history. Ensure broadcasts and background recalculation cannot accidentally publish a pending operational effect early.
Reset transition: effective-dated reset boundaries provide continuous coverage. A cycle is the interval from its boundary to the next boundary. When the reset itself changes, tomorrow's boundary uses the newly scheduled reset; permit one longer or shorter transition cycle, with no overlap or gap. All day/week/month selection, aggregation and calibration queries must use the same effective-dated boundaries. Preserve already closed boundaries.
User communication: show a note before saving that explains next-day activation, then a visible warning/confirmation after saving that says the change is saved and names its exact effective date/time/zone. Do not say the new setting is already active. Expose pending activation information in the API response and admin view. Localize the notice in English and Spanish.
Activation: apply due changes atomically and once, including recovery after an application restart or outage past the effective instant. Keep a durable audit trail distinguishing submission, historical correction and operational activation. Re-evaluate calibration at activation from the corrected evidence; do not smuggle an immediate recalculation into historical-correction handling.
Verification: use real temporary SQLite databases and controlled facility-time clocks. Cover saving before/after today's reset, civil-date rollover, reset moving earlier/later, contiguous transition intervals, historical totals under unchanged boundaries, immediate historical evidence with delayed live calibration, API/UI notices, restart before/after activation, and idempotent activation. Mock external hardware/network calls. Run the full suite and documentation checks.
Documentation: update the agent-facing calibration/time policy and relevant domain glossary with implementation. Record the effective-dated boundary and delayed operational activation trade-off in an ADR; reconcile superseded statements in existing schedule/calibration docs. Do not present the requested behavior as already implemented.

Domain language to capture with implementation

Pending Calibration/Time Change: an operator-submitted change awaiting its recorded next-day effective boundary.
Effective Boundary: the facility-time instant at which a business cycle begins and scheduled operational changes become active.
Historical Correction: an explicit amendment to evidence about an earlier cycle, recorded against that cycle; its live calibration effect follows the scheduled activation policy.

Related: #157 (cache correctness must account for scheduled activation and historical corrections), #161 (holiday/event annotations require their own design).

Split out of #113 (2026-09-25). **Design settled by maintainer triage below; original alternatives retained for context.** `daily_reset_time` decides where every business day starts and ends. It is a single current value, so changing it (e.g. 04:00 → 05:00) re-cuts **all** past business days: events near the old boundary move to a different day, and every past daily, weekly and monthly figure can change. #113 deliberately does not record a reset per day: if each day kept its own reset, adjacent days could overlap or leave a gap when the setting changes, and every query that splits time into business days would need to handle that. Options to decide: 1. Keep one reset and document that changing it re-cuts history (current behaviour; #113 documents it). 2. Reset with effective dates: a change applies from a chosen day onward; the transition day is one business day that is longer or shorter than usual. 3. Forbid changing the reset once counted data exists, except via an explicit migration. Resets change rarely; this does not block the statistics deck. 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Maintainer triage — 2026-09-27 Maintainer decision: manual modifications relating to calibration or times apply from the next day onward, preserving prior behavior/history. The user must see both a note explaining delayed activation and a warning/confirmation that the change has been saved and will take effect the next day, explicitly naming that date. Pending settings must survive restart and remain distinguishable from active settings. Expand this issue beyond daily_reset_time to inventory affected manual calibration/time changes and document the agent-facing policy with the implementation. The accepted activation, transition and historical-correction rules below resolve these questions. This triage specifies future implementation; it does not change running settings. ## Accepted design and implementation acceptance The maintainer accepted all recommendations in Q9–Q11. - **Next day:** the following civil date in facility time, at that date's business-cycle reset, not midnight and not merely the next reset encountered. Saving a change before today's reset still targets tomorrow. Display the effective date, clock time and timezone. If saving on 2026-09-27 in facility time, the notice names 2026-09-28; calculate this dynamically rather than hard-coding it. - **Prospective changes:** manually changed calibration/time settings stay pending until that boundary. Inventory every affected write surface (configuration, schedules/exceptions, multipliers, offsets and reset actions) and apply the policy consistently through UI and direct API calls. Keep active and pending values distinguishable and persist pending changes across restarts. Do not silently apply them mid-cycle. - **Historical corrections:** record corrections to historical trust/audit evidence immediately against the original cycle, retaining audit provenance. Their effect on live operational calibration is deferred until tomorrow's boundary. Historical evidence can change through an explicit correction; an ordinary settings change must not re-cut history. Ensure broadcasts and background recalculation cannot accidentally publish a pending operational effect early. - **Reset transition:** effective-dated reset boundaries provide continuous coverage. A cycle is the interval from its boundary to the next boundary. When the reset itself changes, tomorrow's boundary uses the newly scheduled reset; permit one longer or shorter transition cycle, with no overlap or gap. All day/week/month selection, aggregation and calibration queries must use the same effective-dated boundaries. Preserve already closed boundaries. - **User communication:** show a note before saving that explains next-day activation, then a visible warning/confirmation after saving that says the change is saved and names its exact effective date/time/zone. Do not say the new setting is already active. Expose pending activation information in the API response and admin view. Localize the notice in English and Spanish. - **Activation:** apply due changes atomically and once, including recovery after an application restart or outage past the effective instant. Keep a durable audit trail distinguishing submission, historical correction and operational activation. Re-evaluate calibration at activation from the corrected evidence; do not smuggle an immediate recalculation into historical-correction handling. - **Verification:** use real temporary SQLite databases and controlled facility-time clocks. Cover saving before/after today's reset, civil-date rollover, reset moving earlier/later, contiguous transition intervals, historical totals under unchanged boundaries, immediate historical evidence with delayed live calibration, API/UI notices, restart before/after activation, and idempotent activation. Mock external hardware/network calls. Run the full suite and documentation checks. - **Documentation:** update the agent-facing calibration/time policy and relevant domain glossary with implementation. Record the effective-dated boundary and delayed operational activation trade-off in an ADR; reconcile superseded statements in existing schedule/calibration docs. Do not present the requested behavior as already implemented. ### Domain language to capture with implementation - **Pending Calibration/Time Change:** an operator-submitted change awaiting its recorded next-day effective boundary. - **Effective Boundary:** the facility-time instant at which a business cycle begins and scheduled operational changes become active. - **Historical Correction:** an explicit amendment to evidence about an earlier cycle, recorded against that cycle; its live calibration effect follows the scheduled activation policy. Related: #157 (cache correctness must account for scheduled activation and historical corrections), #161 (holiday/event annotations require their own design).

gabogg added the

needs-triage

label

2026-09-25 18:22:55 +00:00

gabogg referenced this issue

2026-09-25 18:22:56 +00:00

feat(schedule): each business day remembers the schedule it was measured under #113

gabogg referenced this issue

2026-09-27 16:29:42 +00:00

feat(statistics): holiday and event context for investor analytics #161

gabogg changed title from ~~schedule: changing daily_reset_time re-cuts every past business day~~ to feat(schedule): activate manual calibration and time changes next day

2026-09-27 16:34:35 +00:00

gabogg added

ready-for-agent

and removed

needs-triage

labels

2026-09-27 16:34:38 +00:00

gabogg referenced this issue

2026-09-27 23:29:46 +00:00

feat(occupancy): curate monthly historical flow drafts #163

gabogg referenced this issue

2026-09-27 23:33:18 +00:00