Eve library

Tara scheduling · discovery for the next guide

Guide

Revision 1

On this page

This is source discovery, not delivered teaching or a complete assignment. It follows Tara sessions in the active V1 program. 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.