caelus 0.16.0 → 0.18.0

package/dist/src/eclipses.d.ts

@@ -38,3 +38,106 @@ export declare function lunarEclipses(engine: Engine, jdStart: number, jdEnd: nu
  * ```
  */
 export declare function solarEclipses(engine: Engine, jdStart: number, jdEnd: number): SolarEclipse[];
+/** Geographic point on the Earth's surface (geodetic latitude, east longitude). */
+export interface GeoPoint {
+    /** Geodetic latitude in degrees, north positive. */
+    lat: number;
+    /** Longitude in degrees, east positive, in (-180, 180]. */
+    lonEast: number;
+}
+/** Local circumstances of a solar eclipse seen from one place. */
+export interface SolarLocal {
+    /** What the observer sees at maximum: `"none"` when no part of the Sun is
+     *  covered from this place. */
+    type: "total" | "annular" | "partial" | "none";
+    /** Eclipse magnitude: fraction of the Sun's *diameter* covered at maximum
+     *  (can exceed 1 in totality). 0 when `type` is `"none"`. */
+    magnitude: number;
+    /** Obscuration: fraction of the Sun's *area* covered at maximum, in [0, 1]. */
+    obscuration: number;
+    /** Time of maximum eclipse at this place (JD UT), or `null` when unseen. */
+    maxTime: number | null;
+    /** First contact (partial begins), JD UT, or `null` when unseen. */
+    c1: number | null;
+    /** Second contact (totality/annularity begins), JD UT, or `null`. */
+    c2: number | null;
+    /** Third contact (totality/annularity ends), JD UT, or `null`. */
+    c3: number | null;
+    /** Fourth contact (partial ends), JD UT, or `null` when unseen. */
+    c4: number | null;
+}
+/**
+ * Sub-shadow geographic point where the eclipse axis meets the Earth at a
+ * Julian Day (UT): the centre line of totality/annularity at that instant.
+ * Sample it across the eclipse (e.g. between the {@link SolarEclipse} `begin`
+ * and `end`) to draw the ground track.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT) -- typically a
+ *   {@link SolarEclipse.tMax} for the point of greatest eclipse.
+ * @returns The {@link GeoPoint} on the IAU 1976 ellipsoid, or `null` when the
+ *   axis misses the Earth (only a partial eclipse exists anywhere then).
+ */
+export declare function solarEclipseWhere(engine: Engine, jd: number): GeoPoint | null;
+/**
+ * Local circumstances of a solar eclipse as seen from one place: contact
+ * times, magnitude, and obscuration. Topocentric Sun and Moon disks, so it
+ * accounts for lunar parallax (which is what makes the same eclipse total in
+ * one town and partial in the next).
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd A time near the eclipse, JD (UT) -- typically a
+ *   {@link SolarEclipse.tMax}; the local maximum is found within a few hours.
+ * @param latDeg Observer geodetic latitude in degrees (north positive).
+ * @param lonEastDeg Observer longitude in degrees (east positive).
+ * @param altM Observer height above the ellipsoid in metres (default 0).
+ * @returns {@link SolarLocal}. `type` is `"none"` when the Sun is not eclipsed
+ *   from this place at all; `c2`/`c3` are `null` outside totality/annularity.
+ */
+export declare function solarEclipseLocal(engine: Engine, jd: number, latDeg: number, lonEastDeg: number, altM?: number): SolarLocal;
+/** The umbra/antumbra path of a solar eclipse at one instant. */
+export interface EclipsePath {
+    /** Central line point (greatest coverage) at this instant. */
+    center: GeoPoint;
+    /** Northern edge of totality/annularity, or `null` if it runs off the Earth. */
+    north: GeoPoint | null;
+    /** Southern edge, or `null` if it runs off the Earth. */
+    south: GeoPoint | null;
+    /** Full path width (km) between the limits, or `null` when a limit is missing. */
+    widthKm: number | null;
+}
+/**
+ * Ground path of a solar eclipse at a Julian Day (UT): the central point and
+ * the north/south limits of totality (or annularity), with the path width.
+ * Marches perpendicular to the shadow's ground track out to the umbra edge --
+ * where the Moon just fully covers (or is covered by) the Sun. Sample across
+ * the eclipse to trace the full path of totality.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT) -- typically a
+ *   {@link SolarEclipse.tMax} for the path at greatest eclipse.
+ * @returns The {@link EclipsePath}, or `null` when no central eclipse exists
+ *   then (only a partial eclipse, or the axis misses the Earth).
+ */
+export declare function solarEclipseLimits(engine: Engine, jd: number): EclipsePath | null;
+/** Whether a lunar eclipse is up at a place, and how high the Moon stands. */
+export interface LunarLocal {
+    /** Moon's true altitude in degrees at the given instant (negative = below
+     *  the horizon). */
+    altitude: number;
+    /** Whether the Moon is above the horizon (the eclipse is visible there). */
+    visible: boolean;
+}
+/**
+ * Local visibility of a lunar eclipse: a lunar eclipse happens at the same
+ * instant for the whole Earth, so "local circumstances" is simply whether the
+ * Moon is up. Pass a contact time (e.g. {@link LunarEclipse.tMax} or a phase
+ * boundary) to learn whether that phase is visible from a place.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT).
+ * @param latDeg Observer latitude in degrees (north positive).
+ * @param lonEastDeg Observer longitude in degrees (east positive).
+ * @returns {@link LunarLocal} with the Moon's altitude and a visibility flag.
+ */
+export declare function lunarEclipseLocal(engine: Engine, jd: number, latDeg: number, lonEastDeg: number): LunarLocal;

package/dist/src/eclipses.js

@@ -11,9 +11,18 @@
  * Sun-Moon axis to the geocenter in Earth radii; the umbral cone's reach
  * at the surface separates total from annular, a sign change along the
  * track marks hybrids. Types match Swiss Ephemeris exactly over decades.
- * Local circumstances (where/visibility) are not computed here.
+ *
+ * Solar (where): the same shadow axis intersected with the IAU 1976 Earth
+ * ellipsoid gives the sub-shadow geographic point -- the centre line of
+ * totality/annularity at an instant; sampled across the eclipse it draws the
+ * ground track. Solar (local): topocentric Sun/Moon disks at an observer give
+ * the contact times, magnitude, and obscuration as seen from that point. With
+ * a ~2.5" Moon these land within seconds of time and a few km of track: right
+ * for charts, not for eclipse-chaser path maps.
  */
-import { ARCSEC, jdTT, mod } from "./core.js";
+import { ARCSEC, DEG, jdTT, mod, trueObliquity, equatorial, topocentricEcl } from "./core.js";
+import { gast } from "./houses.js";
+import { azAlt } from "./pheno.js";
 const KM_PER_AU = 149597870.7;
 const R_EARTH = 6378.14;
 const R_SUN = 696000.0;
@@ -177,3 +186,252 @@ export function solarEclipses(engine, jdStart, jdEnd) {
     }
     return out;
 }
+// ---------------------------------------------------------------- where + local
+const EARTH_FLAT = 0.99664719; // 1 - f, IAU 1976 figure (b/a)
+const EARTH_FLAT2 = EARTH_FLAT * EARTH_FLAT; // (b/a)^2 = 1 - e^2
+/** Geocentric *equatorial* Cartesian (km) of the Sun and Moon, plus obliquity. */
+function sunMoonEq(engine, jde) {
+    const eps = trueObliquity(engine.data, jde);
+    const vec = (body) => {
+        const [lon, lat, dist] = engine.ecliptic(body, jde);
+        const [ra, dec] = equatorial(lon, lat, eps);
+        const r = dist * KM_PER_AU;
+        return [
+            r * Math.cos(dec) * Math.cos(ra),
+            r * Math.cos(dec) * Math.sin(ra),
+            r * Math.sin(dec),
+        ];
+    };
+    return { S: vec("sun"), M: vec("moon") };
+}
+/**
+ * Sub-shadow geographic point where the eclipse axis meets the Earth at a
+ * Julian Day (UT): the centre line of totality/annularity at that instant.
+ * Sample it across the eclipse (e.g. between the {@link SolarEclipse} `begin`
+ * and `end`) to draw the ground track.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT) -- typically a
+ *   {@link SolarEclipse.tMax} for the point of greatest eclipse.
+ * @returns The {@link GeoPoint} on the IAU 1976 ellipsoid, or `null` when the
+ *   axis misses the Earth (only a partial eclipse exists anywhere then).
+ */
+export function solarEclipseWhere(engine, jd) {
+    const jde = jdTT(jd);
+    const { S, M } = sunMoonEq(engine, jde);
+    const SM = [M[0] - S[0], M[1] - S[1], M[2] - S[2]];
+    const smn = Math.hypot(SM[0], SM[1], SM[2]);
+    const d = SM.map((c) => c / smn); // travels Sun -> Moon -> Earth
+    // Intersect the line M + s*d with the ellipsoid by scaling z by 1/flat,
+    // which maps the ellipsoid to a sphere of radius R_EARTH.
+    const Mz = [M[0], M[1], M[2] / EARTH_FLAT];
+    const dz = [d[0], d[1], d[2] / EARTH_FLAT];
+    const a = dz[0] ** 2 + dz[1] ** 2 + dz[2] ** 2;
+    const b = 2 * (Mz[0] * dz[0] + Mz[1] * dz[1] + Mz[2] * dz[2]);
+    const c = Mz[0] ** 2 + Mz[1] ** 2 + Mz[2] ** 2 - R_EARTH ** 2;
+    const disc = b * b - 4 * a * c;
+    if (disc < 0)
+        return null;
+    const s = (-b - Math.sqrt(disc)) / (2 * a); // near side, facing the Moon
+    const P = [M[0] + s * d[0], M[1] + s * d[1], M[2] + s * d[2]];
+    const rho = Math.hypot(P[0], P[1]);
+    const lat = Math.atan2(P[2], EARTH_FLAT2 * rho); // geocentric -> geodetic
+    const ra = Math.atan2(P[1], P[0]);
+    const lonEast = mod(ra - gast(engine.data, jd) + Math.PI, 2 * Math.PI) - Math.PI;
+    return { lat: lat / DEG, lonEast: lonEast / DEG };
+}
+/** Topocentric Sun/Moon angular separation and disk radii (rad) at a place. */
+function topoCircs(engine, jd, latDeg, lonEastDeg, altM) {
+    const jde = jdTT(jd);
+    const eps = trueObliquity(engine.data, jde);
+    const lst = mod(gast(engine.data, jd) + lonEastDeg * DEG, 2 * Math.PI);
+    const topo = (body) => {
+        const [lon, lat, dist] = engine.ecliptic(body, jde);
+        return topocentricEcl(lon, lat, dist, lst, latDeg * DEG, altM, eps);
+    };
+    const [slon, slat, sdist] = topo("sun");
+    const [mlon, mlat, mdist] = topo("moon");
+    const cosSep = Math.sin(slat) * Math.sin(mlat)
+        + Math.cos(slat) * Math.cos(mlat) * Math.cos(slon - mlon);
+    return {
+        sep: Math.acos(Math.max(-1, Math.min(1, cosSep))),
+        sS: Math.asin(R_SUN / (sdist * KM_PER_AU)),
+        sM: Math.asin(R_MOON / (mdist * KM_PER_AU)),
+    };
+}
+/** Area where two disks (radii r1, r2, centre distance d) overlap. */
+function lensArea(d, r1, r2) {
+    if (d >= r1 + r2)
+        return 0;
+    if (d <= Math.abs(r1 - r2))
+        return Math.PI * Math.min(r1, r2) ** 2;
+    const a1 = Math.acos((d * d + r1 * r1 - r2 * r2) / (2 * d * r1));
+    const a2 = Math.acos((d * d + r2 * r2 - r1 * r1) / (2 * d * r2));
+    return r1 * r1 * (a1 - Math.sin(2 * a1) / 2) + r2 * r2 * (a2 - Math.sin(2 * a2) / 2);
+}
+/** Step out from `tMax` (where g < 0) until `g` changes sign, then bisect. */
+function contact(g, tMax, dir) {
+    const step = 0.003; // ~4.3 min
+    let prev = tMax;
+    let fprev = g(tMax);
+    for (let i = 1; i <= 120; i++) { // search up to ~8.6 h either side
+        const t = tMax + dir * i * step;
+        const f = g(t);
+        if (fprev * f <= 0)
+            return bisect(g, Math.min(prev, t), Math.max(prev, t));
+        prev = t;
+        fprev = f;
+    }
+    return null;
+}
+/**
+ * Local circumstances of a solar eclipse as seen from one place: contact
+ * times, magnitude, and obscuration. Topocentric Sun and Moon disks, so it
+ * accounts for lunar parallax (which is what makes the same eclipse total in
+ * one town and partial in the next).
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd A time near the eclipse, JD (UT) -- typically a
+ *   {@link SolarEclipse.tMax}; the local maximum is found within a few hours.
+ * @param latDeg Observer geodetic latitude in degrees (north positive).
+ * @param lonEastDeg Observer longitude in degrees (east positive).
+ * @param altM Observer height above the ellipsoid in metres (default 0).
+ * @returns {@link SolarLocal}. `type` is `"none"` when the Sun is not eclipsed
+ *   from this place at all; `c2`/`c3` are `null` outside totality/annularity.
+ */
+export function solarEclipseLocal(engine, jd, latDeg, lonEastDeg, altM = 0) {
+    const sepAt = (t) => topoCircs(engine, t, latDeg, lonEastDeg, altM).sep;
+    const tMax = minimize(sepAt, jd - 0.2, jd + 0.2);
+    const { sep, sS, sM } = topoCircs(engine, tMax, latDeg, lonEastDeg, altM);
+    const none = {
+        type: "none", magnitude: 0, obscuration: 0,
+        maxTime: null, c1: null, c2: null, c3: null, c4: null,
+    };
+    if (sep >= sS + sM)
+        return none;
+    const type = sep <= sM - sS ? "total" : sep <= sS - sM ? "annular" : "partial";
+    const gOuter = (t) => {
+        const c = topoCircs(engine, t, latDeg, lonEastDeg, altM);
+        return c.sep - (c.sS + c.sM);
+    };
+    let c2 = null;
+    let c3 = null;
+    if (type === "total" || type === "annular") {
+        const gInner = (t) => {
+            const c = topoCircs(engine, t, latDeg, lonEastDeg, altM);
+            return c.sep - Math.abs(c.sM - c.sS);
+        };
+        c2 = contact(gInner, tMax, -1);
+        c3 = contact(gInner, tMax, 1);
+    }
+    // Magnitude = fraction of the Sun's diameter covered. In the partial regime
+    // one Moon edge is inside the Sun's disk; once central (annular or total) it
+    // is the Moon/Sun diameter ratio -- < 1 in annularity, > 1 in totality.
+    return {
+        type,
+        magnitude: sep <= Math.abs(sM - sS) ? sM / sS : (sS + sM - sep) / (2 * sS),
+        obscuration: lensArea(sep, sS, sM) / (Math.PI * sS * sS),
+        maxTime: tMax,
+        c1: contact(gOuter, tMax, -1),
+        c2, c3,
+        c4: contact(gOuter, tMax, 1),
+    };
+}
+const R_MEAN = 6371.0; // mean Earth radius (km) for short surface offsets
+/** Geodetic destination point `distKm` from (lat, lon) along `bearingDeg`. */
+function destPoint(lat, lon, bearingDeg, distKm) {
+    const d = distKm / R_MEAN;
+    const br = bearingDeg * DEG;
+    const p1 = lat * DEG;
+    const l1 = lon * DEG;
+    const p2 = Math.asin(Math.sin(p1) * Math.cos(d) + Math.cos(p1) * Math.sin(d) * Math.cos(br));
+    const l2 = l1 + Math.atan2(Math.sin(br) * Math.sin(d) * Math.cos(p1), Math.cos(d) - Math.sin(p1) * Math.sin(p2));
+    return { lat: p2 / DEG, lonEast: mod(l2 / DEG + 540, 360) - 180 };
+}
+/** Initial great-circle bearing (deg) from `a` to `b`. */
+function bearing(a, b) {
+    const p1 = a.lat * DEG;
+    const p2 = b.lat * DEG;
+    const dl = (b.lonEast - a.lonEast) * DEG;
+    return mod(Math.atan2(Math.sin(dl) * Math.cos(p2), Math.cos(p1) * Math.sin(p2) - Math.sin(p1) * Math.cos(p2) * Math.cos(dl)) / DEG, 360);
+}
+/** Great-circle distance (km) between two geographic points. */
+function greatCircleKm(a, b) {
+    const p1 = a.lat * DEG;
+    const p2 = b.lat * DEG;
+    const dp = (b.lat - a.lat) * DEG;
+    const dl = (b.lonEast - a.lonEast) * DEG;
+    const h = Math.sin(dp / 2) ** 2 + Math.cos(p1) * Math.cos(p2) * Math.sin(dl / 2) ** 2;
+    return R_MEAN * 2 * Math.atan2(Math.sqrt(h), Math.sqrt(1 - h));
+}
+/**
+ * Ground path of a solar eclipse at a Julian Day (UT): the central point and
+ * the north/south limits of totality (or annularity), with the path width.
+ * Marches perpendicular to the shadow's ground track out to the umbra edge --
+ * where the Moon just fully covers (or is covered by) the Sun. Sample across
+ * the eclipse to trace the full path of totality.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT) -- typically a
+ *   {@link SolarEclipse.tMax} for the path at greatest eclipse.
+ * @returns The {@link EclipsePath}, or `null` when no central eclipse exists
+ *   then (only a partial eclipse, or the axis misses the Earth).
+ */
+export function solarEclipseLimits(engine, jd) {
+    const center = solarEclipseWhere(engine, jd);
+    if (center === null)
+        return null;
+    const ahead = solarEclipseWhere(engine, jd + 1 / 86400);
+    const track = ahead ? bearing(center, ahead) : 0; // ground-track direction
+    // Inside the umbra/antumbra the centres are closer than |radii difference|.
+    const edge = (lat, lon) => {
+        const c = topoCircs(engine, jd, lat, lon, 0);
+        return c.sep - Math.abs(c.sM - c.sS);
+    };
+    const march = (brg) => {
+        let gPrev = edge(center.lat, center.lonEast); // < 0 on the central line
+        for (let s = 4; s <= 400; s += 4) {
+            const q = destPoint(center.lat, center.lonEast, brg, s);
+            if (gPrev * edge(q.lat, q.lonEast) <= 0) {
+                let lo = s - 4;
+                let hi = s; // edge is between lo (inside) and hi (outside)
+                for (let i = 0; i < 40; i++) {
+                    const mid = (lo + hi) / 2;
+                    const qm = destPoint(center.lat, center.lonEast, brg, mid);
+                    if (edge(qm.lat, qm.lonEast) <= 0)
+                        lo = mid;
+                    else
+                        hi = mid;
+                }
+                return destPoint(center.lat, center.lonEast, brg, (lo + hi) / 2);
+            }
+            gPrev = edge(q.lat, q.lonEast);
+        }
+        return null;
+    };
+    const a = march(mod(track - 90, 360));
+    const b = march(mod(track + 90, 360));
+    // Label by latitude so `north` is always the higher-latitude edge.
+    const [north, south] = !a || !b ? [a, b] : a.lat >= b.lat ? [a, b] : [b, a];
+    return {
+        center, north, south,
+        widthKm: north && south ? greatCircleKm(north, south) : null,
+    };
+}
+/**
+ * Local visibility of a lunar eclipse: a lunar eclipse happens at the same
+ * instant for the whole Earth, so "local circumstances" is simply whether the
+ * Moon is up. Pass a contact time (e.g. {@link LunarEclipse.tMax} or a phase
+ * boundary) to learn whether that phase is visible from a place.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT).
+ * @param latDeg Observer latitude in degrees (north positive).
+ * @param lonEastDeg Observer longitude in degrees (east positive).
+ * @returns {@link LunarLocal} with the Moon's altitude and a visibility flag.
+ */
+export function lunarEclipseLocal(engine, jd, latDeg, lonEastDeg) {
+    const [mlon, mlat] = engine.ecliptic("moon", jdTT(jd));
+    const [, altitude] = azAlt(engine.data, mlon / DEG, mlat / DEG, jd, latDeg, lonEastDeg);
+    return { altitude, visible: altitude > 0 };
+}

package/dist/src/index.d.ts

@@ -28,5 +28,11 @@ export * from "./ashtottari.js";
 export * from "./rajayoga.js";
 export * from "./patterns.js";
 export * from "./signature.js";
+export * from "./interpretation.js";
+export * from "./interpret.js";
+export * from "./brief.js";
+export * from "./provenance.js";
+export * from "./anchored.js";
+export * from "./counterfactual.js";
 export * from "./dignity-score.js";
 export * from "./parans.js";

package/dist/src/index.js

@@ -28,5 +28,11 @@ export * from "./ashtottari.js";
 export * from "./rajayoga.js";
 export * from "./patterns.js";
 export * from "./signature.js";
+export * from "./interpretation.js";
+export * from "./interpret.js";
+export * from "./brief.js";
+export * from "./provenance.js";
+export * from "./anchored.js";
+export * from "./counterfactual.js";
 export * from "./dignity-score.js";
 export * from "./parans.js";

package/dist/src/interpret.d.ts

@@ -0,0 +1,156 @@
+/**
+ * astroengine interpretation matching + resolver -- the plug for a content layer.
+ *
+ * The {@link interpretationContext} projection turns a chart into ranked fact
+ * atoms; this layer lets a developer plug in *meaning*. A {@link Selector}
+ * matches atoms (and reports which ones, so a claim carries its provenance); a
+ * {@link Rule} pairs a selector with text; an {@link InterpretationSource}
+ * bundles rules (a tradition, a house style, a third-party corpus). The engine
+ * ships the contract and the resolver, never the content: {@link interpret}
+ * runs sources against a context and returns a ranked {@link Reading}, each
+ * entry tagged with the atom ids it rests on.
+ *
+ * Selectors read the projection directly, so they express the whole fact model
+ * -- house, dignity, pattern membership, signature dominance, aspect phase and
+ * strength -- which the geometric, time-only `query` predicates cannot.
+ */
+import type { FactAtom, InterpretationContext } from "./interpretation.js";
+/** The result of a {@link Selector}: did it match, and on which atoms. */
+export interface Match {
+    matched: boolean;
+    /** The atoms that satisfied the selector (the provenance). Empty for a
+     *  satisfied absence test ({@link matchNone}). */
+    atoms: FactAtom[];
+}
+/** Tests a whole {@link InterpretationContext} and reports the matching atoms. */
+export type Selector = (ctx: InterpretationContext) => Match;
+/** Matches placement atoms by any subset of body / sign / house / retrograde /
+ *  a held dignity. */
+export declare function hasPlacement(filter?: {
+    body?: string;
+    sign?: string;
+    house?: number;
+    retrograde?: boolean;
+    dignity?: string;
+}): Selector;
+/** Matches aspect atoms. `between` is an unordered pair; `minStrength` filters
+ *  loose aspects; `phase` filters applying/separating. */
+export declare function hasAspect(filter?: {
+    a?: string;
+    b?: string;
+    between?: [string, string];
+    aspect?: string;
+    phase?: string;
+    minStrength?: number;
+}): Selector;
+/** Matches configuration atoms by kind and/or a participating body. */
+export declare function hasPattern(filter?: {
+    kind?: string;
+    body?: string;
+}): Selector;
+/** Matches a structural-signature facet, e.g. `("element", "fire")`. */
+export declare function hasSignature(facet: string, value?: string): Selector;
+/** Matches an angle atom by which angle and/or its sign. */
+export declare function hasAngle(angle: string, sign?: string): Selector;
+/** Matches dispositor atoms by body, its dispositor, and/or the final flag
+ *  (a body in its own domicile that terminates a dispositor chain). */
+export declare function hasDispositor(filter?: {
+    body?: string;
+    dispositor?: string;
+    final?: boolean;
+}): Selector;
+/** Matches a mutual reception, optionally involving a given body. */
+export declare function hasReception(filter?: {
+    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. */
+export declare function matchAny(...sels: Selector[]): Selector;
+/** Matches when the selector does NOT match (an absence test); no atoms. */
+export declare function matchNone(sel: Selector): Selector;
+/** One interpretation: a condition and the text it licenses. */
+export interface Rule {
+    /** Stable id, unique within its source. */
+    id: string;
+    /** The condition over the fact projection. */
+    when: Selector;
+    /** The interpretation text, or a function of the match for templating. */
+    text: string | ((match: Match, ctx: InterpretationContext) => string);
+    /** Multiplies the matched atoms' salience when ranking (default 1). */
+    weight?: number;
+    /** Free-form labels (theme, polarity, ...) carried through to the entry. */
+    tags?: string[];
+}
+/** A pluggable corpus of rules: a tradition, a house style, a third party. */
+export interface InterpretationSource {
+    id: string;
+    version: string;
+    rules: Rule[];
+}
+/** One licensed statement in a {@link Reading}, with its provenance. */
+export interface ReadingEntry {
+    /** `"<source>/<rule>"`. */
+    id: string;
+    source: string;
+    rule: string;
+    text: string;
+    /** Ids of the fact atoms this entry rests on -- the audit trail. */
+    atomIds: string[];
+    /** Sum of the matched atoms' salience times the rule weight. */
+    salience: number;
+    tags?: string[];
+}
+/** A resolved interpretation: ranked entries, each citing its facts. */
+export interface Reading {
+    jdUt: number;
+    entries: ReadingEntry[];
+}
+/**
+ * Run interpretation sources against a fact projection and return a ranked
+ * {@link Reading}. Each rule whose selector matches emits an entry carrying the
+ * matched atom ids (provenance) and a salience = sum of those atoms' salience x
+ * the rule weight. The engine never ships the content: the sources are the
+ * caller's.
+ *
+ * @param ctx A projection from {@link interpretationContext}.
+ * @param sources One or more {@link InterpretationSource} corpora.
+ * @returns The {@link Reading}; entries are sorted by descending salience.
+ */
+export declare function interpret(ctx: InterpretationContext, sources: InterpretationSource[]): Reading;
+/** Entries about the same facts, gathered. */
+export interface ReadingGroup {
+    /** Union of the group's cited atom ids -- the facts it is about. */
+    atomIds: string[];
+    /** Member entries, highest salience first. */
+    entries: ReadingEntry[];
+    /** Distinct tags across the members. */
+    tags: string[];
+    /** True when a declared conflicting tag-pair both appear (the corpus made
+     *  opposing claims about the same facts). */
+    contested: boolean;
+    /** The group's salience (its strongest entry). */
+    salience: number;
+}
+export interface ReconcileOptions {
+    /** Tag pairs that contradict, e.g. `[["affirming", "challenging"]]`. */
+    conflicts?: [string, string][];
+    /** Drop an entry whose `text` duplicates a higher-salience one. */
+    dedupe?: boolean;
+}
+/**
+ * Group a {@link Reading}'s entries by the facts they share, so statements about
+ * the same atoms surface together rather than scattered through a flat list --
+ * the substrate for "everything said about this placement" and for spotting
+ * contention. Entries are connected when their cited atoms overlap; an entry
+ * citing nothing (an absence rule) stands alone. A group is `contested` when a
+ * declared conflicting tag-pair both appear in it.
+ *
+ * Semantic contradiction is the corpus author's to declare (via `tags` +
+ * `conflicts`); the resolver does the bookkeeping, not the judgement.
+ *
+ * @param reading A reading from {@link interpret}.
+ * @param opts Conflicting tag pairs and optional text de-duplication.
+ * @returns Groups sorted by descending salience.
+ */
+export declare function reconcile(reading: Reading, opts?: ReconcileOptions): ReadingGroup[];