Add day-of and crock-pot start-by reminders (Feature 20)

Register plan.Service.ReminderSchedules as the day_of_reminder schedule:
daily at the household reminder_time (period YYYY-MM-DD) it emits
day_of_reminder:YYYY-MM-DD, "Tonight: {dinner} · Recipe →" linking
/dinner/{id}; for a crock-pot dinner whose start_by is earlier than
reminder_time it also fires 15 minutes before start_by (period
start:YYYY-MM-DD) and emits day_of_reminder:start:YYYY-MM-DD, "Start the
crock pot by {time}". A date whose week has no plan emits nothing.

The scheduler gains DailyAt rules, whose fire time per date is looked up
from data on every pass (a failed lookup is retried every ClaimRetry),
and a Schedule Key that prefixes period keys so two schedules of one
name claim different periods.

Maestro task 30963b62-2803-4879-82ff-c351cc6628cf.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/scheduler/scheduler.go

@@ -44,6 +44,17 @@
 // occurrence. Either way the period key is that local date's, so the
 // period still runs exactly once.
 //
+// # Fire times from data
+//
+// A DailyAt rule fires at a time read from the household's data rather
+// than the settings: its function gives, for each household-local date,
+// the instant the date's period fires, or none. The period is that date
+// even when the instant falls on another day. The scheduler asks again on
+// every pass, so a change to the data moves the fire time by the next pass,
+// at most maxWait after the change; the claim still runs a period at most
+// once. A lookup that fails is logged and repeated every ClaimRetry, as a
+// failed claim is.
+//
 // # Settings changes
 //
 // The scheduler subscribes to the household settings and records each change
@@ -59,6 +70,7 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"strings"
 	"sync"
 	"time"
 
@@ -102,8 +114,8 @@ const ClaimRetry = time.Minute
 const maxWait = time.Hour
 
 // Rule is when a schedule fires: at household-local Time ("HH:MM") every
-// day, or on Weekday only when Weekly is set. Build one with Daily, Weekly
-// or WeeklyForNextWeek.
+// day, or on Weekday only when Weekly is set, or every day at the instant
+// At gives. Build one with Daily, Weekly, WeeklyForNextWeek or DailyAt.
 type Rule struct {
 	Weekly  bool
 	Weekday time.Weekday
@@ -111,8 +123,15 @@ type Rule struct {
 	// NextWeek keys a weekly period by the ISO week after the fire date,
 	// for work done ahead for the coming week.
 	NextWeek bool
+	// At, instead of Time, gives the instant the period of a
+	// household-local date fires.
+	At FireAt
 }
 
+// FireAt gives the instant the period of household-local date fires, or
+// false when that date's period does not fire.
+type FireAt func(ctx context.Context, date store.LocalDate) (time.Time, bool, error)
+
 // Daily fires every day at hhmm; its period is the local date.
 func Daily(hhmm string) Rule {
 	return Rule{Time: hhmm}
@@ -129,6 +148,12 @@ func WeeklyForNextWeek(day time.Weekday, hhmm string) Rule {
 	return Rule{Weekly: true, Weekday: day, Time: hhmm, NextWeek: true}
 }
 
+// DailyAt fires at most once a day, at the instant at gives for the date;
+// its period is that date, wherever the instant falls.
+func DailyAt(at FireAt) Rule {
+	return Rule{At: at}
+}
+
 // PeriodKey returns the period key of a fire on household-local date
 // fireDate: the date ("2026-10-09") for a daily rule, the ISO week
 // ("2026-W53") for a weekly one, and the ISO week after that ("2027-W01")
@@ -151,6 +176,12 @@ func (r Rule) validate() error {
 	if !r.Weekly && (r.Weekday != time.Sunday || r.NextWeek) {
 		return errors.New("a daily rule has no weekday or next week")
 	}
+	if r.At != nil {
+		if r.Weekly || r.Time != "" {
+			return errors.New("a DailyAt rule has no weekday or time")
+		}
+		return nil
+	}
 	// Any date checks the time's form.
 	_, err := household.LocalTime(time.UTC, store.LocalDateOf(time.Unix(0, 0).UTC()), r.Time)
 	return err
@@ -173,6 +204,10 @@ type Period struct {
 type Schedule struct {
 	// Name is one of the schedule name constants.
 	Name string
+	// Key, when set, prefixes the schedule's period keys with Key and a
+	// colon ("start:2026-10-14"), so two schedules of one Name claim
+	// different periods. Name and Key together are unique.
+	Key string
 	// Rule returns when the schedule fires under settings. It is called
 	// again after every settings change.
 	Rule func(settings household.Settings) Rule
@@ -183,6 +218,14 @@ type Schedule struct {
 	Run func(ctx context.Context, p Period) error
 }
 
+// label names sch in errors and logs: its Name, and its Key if set.
+func (sch Schedule) label() string {
+	if sch.Key == "" {
+		return sch.Name
+	}
+	return sch.Name + ":" + sch.Key
+}
+
 // Settings is the household settings source: *household.SettingsService.
 type Settings interface {
 	Get(ctx context.Context) (household.Settings, error)
@@ -240,19 +283,22 @@ func (s *Scheduler) Register(sch Schedule) error {
 		return fmt.Errorf("scheduler: register: unknown schedule %q", sch.Name)
 	}
 	if sch.Rule == nil {
-		return fmt.Errorf("scheduler: register %s: nil rule", sch.Name)
+		return fmt.Errorf("scheduler: register %s: nil rule", sch.label())
 	}
 	if sch.Run == nil {
-		return fmt.Errorf("scheduler: register %s: nil run", sch.Name)
+		return fmt.Errorf("scheduler: register %s: nil run", sch.label())
+	}
+	if strings.Contains(sch.Key, ":") {
+		return fmt.Errorf("scheduler: register %s: key has a colon", sch.label())
 	}
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if s.started {
-		return fmt.Errorf("scheduler: register %s: already started", sch.Name)
+		return fmt.Errorf("scheduler: register %s: already started", sch.label())
 	}
 	for _, have := range s.schedules {
-		if have.Name == sch.Name {
-			return fmt.Errorf("scheduler: register %s: already registered", sch.Name)
+		if have.Name == sch.Name && have.Key == sch.Key {
+			return fmt.Errorf("scheduler: register %s: already registered", sch.label())
 		}
 	}
 	s.schedules = append(s.schedules, sch)
@@ -346,7 +392,7 @@ func compile(schedules []Schedule, settings household.Settings) (*plan, error) {
 	for i, sch := range schedules {
 		rule := sch.Rule(settings)
 		if err := rule.validate(); err != nil {
-			return nil, fmt.Errorf("scheduler: %s: %w", sch.Name, err)
+			return nil, fmt.Errorf("scheduler: %s: %w", sch.label(), err)
 		}
 		p.items[i] = item{sch: sch, rule: rule}
 	}
@@ -396,7 +442,12 @@ func (s *Scheduler) loop(ctx context.Context, p *plan) {
 		case len(retry) > 0:
 			timeout = s.after(ClaimRetry)
 		case p != nil:
-			if next, ok := p.next(now); ok {
+			next, ok, err := p.next(ctx, now)
+			switch {
+			case err != nil:
+				s.logger.ErrorContext(ctx, "scheduler: look up next fire time failed; retrying", "error", err, "retry_in", ClaimRetry.String())
+				timeout = s.after(ClaimRetry)
+			case ok:
 				timeout = s.after(min(next.Sub(now), maxWait))
 			}
 		}
@@ -423,41 +474,67 @@ func (s *Scheduler) compileChange(ctx context.Context, settings household.Settin
 	return p
 }
 
-// target is one schedule's period, named by the fire time it belongs to.
+// target is one schedule's period, named by the fire time it belongs to
+// and the household-local date of its period. A target whose fire time
+// could not be looked up has lookup set instead, with the stretch
+// (done, until] to look it up in again.
 type target struct {
-	it  item
-	loc *time.Location
-	at  time.Time
+	it   item
+	loc  *time.Location
+	at   time.Time
+	date store.LocalDate
+
+	lookup      bool
+	done, until time.Time
 }
 
 // fire handles, for every schedule, its most recent fire time at or before
 // until if it is after done; now is the current instant. It returns the
-// targets whose claim failed, to be claimed again.
+// targets whose lookup or claim failed, to be handled again.
 func (s *Scheduler) fire(ctx context.Context, p *plan, done, until, now time.Time) []target {
 	var failed []target
 	for _, it := range p.items {
 		if ctx.Err() != nil {
 			return failed
 		}
-		at, due := fireBefore(it.rule, p.loc, until)
-		if !due || !at.After(done) {
-			continue
-		}
-		if t := (target{it: it, loc: p.loc, at: at}); !s.handle(ctx, t, now) {
+		if t, ok := s.fireItem(ctx, it, p.loc, done, until, now); !ok {
 			failed = append(failed, t)
 		}
 	}
 	return failed
 }
 
-// retry handles targets again at now and returns those whose claim still
-// failed.
+// fireItem handles it's most recent fire time at or before until if it is
+// after done. It reports false, with the target to handle again, when the
+// fire time could not be looked up or its period's claim failed.
+func (s *Scheduler) fireItem(ctx context.Context, it item, loc *time.Location, done, until, now time.Time) (target, bool) {
+	f, due, err := fireBefore(ctx, it.rule, loc, until)
+	if err != nil {
+		s.logger.ErrorContext(ctx, "scheduler: look up fire time failed; retrying",
+			"schedule", it.sch.label(), "error", err, "retry_in", ClaimRetry.String())
+		return target{it: it, loc: loc, lookup: true, done: done, until: until}, false
+	}
+	if !due || !f.at.After(done) {
+		return target{}, true
+	}
+	t := target{it: it, loc: loc, at: f.at, date: f.date}
+	return t, s.handle(ctx, t, now)
+}
+
+// retry handles targets again at now and returns those whose lookup or
+// claim still failed.
 func (s *Scheduler) retry(ctx context.Context, targets []target, now time.Time) []target {
 	var failed []target
 	for i, t := range targets {
 		if ctx.Err() != nil {
 			return append(failed, targets[i:]...)
 		}
+		if t.lookup {
+			if again, ok := s.fireItem(ctx, t.it, t.loc, t.done, t.until, now); !ok {
+				failed = append(failed, again)
+			}
+			continue
+		}
 		if !s.handle(ctx, t, now) {
 			failed = append(failed, t)
 		}
@@ -469,9 +546,11 @@ func (s *Scheduler) retry(ctx context.Context, targets []target, now time.Time)
 // its fire time is more than CatchUpWindow before now. It reports false
 // when the claim failed and the period is still unclaimed.
 func (s *Scheduler) handle(ctx context.Context, t target, now time.Time) bool {
-	it, at := t.it, t.at
-	date := household.Today(at, t.loc)
+	it, at, date := t.it, t.at, t.date
 	period := Period{Key: it.rule.PeriodKey(date), FireAt: at, Date: date}
+	if it.sch.Key != "" {
+		period.Key = it.sch.Key + ":" + period.Key
+	}
 	if it.rule.NextWeek {
 		period.Week = household.WeekStart(addDays(date, 7))
 	} else {
@@ -515,16 +594,19 @@ func (s *Scheduler) claim(ctx context.Context, name, key string, now time.Time)
 }
 
 // next returns the earliest fire time of any schedule after now, or false
-// when there is no schedule.
-func (p *plan) next(now time.Time) (time.Time, bool) {
+// when there is none.
+func (p *plan) next(ctx context.Context, now time.Time) (time.Time, bool, error) {
 	var next time.Time
 	for _, it := range p.items {
-		at, ok := fireAfter(it.rule, p.loc, now)
-		if ok && (next.IsZero() || at.Before(next)) {
-			next = at
+		f, ok, err := fireAfter(ctx, it.rule, p.loc, now)
+		if err != nil {
+			return time.Time{}, false, fmt.Errorf("%s: %w", it.sch.label(), err)
+		}
+		if ok && (next.IsZero() || f.at.Before(next)) {
+			next = f.at
 		}
 	}
-	return next, !next.IsZero()
+	return next, !next.IsZero(), nil
 }
 
 // window is how many days either side of a date fireBefore and fireAfter
@@ -532,46 +614,80 @@ func (p *plan) next(now time.Time) (time.Time, bool) {
 // each side.
 const window = 8
 
+// atWindow is how many days either side of a date fireBefore and fireAfter
+// look up a DailyAt rule's fire times. A period firing further off is
+// looked up on a later pass, which comes within maxWait.
+const atWindow = 2
+
+// fireTime is a fire time and the household-local date of its period.
+type fireTime struct {
+	at   time.Time
+	date store.LocalDate
+}
+
 // fireBefore returns the latest fire time of r in zone loc at or before t.
-func fireBefore(r Rule, loc *time.Location, t time.Time) (time.Time, bool) {
-	var best time.Time
-	for _, at := range fireTimes(r, loc, t) {
-		if !at.After(t) && (best.IsZero() || at.After(best)) {
-			best = at
+func fireBefore(ctx context.Context, r Rule, loc *time.Location, t time.Time) (fireTime, bool, error) {
+	fs, err := fireTimes(ctx, r, loc, t)
+	if err != nil {
+		return fireTime{}, false, err
+	}
+	var best fireTime
+	for _, f := range fs {
+		if !f.at.After(t) && (best.at.IsZero() || f.at.After(best.at)) {
+			best = f
 		}
 	}
-	return best, !best.IsZero()
+	return best, !best.at.IsZero(), nil
 }
 
 // fireAfter returns the earliest fire time of r in zone loc after t.
-func fireAfter(r Rule, loc *time.Location, t time.Time) (time.Time, bool) {
-	var best time.Time
-	for _, at := range fireTimes(r, loc, t) {
-		if at.After(t) && (best.IsZero() || at.Before(best)) {
-			best = at
+func fireAfter(ctx context.Context, r Rule, loc *time.Location, t time.Time) (fireTime, bool, error) {
+	fs, err := fireTimes(ctx, r, loc, t)
+	if err != nil {
+		return fireTime{}, false, err
+	}
+	var best fireTime
+	for _, f := range fs {
+		if f.at.After(t) && (best.at.IsZero() || f.at.Before(best.at)) {
+			best = f
 		}
 	}
-	return best, !best.IsZero()
+	return best, !best.at.IsZero(), nil
 }
 
-// fireTimes returns r's fire times on the local dates within window days
-// of t's. A rule that fails to resolve was validated at compile, so it
-// cannot.
-func fireTimes(r Rule, loc *time.Location, t time.Time) []time.Time {
+// fireTimes returns r's fire times for the local dates within window days
+// of t's, or atWindow days for a DailyAt rule. A Time that fails to
+// resolve was validated at compile, so it cannot; a DailyAt lookup that
+// fails is an error.
+func fireTimes(ctx context.Context, r Rule, loc *time.Location, t time.Time) ([]fireTime, error) {
 	today := household.Today(t, loc)
-	var out []time.Time
-	for i := -window; i <= window; i++ {
+	span := window
+	if r.At != nil {
+		span = atWindow
+	}
+	var out []fireTime
+	for i := -span; i <= span; i++ {
 		d := addDays(today, i)
 		if r.Weekly && weekday(d) != r.Weekday {
 			continue
 		}
+		if r.At != nil {
+			at, ok, err := r.At(ctx, d)
+			if err != nil {
+				return nil, fmt.Errorf("fire time of %s: %w", d, err)
+			}
+			if ok {
+				out = append(out, fireTime{at: at, date: d})
+			}
+			continue
+		}
 		at, err := household.LocalTime(loc, d, r.Time)
 		if err != nil {
 			panic(fmt.Sprintf("scheduler: validated rule %+v: %v", r, err))
 		}
-		out = append(out, at)
+		out = append(out, fireTime{at: at, date: d})
 	}
-	return out
+	return out, nil
 }
 
 // addDays returns d plus n calendar days.