panchang-ts 3.1.0 → 4.0.0

package/README.md

@@ -42,9 +42,11 @@ sources, and exposed through the public API. Click a row to jump to its usage ex
 | **Vimshottari Dasha** | Maha → Antar → Pratyantar (3-level) breakdown from birth | [↓](#12-vimshottari-dasha) |
 | **Personal Transits** | Chandra Balam, Tarabala (9-tara cycle), Sade Sati (Saturn arc) | [↓](#13-personal-transits) |
 | **Birth Chart (Kundli)** | Lagna (sidereal), Bhava under 3 house systems, D1 / D2 / D3 / D7 / D9 / D10 / D12 / D30 charts, Planetary Dignity | [↓](#14-birth-chart-kundli) |
-| **Compatibility & Doshas** | Ashtakoot Guna Milan (36-point), Mangal Dosha, Kaal Sarp Dosha (12 subtypes), Pitru Dosha | [↓](#15-compatibility--doshas) |
-| **Aspects & Strength** | Drishti (graha aspects), Shadbala (six-fold strength) | [↓](#16-aspects--strength) |
-| **Dasha Systems** | Vimshottari (Maha→Antar→Pratyantar), Ashtottari, Yogini, Chara (Jaimini) | [↓](#17-dasha-systems) |
+| **Compatibility & Doshas** | Ashtakoot Guna Milan (36-point), Pathu Porutham (Tamil 10-fold), Mangal Dosha, Kaal Sarp Dosha (12 subtypes), Pitru Dosha | [↓](#15-compatibility--doshas) |
+| **Aspects & Strength** | Drishti (graha aspects), Shadbala (six-fold strength), Ashtakavarga (Bhinnashtaka + Sarvashtaka), Yogas (25 named), Karakas, Bhava Bala, Argala | [↓](#16-aspects--strength) |
+| **Annual & Sensitive Layers** | Varshaphala (Tajik annual chart + 27 Sahams), Tithi Pravesha, Arudha padas, Hora/Ghati/Bhava/Sripati lagnas, Upagrahas (Gulika, Mandi, Dhuma, Vyatipata, Parivesha, Indrachapa, Upaketu) | [↓](#16-aspects--strength) |
+| **KP & Prashna** | KP sub-lord at any longitude, cuspal sub-lords (Placidus-KP), KP significators, Prashna (horary) chart | [↓](#16-aspects--strength) |
+| **Dasha Systems** | Vimshottari (Maha→Antar→Pratyantar), Ashtottari, Yogini, Chara (Jaimini), Narayan (Jaimini with padi direction) | [↓](#17-dasha-systems) |
 | **Muhurta Engine** | Configurable scoring + 13 stock occasions (vivah, griha pravesh, namakarana, …) | [↓](#18-muhurta-engine) |
 | **Calendar Conversion** | Gregorian↔Hindu, Kali Yuga year, Hindu New Year, yearly Ekadashi / Sankranti / festival listings | [↓](#19-calendar-conversion) |
 | **Localization** | English + Hindi (Devanagari) on every returned name | [↓](#20-localization) |
@@ -225,7 +227,7 @@ Pratah / Sayahna Sandhya, and nakshatra-keyed Amrit Kala.
 const r = getDailyPanchang(date, loc, { timezone: 330 })!;
 
 r.brahmaMuhurta;     // two muhurtas before sunrise
-r.abhijitMuhurta;    // 8th day-muhurta — universally auspicious
+r.abhijitMuhurta;    // 8th day-muhurta, or null on Wednesday (Buddha-vara, Drik convention)
 r.vijayaMuhurta;     // 11th day-muhurta — auspicious for success
 r.godhuliMuhurta;    // "cow-dust" — sunset muhurta
 r.nishitaMuhurta;    // midnight muhurta (Shivaratri)
@@ -530,9 +532,10 @@ ayanamsa positional arg.
 
 ## 15. Compatibility & Doshas
 
-**Ashtakoot Guna Milan** (36-point marriage compatibility), **Mangal Dosha** (Manglik
-with cancellations), **Kaal Sarp Dosha** (12 named subtypes by Rahu's house), and
-**Pitru Dosha** (ancestral affliction triggers).
+**Ashtakoot Guna Milan** (36-point marriage compatibility), **Pathu Porutham**
+(Tamil 10-fold counterpart — see ["Pathu Porutham" in §16](#pathu-porutham-tamil-10-fold-marriage-matching)),
+**Mangal Dosha** (Manglik with cancellations), **Kaal Sarp Dosha** (12 named subtypes
+by Rahu's house), and **Pitru Dosha** (ancestral affliction triggers).
 
 ```typescript
 import {
@@ -600,14 +603,578 @@ const bala = computeShadbala(birth, loc);
 Both functions return additive surface — they do **not** modify the
 `getDailyPanchang` / birth-chart pipelines. Call them on demand.
 
+### Ashtakavarga
+
+**Ashtakavarga** (BPHS Ch. 66) — per-graha 12-rashi bindu grids
+(Bhinnashtaka) and the summed Sarvashtaka grid. Each cell counts how many
+of the 8 contributors (the 7 visible grahas + the lagna) donate a benefic
+dot to that rashi for the given receiver.
+
+```typescript
+import { computeRashiChart, computeAshtakavarga } from 'panchang-ts';
+
+const chart = computeRashiChart(birth, loc);
+const av = computeAshtakavarga(chart);
+
+av.sarvashtaka;
+// → 12-cell grid (Mesha … Meena), each 0..56, total 336.
+
+av.bhinnashtaka.Jupiter;
+// → Jupiter's 12-cell grid; total = 56 (chart-invariant per BPHS).
+//   Other invariant totals: Sun=47, Moon=49, Mars=39, Mercury=54,
+//   Venus=52, Saturn=39.
+
+// Opt in to Trikona + Ekadhipatya Sodhana reductions (BPHS Ch. 67):
+const reduced = computeAshtakavarga(chart, { reductions: true });
+reduced.reduced!.sarvashtaka;          // post-reduction Sarvashtaka
+reduced.reduced!.bhinnashtaka.Jupiter; // post-reduction Bhinnashtaka
+```
+
+The BENEFIC_OFFSETS lookup table is the canonical BPHS Ch. 66 form used by
+every public Ashtakavarga calculator (ProKerala, AstroSage, PyJHora). Rahu
+and Ketu are not Ashtakavarga receivers or contributors in the classical
+Parashara scheme.
+
+### Yogas (named classical combinations)
+
+**Yogas** (BPHS Chs. 36–43) — detect ~25 classical combinations from a
+natal chart against a fixed declarative catalog. Each entry returns a
+`name`, a `type` (one of `mahapurusha | lunar | solar | raja | dhana |
+special | cancellation | negative`), and one-or-more `reasons[]` strings
+describing why the rule matched.
+
+```typescript
+import { computeRashiChart, computeNavamsa, computeYogas } from 'panchang-ts';
+
+const chart = computeRashiChart(birth, loc);
+const yogas = computeYogas(chart);
+// → [{ name: 'Gajakesari', type: 'lunar',
+//      reasons: ['Jupiter in 4th from Moon (kendra)'] }, …]
+
+// Filter by type — restricts evaluation to a subset of the catalog.
+const raja = computeYogas(chart, { types: ['raja', 'dhana'] });
+
+// Vargottama needs the D9 — pass it via options.
+const d9 = computeNavamsa(birth, loc);
+const all = computeYogas(chart, { navamsa: d9 });
+```
+
+The catalog covers Pancha Mahapurusha (Ruchaka / Bhadra / Hamsa / Malavya
+/ Sasha), lunar yogas (Gajakesari, Sunapha, Anapha, Durudhura, Kemadruma),
+solar yogas (Budha-Aditya, Veshi, Vasi, Ubhayachari), Raja yogas (generic
+kendra/trikona-lord rule, Dharma-Karmadhipati, Vipareeta Raja, Lakshmi),
+Dhana yogas (2–11, 5–9, Vasumati), Vargottama, Yogakaraka, Neecha Bhanga,
+and Daridra. Yoga names are English/transliterated proper nouns and are
+intentionally **not** locale-resolved — `'Gajakesari'` reads the same in
+`'en'` and `'hi'`.
+
+Adding a new yoga is a data-only change in
+[src/jyotish/yogasCatalog.ts](src/jyotish/yogasCatalog.ts) — the engine
+is a thin loop over the catalog. Each rule receives the chart plus
+precomputed `dignity` / `aspects` (and optionally a D9 chart) and returns
+a `YogaMatch | null`.
+
+### Jaimini Karakas
+
+**Karakas** (Jaimini *Upadesa Sutras* Ch. 1, Parashara variant) — the 7
+Chara Karakas ranked by descending degree-in-rashi of the visible grahas.
+Atmakaraka (highest) signifies the Self; Darakaraka (lowest) signifies
+spouse.
+
+```typescript
+import { computeRashiChart, computeJaiminiKarakas } from 'panchang-ts';
+
+const chart = computeRashiChart(birth, loc);
+const k = computeJaiminiKarakas(chart);
+k.Atmakaraka;     // graha at the highest degree-in-rashi (e.g. 'Saturn')
+k.Amatyakaraka;   // 2nd-highest
+k.Darakaraka;     // graha at the lowest degree-in-rashi
+```
+
+The 7 visible grahas are ranked — Rahu and Ketu are not included (this is
+the **7-Karaka Parashara variant**, not the reversed-Rahu 8-Karaka Jaimini
+variant). On the rare exact tie in degree-in-rashi, the canonical order
+Sun → Moon → Mars → Mercury → Jupiter → Venus → Saturn breaks the tie
+(stable sort) — the earlier graha wins the more-significant Karaka role.
+
+Karaka names are English/transliterated proper nouns and intentionally
+**not** locale-resolved.
+
+### Bhava Bala
+
+**Bhava Bala** (BPHS Ch. 27) — four-source house strength for the 12 bhavas
+of a natal chart, in Virupas (60 V = 1 Rupa). Built on top of `computeShadbala`
+— the natural-strength table, drishti weights, and benefic/malefic
+classification are all shared.
+
+```typescript
+import { computeBhavaBala } from 'panchang-ts';
+
+const bhavaBala = computeBhavaBala(birth, loc);
+bhavaBala.houses.length;             // 12 (one entry per bhava, index 0 = bhava 1)
+bhavaBala.houses[0].total;           // 1st-bhava total in Virupas
+bhavaBala.houses[9].bhavadhipati;    // 10th-bhava lord's Shadbala total
+// → each entry: { bhavadhipati, dik, drik, sthana, total }
+```
+
+`bhavadhipati` is the total Shadbala of the rashi-lord of the bhava cusp;
+`dik` is a fixed directional value from a simplified cardinal-anchor table
+(cardinal bhavas anchor at 60 / 0 / 15 / 30 V; intermediates linearly
+interpolated around the wheel — not the canonical BPHS Ch. 27 numbers);
+`drik` is the net aspect strength on the cusp from the 7 visible grahas
+(benefics +, malefics −, clamped ≥ 0); `sthana` sums the natural strength
+of grahas occupying the bhava (Mercury counted as benefic per BPHS — the
+"associated benefic" nuance is intentionally out of scope). Rahu and Ketu
+do not contribute. `total` is the arithmetic sum of the four components.
+
+### Varshaphala (Tajik annual horoscope)
+
+**Varshaphala** is the Tajik solar-return chart for a given age of the
+native, with the classical analytical layer — Muntha, year lord
+(Varsha Pati), and the 27 core Sahams — already computed.
+
+```typescript
+import { computeVarshaphala } from 'panchang-ts';
+
+const birth = new Date('1995-08-15T05:30:00Z');
+const loc   = { latitude: 28.6139, longitude: 77.2090 };
+
+const varsha = computeVarshaphala(birth, 30, loc);   // 30th solar return
+varsha.solarReturnInstant;       // exact UTC moment Sun returns to natal lon
+varsha.varshaLagna.rashi.name;   // ascendant rashi at the SR instant
+varsha.muntha.rashi;             // (natalLagnaRashi + 30) mod 12
+varsha.muntha.lord;              // rashi-lord of muntha rashi
+varsha.muntha.house;             // muntha's house from varsha lagna (1..12)
+varsha.yearLord;                 // strongest of 4 candidates by Shadbala
+varsha.isDayBirth;               // Sun above horizon at SR instant?
+
+// 27 Sahams (Punya, Vidya, …, Tapas) — each: { longitude, rashi, rashiName, house }
+varsha.sahams.Punya.longitude;
+varsha.sahams.Punya.house;       // Punya's house from varsha lagna
+varsha.sahams.Vivaha.rashi;      // Vivaha (marriage) Saham rashi
+```
+
+**Solar-return search.** A Newton-style refinement around `birth +
+N × 365.25636 days` finds the UTC instant where sidereal Sun returns
+to its natal longitude (within 0.0001° / ~9 arcseconds). Convergence
+is 3–5 iterations on cooperative inputs.
+
+**Year lord (Varsha Pati).** Picked as the planet with the highest
+total Shadbala among:
+1. Varsha lagna lord
+2. Muntha lord
+3. Lord of the Sun's rashi at the varsha instant
+4. Triraashi Pati (3-rashi-trine ruler) of the varsha lagna's element,
+   per the Tajik day/night table (fire→Sun day / Jupiter night;
+   earth→Venus / Moon; air→Saturn / Mercury; water→Venus / Mars)
+
+**Sahams scope.** This is the **27-Saham core set** — Punya, Vidya,
+Yasas, Mitra, Karma, Vivaha, Putra, Roga, Marana, Rajya, Raja, Bandhu,
+Dharma, Gnati, Apamrityu, Bhratri, Matri, Pitri, Sama, Bandhana,
+Karyasiddhi, Vyapara, Sastra, Asha, Labha, Susha, Tapas. The extended
+50-Saham list (Mahaprasna, Adhana, Krodha, Kali, …) is deferred to a
+later release. Day/night X-Y operand swap follows **Neelakantha**'s
+*Tajika Neelakanthi*; 9 Sahams (Punya, Vidya, Karma, Putra, Roga,
+Gnati, Bhratri, Matri, Pitri) flip on night birth. Other Tajik
+commentators (Hari Hara) define different swap subsets — documented
+in [src/jyotish/sahamsTables.ts](src/jyotish/sahamsTables.ts).
+
+**Sourcing:** Neelakantha *Tajika Neelakanthi* (1587 CE); B.V. Raman
+*Annual Horoscope*; Sanjay Rath *Crux of Vedic Astrology* Tajik
+appendix; PVR Narasimha Rao *Tajik notes* (Saptarishis Astrology).
+Saham names are English/transliterated proper nouns and intentionally
+**not** locale-resolved (same convention as Yoga names).
+
+### Tithi Pravesha (annual soli-lunar return)
+
+**Tithi Pravesha** is the South-Indian annual chart cast at the moment
+in year-N when *both* (a) the sidereal Sun is in its natal sidereal
+sign **and** (b) the Sun-Moon angular separation equals the natal
+separation. The tithi is preserved exactly — `praveshTithi` always
+equals `natalTithi`.
+
+```typescript
+import { computeTithiPravesha } from 'panchang-ts';
+
+const tp = computeTithiPravesha(
+  new Date('1995-08-15T05:30:00Z'),
+  30,                                            // 30th annual cycle
+  { latitude: 28.6139, longitude: 77.2090 },     // New Delhi
+);
+tp.praveshInstant;                  // exact UTC moment
+tp.natalTithi === tp.praveshTithi;  // always true
+tp.varshaLagna.rashi.name;          // ascendant at pravesha
+tp.planets;                         // 9-graha placements
+tp.bhava.houses;                    // 12 cusps under configured house system
+```
+
+**Algorithm.** The implementation follows **PVR Narasimha Rao's
+redefinition** (Saptarishis Astrology) rather than the older calendar-
+anniversary heuristic:
+
+1. Compute the natal Sun-Moon angular separation `Δ_natal`.
+2. Locate the **solar-return instant** for the requested year (re-uses
+   the Varshaphala Newton search).
+3. Newton-iterate on the Moon-Sun phase deviation until
+   `(Moon − Sun) mod 360°` equals `Δ_natal` to better than 0.0001°.
+4. If Sun's rashi at that instant differs from natal Sun's rashi
+   (closest tithi-match landed across a sign boundary), shift by one
+   synodic month (~29.5 days) toward the solar-return centre and
+   re-iterate. Adjacent tithi-matches are 29.53 days apart and the
+   Sun-in-natal-sign window is 30.4 days wide, so exactly one
+   neighbour falls in the natal sign for every fixture.
+
+The pravesha instant can therefore be up to ~30 days before or after
+the calendar anniversary depending on where the natal moon was in the
+synodic cycle.
+
+**Sourcing:** Sanjay Rath, *Tithi Pravesha* (srath.com); PVR Narasimha
+Rao, *Re-Defining Tithi Pravesha Chart* (Saptarishis Astrology Vol. 8).
+
+### Arudha Lagna + 12 Arudha Padas
+
+The **Arudha pada** of a bhava is the rashi reached by counting from the
+bhava's lord the same number of houses as the lord is from the bhava
+itself. Each Arudha is the *image / reflection* of its bhava — Bhava 1's
+Arudha is **Arudha Lagna (AL)**, the social / public-facing self
+(distinct from Lagna, which is the inner / soul-rooted self).
+
+```typescript
+import { computeRashiChart, computeArudhas } from 'panchang-ts';
+
+const chart = computeRashiChart(
+  new Date('1995-08-15T05:30:00Z'),
+  { latitude: 28.6139, longitude: 77.2090 },
+);
+const arudhas = computeArudhas(chart);
+arudhas.length;                   // 12
+arudhas[0]!.bhava;                // 1 — this is Arudha Lagna (AL)
+arudhas[0]!.arudhaRashi;          // 0..11
+arudhas[0]!.arudhaRashiName;      // localized rashi name
+arudhas[0]!.arudhaLord;           // rashi-lord of arudha rashi
+arudhas[6]!.bhava;                // 7 — Darapada (spouse pada)
+```
+
+**Algorithm.** Per Jaimini *Upadesa Sutras* Ch. 1 (Sanjay Rath
+commentary):
+
+1. For each bhava `B`, find the rashi the bhava's lord *occupies*.
+2. Compute `D` = inclusive distance from the bhava to its lord (1..12,
+   so lord-in-own-bhava → D=1).
+3. Standard rule: count another `D` houses from the lord →
+   `arudha = (lordRashi + D − 1) mod 12`.
+4. **Two exceptions** to avoid the Arudha collapsing onto the bhava
+   itself or its 7th:
+   - `D == 1` (lord in own bhava) → Arudha = **10th** from lord
+     (`lordRashi + 9 mod 12`).
+   - `D == 7` (lord in 7th from bhava) → Arudha = **4th** from lord
+     (`lordRashi + 3 mod 12`).
+
+`arudhaLord` is the rashi-lord of the *Arudha rashi itself* (not the
+original bhava's lord) — useful for analysing the pada's significations
+directly.
+
+**Sourcing:** Jaimini, *Upadesa Sutras* Ch. 1; Sanjay Rath, *Jaimini
+Maharishi's Upadesa Sutras* (commentary); BPHS Ch. 29.
+
+### Special Lagnas (Hora / Ghati / Bhava / Sripati)
+
+Time-derived sensitive lagnas used in classical timing analysis. Each
+advances at a different rate from the sunrise on or before the birth
+instant.
+
+```typescript
+import {
+  computeHoraLagna, computeGhatiLagna, computeBhavaLagna, computeSripatiLagna,
+} from 'panchang-ts';
+
+const birth = new Date('1995-08-15T05:30:00Z');
+const loc   = { latitude: 28.6139, longitude: 77.2090 };
+
+const hora    = computeHoraLagna(birth, loc);     // 1 rashi / 1 hour from sunrise
+const ghati   = computeGhatiLagna(birth, loc);    // 1 rashi / 1 ghatika (24 min)
+const bhava   = computeBhavaLagna(birth, loc);    // 1 rashi / 5 ghatikas (2 hours)
+const sripati = computeSripatiLagna(birth, loc);  // Sripati cusp 1 = natal lagna
+hora.rashi.name;       // each returns a `LagnaInfo` with rashi / nakshatra / pada
+```
+
+| Lagna | Rate | Period |
+|-------|------|--------|
+| Hora | 30°/hour (1 rashi / 1 hour) | 12 hours |
+| Ghati | 75°/hour (1 rashi / 24 min) | 4 h 48 min |
+| Bhava | 15°/hour (1 rashi / 2 hours) | 24 hours |
+| Sripati | n/a (= natal lagna) | n/a |
+
+> **Note.** Hora Lagna advances at 30°/hour (1 rashi / hour) per BPHS
+> Ch. 4 and *Phaladeepika* Ch. 1 — twice the rate of Bhava Lagna,
+> which advances at 15°/hour (1 rashi / 5 ghatikas). The two are
+> numerically distinct timing anchors, not interchangeable. Sripati
+> Lagna currently returns the natal ascendant (Sripati cusp-1 by
+> construction); the bhava-midpoint form is a future extension.
+
+**Sourcing:** BPHS Ch. 4; *Phaladeepika* Ch. 1; Sripati, *Sripati Paddhati*.
+
+### Upagrahas (sub-grahas as positions)
+
+The 7 upagrahas are sensitive points used in Vedic and Tajik analysis.
+The library returns each one as a **longitude** + rashi + house — the
+position-form, distinct from Phase-2 Gulika *Kalam* (the time-form).
+
+```typescript
+import { computeUpagrahas } from 'panchang-ts';
+
+const u = computeUpagrahas(
+  new Date('1995-08-15T05:30:00Z'),
+  { latitude: 28.6139, longitude: 77.2090 },
+);
+u.gulika.longitude;     // sidereal degrees
+u.gulika.rashi;         // 0..11
+u.gulika.rashiName;     // localized
+u.gulika.house;         // whole-sign from natal lagna
+u.mandi.longitude;      // Saturn-segment midpoint
+u.dhuma.longitude;      // Sun + 133°20'
+u.upaketu.longitude;    // Sun + ~150° (after the chain)
+```
+
+**Gulika & Mandi.** Day birth: divide sunrise → sunset into 8 equal
+segments; the day-lord rotation Sun → Moon → Mars → Mercury → Jupiter
+→ Venus → Saturn places Saturn at one segment per weekday. Gulika is
+the **rising ascendant at the *start*** of Saturn's segment; Mandi is
+the **rising ascendant at the *midpoint***. Night birth: same procedure
+on the sunset → next-sunrise window, with the rotation starting from
+the planet 5 weekdays from the day-lord (Phaladeepika Ch. 5).
+
+**Sun-derived upagrahas.** Fixed offsets from sidereal Sun:
+
+| Upagraha | Formula |
+|----------|---------|
+| Dhuma | `Sun + 133°20'` |
+| Vyatipata | `360° − Dhuma` |
+| Parivesha | `Vyatipata + 180°` |
+| Indrachapa | `360° − Parivesha` |
+| Upaketu | `Indrachapa + 16°40'` |
+
+`Dhuma + Vyatipata ≡ 360°` and `Parivesha + Indrachapa ≡ 360°` are
+structural invariants that hold for every chart.
+
+**Sourcing:** BPHS Ch. 5; Sanjay Rath, *Brihat Nakshatra* (upagraha
+section); Phaladeepika Ch. 5.
+
+### Argala (Jaimini intervention)
+
+Per-bhava arc-influence rules from Jaimini *Upadesa Sutras* Ch. 1 and
+BPHS Ch. 51. Planets in the 2nd, 4th, or 11th from a bhava form
+**Argala** (intervention / help); planets in the 3rd, 10th, or 12th
+form **Virodhargala** (counter-intervention).
+
+```typescript
+import { computeRashiChart, computeArgala } from 'panchang-ts';
+
+const chart = computeRashiChart(
+  new Date('1995-08-15T05:30:00Z'),
+  { latitude: 28.6139, longitude: 77.2090 },
+);
+const argala = computeArgala(chart);
+argala[0]!.bhava;             // 1
+argala[0]!.argala;            // PlanetPlacement[] in 2nd / 4th / 11th from lagna
+argala[0]!.virodhargala;      // PlanetPlacement[] in 3rd / 10th / 12th from lagna
+```
+
+**Structural invariant.** Each planet contributes to **exactly 6 of
+the 12 bhavas** — 3 Argala + 3 Virodhargala. The 2/4/11 and 3/10/12
+offsets are mutually exclusive, so a planet's house position
+deterministically partitions the bhava wheel into a 6-cell influence
+set.
+
+All 9 grahas (Sun..Saturn + Rahu + Ketu) participate. Benefic / malefic
+distinction is not applied — the caller can filter the returned lists
+by graha if their tradition requires it. The 5th-from-bhava ("primary
+Argala") and 9th ("primary Virodhargala") are not included in this
+simplified BPHS Ch. 51 form.
+
+**Sourcing:** Jaimini, *Upadesa Sutras* Ch. 1; BPHS Ch. 51.
+
+### Pathu Porutham (Tamil 10-fold marriage matching)
+
+Tamil/Kerala marriage compatibility test, scored across **10 koots**.
+Used instead of Ashtakoot in Tamil Nadu, Kerala, and parts of Karnataka.
+Each koot is binary-scored (pass / fail) per the AstroVed / Drik Tamil
+convention; the aggregate score is the count of passing koots in 0..10.
+Three koots (Yoni, Rajju, Vedha) are **strong vetoes** — if any fails,
+`recommended` flips to false regardless of the count.
+
+```typescript
+import { computePathuPorutham } from 'panchang-ts';
+
+const result = computePathuPorutham(
+  { rashi: 4, nakshatra: 9 },   // Boy:  Magha / Leo
+  { rashi: 0, nakshatra: 1 },   // Girl: Bharani / Aries
+);
+result.totalPasses;             // 0..10
+result.recommended;             // boolean (no veto + ≥5 passes)
+result.poruthams[4]!.name;      // 'Yoni' (a veto-level koot)
+result.poruthams[8]!.veto;      // true if Rajju fails
+```
+
+**Koot catalog:**
+
+| Koot           | Tests                                               | Veto |
+|----------------|-----------------------------------------------------|:----:|
+| Dina           | Boy→Girl nakshatra distance mod 9 ∈ {1, 3, 5, 7}    | no   |
+| Gana           | Reuses Phase 29 NAKSHATRA_GANA — Manushya↔Rakshasa fails | no |
+| Mahendra       | Distance ∈ {4, 7, 10, 13, 16, 19, 22, 25}           | no   |
+| Sthree Deergha | Boy→Girl nakshatra distance > 9                     | no   |
+| Yoni           | Reuses Phase 29 NAKSHATRA_YONI / YONI_SCORE         | yes  |
+| Rashi          | Distance not in doshic set ({2,12}, {6,8})          | no   |
+| Rashyathipathi | Rashi-lord friendship (Naisargika Maitri)           | no   |
+| Vasya          | Reuses Phase 29 RASHI_VASHYA / VASHYA_SCORE         | no   |
+| Rajju          | Same Rajju (Pada/Kati/Nabhi/Kantha/Sira) fails      | yes  |
+| Vedha          | Same Vedha pair fails                               | yes  |
+
+Pathu Porutham and Ashtakoot consume the same `NatalMoon` shape
+(`{ rashi, nakshatra }`) — call both side-by-side to surface both
+North-Indian and South-Indian compatibility views.
+
+**Sources.** *Jathaka Tatva* (Tamil); AstroVed.com 10-Porutham reference;
+ProKerala's free Pathu Porutham implementation; drikpanchang.com Tamil
+porutham panel.
+
+### Narayan Dasha (Jaimini sign-dasha with padi direction)
+
+Jaimini sign-based dasha that incorporates the **vishama-pada / sama-pada**
+parity rule per Sanjay Rath's *Narayana Dasa* (Sagar Publications). Cycle
+direction depends on which parity-class the lagna's rashi falls into:
+
+  - **Vishama-pada** lagna in {Aries, Taurus, Gemini, Libra, Scorpio,
+    Sagittarius} → cycle proceeds **forward** (zodiacal).
+  - **Sama-pada** lagna in {Cancer, Leo, Virgo, Capricorn, Aquarius,
+    Pisces} → cycle proceeds **backward** (anti-zodiacal).
+
+```typescript
+import { computeNarayanDasha } from 'panchang-ts';
+
+const narayan = computeNarayanDasha(
+  new Date('1995-08-15T05:30:00Z'),
+  { latitude: 28.6139, longitude: 77.2090 },
+);
+narayan.direction;            // 'forward' | 'backward'
+narayan.startingRashi;        // lagna rashi (0..11)
+narayan.mahaDashas[0]!.rashi; // same as startingRashi
+narayan.mahaDashas[0]!.lord;  // sign-lord of starting rashi
+narayan.mahaDashas[0]!.years; // 7, 8, or 9 per modality
+```
+
+Years per rashi follow the same Movable 9 / Fixed 8 / Dual 7 scheme as
+Chara Dasha. The Mahadasha sequence covers ~96 years (sum of all 12
+rashi durations). Lord assignment is the rashi's natural lord (Mars for
+Aries / Scorpio, Venus for Taurus / Libra, etc.). Antardasha breakdown
+is not exposed — the Mahadasha alone is the dominant Jaimini timing
+layer for Narayan analysis.
+
+**Difference from Chara Dasha** (already shipped): Chara always advances
+forward from lagna; Narayan applies the parity-based direction. For
+vishama-pada lagnas the two systems' Mahadasha sequence is identical.
+
+**Sources.** Sanjay Rath, *Narayana Dasa* (Sagar Publications);
+*Jaimini Upadesa Sutras* Ch. 2.
+
+### KP sub-lord layer
+
+K.S. Krishnamurti's KP-Paddhati uses a 9-fold subdivision of each
+nakshatra (243 sub-divisions across the zodiac), proportional to the
+Vimshottari dasha years of the 9 planets. The sub-lord at any longitude
+is one of the 9 KP planets (Sun..Saturn + Rahu + Ketu).
+
+```typescript
+import {
+  computeKpSubLord, computeKpCuspalSubLords, computeKpSignificators,
+  computeRashiChart,
+} from 'panchang-ts';
+
+// 1. Sub-lord at any sidereal longitude.
+const info = computeKpSubLord(45.5);  // 15°30' Taurus
+info.signLord;   // 'Venus' (rashi lord of Taurus)
+info.starLord;   // 'Moon'  (nakshatra lord of Rohini)
+info.subLord;    // KP sub-lord — depends on degree
+
+// 2. Cuspal sub-lords for the 12 Placidus-KP cusps.
+const cusps = computeKpCuspalSubLords(
+  new Date('1995-08-15T05:30:00Z'),
+  { latitude: 28.6139, longitude: 77.2090 },
+);
+cusps.cusps[0]!.subLord;  // sub-lord of cusp 1 (ascendant)
+cusps.cusps[6]!.subLord;  // sub-lord of cusp 7 (descendant)
+
+// 3. Significators — for each planet, the houses it signifies via the
+// 4-fold KP rule (occupant + star-lord-occupant + owner + star-lord-owner).
+const chart = computeRashiChart(birth, location);
+const sig = computeKpSignificators(chart);
+sig.byPlanet.Sun;   // [houses Sun signifies]
+sig.byHouse[10];    // [planets that signify the 10th house]
+```
+
+`computeKpCuspalSubLords` always uses the Placidus-KP house system —
+the cuspal scheme KP analysis is built on. Whole-sign and equal-house
+cusps fall on rashi boundaries by construction and lose the cuspal-sub-
+lord granularity that drives KP timing analysis.
+
+**Sources.** K.S. Krishnamurti, *Krishnamurti Paddhati* (5 vols);
+KP Astrology online references.
+
+### Prashna foundation (horary chart)
+
+Cast a chart for the precise moment a question is asked, with the
+querent's location as the geographic anchor. Prashna analysis proceeds
+on the resulting chart in the same way as a natal chart — houses,
+planets, dignity, dashas all apply to the question being asked.
+
+```typescript
+import { computePrashnaChart, computeKpCuspalSubLords } from 'panchang-ts';
+
+// Question asked at a specific UTC moment from Mumbai.
+const chart = computePrashnaChart(
+  new Date('2026-05-09T14:30:00Z'),
+  { latitude: 19.0760, longitude: 72.8777 },
+);
+chart.lagna.rashi.name;   // ascendant of the prashna
+chart.bhava.system;       // 'placidus-kp' (KP horary anchor) by default
+chart.planets[1]!.house;  // Moon's house — primary mind significator
+
+// KP cuspal sub-lord analysis on the prashna cusps:
+const cusps = computeKpCuspalSubLords(
+  new Date('2026-05-09T14:30:00Z'),
+  { latitude: 19.0760, longitude: 72.8777 },
+);
+```
+
+The returned shape is identical to a natal `BirthChart`. The dedicated
+function is intent-named so callers' analysis context is explicit at
+the call site, and so future Prashna-specific layers (Ruling Planets,
+horary numbers 1..249, significator-driven event timing) can land
+additively in this module.
+
+**Default house system.** Defaults to `'placidus-kp'` — KP horary's
+standard cuspal scheme. Pass `{ houseSystem: 'whole-sign' }` for
+traditional Vedic Prashna.
+
+**Out of scope** (deferred to a later phase):
+- Ruling Planets (5-fold lord set used to refine timing in KP horary).
+- Horary number mapping (KP 1..249 number → cusp sub-lord table).
+- Significator-driven event timing (dasha-walk against significator sets).
+
+**Sources.** B. Suryanarain Rao, *Prasna Marga*; K.S. Krishnamurti,
+*Horary Astrology* (KP Reader VI); Sanjay Rath, *Horary Astrology*
+(srath.com).
+
 ## 17. Dasha Systems
 
-Four classical dasha systems are exposed:
+Five classical dasha systems are exposed:
 
 ```typescript
 import {
   computeVimshottariDashaFromBirth, computeVimshottariPratyantar,
   computeAshtottariDasha, computeYoginiDasha, computeCharaDasha,
+  computeNarayanDasha,
 } from 'panchang-ts';
 
 const birth = new Date('1995-08-15T05:30:00Z');
@@ -628,18 +1195,26 @@ const yog = computeYoginiDasha(birth, moonLon);
 yog.mahaDashas[0].yogini;   // 'Dhanya' (Magha → nakshatra 10, 10 % 8 = 2)
 yog.mahaDashas[0].lord;     // 'Jupiter' (Dhanya's planet)
 
-// 4. Chara (Jaimini, sign-based, 9-8-7 years per modality)
+// 4. Chara (Jaimini, sign-based, 9-8-7 years per modality, forward only)
 const cha = computeCharaDasha(birth, loc);
 cha.mahaDashas[0].rashi;    // lagna's rashi
 cha.mahaDashas[0].lord;     // sign-lord planet
 cha.mahaDashas[0].years;    // 9 (movable) | 8 (fixed) | 7 (dual)
+
+// 5. Narayan (Jaimini, sign-based, parity-based direction per Sanjay Rath)
+const nar = computeNarayanDasha(birth, loc);
+nar.direction;              // 'forward' (vishama-pada) | 'backward' (sama-pada)
+nar.startingRashi;          // lagna rashi
+nar.mahaDashas[0].rashi;    // == startingRashi
+nar.mahaDashas[1].rashi;    // depends on direction
 ```
 
 **Sourcing:** Vimshottari per Parashara (BPHS Ch. 51); Ashtottari per Satya Acharya;
 Yogini per Sanjay Rath (1999) / Charak; Chara per Jaimini Sutras Ch. 1 (9-8-7 years
-variant). Documented limitations: Chara uses the forward zodiacal direction
-unconditionally (Sundar / Achyutananda variant); the reverse-direction rule for
-even-rashi lagnas is not currently exposed.
+variant); Narayan per Sanjay Rath, *Narayana Dasa* (Sagar Publications) — vishama /
+sama-pada parity rule. Documented limitations: Chara uses the forward zodiacal
+direction unconditionally (Sundar / Achyutananda variant); the parity-based variant
+ships separately as `computeNarayanDasha`.
 
 ## 18. Muhurta Engine
 
@@ -1088,12 +1663,18 @@ getUpcomingSolarEclipse, getUpcomingLunarEclipse, getEclipseDuringDay
 // Jyotish
 computePlanetaryPositions, GRAHA_ABBR
 computeVimshottariDasha, computeVimshottariDashaFromBirth, computeVimshottariPratyantar
-computeAshtottariDasha, computeYoginiDasha, computeCharaDasha
+computeAshtottariDasha, computeYoginiDasha, computeCharaDasha, computeNarayanDasha
 computeChandraBalam, computeTarabala
 computeLagna, computeBhava, computeRashiChart, computeNavamsa, computeDivisionalChart
-computeAspects, computeShadbala
-computeAshtakoot, computeMangalDosha, computeKaalSarp, computePitruDosha
+computeHoraLagna, computeGhatiLagna, computeBhavaLagna, computeSripatiLagna
+computeAspects, computeShadbala, computeBhavaBala, computeAshtakavarga
+computeYogas, computeJaiminiKarakas
+computeVarshaphala, computeTithiPravesha, computeArudhas, computeUpagrahas, computeArgala
+computeAshtakoot, computePathuPorutham
+computeMangalDosha, computeKaalSarp, computePitruDosha
 computeSadeSati, computeDignity
+computeKpSubLord, computeKpCuspalSubLords, computeKpSignificators
+computePrashnaChart
 
 // Muhurta engine
 scoreMuhurta, findAuspiciousDates, STOCK_MUHURTA_RULES