caelus 0.18.0 → 0.20.0

package/dist/src/chart.d.ts

@@ -242,6 +242,44 @@ export declare class Engine {
      * @returns Sorted catalog star names.
      */
     starNames(): string[];
+    /**
+     * Fixed-star conjunctions in a chart: each body within `orb` of a catalog
+     * star, in the chart's own zodiac. Feed the result to
+     * {@link interpretationContext} as `stars` to project `star` fact atoms (the
+     * Chart itself carries no star catalog).
+     *
+     * @param chart A chart from {@link Engine.chart} / {@link Engine.chartAt}.
+     * @param opts `orb` (default 1°); `stars` to restrict to named stars (then no
+     *   magnitude filter); else `maxMag` keeps only stars brighter than it
+     *   (default 2.5) so obscure catalog entries do not flood the result.
+     * @returns Conjunctions sorted by increasing orb.
+     */
+    starConjunctions(chart: Chart, opts?: {
+        orb?: number;
+        maxMag?: number;
+        stars?: string[];
+    }): {
+        body: string;
+        star: string;
+        orb: number;
+    }[];
+    /**
+     * The seven Hermetic lots of a chart, each placed by sign and house. Sect is
+     * read from the Sun (above the horizon -> a day chart). Feed the result to
+     * {@link interpretationContext} as `lots` to project `lot` fact atoms.
+     *
+     * @param chart A chart from {@link Engine.chart} / {@link Engine.chartAt}; it
+     *   must carry the seven classical planets.
+     * @returns One entry per lot with its longitude, sign, `signDeg`, and house,
+     *   or an empty array if a required planet is absent.
+     */
+    lots(chart: Chart): {
+        lot: string;
+        lon: number;
+        sign: string;
+        signDeg: number;
+        house: number;
+    }[];
     private lonOnly;
     /**
      * Apparent geocentric ecliptic longitude of a body, in degrees `[0, 360)`,

package/dist/src/chart.js

@@ -1,6 +1,7 @@
 /** astroengine chart -- public API: natal charts, aspects, retrogrades. */
 import { DEG, mod, jdTT, julianDay, ChebSeries, planetApparent, sunApparent, moonApparentSeries, moonApparentPrecise, plutoApparent, chironApparent, meanNode, trueNodeSeries, trueNodePrecise, equatorial, ayanamsa, AYANAMSA_J2000, meanLilith, topocentricEcl, oscApogeePrecise, oscApogeeSeries, KeplerOrbit, trueObliquity, nutation, plutoHeliocentric, vsopHeliocentric, precessEcliptic, J2000, } from "./core.js";
 import { starApparent } from "./stars.js";
+import { hermeticLots, HERMETIC_LOTS } from "./lots.js";
 import * as H from "./houses.js";
 const TWO_PI = 2 * Math.PI;
 export const BODIES = [
@@ -295,6 +296,68 @@ export class Engine {
     starNames() {
         return Object.keys(this.data.fixedStars?.stars ?? {}).sort();
     }
+    /**
+     * Fixed-star conjunctions in a chart: each body within `orb` of a catalog
+     * star, in the chart's own zodiac. Feed the result to
+     * {@link interpretationContext} as `stars` to project `star` fact atoms (the
+     * Chart itself carries no star catalog).
+     *
+     * @param chart A chart from {@link Engine.chart} / {@link Engine.chartAt}.
+     * @param opts `orb` (default 1°); `stars` to restrict to named stars (then no
+     *   magnitude filter); else `maxMag` keeps only stars brighter than it
+     *   (default 2.5) so obscure catalog entries do not flood the result.
+     * @returns Conjunctions sorted by increasing orb.
+     */
+    starConjunctions(chart, opts = {}) {
+        const catalog = this.data.fixedStars?.stars;
+        if (!catalog)
+            return [];
+        const orbLimit = opts.orb ?? 1.0;
+        const names = opts.stars ?? Object.keys(catalog);
+        const useMag = opts.stars === undefined;
+        const maxMag = opts.maxMag ?? 2.5;
+        const out = [];
+        for (const name of names) {
+            const s = catalog[name];
+            if (!s || (useMag && s.mag > maxMag))
+                continue;
+            const starLon = this.fixedStar(name, chart.jdUt, { zodiac: chart.zodiac }).lon;
+            for (const [body, p] of Object.entries(chart.bodies)) {
+                if (!p)
+                    continue;
+                const sep = Math.abs(mod(p.lon - starLon + 180, 360) - 180);
+                if (sep <= orbLimit)
+                    out.push({ body, star: name, orb: sep });
+            }
+        }
+        out.sort((a, b) => a.orb - b.orb);
+        return out;
+    }
+    /**
+     * The seven Hermetic lots of a chart, each placed by sign and house. Sect is
+     * read from the Sun (above the horizon -> a day chart). Feed the result to
+     * {@link interpretationContext} as `lots` to project `lot` fact atoms.
+     *
+     * @param chart A chart from {@link Engine.chart} / {@link Engine.chartAt}; it
+     *   must carry the seven classical planets.
+     * @returns One entry per lot with its longitude, sign, `signDeg`, and house,
+     *   or an empty array if a required planet is absent.
+     */
+    lots(chart) {
+        const b = chart.bodies;
+        const need = ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn"];
+        if (need.some((k) => !b[k]))
+            return [];
+        const day = (b.sun.house >= 7); // Sun above the horizon (houses 7-12)
+        const h = hermeticLots(chart.angles.asc, day, b.sun.lon, b.moon.lon, b.mercury.lon, b.venus.lon, b.mars.lon, b.jupiter.lon, b.saturn.lon);
+        return HERMETIC_LOTS.map((lot) => {
+            const lon = mod(h[lot], 360);
+            return {
+                lot, lon, sign: SIGNS[Math.floor(lon / 30)], signDeg: mod(lon, 30),
+                house: houseIndex(lon, chart.cusps),
+            };
+        });
+    }
     lonOnly(body, jdUt, mode, topo) {
         const jde = jdTT(jdUt);
         let [lon, lat, dist] = this.ecliptic(body, jde);

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

@@ -63,6 +63,69 @@ export declare function hasDispositor(filter?: {
 export declare function hasReception(filter?: {
     body?: string;
 }): Selector;
+/** Matches a fixed-star conjunction by the catalog star and/or the body on it. */
+export declare function hasStar(filter?: {
+    body?: string;
+    star?: string;
+}): Selector;
+/** Matches a Hermetic lot by name, and/or its sign or house. */
+export declare function hasLot(filter?: {
+    lot?: string;
+    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

@@ -61,6 +61,99 @@ export function hasReception(filter = {}) {
     return (ctx) => hit(ctx.atoms.filter((a) => a.kind === "reception"
         && (filter.body === undefined || a.bodies.includes(filter.body))));
 }
+/** Matches a fixed-star conjunction by the catalog star and/or the body on it. */
+export function hasStar(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => a.kind === "star"
+        && (filter.body === undefined || a.body === filter.body)
+        && (filter.star === undefined || a.star === filter.star)));
+}
+/** Matches a Hermetic lot by name, and/or its sign or house. */
+export function hasLot(filter = {}) {
+    return (ctx) => hit(ctx.atoms.filter((a) => a.kind === "lot"
+        && (filter.lot === undefined || a.lot === filter.lot)
+        && (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";
+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. */
@@ -72,7 +74,83 @@ export interface ReceptionAtom extends FactAtomBase {
      *  else a sorted pair for a mixed reception (e.g. `"domicile-exaltation"`). */
     by: string;
 }
-export type FactAtom = PlacementAtom | AspectAtom | PatternAtom | SignatureAtom | AngleAtom | DispositorAtom | ReceptionAtom;
+export interface StarAtom extends FactAtomBase {
+    kind: "star";
+    /** The body conjunct the fixed star. */
+    body: string;
+    /** Catalog star name (see {@link Engine.starNames}). */
+    star: string;
+    /** Orb from exact conjunction, degrees. */
+    orb: number;
+}
+export interface LotAtom extends FactAtomBase {
+    kind: "lot";
+    /** Hermetic lot name, e.g. `"fortune"` (see {@link HERMETIC_LOTS}). */
+    lot: string;
+    sign: string;
+    signDeg: number;
+    house: number;
+}
+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;
@@ -108,6 +186,22 @@ export interface SalienceWeights {
     dispositor: number;
     /** Added to a mutual reception. */
     reception: number;
+    /** Added to a body's conjunction with a fixed star. */
+    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 {
@@ -122,6 +216,64 @@ export interface ContextOptions {
         realm?: Realm;
         certainty?: Certainty;
     };
+    /** Fixed-star conjunctions to project as `star` atoms. The engine does not
+     *  compute these from a bare {@link Chart} (the star catalog lives in the
+     *  data pack), so a caller supplies them, e.g. from
+     *  {@link Engine.starConjunctions}. */
+    stars?: {
+        body: string;
+        star: string;
+        orb: number;
+    }[];
+    /** Hermetic lots to project as `lot` atoms, e.g. from {@link Engine.lots}. */
+    lots?: {
+        lot: string;
+        sign: string;
+        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,6 +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, 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. */
@@ -62,7 +66,7 @@ const TIME_SENSITIVE_KEEP = {
 /** Time-sensitive atoms: the angles (rotate ~15°/h) and anything about the Moon
  *  (~13°/day), the fastest-shifting facts under a time error. */
 function timeSensitive(atom) {
-    return atom.kind === "angle" || atom.bodies.includes("moon");
+    return atom.kind === "angle" || atom.kind === "lot" || atom.bodies.includes("moon");
 }
 function title(body) {
     return body.split("_").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
@@ -234,6 +238,237 @@ export function interpretationContext(chart, opts = {}) {
     angleAtom("mc", chart.angles.mc);
     angleAtom("vertex", chart.angles.vertex);
     angleAtom("eastPoint", chart.angles.eastPoint);
+    // Fixed-star conjunctions (caller-supplied; the catalog is not on the Chart).
+    for (const sc of opts.stars ?? []) {
+        let salience = w.base + w.star;
+        if (LUMINARIES.has(sc.body))
+            salience += w.luminary;
+        atoms.push({
+            id: `star:${sc.body}:${sc.star}`, kind: "star", bodies: [sc.body], salience,
+            body: sc.body, star: sc.star, orb: sc.orb,
+            text: `${title(sc.body)} conjunct ${sc.star} (orb ${sc.orb.toFixed(1)}°)`,
+        });
+    }
+    // Hermetic lots (caller-supplied; computed from the chart's points + sect).
+    for (const l of opts.lots ?? []) {
+        atoms.push({
+            id: `lot:${l.lot}`, kind: "lot", bodies: [], salience: w.base + w.lot,
+            lot: l.lot, sign: l.sign, signDeg: l.signDeg, house: l.house,
+            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.18.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",