mirror of
https://github.com/cpvalente/ontime.git
synced 2026-08-31 11:59:10 +00:00
Carlos Valente
68 lines
2.9 KiB
Markdown
68 lines
2.9 KiB
Markdown
# runtimeState time-core migration
|
|
|
|
**Status:** In progress
|
|
|
|
## Goal
|
|
|
|
Make temporal meaning explicit across `runtimeState` and timer calculations. Prevent mixing:
|
|
|
|
- `Instant`: epoch timestamp;
|
|
- `TimeOfDay`: local milliseconds since midnight, range `[0, dayInMs)`;
|
|
- `Duration`: elapsed or remaining milliseconds;
|
|
- `Day`: calendar-day offset.
|
|
|
|
Use `apps/server/src/lib/time-core/timeCore.ts` for conversions and temporal arithmetic. Branded types remain numbers at serialization boundaries.
|
|
|
|
## Current state
|
|
|
|
Completed foundation:
|
|
|
|
- temporal brands in `ontime-types`;
|
|
- `timeCore` helpers for now, conversion, duration arithmetic, midnight crossing, calendar-day distance;
|
|
- partial `runtimeState` adoption of `Instant`, `TimeOfDay`, `Day`, and `timeCore`.
|
|
|
|
Remaining ambiguity:
|
|
|
|
- `TimerState`, `RundownState`, and `Offset` expose temporal fields as `number`/`MaybeNumber`;
|
|
- `timerUtils` accepts/returns raw numbers with different meanings;
|
|
- `runtimeState` retains raw duration fields, manual arithmetic, and `as TimeOfDay`/`as Duration` casts.
|
|
|
|
## Migration rules
|
|
|
|
- Classify each temporal field before changing it. No generic `Time` type.
|
|
- Convert only through `timeCore` or an explicit transport adapter.
|
|
- Keep public/websocket JSON numeric where required; brand at the boundary.
|
|
- Keep type migration separate from behaviour changes.
|
|
- Preserve current midnight, rollover, pause, add-time, roll, and offset behaviour per slice.
|
|
- Add helpers only when they encode a named temporal rule and remove caller casts/arithmetic.
|
|
|
|
## Slices
|
|
|
|
- [x] Add temporal brands and initial `timeCore` helpers/tests.
|
|
- [ ] Inventory temporal fields in `TimerState`, `RundownState`, `Offset`, and private runtime state; assign intended types.
|
|
- [ ] Migrate pure `timerUtils` functions by temporal concept; add focused midnight/rollover tests.
|
|
- [ ] Migrate private `RuntimeState` fields and calculations; remove local casts/manual conversions.
|
|
- [ ] Migrate shared runtime contracts and add numeric transport adapters where compatibility requires them.
|
|
- [ ] Update remaining callers, fixtures, and mocks.
|
|
- [ ] Remove superseded helpers, casts, and ambiguous temporal numbers.
|
|
|
|
Each slice must leave old/new boundaries explicit, compile cleanly, and preserve behaviour.
|
|
|
|
## Required coverage
|
|
|
|
- before, at, and after midnight;
|
|
- overnight and multi-day rundowns;
|
|
- local-day calculation across timezone/DST offset changes;
|
|
- pause/resume, added time, elapsed/remaining duration;
|
|
- roll secondary targets and expected finish;
|
|
- absolute/relative offsets and day offsets.
|
|
|
|
## Complete when
|
|
|
|
- Runtime/timer boundaries use semantic temporal types or documented numeric transport fields.
|
|
- Temporal conversions/arithmetic use `timeCore` or named pure helpers.
|
|
- No unexplained temporal casts or ambiguous numeric fields remain in migrated scope.
|
|
- Focused tests cover the required boundaries.
|
|
|
|
After completion, remove this migration tracker. Keep durable rules in `docs/agent-guides/domain-invariants.md`.
|