Muhurta Pack `yatra@1` — Specification (V-13)

Status: Draft specification · Task: V-13 · Updated: 2026-10-25 · Implements nothing: V-14 implements this pack in packages/vedic.

A muhurta is an auspicious time window chosen for a purpose. The first muhurta purpose pack selects daytime windows for starting a journey (yatra). It is a pure filter over already-calculated panchang (Vedic almanac) intervals and supplied request facts. It was chosen because nearly all its factors come from panchang (V-08), so it needs no lagna (rising sign) or chart-judgment pack. The research background is in research §3.10 and convention C20.

1. Assumptions pending upstream tasks

Assumed input	Meaning	Reconcile with
Profile `parashari-lahiri@1`	Sidereal Lahiri ayanamsa; Hindu sunrise (C6); sunrise day boundary (C7)	V-01
`PanchangDay`	One V-08 output per local day: `day`, `vara`, `limbs.tithi[]`, `limbs.nakshatra[]` (vara weekday, tithi lunar day, nakshatra lunar mansion)	V-08
`day.sunset`	Required by this pack even though V-08 makes it optional	V-08 / C-05
`MoonSignInterval[]`	Moon sign ingress intervals for the day	V-08 opt-in `moonSigns` (`includeMoonSigns`); P2 met

All instants are UTC epoch milliseconds. Intervals are half-open [start, end).

2. Request

Field	Meaning	Validation
`purpose`	`yatra`	Any other value fails `MUHURTA_PACK_UNKNOWN`
`packVersion`	`1`	Unknown version fails
`direction`	`east`, `south`, `west` or `north`	Required; no default direction
`days`	Consecutive V-08 `PanchangDay` results	1–31 days, ordered, same observer and profile; gaps fail
`minimumMinutes`	Shortest accepted window	Optional; default 48 (one muhurta); 1–720

The window limit of 31 days is checked before any work. The engine obtains the panchang days; the pack does not fetch them.

3. Factors

Each factor is a rule-family row in muhurta.yatra.v1. The tables are draft: they follow the common Parashari/Muhurta-Chintamani usage but must be confirmed against a named primary text, recorded in the bundle manifest, before V-14 freezes fixtures.

3.1 Scope

Id	Rule	Source fact
Y-SCOPE	Candidates lie only in daytime `[sunrise, sunset)`	`day.sunrise`, `day.sunset`

3.2 Exclusions (hard)

Id	Excludes	Definition	Source fact
Y-X1 Rahu kala (named after Rahu)	One eighth of daytime	Segment by vara: Sun 8, Mon 2, Tue 7, Wed 5, Thu 6, Fri 4, Sat 3	`vara`, sunrise, sunset
Y-X2 Yamaganda	One eighth of daytime	Sun 5, Mon 4, Tue 3, Wed 2, Thu 1, Fri 7, Sat 6	`vara`, sunrise, sunset
Y-X3 Gulika kala	One eighth of daytime	Sun 7, Mon 6, Tue 5, Wed 4, Thu 3, Fri 2, Sat 1	`vara`, sunrise, sunset
Y-X4 Rikta tithi	Whole tithi interval	Tithi index 4, 9, 14, 19, 24, 29	`limbs.tithi[]`
Y-X5 Amavasya	Whole tithi interval	Tithi index 30	`limbs.tithi[]`
Y-X6 Disha shoola	Whole day	Vara/direction: Mon, Sat → east; Sun, Fri → west; Tue, Wed → north; Thu → south	`vara`, request `direction`
Y-X7 Panchaka	Moon in Aquarius or Pisces	Moon sidereal sign `aquarius` or `pisces`	`MoonSignInterval[]` (P2)

Segment k of daytime is [sunrise + (k−1)·d/8, sunrise + k·d/8) with d = sunset − sunrise. Every day fraction (segments here, Abhijit in §3.4) is computed in integer milliseconds as sunrise + floor(n·d/m), so adjacent fractions share boundaries exactly.

3.3 Inclusions (required)

Id	Requires	Definition	Source fact
Y-I1 Travel nakshatra	Moon nakshatra in the list	`ashwini`, `mrigashira`, `punarvasu`, `pushya`, `hasta`, `anuradha`, `shravana`, `dhanishta`, `revati`	`limbs.nakshatra[]` (Binder ids)

3.4 Tags (informational)

Id	Tag	Definition
Y-T1 Abhijit	Overlap with the 8th of 15 daytime muhurtas	`[sunrise + 7·d/15, sunrise + 8·d/15)`

Abhijit does not override any exclusion in yatra@1; it is reported on accepted windows that overlap it. A pack that lets Abhijit cancel exclusions is a different version.

4. Precedence and interval rules

Scope first. Candidate time is the union of daytime intervals of the requested days.
Exclusions win. Remove every Y-X interval. No inclusion or tag restores excluded time.
Inclusions intersect. Keep only time inside a Y-I1 nakshatra interval.
Split at every boundary. The remaining time is split at every limb, segment and tag boundary so each piece has one constant set of satisfied rules.
Merge. Adjacent pieces (a.end === b.start) with an identical satisfied rule-id set merge. Pieces whose rule sets differ (for example, different nakshatras or Abhijit overlap) stay separate but contiguous.
Minimum length. A merged window shorter than minimumMinutes is moved to excluded with reason below-minimum-duration. A contiguous run of distinct pieces is measured per piece, not as a run.
Order. Windows and excluded candidates are ordered by start; ties by rule id.

Boundaries are half-open: an exclusion ending at t leaves t itself available. Every excluded piece retains every rule id that excluded it, not just the first.

5. Result

Field	Meaning
`pack`	`{ purpose: 'yatra', version: 1, rulesHash }`
`windows[]`	`{ start, end, satisfied: ruleIds[], tags: ruleIds[] }`
`excluded[]`	`{ start, end, reasons: ruleIds[] }`, covering all removed daytime
`days[]`	Per-day sunrise, sunset and the panchang day reference used

windows and excluded together tile the requested daytime exactly, with no gaps or overlaps. An empty windows[] is a successful result; the excluded list explains why.

6. Failures

Case	Behavior
Unknown purpose/version	`MUHURTA_PACK_UNKNOWN` before any work
More than 31 days, missing day, unordered days	`INVALID_REQUEST` before any work
Missing `direction`	`INVALID_REQUEST`; no default direction
Day without sunset	`FACTOR_UNAVAILABLE` (`Y-SCOPE`); no 12-hour day is assumed
Polar day/night (no sunrise)	Inherited V-08 failure; the pack never runs
`MoonSignInterval[]` absent	`FACTOR_UNAVAILABLE` (`Y-X7`); panchaka is never approximated from nakshatras
Mixed profiles or observers across days	`INVALID_REQUEST`

There is no partial result: every factor is required.

7. Examples

Synthetic day E1: Wednesday (budhavara), sunrise 06:00Z, sunset 18:00Z (d = 12 h, segment 1 h 30 min, muhurta 48 min). Tithi 5 (Panchami) all day. Nakshatra hasta until 14:00Z, then chitra. Moon in Virgo all day. minimumMinutes 48.

Day segments: Yamaganda (2) 07:30–09:00, Gulika (4) 10:30–12:00, Rahu kala (5) 12:00–13:30. Abhijit 11:36–12:24.

Direction	Windows	Excluded
`east`	06:00–07:30 `[Y-I1]`; 09:00–10:30 `[Y-I1]`	07:30–09:00 `[Y-X2]`; 10:30–12:00 `[Y-X3]`; 12:00–13:30 `[Y-X1]`; 13:30–14:00 `[below-minimum-duration]`; 14:00–18:00 `[Y-I1 unmet]`
`north`	none	06:00–18:00 `[Y-X6]` plus the overlapping reasons above

Abhijit (11:36–12:24) lies wholly inside Gulika and Rahu kala, so no accepted window carries Y-T1.

Example E2: same day but tithi 9 (Rikta) from 06:00Z to 10:00Z, then tithi 10. Direction east. 06:00–10:00 is excluded by Y-X4 (with Y-X2 also on 07:30–09:00). The only remaining Hasta time is 10:00–10:30 and 13:30–14:00, both below-minimum-duration. windows[] is empty; success.

Example E3: boundary. Yamaganda ends exactly at 09:00Z and a Y-I1 window starts at 09:00Z. The window starts at 09:00:00.000Z inclusive; 08:59:59.999Z is excluded.

Example E4: 32 requested days fail with INVALID_REQUEST before any rule evaluates.

8. Prerequisites before scheduling V-14

Id	Prerequisite	Owner
P1	V-08 panchang days with required sunset	V-08 (with B-01 → C-05 rise/set)
P2	Moon sign ingress intervals per day (for panchaka)	Met: V-08 `includeMoonSigns`, solved with the limb solver and Binder sign ids
P3	Named primary source for every table in §3, recorded in the bundle	Pack reviewer
P4	`muhurta.yatra.v1` rule-family schema registered	V-17
P5	V-01 profile carrying Hindu sunrise and sunrise day boundary	V-01

No chart-judgment (V-02) or yoga/dosha pack is required by yatra@1.

9. Out of scope

Lagna-based, hora, choghadiya and night-time selection.
Tara bala and chandra bala (need natal Moon; a later pack version).
Interpretation text, remedies and display names.

Muhurta Pack yatra@1 — Specification (V-13)