caelus 0.19.0 → 0.20.0

package/dist/src/index.d.ts

@@ -29,7 +29,9 @@ export * from "./rajayoga.js";
 export * from "./patterns.js";
 export * from "./signature.js";
 export * from "./interpretation.js";
+export * from "./interpretation-enrich.js";
 export * from "./interpret.js";
+export * from "./relational.js";
 export * from "./brief.js";
 export * from "./provenance.js";
 export * from "./anchored.js";

package/dist/src/index.js

@@ -29,7 +29,9 @@ export * from "./rajayoga.js";
 export * from "./patterns.js";
 export * from "./signature.js";
 export * from "./interpretation.js";
+export * from "./interpretation-enrich.js";
 export * from "./interpret.js";
+export * from "./relational.js";
 export * from "./brief.js";
 export * from "./provenance.js";
 export * from "./anchored.js";

package/dist/src/interpret.d.ts

@@ -74,6 +74,58 @@ export declare function hasLot(filter?: {
     sign?: string;
     house?: number;
 }): Selector;
+/** Matches transit-to-natal aspect atoms. */
+export declare function hasTransit(filter?: {
+    transit?: string;
+    natal?: string;
+    aspect?: string;
+    phase?: string;
+    minStrength?: number;
+}): Selector;
+/** Matches synastry aspect or house-overlay atoms. */
+export declare function hasSynastry(filter?: {
+    mode?: "aspect" | "overlay";
+    a?: string;
+    b?: string;
+    aspect?: string;
+    body?: string;
+    partner?: "a" | "b";
+    house?: number;
+}): Selector;
+/** Matches a composite midpoint placement. */
+export declare function hasComposite(filter?: {
+    body?: string;
+    sign?: string;
+}): Selector;
+/** Matches an active time-lord period. */
+export declare function hasTimelord(filter?: {
+    system?: "profection" | "zr" | "firdaria" | "dasha";
+    level?: string;
+    lord?: string;
+}): Selector;
+/** Matches finer essential-dignity facts (term, face, triplicity, almuten). */
+export declare function hasDignityFine(filter?: {
+    facet?: "term" | "face" | "triplicity" | "almuten";
+    body?: string;
+    ruler?: string;
+}): Selector;
+/** Matches a nakshatra placement. */
+export declare function hasNakshatra(filter?: {
+    body?: string;
+    name?: string;
+    lord?: string;
+}): Selector;
+/** Matches a varga (divisional chart) placement. */
+export declare function hasVarga(filter?: {
+    division?: number;
+    body?: string;
+    sign?: string;
+}): Selector;
+/** Matches a classical yoga. */
+export declare function hasYoga(filter?: {
+    yoga?: string;
+    body?: string;
+}): Selector;
 /** Matches only when every selector matches; returns the union of their atoms. */
 export declare function matchAll(...sels: Selector[]): Selector;
 /** Matches when any selector matches; returns the atoms from those that did. */

package/dist/src/interpret.js

@@ -74,6 +74,86 @@ export function hasLot(filter = {}) {
         && (filter.sign === undefined || a.sign === filter.sign)
         && (filter.house === undefined || a.house === filter.house)));
 }
+/** Matches transit-to-natal aspect atoms. */
+export function hasTransit(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => {
+        if (a.kind !== "transit")
+            return false;
+        if (filter.transit !== undefined && a.transit !== filter.transit)
+            return false;
+        if (filter.natal !== undefined && a.natal !== filter.natal)
+            return false;
+        if (filter.aspect !== undefined && a.aspect !== filter.aspect)
+            return false;
+        if (filter.phase !== undefined && a.phase !== filter.phase)
+            return false;
+        if (filter.minStrength !== undefined && a.strength < filter.minStrength)
+            return false;
+        return true;
+    }));
+}
+/** Matches synastry aspect or house-overlay atoms. */
+export function hasSynastry(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => {
+        if (a.kind !== "synastry")
+            return false;
+        if (filter.mode !== undefined && a.mode !== filter.mode)
+            return false;
+        if (filter.a !== undefined && a.a !== filter.a)
+            return false;
+        if (filter.b !== undefined && a.b !== filter.b)
+            return false;
+        if (filter.aspect !== undefined && a.aspect !== filter.aspect)
+            return false;
+        if (filter.body !== undefined && a.body !== filter.body)
+            return false;
+        if (filter.partner !== undefined && a.partner !== filter.partner)
+            return false;
+        if (filter.house !== undefined && a.house !== filter.house)
+            return false;
+        return true;
+    }));
+}
+/** Matches a composite midpoint placement. */
+export function hasComposite(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => a.kind === "composite"
+        && (filter.body === undefined || a.body === filter.body)
+        && (filter.sign === undefined || a.sign === filter.sign)));
+}
+/** Matches an active time-lord period. */
+export function hasTimelord(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => a.kind === "timelord"
+        && (filter.system === undefined || a.system === filter.system)
+        && (filter.level === undefined || a.level === filter.level)
+        && (filter.lord === undefined || a.lord === filter.lord)));
+}
+/** Matches finer essential-dignity facts (term, face, triplicity, almuten). */
+export function hasDignityFine(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => a.kind === "dignity"
+        && (filter.facet === undefined || a.facet === filter.facet)
+        && (filter.body === undefined || a.body === filter.body)
+        && (filter.ruler === undefined || a.ruler === filter.ruler)));
+}
+/** Matches a nakshatra placement. */
+export function hasNakshatra(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => a.kind === "nakshatra"
+        && (filter.body === undefined || a.body === filter.body)
+        && (filter.name === undefined || a.name === filter.name)
+        && (filter.lord === undefined || a.lord === filter.lord)));
+}
+/** Matches a varga (divisional chart) placement. */
+export function hasVarga(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => a.kind === "varga"
+        && (filter.division === undefined || a.division === filter.division)
+        && (filter.body === undefined || a.body === filter.body)
+        && (filter.sign === undefined || a.sign === filter.sign)));
+}
+/** Matches a classical yoga. */
+export function hasYoga(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => a.kind === "yoga"
+        && (filter.yoga === undefined || a.yoga === filter.yoga)
+        && (filter.body === undefined || a.bodies.includes(filter.body))));
+}
 // ----------------------------------------------------------------- combinators
 /** Matches only when every selector matches; returns the union of their atoms. */
 export function matchAll(...sels) {

package/dist/src/interpretation-enrich.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Enrich an {@link interpretationContext} with diachronic and Vedic facts at a
+ * target instant — transits, time-lords, nakshatras, vargas, yogas.
+ */
+import { type Chart, type Engine, type Zodiac } from "./chart.js";
+import type { ContextOptions } from "./interpretation.js";
+export interface EnrichTarget {
+    jd: number;
+    lat: number;
+    lonEast: number;
+    zodiac?: Zodiac;
+}
+export interface EnrichFlags {
+    /** Project transit-to-natal aspects. Default true. */
+    transits?: boolean;
+    /** Project profection, ZR, firdaria, dasha. Default true. */
+    timelords?: boolean;
+    /** Project nakshatras, D9, yogas. Default true when chart zodiac is sidereal. */
+    vedic?: boolean;
+    /** Max orb for transit aspects. Default 3. */
+    transitOrb?: number;
+}
+/**
+ * Build {@link ContextOptions} extras for a natal chart evaluated at `target`.
+ * Merge the result into `interpretationContext(chart, { ...base, ...extras })`.
+ */
+export declare function enrichContextOptions(engine: Engine, chart: Chart, target: EnrichTarget, flags?: EnrichFlags): Pick<ContextOptions, "transits" | "timelords" | "vedic">;
+/** Synastry and composite atoms for two natal charts (A is the projection base). */
+export declare function enrichSynastryOptions(engine: Engine, chartA: Chart, chartB: Chart, opts?: {
+    orb?: number;
+    zodiac?: Zodiac;
+}): Pick<ContextOptions, "synastry" | "composite">;

package/dist/src/interpretation-enrich.js

@@ -0,0 +1,63 @@
+/**
+ * Enrich an {@link interpretationContext} with diachronic and Vedic facts at a
+ * target instant — transits, time-lords, nakshatras, vargas, yogas.
+ */
+import { BODIES } from "./chart.js";
+import { firdariaAt } from "./firdaria.js";
+import { profectionAt } from "./profections.js";
+import { zrAt } from "./releasing.js";
+import { compositePlacements, synastryAspects, synastryOverlays, transitAspects, } from "./relational.js";
+import { vimshottariAt } from "./vedic.js";
+import { yogasAt } from "./yogas.js";
+/**
+ * Build {@link ContextOptions} extras for a natal chart evaluated at `target`.
+ * Merge the result into `interpretationContext(chart, { ...base, ...extras })`.
+ */
+export function enrichContextOptions(engine, chart, target, flags = {}) {
+    const zodiac = target.zodiac ?? chart.zodiac;
+    const { lat, lonEast } = target;
+    const out = {};
+    if (flags.transits !== false) {
+        out.transits = transitAspects(chart, engine, target.jd, {
+            maxOrb: flags.transitOrb ?? 3, zodiac,
+        });
+    }
+    if (flags.timelords !== false) {
+        const prof = profectionAt(engine, chart.jdUt, target.jd, lat, lonEast, zodiac);
+        const zr = zrAt(engine, chart.jdUt, target.jd, lat, lonEast);
+        const fir = firdariaAt(engine, chart.jdUt, target.jd, lat, lonEast);
+        const dasha = vimshottariAt(engine, chart.jdUt, target.jd, "sidereal:lahiri");
+        out.timelords = {
+            profection: prof,
+            zr: {
+                l1: zr.l1, l2: zr.l2, l3: zr.l3, l4: zr.l4, lot: zr.lot,
+            },
+            firdaria: { major: fir.major, sub: fir.sub, day: fir.day },
+            dasha: {
+                maha: dasha.maha, antar: dasha.antar ?? null,
+                pratyantar: dasha.pratyantar ?? null, moon_nakshatra: dasha.moon_nakshatra,
+            },
+        };
+    }
+    const wantVedic = flags.vedic ?? zodiac.startsWith("sidereal");
+    if (wantVedic) {
+        out.vedic = {
+            nakshatraBodies: ["moon", "sun", "mars", "mercury", "jupiter", "venus", "saturn"],
+            vargas: [9],
+            yogas: yogasAt(engine, chart.jdUt, lat, lonEast, "sidereal:lahiri"),
+        };
+    }
+    return out;
+}
+/** Synastry and composite atoms for two natal charts (A is the projection base). */
+export function enrichSynastryOptions(engine, chartA, chartB, opts = {}) {
+    const orb = opts.orb ?? 4;
+    const zodiac = opts.zodiac ?? chartA.zodiac;
+    return {
+        synastry: {
+            aspects: synastryAspects(chartA, chartB, orb),
+            overlays: synastryOverlays(chartA, chartB),
+        },
+        composite: compositePlacements(engine, chartA.jdUt, chartB.jdUt, BODIES, zodiac),
+    };
+}

package/dist/src/interpretation.d.ts

@@ -3,8 +3,10 @@ import type { AspectPhase } from "./electional.js";
 import { ChartPattern } from "./patterns.js";
 import { ChartSignature } from "./signature.js";
 import type { Realm, Certainty } from "./provenance.js";
+import type { Profection } from "./profections.js";
+import type { CompositePlacement, SynastryAspectHit, SynastryOverlays, TransitHit } from "./relational.js";
 /** Atom kinds in an {@link InterpretationContext}. */
-export type FactKind = "placement" | "aspect" | "pattern" | "signature" | "angle" | "dispositor" | "reception" | "star" | "lot";
+export type FactKind = "placement" | "aspect" | "pattern" | "signature" | "angle" | "dispositor" | "reception" | "star" | "lot" | "transit" | "synastry" | "composite" | "timelord" | "dignity" | "nakshatra" | "varga" | "yoga";
 interface FactAtomBase {
     /** Stable, content-addressable id, e.g. `"placement:mars"` or
      *  `"aspect:mars~saturn:square"`. Interpretations cite this. */
@@ -89,7 +91,66 @@ export interface LotAtom extends FactAtomBase {
     signDeg: number;
     house: number;
 }
-export type FactAtom = PlacementAtom | AspectAtom | PatternAtom | SignatureAtom | AngleAtom | DispositorAtom | ReceptionAtom | StarAtom | LotAtom;
+export interface TransitAtom extends FactAtomBase {
+    kind: "transit";
+    transit: string;
+    natal: string;
+    aspect: string;
+    orb: number;
+    phase: AspectPhase;
+    strength: number;
+    natalHouse: number;
+}
+export interface SynastryAtom extends FactAtomBase {
+    kind: "synastry";
+    mode: "aspect" | "overlay";
+    a?: string;
+    b?: string;
+    aspect?: string;
+    orb?: number;
+    strength?: number;
+    body?: string;
+    partner?: "a" | "b";
+    house?: number;
+}
+export interface CompositeAtom extends FactAtomBase {
+    kind: "composite";
+    body: string;
+    sign: string;
+    signDeg: number;
+}
+export interface TimelordAtom extends FactAtomBase {
+    kind: "timelord";
+    system: "profection" | "zr" | "firdaria" | "dasha";
+    level: string;
+    lord: string;
+    sign?: string;
+}
+export interface DignityAtom extends FactAtomBase {
+    kind: "dignity";
+    facet: "term" | "face" | "triplicity" | "almuten";
+    body: string;
+    ruler?: string;
+}
+export interface NakshatraAtom extends FactAtomBase {
+    kind: "nakshatra";
+    body: string;
+    name: string;
+    pada: number;
+    lord: string;
+}
+export interface VargaAtom extends FactAtomBase {
+    kind: "varga";
+    division: number;
+    body: string;
+    sign: string;
+}
+export interface YogaAtom extends FactAtomBase {
+    kind: "yoga";
+    yoga: string;
+    planets: string[];
+}
+export type FactAtom = PlacementAtom | AspectAtom | PatternAtom | SignatureAtom | AngleAtom | DispositorAtom | ReceptionAtom | StarAtom | LotAtom | TransitAtom | SynastryAtom | CompositeAtom | TimelordAtom | DignityAtom | NakshatraAtom | VargaAtom | YogaAtom;
 /** A chart as a flat, ranked list of {@link FactAtom}s. */
 export interface InterpretationContext {
     jdUt: number;
@@ -129,6 +190,18 @@ export interface SalienceWeights {
     star: number;
     /** Added to a Hermetic lot (the Part of Fortune and its companions). */
     lot: number;
+    /** Added to a transit-to-natal aspect. */
+    transit: number;
+    /** Added to a synastry aspect or house overlay. */
+    synastry: number;
+    /** Added to a composite midpoint placement. */
+    composite: number;
+    /** Added to an active time-lord period. */
+    timelord: number;
+    /** Added to a finer essential-dignity fact. */
+    dignityFine: number;
+    /** Added to a nakshatra / varga / yoga fact. */
+    vedic: number;
 }
 export declare const DEFAULT_SALIENCE: SalienceWeights;
 export interface ContextOptions {
@@ -159,6 +232,48 @@ export interface ContextOptions {
         signDeg: number;
         house: number;
     }[];
+    /** Transit-to-natal hits, e.g. from {@link transitAspects}. */
+    transits?: TransitHit[];
+    /** Synastry aspects and/or house overlays between two charts. */
+    synastry?: {
+        aspects?: SynastryAspectHit[];
+        overlays?: SynastryOverlays;
+    };
+    /** Composite midpoint placements, e.g. from {@link compositePlacements}. */
+    composite?: CompositePlacement[];
+    /** Active time-lord periods at a target instant (caller-supplied). */
+    timelords?: {
+        profection?: Profection;
+        zr?: {
+            l1: string;
+            l2: string;
+            l3: string;
+            l4: string;
+            lot?: string;
+        };
+        firdaria?: {
+            major: string | null;
+            sub: string | null;
+            day?: boolean;
+        };
+        dasha?: {
+            maha: string;
+            antar?: string | null;
+            pratyantar?: string | null;
+            moon_nakshatra?: string;
+        };
+    };
+    /** Vedic structure facts (caller-supplied or auto from sidereal chart). */
+    vedic?: {
+        /** Project nakshatras for these bodies from the chart longitudes. */
+        nakshatraBodies?: string[];
+        /** Project varga D-n for these bodies (default `[9]` when set true). */
+        vargas?: number[] | true;
+        yogas?: {
+            yoga: string;
+            planets: string[];
+        }[];
+    };
 }
 /**
  * Project a {@link Chart} into a ranked list of {@link FactAtom}s -- the

package/dist/src/interpretation.js

@@ -23,7 +23,9 @@ import { mod } from "./core.js";
 import { SIGNS, DOMICILE, EXALTATION } from "./chart.js";
 import { detectPatterns } from "./patterns.js";
 import { chartSignature } from "./signature.js";
-import { TRIPLICITY } from "./dignity-score.js";
+import { TRIPLICITY, dignityScore, almuten } from "./dignity-score.js";
+import { nakshatra } from "./vedic.js";
+import { varga } from "./vargas.js";
 const LUMINARIES = new Set(["sun", "moon"]);
 const ANGULAR_HOUSES = new Set([1, 4, 7, 10]);
 const HARD_ASPECTS = new Set(["conjunction", "square", "opposition"]);
@@ -53,7 +55,8 @@ const DIGNITY_RANK = { domicile: 3, exaltation: 2, triplicity: 1 };
 export const DEFAULT_SALIENCE = {
     base: 1, luminary: 1.5, angular: 1, chartRuler: 1,
     dignity: 0.5, hardAspect: 1, pattern: 4, dispositor: 0.5, reception: 2,
-    star: 2, lot: 2,
+    star: 2, lot: 2, transit: 1.5, synastry: 1, composite: 0.8, timelord: 2,
+    dignityFine: 0.4, vedic: 1,
 };
 /** How much to keep of a time-sensitive atom's salience at each certainty -- the
  *  Moon and the angles move fastest, so an uncertain instant trusts them least. */
@@ -254,6 +257,218 @@ export function interpretationContext(chart, opts = {}) {
             text: `Lot of ${title(l.lot)} in ${l.sign}, house ${l.house}`,
         });
     }
+    // Finer essential dignities: term, face, triplicity held, almuten of each degree.
+    const chartSect = sunHouse !== undefined && sunHouse >= 7 ? "day" : "night";
+    for (const body of CLASSICAL) {
+        const p = chart.bodies[body];
+        if (!p)
+            continue;
+        const ds = dignityScore(body, p.lon, chartSect);
+        const alm = almuten(p.lon, chartSect);
+        let sal = w.base + w.dignityFine;
+        if (LUMINARIES.has(body))
+            sal += w.luminary;
+        atoms.push({
+            id: `term:${body}:${ds.term_ruler}`, kind: "dignity", bodies: [body], salience: sal,
+            facet: "term", body, ruler: ds.term_ruler,
+            text: `${title(body)} in the term of ${title(ds.term_ruler)}`
+                + (ds.term > 0 ? " (holds term dignity)" : ""),
+        });
+        atoms.push({
+            id: `face:${body}:${ds.face_ruler}`, kind: "dignity", bodies: [body], salience: sal,
+            facet: "face", body, ruler: ds.face_ruler,
+            text: `${title(body)} in the face of ${title(ds.face_ruler)}`
+                + (ds.face > 0 ? " (holds face dignity)" : ""),
+        });
+        if (ds.triplicity > 0) {
+            atoms.push({
+                id: `triplicity:${body}`, kind: "dignity", bodies: [body],
+                salience: sal + w.dignity, facet: "triplicity", body,
+                text: `${title(body)} holds ${chartSect} triplicity`,
+            });
+        }
+        atoms.push({
+            id: `almuten:${body}:${alm.planet}`, kind: "dignity", bodies: [body],
+            salience: sal + (alm.planet === body ? w.dignity : 0),
+            facet: "almuten", body, ruler: alm.planet,
+            text: `${title(alm.planet)} is almuten of ${title(body)}'s degree`,
+        });
+    }
+    // Transit-to-natal aspects (caller-supplied).
+    for (const t of opts.transits ?? []) {
+        let salience = w.base + w.transit + t.strength;
+        if (HARD_ASPECTS.has(t.aspect))
+            salience += w.hardAspect;
+        if (LUMINARIES.has(t.transit) || LUMINARIES.has(t.natal))
+            salience += w.luminary;
+        atoms.push({
+            id: `transit:${t.transit}~natal_${t.natal}:${t.aspect}`, kind: "transit",
+            bodies: [t.transit, t.natal], salience,
+            transit: t.transit, natal: t.natal, aspect: t.aspect, orb: t.orb,
+            phase: t.phase, strength: t.strength, natalHouse: t.natalHouse,
+            text: `Transiting ${title(t.transit)} ${t.aspect} natal ${title(t.natal)} `
+                + `(${t.phase}, orb ${t.orb.toFixed(1)}°, natal house ${t.natalHouse})`,
+        });
+    }
+    // Synastry: inter-chart aspects and house overlays.
+    for (const s of opts.synastry?.aspects ?? []) {
+        let salience = w.base + w.synastry + s.strength;
+        if (HARD_ASPECTS.has(s.aspect))
+            salience += w.hardAspect;
+        if (LUMINARIES.has(s.a) || LUMINARIES.has(s.b))
+            salience += w.luminary;
+        atoms.push({
+            id: `synastry:${s.a}~b_${s.b}:${s.aspect}`, kind: "synastry",
+            bodies: [s.a, s.b], salience, mode: "aspect",
+            a: s.a, b: s.b, aspect: s.aspect, orb: s.orb, strength: s.strength,
+            text: `${title(s.a)} ${s.aspect} partner's ${title(s.b)} (orb ${s.orb.toFixed(1)}°)`,
+        });
+    }
+    const overlays = opts.synastry?.overlays;
+    if (overlays) {
+        for (const [body, house] of Object.entries(overlays.aInB)) {
+            atoms.push({
+                id: `synastry:overlay:a:${body}:house:${house}`, kind: "synastry",
+                bodies: [body], salience: w.base + w.synastry, mode: "overlay",
+                body, partner: "a", house,
+                text: `${title(body)} falls in partner's house ${house}`,
+            });
+        }
+        for (const [body, house] of Object.entries(overlays.bInA)) {
+            atoms.push({
+                id: `synastry:overlay:b:${body}:house:${house}`, kind: "synastry",
+                bodies: [body], salience: w.base + w.synastry, mode: "overlay",
+                body, partner: "b", house,
+                text: `Partner's ${title(body)} falls in house ${house}`,
+            });
+        }
+    }
+    // Composite midpoint placements.
+    for (const c of opts.composite ?? []) {
+        atoms.push({
+            id: `composite:${c.body}`, kind: "composite", bodies: [c.body],
+            salience: w.base + w.composite + (LUMINARIES.has(c.body) ? w.luminary : 0),
+            body: c.body, sign: c.sign, signDeg: c.signDeg,
+            text: `Composite ${title(c.body)} in ${c.sign}`,
+        });
+    }
+    // Time-lords: profection, zodiacal releasing, firdaria, dasha.
+    const tl = opts.timelords;
+    if (tl?.profection) {
+        const pf = tl.profection;
+        atoms.push({
+            id: `profection:year:${pf.annual.sign.toLowerCase()}:${pf.annual.lord}`, kind: "timelord",
+            bodies: [pf.annual.lord], salience: w.base + w.timelord, system: "profection",
+            level: "year", lord: pf.annual.lord, sign: pf.annual.sign,
+            text: `Annual profection: ${pf.annual.sign} (house ${pf.annual.house}), lord ${title(pf.annual.lord)}`,
+        });
+        atoms.push({
+            id: `profection:month:${pf.monthly.sign.toLowerCase()}:${pf.monthly.lord}`, kind: "timelord",
+            bodies: [pf.monthly.lord], salience: w.base + w.timelord * 0.7, system: "profection",
+            level: "month", lord: pf.monthly.lord, sign: pf.monthly.sign,
+            text: `Monthly profection: ${pf.monthly.sign} (house ${pf.monthly.house}), lord ${title(pf.monthly.lord)}`,
+        });
+    }
+    if (tl?.zr) {
+        const zrWeight = { l1: 1, l2: 0.75, l3: 0.5, l4: 0.35 };
+        const zrLevels = [
+            ["l1", tl.zr.l1], ["l2", tl.zr.l2], ["l3", tl.zr.l3], ["l4", tl.zr.l4],
+        ];
+        for (const [level, sign] of zrLevels) {
+            const signIdx = SIGNS.indexOf(sign);
+            const lord = signIdx >= 0 ? SIGN_RULER[signIdx] : "";
+            atoms.push({
+                id: `zr:${level}:${sign.toLowerCase()}:${lord}`, kind: "timelord",
+                bodies: lord ? [lord] : [], salience: w.base + w.timelord * (zrWeight[level] ?? 0.5),
+                system: "zr", level, lord, sign,
+                text: `Zodiacal releasing ${level.toUpperCase()}: ${sign}`
+                    + (lord ? `, lord ${title(lord)}` : "")
+                    + (tl.zr.lot ? ` (from Lot of ${title(tl.zr.lot)})` : ""),
+            });
+        }
+    }
+    if (tl?.firdaria?.major) {
+        atoms.push({
+            id: `firdaria:major:${tl.firdaria.major}`, kind: "timelord",
+            bodies: [tl.firdaria.major], salience: w.base + w.timelord, system: "firdaria",
+            level: "major", lord: tl.firdaria.major,
+            text: `Firdaria major period: ${title(tl.firdaria.major)}`
+                + (tl.firdaria.day !== undefined ? ` (${tl.firdaria.day ? "day" : "night"} chart)` : ""),
+        });
+        if (tl.firdaria.sub) {
+            atoms.push({
+                id: `firdaria:sub:${tl.firdaria.sub}`, kind: "timelord",
+                bodies: [tl.firdaria.sub], salience: w.base + w.timelord * 0.7, system: "firdaria",
+                level: "sub", lord: tl.firdaria.sub,
+                text: `Firdaria sub-period: ${title(tl.firdaria.sub)}`,
+            });
+        }
+    }
+    if (tl?.dasha?.maha) {
+        const d = tl.dasha;
+        atoms.push({
+            id: `dasha:maha:${d.maha}`, kind: "timelord", bodies: [d.maha],
+            salience: w.base + w.timelord, system: "dasha", level: "maha", lord: d.maha,
+            text: `Vimshottari mahadasha: ${title(d.maha)}`
+                + (d.moon_nakshatra ? ` (Moon in ${d.moon_nakshatra})` : ""),
+        });
+        if (d.antar) {
+            atoms.push({
+                id: `dasha:antar:${d.antar}`, kind: "timelord", bodies: [d.antar],
+                salience: w.base + w.timelord * 0.8, system: "dasha", level: "antar", lord: d.antar,
+                text: `Vimshottari antardasha: ${title(d.antar)}`,
+            });
+        }
+        if (d.pratyantar) {
+            atoms.push({
+                id: `dasha:pratyantar:${d.pratyantar}`, kind: "timelord", bodies: [d.pratyantar],
+                salience: w.base + w.timelord * 0.6, system: "dasha", level: "pratyantar", lord: d.pratyantar,
+                text: `Vimshottari pratyantardasha: ${title(d.pratyantar)}`,
+            });
+        }
+    }
+    // Vedic: nakshatras, vargas, yogas.
+    const vedic = opts.vedic;
+    if (vedic) {
+        const nakBodies = vedic.nakshatraBodies
+            ?? ["moon", "sun", "mars", "mercury", "jupiter", "venus", "saturn"];
+        for (const body of nakBodies) {
+            const p = chart.bodies[body];
+            if (!p)
+                continue;
+            const nak = nakshatra(p.lon);
+            let salience = w.base + w.vedic;
+            if (body === "moon")
+                salience += w.luminary;
+            atoms.push({
+                id: `nakshatra:${body}:${nak.name.replace(/\s+/g, "_")}`, kind: "nakshatra",
+                bodies: [body], salience, body, name: nak.name, pada: nak.pada, lord: nak.lord,
+                text: `${title(body)} in ${nak.name} (pada ${nak.pada}, lord ${title(nak.lord)})`,
+            });
+        }
+        const vargaDivs = vedic.vargas === true ? [9] : (vedic.vargas ?? []);
+        for (const n of vargaDivs) {
+            for (const body of nakBodies) {
+                const p = chart.bodies[body];
+                if (!p)
+                    continue;
+                const v = varga(p.lon, n);
+                atoms.push({
+                    id: `varga:d${n}:${body}:${v.sign.toLowerCase()}`, kind: "varga",
+                    bodies: [body], salience: w.base + w.vedic, division: n, body, sign: v.sign,
+                    text: `${title(body)} D${n} (${v.sign})`,
+                });
+            }
+        }
+        for (const y of vedic.yogas ?? []) {
+            atoms.push({
+                id: `yoga:${y.yoga.replace(/\s+/g, "_")}`, kind: "yoga",
+                bodies: y.planets, salience: w.base + w.timelord * 0.5 + w.vedic,
+                yoga: y.yoga, planets: y.planets,
+                text: `Yoga ${y.yoga} (${y.planets.map(title).join(", ")})`,
+            });
+        }
+    }
     // An inexact instant trusts the fast-moving facts least.
     const prov = opts.provenance;
     if (prov?.certainty && prov.certainty !== "exact") {

package/dist/src/relational.d.ts

@@ -0,0 +1,54 @@
+import { type BodyId, type Chart, type Engine, type Zodiac } from "./chart.js";
+import { type AspectPhase } from "./electional.js";
+/** A transiting body aspecting a natal point. */
+export interface TransitHit {
+    transit: string;
+    natal: string;
+    aspect: string;
+    orb: number;
+    phase: AspectPhase;
+    strength: number;
+    /** Natal house the transiting body occupies (by natal cusps). */
+    natalHouse: number;
+}
+/** An inter-chart aspect between person A's body and person B's body. */
+export interface SynastryAspectHit {
+    a: string;
+    b: string;
+    aspect: string;
+    orb: number;
+    strength: number;
+}
+export interface SynastryOverlays {
+    /** Person A's bodies in person B's houses. */
+    aInB: Record<string, number>;
+    /** Person B's bodies in person A's houses. */
+    bInA: Record<string, number>;
+}
+/** A composite-chart body placement (midpoint method). */
+export interface CompositePlacement {
+    body: string;
+    lon: number;
+    sign: string;
+    signDeg: number;
+}
+/**
+ * Transiting bodies aspecting a natal chart at `transitJd`. Natal longitudes are
+ * fixed; phase reflects the transiting body's motion toward the natal point.
+ */
+export declare function transitAspects(natal: Chart, engine: Engine, transitJd: number, opts?: {
+    maxOrb?: number;
+    zodiac?: Zodiac;
+    orbs?: Record<string, number>;
+    bodies?: BodyId[];
+}): TransitHit[];
+/**
+ * Inter-chart aspects between two natal charts (static snapshot; both speeds 0).
+ */
+export declare function synastryAspects(chartA: Chart, chartB: Chart, maxOrb?: number, orbs?: Record<string, number>): SynastryAspectHit[];
+/** House overlays both ways between two charts. */
+export declare function synastryOverlays(chartA: Chart, chartB: Chart): SynastryOverlays;
+/**
+ * Midpoint-composite placements for `bodies` from two birth instants.
+ */
+export declare function compositePlacements(engine: Engine, jdA: number, jdB: number, bodies?: BodyId[], zodiac?: Zodiac): CompositePlacement[];

package/dist/src/relational.js

@@ -0,0 +1,103 @@
+/**
+ * astroengine relational -- diachronic and two-chart derivations for the
+ * interpretation layer: transits vs natal, synastry, composite midpoints.
+ *
+ * Pure geometry on validated positions; no interpretation. Mirrors the MCP
+ * transits/synastry/composite tools but returns structured hits the fact
+ * projection can turn into citable atoms.
+ */
+import { mod } from "./core.js";
+import { ASPECTS, BODIES, DEFAULT_ORBS, NOT_ASPECTABLE, SIGNS, } from "./chart.js";
+import { aspectPhase } from "./electional.js";
+import { compositeLongitudes } from "./derived.js";
+function houseIndex(lon, cusps) {
+    for (let i = 0; i < 12; i++) {
+        if (mod(lon - cusps[i], 360) < mod(cusps[(i + 1) % 12] - cusps[i], 360))
+            return i + 1;
+    }
+    return 12;
+}
+function aspectHits(lonA, speedA, labelA, lonB, speedB, labelB, maxOrb, orbs) {
+    const sep = Math.abs(mod(lonA - lonB + 180, 360) - 180);
+    const out = [];
+    for (const [name, angle] of Object.entries(ASPECTS)) {
+        const limit = Math.min(maxOrb, orbs[name] ?? maxOrb);
+        const orb = Math.abs(sep - angle);
+        if (orb > limit)
+            continue;
+        const orbRounded = Math.round(orb * 100) / 100;
+        out.push({
+            a: labelA, b: labelB, aspect: name, orb: orbRounded,
+            phase: aspectPhase(lonA, speedA, lonB, speedB, angle),
+            strength: Math.max(0, 1 - orbRounded / limit),
+        });
+    }
+    return out;
+}
+/**
+ * Transiting bodies aspecting a natal chart at `transitJd`. Natal longitudes are
+ * fixed; phase reflects the transiting body's motion toward the natal point.
+ */
+export function transitAspects(natal, engine, transitJd, opts = {}) {
+    const maxOrb = opts.maxOrb ?? 3;
+    const orbs = opts.orbs ?? DEFAULT_ORBS;
+    const zodiac = opts.zodiac ?? natal.zodiac;
+    const bodies = opts.bodies ?? BODIES;
+    const natalBodies = bodies.filter((b) => natal.bodies[b] && !NOT_ASPECTABLE.has(b));
+    const out = [];
+    for (const tb of bodies) {
+        if (NOT_ASPECTABLE.has(tb))
+            continue;
+        const tp = engine.position(tb, transitJd, { zodiac });
+        const natalHouse = houseIndex(tp.lon, natal.cusps);
+        for (const nb of natalBodies) {
+            const nLon = natal.bodies[nb].lon;
+            for (const hit of aspectHits(tp.lon, tp.speed, tb, nLon, 0, nb, maxOrb, orbs)) {
+                out.push({
+                    transit: hit.a, natal: hit.b, aspect: hit.aspect,
+                    orb: hit.orb, phase: hit.phase, strength: hit.strength, natalHouse,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Inter-chart aspects between two natal charts (static snapshot; both speeds 0).
+ */
+export function synastryAspects(chartA, chartB, maxOrb = 4, orbs = DEFAULT_ORBS) {
+    const bodies = BODIES.filter((b) => chartA.bodies[b] && chartB.bodies[b] && !NOT_ASPECTABLE.has(b));
+    const out = [];
+    for (const ba of bodies) {
+        const la = chartA.bodies[ba].lon;
+        for (const bb of bodies) {
+            const lb = chartB.bodies[bb].lon;
+            for (const hit of aspectHits(la, 0, ba, lb, 0, bb, maxOrb, orbs)) {
+                out.push({ a: hit.a, b: hit.b, aspect: hit.aspect, orb: hit.orb, strength: hit.strength });
+            }
+        }
+    }
+    return out;
+}
+/** House overlays both ways between two charts. */
+export function synastryOverlays(chartA, chartB) {
+    const bodies = BODIES.filter((b) => chartA.bodies[b] && chartB.bodies[b]);
+    const aInB = {};
+    const bInA = {};
+    for (const b of bodies) {
+        aInB[b] = houseIndex(chartA.bodies[b].lon, chartB.cusps);
+        bInA[b] = houseIndex(chartB.bodies[b].lon, chartA.cusps);
+    }
+    return { aInB, bInA };
+}
+/**
+ * Midpoint-composite placements for `bodies` from two birth instants.
+ */
+export function compositePlacements(engine, jdA, jdB, bodies = BODIES, zodiac = "tropical") {
+    const lons = compositeLongitudes(engine, jdA, jdB, bodies, zodiac);
+    return bodies.map((body) => {
+        const lon = mod(lons[body], 360);
+        const signIdx = Math.floor(lon / 30) % 12;
+        return { body, lon, sign: SIGNS[signIdx], signDeg: mod(lon, 30) };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caelus",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Astrological ephemeris engine. MIT, no AGPL, no ephemeris files. Checked against Swiss Ephemeris.",
   "type": "module",
   "main": "dist/src/index.js",