# Tara scheduling · discovery for the next guide

This is source discovery, not delivered teaching or a complete assignment. It
follows [Tara sessions](v1-tara-sessions.md) in the active
[V1 program](v1-completion.md). Baseline:
`4d893c29bb7a24f7c1b1dde051ae4d075db0d6ae`; relevant domain files are
byte-identical to primary pin `1ceae52c7896a59ac74a4429d410f3218f0b91c6`.

Read all of `libs/oshun/domain-tara/src/ritual-scheduling.ts` (586 lines),
`ritual-scheduling.test.ts`, `ritual-operations.ts`, `ritual-operations.test.ts`
and the lifecycle integration test. Tests were inspected; the whole owning
Vitest suite was not executed here. Session VM fixtures execute recovery's
actual scheduler call with reminders disabled. Full scheduling edge fixtures
remain to be authored and run with its guide.

## Models and ownership

The contract's RitualSchedulingRules declares cadence, local time, quiet hours,
conflict policy and humane-miss policy. Domain TaraRitualTrigger additionally
declares recurrence, daypart, priority, enabled-by-default, continuity, event,
minimum-hours and preference match. The plan builder does not consume all of
these declarations.

It uses an explicit preference timezone/time, caller-supplied continuity and the
template's first trigger with a daypart, otherwise a moment-derived daypart. It
does not implement the whole cadence, calendar-conflict or trigger-admission
policy. preferredDayparts is unused here. The first-daypart lookup neither
filters enabledByDefault nor ranks priority.

TaraRitualScheduler defaults to a cloning in-memory Map. createPlan builds and
saves. getUpcomingPlans filters subject and time but not cancelled/completed
status. getDueReminders flattens all plans, filters time and sorts, without
filtering reminder status or subject, or marking anything sent. Delivery must
enforce those responsibilities separately.

## Selecting a time

| Supplied continuity                | Candidate before quiet hours                                 |
| ---------------------------------- | ------------------------------------------------------------ |
| resume_window / after_interruption | max(now, lastActivityAt) + 15 minutes                        |
| missed_window / recovery_window    | Today's preferred time if future; otherwise now + 30 minutes |
| recent_completion                  | Tomorrow at preferred time                                   |
| fresh_start / fallback             | Today's preferred time if future; otherwise tomorrow         |

lastCompletedAt does not infer recent_completion here; the caller selects that
state. Default daypart times: pre_dawn 05:30, morning 07:30, midday 12:30,
afternoon 15:30, evening 19:30, night 21:00, late_night 22:30. Moment mapping:
morning_opening→morning; midday_reset→midday; transition_pause→afternoon;
reflection_close/news_decompression→evening; sleep_descent→night.

The zone helper chooses the earlier instant for repeated wall time, and shifts
nonexistent time forward using the prior offset. Its resolution kind is unique,
ambiguity-resolved or gap-shifted; the plan builder retains only `.at`. Run
explicit DST/gap fixtures before teaching numerical examples. The inspected
scheduling test file does not cover these cases.

## Quiet hours and reminders

Quiet hours use their own timezone and the candidate instant's local weekday.
That weekday matters for overnight active-day semantics. Start is inclusive, end
exclusive; equal endpoints create no quiet interval. Inside a quiet window, the
helper shifts to the end on the same date when before that end, otherwise the
next date. Characterize overnight and daytime windows before claiming a general
calendar policy.

Disabled reminders yield an empty array, but the plan still exists. Otherwise,
primary = scheduledAt minus lead minutes, independently shifted by quiet hours.
A single follow-up is added only for missed/recovery state with recovery
reminders enabled, at scheduledAt plus its lead minutes. suppressedByQuietHours
means shifted, not removed. Collapsed times and already-past reminders need
delivery-side handling.

Plan status uses injected now; reminder status uses actual Date.now. Pin both
clocks for deterministic examples. Due queries compare timestamps separately. No
push, OS alarm or receipt is produced by these helpers.

## Reschedule identity

rescheduleTaraRitualPlan rebuilds a plan, then restores the original outer
planId. Nested reminder IDs and their planId references remain derived from the
newly built plan. Characterize that distinction: the existing test checks only
the preserved outer ID.

The new ID contains template ID, Date.now and a random suffix. An existing test
title describes user/schedule/sequence inputs, but its assertions check only the
prefix and two differing examples. Do not teach the test title as key structure
or a uniqueness proof.

## Next authoring action

Begin with an interrupted practice near quiet hours. Separate time selection,
zone resolution, quiet-hour shift, reminder record, storage query and actual
delivery. Use a continuity comparison, clock cases, overnight diagram and
ownership handoffs. Close with missed, disabled, repeated and rescheduled cases.
Execute source fixtures for these findings before assigning scheduling units.
Practice selection, player controls, companions, mentors and the content
workbench remain separate required work.
