diet-guard/docs/DOCS-meal-schedule.md
Krzysztof kuhy Rudnicki 6dd52a11ae slots: never post the schedule combobox list; kuchnia dedup on raw minute
- The popdown maps beneath the gatelock surface yet holds ttk's grab
  (verified on Xvfb: invisible, swallows the next click, steals keys), so
  arrow clicks are intercepted as Down already was. Typing and Up/Down stay.
- Catering dedup compares the entry's recorded minute (parity with the
  app); occupancy (fill_plan) still snaps.
- Test: a corrupt peer slot (slot 24, slot_min 5000) re-signs and reads
  without raising.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015npsYVB2PdtWkG7MPAi4tn
2026-10-10 20:06:16 +02:00

102 lines
6.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# The meal schedule (`_meal_schedule.py` / `meal_schedule.dart`)
_Split out of `CLAUDE.md` to keep it under the repo's 250-line cap._
Every slot is a **minute of day**, an int in `0..1439`. The user sets a first
meal and a last meal (any `HH:MM`) and how many meals fall between them; the
intermediate checkpoints are derived by even division and rounded to the
15-minute grid. `MealSchedule(480, 1200, 5)` → `08:00, 11:00, 14:00, 17:00,
20:00`; `MealSchedule(435, 1140, 5)` → `07:15, 10:15, 13:15, 16:00, 19:00`.
The default `MealSchedule(480, 1200, 4)` reproduces the hours that used to be
hardcoded, so an existing install sees no change until it is edited.
The fields are `first_minute`/`last_minute` (`firstMinute`/`lastMinute`),
deliberately renamed from the old hour-valued `first`/`last` so the type
checker enumerated every caller still thinking in hours.
## The rules, each load-bearing
- **Integer arithmetic only** — see the `Do NOT` entry in `CLAUDE.md`.
Python's `round` is banker's and Dart's is half-away-from-zero, and
Python's `//` floors where Dart's `~/` truncates, so every division runs on
a value `normalized()` has already pulled into the day. The shared vectors
in `tests/fixtures/meal_schedule_vectors.json` (regenerated by
`scripts/build_meal_schedule_fixture.py`) are asserted by
`test_meal_schedule_vectors.py` *and* `meal_schedule_vectors_test.dart`;
that is what catches a cross-language divergence before it reaches a device.
- **Interior slots round to the 15-minute grid; the endpoints never do.**
With `span = last - first` and `d = count - 1`, interior slot *i* is
`raw = first + (i*span + d//2) // d`, snapped by `(raw + 7) // 15 * 15`.
The first and last meal are exactly what the user typed, even `07:23`.
- **Counts are clamped to the window, in 15-minute steps:**
`count <= min(6, (last - first) // 15 + 1)`, and `last >= first + 15`.
Two checkpoints closer than one grid step would snap onto the same mark,
and slot minutes are set members, dict keys *and* notification ids — a
duplicate silently drops a checkpoint. The two edit surfaces reject such
input with a message; `normalized()` clamps it, which is the defence
against a peer's corrupt sync data rather than the input contract.
- **The enforcement cutoff is `last + 120` minutes, clamped to 1440.** It is a
grace period for a late dinner, deliberately independent of meal count.
Unclamped, a 23:00 last meal gives 1500 and `minute < cutoff` is vacuously
true — the window never closes and the gate can never stop firing.
- **The wire is additive; whole hours are byte-identical to the old format.**
- A log entry always carries `slot = minute // 60` and adds
`slot_min = minute` only when `minute % 60 != 0` (`_slot_wire.slot_fields`
/ `slotFields`). Readers prefer an int `slot_min`, else `slot * 60`
(`entry_slot_minute` / `entrySlotMinute`). A whole-hour entry is exactly
what an old build wrote — no re-signing storm — and an old build reading an
off-hour entry sees the hour it starts in. The writer adds `slot_min`
**before** signing: the HMAC covers the whole entry.
- A schedule history entry (`sched:<date>` on the `budget` record, and the
`.meal_schedule` file) carries `f`/`l` as hours and `n`, plus `fm`/`lm`
minutes only for an off-hour endpoint (`schedule_to_wire` /
`scheduleToWire`). `fm`/`lm` win when present.
- `bool` is never an int, on either side: Python's `bool` subclasses `int`,
Dart's does not, and a value one device accepts while the other ignores
is a split brain.
- **A logged meal satisfies the slot nearest its recorded minute**
(`satisfied_slots` / `satisfiedSlots`; an exact tie goes to the *earlier*
slot). Nothing on disk is rewritten when the schedule changes: meals logged
at 07:00 and 10:00 under `07:00–19:00 × 5` still cover 07:15 and 10:15
after a move to `07:15–19:00 × 5`, so nothing re-opens. Every "is this slot
logged?" site goes through it — the gate (`logged_slots_today`), the CLI
status, MCP, and the catering import's occupancy and dedup
(`_slot_wire.satisfied_by_entries`). Many-to-one is intended: two meals
that snap onto one slot satisfy only that slot.
`_slots.py` / `slot.dart` take the schedule as a **required** argument. A
default there would let a call site missed in a refactor keep deriving the old
fixed slots on one device only, which is the split brain that can lock the
user out; making it required lets mypy and `flutter analyze` enumerate the
sites. Callers resolve it at the impure edge through
`_meal_schedule_store.current_schedule()` / `MealScheduleService.current`.
## History and editing
The history is forward-only (`_meal_schedule_store.py` /
`meal_schedule_history.dart`), so switching from four meals to five does not
retroactively mark past days as having missed a checkpoint. It seeds the
default at `1970-01-01` **before** recording today's value — same ordering
requirement as `_budget_history.py`. It syncs as `sched:<YYYY-MM-DD>` fields
on the existing `budget` CRDT record, so devices predating the feature relay
them untouched.
Editable on both surfaces: the app's Settings screen
(`settings_meal_schedule.dart`) and the gate's History tab
(`_gatelock_scheduleedit.py`, widgets in `_gatelock_calendar_schedule.py`).
The gate's first/last fields are `ttk.Combobox`es offering every quarter hour
and accepting any typed `HH:MM`; Up/Down step 15 minutes. The dropdown list is
**never posted** (arrow clicks and Down are intercepted): a posted popdown maps
*beneath* the lock surface, which gatelock keeps raised, while still holding
ttk's grab — invisible, it swallows the next click and steals keystrokes.
`diet-guard-gate.timer` fires every 15 minutes (`*:00/15:00`), so it lands on
every grid slot exactly; an off-grid first/last meal is caught by the next
tick.
**Notification ids are slot minutes.** The app's `syncToSlots` must sweep the
whole id space — every minute id *and* the legacy `0..23` hour ids an older
build scheduled — not just the current schedule's slots. Otherwise a schedule
change (or the upgrade itself) orphans ids it no longer contains, and they
nag forever.