1) Goals

• Users can schedule jobs using their local date/time and time zone, and the job will run at the correct absolute instant even across DST and zone changes.
• This must take into account Daylight Savings time changes in the Spring and Fall
• The current Opti control panel only allows one time zone to be used (UTC). Need the ability to handle more than one.
• User should not have to manually re-schedule jobs two times per year when clocks change
• Admins and integrators can display and manage schedules in any time zone, and any time circumstance.

2) Functional Requirements

2.1 Scheduling (User flows)
• Allow user to pick:
o Local date (YYYY-MM-DD)
o Local time (HH:MM)
o Time zone (IANA with search/autocomplete)
• Display converted times prominently (Local user view, Tenant admin view, and UTC).
• Allow recurring schedules with explicit interpretation rules

3) UI behavior
• When user selects a time zone, display both the local selected time and the equivalent UTC and the viewer’s local time.
• Warn users during DST transition windows (scheduling into the "missing hour" or ambiguous hour) and require confirmation/explicit selection where ambiguity exists.
• Provide a toggle to show times in: “Viewer local”, “Scheduler’s zone (stored)”, and “UTC”.

4) Edge Cases & DST handling
• Ambiguous times (fall-back hour): e.g., in many zones 01:30 occurs twice. Require user to choose “first” or “second” occurrence or explicitly pick UTC offset to disambiguate. Persist which one was chosen.
• Non-existent times (spring-forward): e.g., 02:30 may not exist. Offer to:
o Shift to the next valid instant, or
o Ask user to pick an explicit offset, or
o Reject and request different time — UI should explain.
• Time zone rule changes after schedule creation: If a zone's rules change (government changes DST), previously computed UTC times might shift.
• Options:
o Recompute next occurrences dynamically at runtime using the current tzdb (and record changes), or
o Freeze behavior to the tzdb version at creation (store tzdatabaseversion) and only change after administrative approval. (Prefer dynamic recompute for user expectations, but keep audit trail.)
• Cross-tenant or cross-user views: always display a note when converting times indicating which tz rules were used and show both local and UTC values.

5) Scheduler / Execution design
• Scheduler service runs in UTC. Jobs are queued for the exact scheduledatutc.
• For recurring jobs, a separate recurrence manager:
o When a run completes (or is consumed), compute and persist the next run(s) in UTC.
o Optionally precompute N future runs to reduce runtime computation and to detect DST/ambiguity early.

6) API & Client guidance
• Clients must send the IANA tz id when scheduling. If omitted, reject with an error (no implicit server-local timezone).
• Provide a time zone autocomplete endpoint (GET /api/time zones ?q=Chicago) powered by a canonical list from tzdata.
• Provide helper endpoints for preview:
o POST /api/schedules/preview — returns UTC instant(s), localized displays for multiple viewer zones, and any DST warnings.