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.

The rendered schedule now separates mild-seek ("see some light", roughly 50–250 melanopic EDI) from strong-seek ("bright light", ≥250 melanopic EDI). This keeps the broad low-burden daylight envelope visible without overstating every hour as light therapy.

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

visible_bedtime_dose = bedtime[d] − 0.5 h     # optional sleep-aid dose on
                                              # eastbound pre-flight,
                                              # arrival, and first
                                              # destination nights; skip if
                                              # another melatonin dose is too
                                              # close or sedatives/alcohol
                                              # were declared for the flight

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

# Protocol-day cutoff:
caffeine_cutoff_protocol = bedtime[d] − 9.5 h
                            # Timeshifter-calibrated product/clinical
                            # cutoff; earlier than the previous 8h/6h split

# 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 abs_shift >= 6h
   and selected_leg overlaps destination_night by >= 3h:
    main_sleep_block = destination-night-aligned
    max_duration     = 8h
    buffers          = 30 min after takeoff/climb, 60 min before landing
    dest_night_creep = up to 210 min when leg time allows

elif direction == DELAY:
    late_nap_block = [pre_landing − 4h, pre_landing − 1h]

else:
    no in-flight sleep block

The previous 6 h cap was too conservative in the Timeshifter comparison set. The 8 h cap and destination-night creep remain quarantined product parameters, while the qualitative rule — sleep when the destination says night and avoid early pressure-discharging naps — follows the sleep-pressure and jet-lag literature.

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.

Arrival day is emitted as separate, Timeshifter-style protocol actions instead of one overloaded light cue:

LANDING_ANCHOR
POST_LANDING_LIGHT = [landing + 60 min, landing + 120 min]
STAY_AWAKE_BLOCK   = [landing, bedtime]          # only if >=90 min long
DIM_RUNWAY_BLOCK   = [max(landing, bedtime − 3h), bedtime]
BEDTIME_ANCHOR

The light action is a bounded daylight / bright-indoor dose plus movement. The stay-awake block protects sleep pressure and local-routine entrainment; it is not a light prescription. The dim-runway block keeps evening melanopic EDI low into sleep. If landing is close to bedtime, skip the light and stay-awake blocks and go straight into dim/direct-to-bed guidance.

Wake-anchor light rule. Get strong-seek light immediately on wake, every adaptation day. The app places this window on the right side of the Khalsa PRC for the current phase estimate, so it pulls in the same direction as the protocol rather than counter-shifting. 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:00 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, applied uniformly across advance and delay protocols. 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 == 0:
    skip protocol
    output: "No circadian shift needed — same time zone."

elif magnitude < 3 hours:
    skip protocol
    output: "No full timeshift needed — use local routine plus alertness tactics."

elif trip_length <= 2 nights:
    skip protocol
    output: "Stay on home time — adaptation cost > jet-lag cost for short trips."

elif trip_length == 3 nights AND magnitude < 5 hours:
    emit minimal protocol with marginal-benefit warning

# One-way visible protocol cap:
historical_cap = min(days_to_adapt, 6)
if one_way and magnitude < 5h:
    visible_destination_protocol_days = historical_cap
elif one_way and 5h <= magnitude <= 8h:
    visible_destination_protocol_days = 1
elif one_way and 8h < magnitude <= 11h:
    visible_destination_protocol_days = 2
elif one_way:
    visible_destination_protocol_days = 3

CDC Travelers' Health provides the practical more-than-3-time-zone/hour threshold language. CDC Yellow Book 2026 supports destination-time routines when adapting and home-base schedules for short trips. Roach & Sargent 2019 and Eastman & Burgess 2009 support the cost-benefit short-trip gate.

The one-way visible-protocol cap is a Timeshifter-calibrated product policy, not a replacement for the physiological adaptation estimate. The API preserves meta.expectedAdaptationDays when visible guidance is shorter than the estimated adaptation duration.

Older adults (55+) show wider individual variability in circadian phase response, not a universal PRC amplitude reduction (Kripke 2007). The algorithm compensates with three quarantined heuristics rather than a blanket rate scaling:

ageOver55:
    strong_seek_window     += 30 min   (+30 retina = 60 min cap)
    caffeine_cutoff_dest   += 30 min   (DEST days only; stacks with R13)
    expected_adaptation     = [N, N+2] days  (wider range, not a slower rate)
    meta.phaseEstimateConfidence = 0.8

Rationale: Brown 2022 documents the lens-transmission decline that reduces effective melanopic input from outdoor light in older adults — the strong-seek widening keeps the cumulative melanopic dose roughly invariant. The caffeine widening reflects clinical observation that older adults often need additional daytime alertness support during entrainment. The adaptation range exposes the wider individual variability Kripke 2007 found without slowing the per-day rate.

ENGINEERING QUARANTINE. All three deltas are heuristic (30-min steps, +2 day range) and not literature-derived; Brown 2022 and Kripke 2007 supply qualitative grounding only. PRC amplitude scaling was removed in a prior revision after Kripke 2007's null result on a universal age effect.

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

caffeine_cutoff_protocol_slow = bedtime[d] − 11.5 h