The rule book.

Estimate the user's current circadian phase from habitual bedtime, habitual wake, and chronotype.

chronotype ∈ {early, intermediate, late}
DLMO_offset = {early: 2.0 h, intermediate: 2.5 h, late: 3.0 h}[chronotype]

DLMO       = habitual_bedtime − DLMO_offset
DLMO_check = habitual_wake_time + 13.5 h
            # take mean if both available; flag if they disagree by >2 h
CBT_min    = DLMO + 7 h
            # cross-check: should fall ~1.5–2 h before habitual_wake_time

delta = destination_TZ − origin_TZ                # positive = eastward
if abs(delta) > 12: delta = -sign(delta) × (24 − abs(delta))
direction = "advance" if delta > 0 else "delay"
magnitude = abs(delta)                            # in hours

The 12-hour rule encodes that for very large eastward shifts, going around the long way (delay) is faster.

rate_advance = 1.0 h/day      # with full intervention (light + melatonin + sleep)
rate_delay   = 1.5 h/day      # with full intervention

# Without intervention, real-world rates degrade to:
rate_advance_natural = 0.95 h/day   # ~57 min
rate_delay_natural   = 1.5 h/day    # ~92 min

days_to_adapt = ceil(magnitude / rate_for_direction)

Discrete approximation of the dose-response. Updated to use melanopic equivalent daylight illuminance (melanopic EDI) per Brown et al. 2022, the field-standard metric — replaces simple photopic lux. Phillips et al. 2019 establishes that the population-mean ED50 is far lower than Zeitzer 2000 reported and that individual sensitivity varies >50× — both reflected below.

Conversion notes. Photopic lux ≠ melanopic EDI; the multiplier depends on light-source spectrum:

• Incandescent / warm LED (2700 K): melanopic EDI ≈ 0.45 × photopic lux
• Daylight LED (5000 K): melanopic EDI ≈ 0.9 × photopic lux
• Daylight (≥6000 K, blue sky): melanopic EDI ≈ 1.1 × photopic lux

When a user reports light exposure in lux from a phone meter (which measures photopic), apply the conversion before tier classification.

Per Phillips 2019, ED50 ranges from 6 lux (most sensitive) to 350 lux (least sensitive). Three-bucket approximation:

sensitivity ∈ {sensitive, average, resistant}  # default: average

if sensitivity == "sensitive":
    soft_avoid_upper  *= 0.4   # tighter evening dim required
    strong_seek_lower *= 0.5   # smaller dose still effective

elif sensitivity == "resistant":
    soft_avoid_upper  *= 1.5
    strong_seek_lower *= 2.0

Detect sensitivity from: (a) explicit user self-report ("evening light makes me wired" → sensitive; "I can sleep with the TV on" → resistant), or (b) feedback from prior protocols (no shift after 2 days at standard dose → resistant; vivid dreams + insomnia at standard dose → sensitive).

In current implementation, default to "average" if no signal. The form does not yet collect this knob — once it does, the per-tier multipliers above apply.

CBT_min is the pivot point of the Khalsa light PRC. Light before CBT_min delays; light after CBT_min advances.

For delay (westward) protocol:

STRONG_SEEK = [CBT_min − 5h, CBT_min − 2h]   # peak biological evening
MILD_SEEK   = [CBT_min − 8h, CBT_min − 5h]   # late afternoon body-time
SOFT_AVOID  = [CBT_min − 1h, CBT_min + 1h]   # peri-CBT_min
FULL_AVOID  = [CBT_min + 1h, CBT_min + 5h]   # biological early morning

For advance (eastward) protocol:

STRONG_SEEK = [CBT_min + 2h, CBT_min + 5h]   # peak biological early morning
MILD_SEEK   = [CBT_min + 5h, CBT_min + 8h]   # mid-morning body-time
SOFT_AVOID  = [CBT_min − 1h, CBT_min + 1h]   # peri-CBT_min
FULL_AVOID  = [CBT_min − 5h, CBT_min − 1h]   # biological late evening

Each protocol day, after applying the day's shift, slide CBT_min forward (advance) or back (delay) by rate_for_direction hours and recompute the windows.

The windows in R5 come from constant-routine PRCs where the subject is awake 24/7. In a real plan the user is asleep during much of the theoretical STRONG_SEEK window. So:

• Pre-flight delay: brightest practical light from late afternoon to ~30 min before bedtime. Don't prescribe light during the theoretical peak (which is during sleep).
• Pre-flight advance: brightest practical light from wake until ~5 h after wake.
• Post-arrival: light intensity follows the user's actual wake/sleep schedule, not the theoretical PRC windows. See R8.3.

Rule of thumb: prescribe strong-seek on the side of the day farthest from the user's planned sleep — evening for delay, morning for advance — accepting that the theoretical peak may be unreachable.

Default dose: 0.5 mg, immediate-release, sublingual or oral. The 0.5 mg PRC is shifted ~1.5 h later than the 3.0 mg PRC and produces equivalent shifts when timed correctly, without daytime grogginess.

# 0.5 mg PRC
max_advance_dose_time = DLMO − 3.0 h       # ≡ bedtime − 5.5 h ≡ CBT_min − 10.5 h
max_delay_dose_time   = CBT_min + 6.5 h    # ≡ wake_time + 3.5 h

For advance (eastward) protocol:

pre_flight_dose     = bedtime[d] − 5.5 h     # afternoon at origin
return_flight_dose  = takeoff_time + ~1 h    # early in-flight, just before
                                              # the in-flight sleep window
post_arrival_dose   = bedtime[d] − 5.5 h     # tapered over 2–3 nights,
                                              # judgement call by sleep
                                              # quality

For delay (westward) protocol:

in_flight_dose      = NONE                   # the literature is tepid on
                                              # westward melatonin
arrival_night_dose  = bedtime_destination − 0.5 h   # small soporific dose
adaptation_doses    = OPTIONAL, 1–2 nights at bedtime − 0.5 h, drop if
                      sleep is good

half_life      = ~5 h        # median; range 2–10 h
phase_effect   = ~40 min delay per 200 mg dose given 3 h before bedtime
                              # ~half the magnitude of 3 h evening bright
                              # light at 3000 lux

# Cutoff timing differs by direction:
caffeine_cutoff_advance = bedtime[d] − 8 h   # earlier — caffeine would
                                              # phase-delay against the goal
caffeine_cutoff_delay   = bedtime[d] − 6 h   # more permissive — mildly
                                              # aligned with the delay
                                              # direction

# Output as paired blocks per day:
CAFFEINE_OK_block  = [wake_time, caffeine_cutoff]
NO_CAFFEINE_block  = [caffeine_cutoff, bedtime]

Dose guidance accompanying the schedule: "little and often" — 20–50 mg every 1–2 h beats a single 200 mg slug. Total daily intake unchanged; sleep disruption reduced.

Naive rule "drift bedtime 1 h/day in the protocol direction" is wrong when departure-day wake is unusually early (e.g. early feeder flight). Override with sleep-banking on the night before flight:

For each pre-flight day d:
    protocol_bedtime    = bedtime[d−1] + (sign × 1.0 h)
    sleep_bank_bedtime  = depart_day_wake_time − target_sleep_h

    if direction == DELAY:
        bedtime[d] = min(protocol_bedtime, sleep_bank_bedtime)
                     # take the EARLIER — sleep-bank wins if morning forces it
    elif direction == ADVANCE:
        bedtime[d] = max(protocol_bedtime, sleep_bank_bedtime)
                     # take the LATER — sleep-bank wins if departure logistics
                     # require later sleep

Two-out from departure (D−2) is typically protocol-shifted; D−1 is typically sleep-bank-dominated when the flight is early. The flight's own sleep block carries the actual phase shift.

Anti-reversal correction. If D−1's sleep-bank bedtime is opposite the protocol direction, D−2's protocol drift is wasted because D−1 reverses it. In that case soften D−2's drift to 0.5 h (or skip if magnitude is small):

if direction == DELAY and sleep_bank_bedtime[d=−1] < bedtime_baseline:
    bedtime[d=−2] = bedtime_baseline + 0.5h
elif direction == ADVANCE and sleep_bank_bedtime[d=−1] > bedtime_baseline:
    bedtime[d=−2] = bedtime_baseline − 0.5h

For long-haul flights:

if flight_duration > 9h and direction == ADVANCE:
    nap_block        = [takeoff + 1h, takeoff + 3h]      # ~2h short nap
    main_sleep_block = [mid_flight, pre_landing − 1h]    # destination-night-aligned

elif flight_duration > 9h and direction == DELAY:
    # No early nap (would erase homeostatic pressure for destination bedtime).
    late_nap_block   = [pre_landing − 4h, pre_landing − 1h]
    # Main sleep happens at destination.

Anchor the wake time to destination clock — wake time is the dominant entrainment cue. Bedtime is whatever the user can fall asleep at; sleep duration may be short on early adaptation nights.

Wake-anchor light rule. Get strong-seek light immediately on wake, every adaptation day, regardless of where wake falls relative to the still-shifting CBT_min. Rationale:

• The theoretical PRC says morning light during a delay protocol could counter-shift. In practice the alertness benefit + entrainment to destination clock dominates the small advance contribution.
• The strong-seek dose first thing on wake also resets the entrainment phase — wake-time light is the dominant zeitgeber for stable entrainment.
• For delay protocols, the strong-seek dose continues into late afternoon/evening; for advance protocols, it's concentrated in the morning only.

This rule is the practical compromise between pure-PRC theory and adherence: telling the user to "sleep in until 11 AM destination time and avoid morning light for 4 days" produces compliance failures worse than the small theoretical loss from morning light.

A 30–60 min discrete pre-bed event of dim lighting + screens off, regardless of phase-shift direction. Soporific aid for melatonin onset; lower light is sufficient (well below the CBT-min-relative window).

WIND_DOWN_block = [bedtime[d] − 0.5 h, bedtime[d]]

The skill consumes generic signals from whichever data source the user has connected — Garmin, Apple Watch (HealthKit), Oura, Whoop, Withings, manual self-report. Map vendor-specific fields to abstract signals:

# Modulation rules (per Chinoy 2021: relative-to-personal-baseline, never absolute):

if 7d_sleep_score < (personal_30d_sleep_score_avg − 1 SD)
   OR HRV_trend < −10% personal baseline:
    pre_flight_drift_rate *= 0.5     # soften pre-flight to 0.5 h/day
    in_flight_nap_aggressiveness *= 0.7

if RHR_trend > +5 bpm vs personal baseline:
    flag_to_user("RHR elevated — possible illness/recovery debt; consider
                 delaying optional pre-shift component")

if no recent sleep deficit (all signals at or above personal baseline):
    run protocol at full nominal intensity

Do NOT use:

• Absolute sleep-score thresholds (e.g. "<70"). Vendor-specific scales don't translate — a 70 on Oura is not equivalent to a 70 on Garmin. Always express as a delta from the user's own 30-day baseline.
• Sleep-stage data (deep / REM absolute durations). Per Chinoy 2021, consumer-tracker stage accuracy ranges 30–65% epoch-by-epoch — too poor to gate decisions on.

Fallback if no wearable connected:

ask: "How was your sleep last week — good / mixed / poor?"
  good  → full intensity
  mixed → soften by 25%
  poor  → soften by 50%, flag user

if magnitude < 3 hours AND trip_length < 3 nights:
    skip protocol
    output: "Stay on home time — adaptation cost > jet-lag cost for short trips."

PRC amplitude shrinks ~25% in adults >55. Scale rate_for_direction accordingly when computing total days.

If user reports slow caffeine metabolism (CYP1A2 *1F/*1F genotype, hormonal contraceptives, pregnancy, smoking cessation), extend the no-caffeine block:

caffeine_cutoff_advance_slow = bedtime[d] − 10 h
caffeine_cutoff_delay_slow   = bedtime[d] − 8 h