caelus 0.18.0 → 0.19.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/interpret.d.ts

@@ -63,6 +63,17 @@ 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 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,19 @@ 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)));
+}
 // ----------------------------------------------------------------- combinators
 /** Matches only when every selector matches; returns the union of their atoms. */
 export function matchAll(...sels) {

package/dist/src/interpretation.d.ts

@@ -4,7 +4,7 @@ import { ChartPattern } from "./patterns.js";
 import { ChartSignature } from "./signature.js";
 import type { Realm, Certainty } from "./provenance.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";
 interface FactAtomBase {
     /** Stable, content-addressable id, e.g. `"placement:mars"` or
      *  `"aspect:mars~saturn:square"`. Interpretations cite this. */
@@ -72,7 +72,24 @@ 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 type FactAtom = PlacementAtom | AspectAtom | PatternAtom | SignatureAtom | AngleAtom | DispositorAtom | ReceptionAtom | StarAtom | LotAtom;
 /** A chart as a flat, ranked list of {@link FactAtom}s. */
 export interface InterpretationContext {
     jdUt: number;
@@ -108,6 +125,10 @@ 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;
 }
 export declare const DEFAULT_SALIENCE: SalienceWeights;
 export interface ContextOptions {
@@ -122,6 +143,22 @@ 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;
+    }[];
 }
 /**
  * Project a {@link Chart} into a ranked list of {@link FactAtom}s -- the

package/dist/src/interpretation.js

@@ -53,6 +53,7 @@ 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,
 };
 /** 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 +63,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 +235,25 @@ 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}`,
+        });
+    }
     // An inexact instant trusts the fast-moving facts least.
     const prov = opts.provenance;
     if (prov?.certainty && prov.certainty !== "exact") {

package/package.json

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