caelus 0.17.0 → 0.19.0

package/dist/src/interpretation.js

@@ -0,0 +1,270 @@
+/**
+ * astroengine interpretation context -- a chart projected into typed, addressable
+ * "fact atoms" for an interpretation layer to consume.
+ *
+ * Caelus stops at validated geometry; this is the seam where interpretation
+ * begins. It does NOT interpret. It normalizes a {@link Chart}'s facts --
+ * placements, aspects, classical configurations, the structural signature, the
+ * angles -- into a flat list of atoms, each with a stable id, a transparent
+ * salience score, and a plain-language rendering. Rule-based and LLM-based
+ * interpreters alike build on this substrate: a rule corpus matches atoms by
+ * `kind`/`id`, and an LLM reads the `text` and cites the `id`.
+ *
+ * Salience is explicit and overridable (see {@link SalienceWeights}), never a
+ * magic number -- it ranks atoms so a reader can lead with what is prominent
+ * (luminaries, angular placements, the chart ruler, tight and hard aspects,
+ * whole configurations) without the engine asserting meaning.
+ *
+ * This is TS-side framework code, not ephemeris: there is no Swiss Ephemeris
+ * oracle for "which facts matter," so it is unit-tested for structure rather
+ * than pinned by a parity golden.
+ */
+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";
+const LUMINARIES = new Set(["sun", "moon"]);
+const ANGULAR_HOUSES = new Set([1, 4, 7, 10]);
+const HARD_ASPECTS = new Set(["conjunction", "square", "opposition"]);
+/** The seven classical planets that participate in the dispositor scheme. */
+const CLASSICAL = ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn"];
+/** Traditional domicile ruler of each sign (index 0-11), inverted from
+ *  {@link DOMICILE}: the body that rules a body's sign disposits it. */
+const SIGN_RULER = (() => {
+    const r = new Array(12);
+    for (const [body, signs] of Object.entries(DOMICILE)) {
+        for (const s of signs)
+            r[s] = body;
+    }
+    return r;
+})();
+/** Body exalted in each sign (index 0-11), or undefined; inverted from
+ *  {@link EXALTATION}. */
+const SIGN_EXALT = (() => {
+    const r = new Array(12);
+    for (const [body, sign] of Object.entries(EXALTATION))
+        r[sign] = body;
+    return r;
+})();
+/** How a reception's dignities rank (stronger = larger), for the salience
+ *  scaling and the `by` summary. */
+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. */
+const TIME_SENSITIVE_KEEP = {
+    exact: 1, approximate: 0.7, representative: 0.6, none: 0.5,
+};
+/** 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.kind === "lot" || atom.bodies.includes("moon");
+}
+function title(body) {
+    return body.split("_").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+}
+function humanizePattern(kind) {
+    const special = {
+        t_square: "T-square", grand_trine: "Grand trine", grand_cross: "Grand cross",
+        mystic_rectangle: "Mystic rectangle", stellium_sign: "Stellium",
+        stellium_house: "Stellium",
+    };
+    return special[kind] ?? title(kind);
+}
+/**
+ * Project a {@link Chart} into a ranked list of {@link FactAtom}s -- the
+ * substrate an interpretation layer consumes. Pure and deterministic; computes
+ * applying/separating and a normalized strength for each aspect that the bare
+ * {@link Chart.aspects} list omits.
+ *
+ * @param chart A chart from {@link Engine.chart} / {@link Engine.chartAt}.
+ * @param opts Salience overrides, orb policy, and precomputed reductions.
+ * @returns The {@link InterpretationContext}; `atoms` are sorted by salience.
+ */
+export function interpretationContext(chart, opts = {}) {
+    const w = { ...DEFAULT_SALIENCE, ...opts.salience };
+    const sig = opts.signature ?? chartSignature(chart);
+    const patterns = opts.patterns ?? detectPatterns(chart);
+    const atoms = [];
+    // Placements: one atom per present body.
+    for (const [body, p] of Object.entries(chart.bodies)) {
+        if (!p)
+            continue;
+        let salience = w.base;
+        if (LUMINARIES.has(body))
+            salience += w.luminary;
+        if (ANGULAR_HOUSES.has(p.house))
+            salience += w.angular;
+        if (sig.ruler === body)
+            salience += w.chartRuler;
+        salience += w.dignity * p.dignities.length;
+        const extra = [
+            p.retrograde ? "retrograde" : null,
+            ...p.dignities,
+        ].filter(Boolean);
+        atoms.push({
+            id: `placement:${body}`, kind: "placement", bodies: [body], salience,
+            body, sign: p.sign, signDeg: p.signDeg, house: p.house,
+            retrograde: p.retrograde, dignities: p.dignities,
+            text: `${title(body)} in ${p.sign}, house ${p.house}`
+                + (extra.length ? ` (${extra.join(", ")})` : ""),
+        });
+    }
+    // Aspects: phase and strength come straight from the enriched chart aspect.
+    for (const asp of chart.aspects) {
+        let salience = w.base + asp.strength;
+        if (HARD_ASPECTS.has(asp.aspect))
+            salience += w.hardAspect;
+        if (LUMINARIES.has(asp.a) || LUMINARIES.has(asp.b))
+            salience += w.luminary;
+        const [x, y] = [asp.a, asp.b].sort();
+        atoms.push({
+            id: `aspect:${x}~${y}:${asp.aspect}`, kind: "aspect", bodies: [asp.a, asp.b],
+            salience, a: asp.a, b: asp.b, aspect: asp.aspect, orb: asp.orb,
+            phase: asp.phase, strength: asp.strength,
+            text: `${title(asp.a)} ${asp.aspect} ${title(asp.b)} `
+                + `(${asp.phase}, orb ${Math.abs(asp.orb).toFixed(1)}°)`,
+        });
+    }
+    // Configurations.
+    for (const pat of patterns) {
+        let salience = w.pattern;
+        if (pat.bodies.some((b) => LUMINARIES.has(b)))
+            salience += w.luminary;
+        const names = pat.bodies.map(title).join(", ");
+        atoms.push({
+            id: `pattern:${pat.kind}:${pat.bodies.join("-")}`, kind: "pattern",
+            bodies: pat.bodies, salience, pattern: pat.kind, apex: pat.apex,
+            text: `${humanizePattern(pat.kind)}: ${names}`
+                + (pat.apex ? ` (apex ${title(pat.apex)})` : "")
+                + (pat.sign ? ` in ${pat.sign}` : ""),
+        });
+    }
+    // Structural signature: the dominant facets and the chart ruler.
+    const sigAtom = (facet, value, text) => {
+        if (value === null)
+            return;
+        atoms.push({
+            id: `signature:${facet}:${value}`, kind: "signature",
+            bodies: facet === "ruler" ? [value] : [], salience: w.base + 1,
+            facet, value, text,
+        });
+    };
+    sigAtom("element", sig.dominant.element, `${title(sig.dominant.element)} is the dominant element`);
+    sigAtom("modality", sig.dominant.modality, `${title(sig.dominant.modality)} is the dominant modality`);
+    sigAtom("sign", sig.dominant.sign, `${sig.dominant.sign} is the most-occupied sign`);
+    sigAtom("ruler", sig.ruler, `${title(sig.ruler ?? "")} is the chart ruler`);
+    // Dispositors: the classical ruler of each classical planet's sign, plus any
+    // mutual receptions (a disposits b and b disposits a) among them.
+    const dispositorOf = (body) => {
+        const p = chart.bodies[body];
+        return p ? SIGN_RULER[Math.floor(mod(p.lon, 360) / 30)] : null;
+    };
+    for (const body of CLASSICAL) {
+        if (!chart.bodies[body])
+            continue;
+        const disp = dispositorOf(body);
+        const final = disp === body;
+        let salience = w.base + w.dispositor + (final ? w.dispositor : 0);
+        if (LUMINARIES.has(body))
+            salience += w.luminary;
+        atoms.push({
+            id: `dispositor:${body}`, kind: "dispositor", bodies: [body], salience,
+            body, dispositor: disp, final,
+            text: final
+                ? `${title(body)} is in its own domicile (final dispositor)`
+                : `${title(body)} is disposited by ${title(disp)}`,
+        });
+    }
+    // Reception (mutual): each body holds a dignity in the other's sign. Checked
+    // by domicile, exaltation, and the sect's triplicity ruler (sect = day when
+    // the Sun is above the horizon, houses 7-12). `by` names the strongest
+    // dignity each direction; salience scales with the weaker link.
+    const sunHouse = chart.bodies.sun?.house;
+    const sect = sunHouse !== undefined && sunHouse >= 7 ? 0 : 1; // 0 day, 1 night
+    const signOf = (body) => Math.floor(mod(chart.bodies[body].lon, 360) / 30);
+    const receives = (a, otherSign) => {
+        const ds = [];
+        if (SIGN_RULER[otherSign] === a)
+            ds.push("domicile");
+        if (SIGN_EXALT[otherSign] === a)
+            ds.push("exaltation");
+        if (TRIPLICITY[otherSign % 4][sect] === a)
+            ds.push("triplicity");
+        return ds;
+    };
+    const strongest = (ds) => ds.reduce((best, d) => (DIGNITY_RANK[d] > DIGNITY_RANK[best] ? d : best), ds[0]);
+    for (let i = 0; i < CLASSICAL.length; i++) {
+        for (let j = i + 1; j < CLASSICAL.length; j++) {
+            const a = CLASSICAL[i];
+            const b = CLASSICAL[j];
+            if (!chart.bodies[a] || !chart.bodies[b])
+                continue;
+            const aRec = receives(a, signOf(b));
+            const bRec = receives(b, signOf(a));
+            if (!aRec.length || !bRec.length)
+                continue;
+            const da = strongest(aRec);
+            const db = strongest(bRec);
+            const by = da === db ? da : [da, db].sort().join("-");
+            let salience = w.base + w.reception * (Math.min(DIGNITY_RANK[da], DIGNITY_RANK[db]) / 3);
+            if (LUMINARIES.has(a) || LUMINARIES.has(b))
+                salience += w.luminary;
+            atoms.push({
+                id: `reception:${a}~${b}`, kind: "reception", bodies: [a, b], salience, by,
+                text: `Mutual reception: ${title(a)} and ${title(b)} (${by})`,
+            });
+        }
+    }
+    // Angles.
+    const angleAtom = (angle, lon) => {
+        const sign = SIGNS[Math.floor(mod(lon, 360) / 30)];
+        const label = { asc: "Ascendant", mc: "Midheaven", vertex: "Vertex", eastPoint: "East Point" }[angle];
+        atoms.push({
+            id: `angle:${angle}`, kind: "angle", bodies: [], salience: w.base + w.angular,
+            angle, sign, signDeg: mod(lon, 30),
+            text: `${label} in ${sign}`,
+        });
+    };
+    angleAtom("asc", chart.angles.asc);
+    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") {
+        const keep = TIME_SENSITIVE_KEEP[prov.certainty];
+        for (const a of atoms)
+            if (timeSensitive(a))
+                a.salience *= keep;
+    }
+    atoms.sort((m, n) => n.salience - m.salience || (m.id < n.id ? -1 : 1));
+    return {
+        jdUt: chart.jdUt, zodiac: chart.zodiac, atoms,
+        realm: prov?.realm, certainty: prov?.certainty,
+    };
+}

package/dist/src/node-loader.js

@@ -34,8 +34,11 @@ export function loadNodeData(dir, level = "embedded", moonTier = "full") {
     if (existsSync(join(dir, "fixed_stars.json"))) {
         data.fixedStars = j("fixed_stars.json");
     }
-    // asteroid packs (Horizons fits): loaded when present, ~380 KB total
-    for (const b of ["ceres", "pallas", "juno", "vesta", "pholus"]) {
+    // asteroid packs (Horizons fits): loaded when present, ~380 KB total.
+    // `pluto` is optional too: when a wide-range Chebyshev pack is present it
+    // supersedes the embedded Meeus ch.37 series (valid 1885-2099) above, so
+    // Pluto extends past that window at full precision; see fit_pluto.py.
+    for (const b of ["ceres", "pallas", "juno", "vesta", "pholus", "pluto"]) {
         if (existsSync(join(dir, `${b}_cheb.json`))) {
             (data.chebPacks ??= {})[b] = j(`${b}_cheb.json`);
         }

package/dist/src/provenance.d.ts

@@ -0,0 +1,135 @@
+/**
+ * astroengine provenance -- what a chart is, and when and where it is anchored.
+ *
+ * A chart silently asserts "a real instant at a real place." That is wrong for
+ * most interesting cases: forecasts, fictional or mythic subjects, archetypes,
+ * counterfactuals, charts with only an approximate or relative time. This module
+ * makes the chart's grounding first-class so the rest of the system can act on
+ * it -- route generation (ephemeris vs the compiler's symbolic synthesis), frame
+ * interpretation honestly, and degrade gracefully when no instant exists.
+ *
+ * It does not compute charts; it resolves a {@link TemporalAnchor} /
+ * {@link SpatialAnchor} to a usable instant / place (or reports that none can be
+ * derived, and why). Pure and deterministic.
+ */
+/** What a chart's subject *is* -- its epistemic / ontological status. */
+export type Realm = "observed" | "reported" | "planned" | "forecast" | "fictional" | "mythic" | "counterfactual" | "archetypal" | "conceptual";
+/** How a chart's time is known. */
+export type TemporalAnchor = {
+    kind: "instant";
+    utc: string;
+} | {
+    kind: "range";
+    earliest: string;
+    latest: string;
+} | {
+    kind: "relative";
+    relation: "before" | "after" | "during";
+    anchorId: string;
+    offset?: string;
+} | {
+    kind: "narrative";
+    calendar?: string;
+    value: string;
+    sequence?: number;
+} | {
+    kind: "symbolic";
+    rationale: string;
+} | {
+    kind: "none";
+    reason: "atemporal" | "time_irrelevant" | "intentionally_unset";
+};
+/** How a chart's place is known -- the spatial twin of {@link TemporalAnchor}. */
+export type SpatialAnchor = {
+    kind: "geo";
+    lat: number;
+    lonEast: number;
+    altM?: number;
+} | {
+    kind: "named";
+    placeId: string;
+} | {
+    kind: "region";
+    lat: number;
+    lonEast: number;
+    radiusKm: number;
+} | {
+    kind: "relative";
+    relation: "near" | "at";
+    anchorId: string;
+} | {
+    kind: "fictional";
+    value: string;
+} | {
+    kind: "none";
+    reason: "heliocentric" | "atemporal" | "intentionally_unset";
+};
+/** Resolved coordinates a chart can be computed at. */
+export interface GeoPlace {
+    lat: number;
+    lonEast: number;
+    altM?: number;
+}
+/** Lookups an anchor may need to resolve: prior instants/places for `relative`
+ *  anchors, calendar resolvers for `narrative` times, a gazetteer for `named`
+ *  places. All optional; an anchor that needs a missing one resolves to null. */
+export interface AnchorRegistry {
+    /** `anchorId` -> a resolved instant (UT Julian Day). */
+    instants?: Record<string, number>;
+    /** Calendar name -> `value` -> UT Julian Day (or null when unmappable). */
+    calendars?: Record<string, (value: string) => number | null>;
+    /** `anchorId` -> a resolved place. */
+    places?: Record<string, GeoPlace>;
+    /** Named-place resolver (e.g. the gazetteer). */
+    gazetteer?: (placeId: string) => GeoPlace | null;
+}
+/** How trustworthy a resolved instant/place is for computation. */
+export type Certainty = "exact" | "approximate" | "representative" | "none";
+/** The outcome of resolving a {@link TemporalAnchor}. */
+export interface ResolvedTime {
+    /** A concrete UT Julian Day to compute with, or null when none can be derived. */
+    jd: number | null;
+    certainty: Certainty;
+    /** Bounds in UT JD, for ranges (and relatives with a known reference). */
+    earliest?: number;
+    latest?: number;
+    /** How `jd` was derived, or why it is null. */
+    note?: string;
+}
+/** The outcome of resolving a {@link SpatialAnchor}. */
+export interface ResolvedPlace {
+    place: GeoPlace | null;
+    certainty: Certainty;
+    /** For a `region`, its radius in km. */
+    radiusKm?: number;
+    note?: string;
+}
+/** ISO-8601 timestamp -> UT Julian Day, or null when unparseable. */
+export declare function isoToJd(iso: string): number | null;
+/**
+ * Parse a duration offset into days. Accepts a compact single unit
+ * (`"3d"`, `"-2h"`, `"1.5y"`, `"6mo"`, `"90m"`) or an ISO-8601 duration
+ * (`"P1Y2M10DT2H30M"`). Calendar units use mean lengths (year 365.2425 d,
+ * month 30.436875 d). Returns `NaN` when unparseable.
+ */
+export declare function parseOffset(offset: string): number;
+/**
+ * Resolve a {@link TemporalAnchor} to a usable instant, using `registry` for
+ * relative references and narrative calendars. The result always reports its
+ * {@link Certainty}; `jd` is null exactly when no instant can be derived
+ * (`symbolic`, `none`, an unknown reference, or an unmappable calendar).
+ */
+export declare function resolveTime(anchor: TemporalAnchor, registry?: AnchorRegistry): ResolvedTime;
+/**
+ * Resolve a {@link SpatialAnchor} to coordinates, using `registry` for relative
+ * references and the gazetteer for named places. `place` is null when no
+ * coordinates can be derived (`fictional`, `none`, an unknown reference).
+ */
+export declare function resolvePlace(anchor: SpatialAnchor, registry?: AnchorRegistry): ResolvedPlace;
+/** Realms whose charts come from a time + place (the ephemeris path). The rest
+ *  (`archetypal`, `conceptual`, `mythic`) are better generated from constraints
+ *  via the compiler, since they have no instant to compute from. */
+export declare const TIME_ANCHORED_REALMS: ReadonlySet<Realm>;
+/** Whether a realm is normally grounded in an instant (ephemeris) rather than
+ *  synthesized from symbolic constraints. */
+export declare function isTimeAnchored(realm: Realm): boolean;

package/dist/src/provenance.js

@@ -0,0 +1,159 @@
+/**
+ * astroengine provenance -- what a chart is, and when and where it is anchored.
+ *
+ * A chart silently asserts "a real instant at a real place." That is wrong for
+ * most interesting cases: forecasts, fictional or mythic subjects, archetypes,
+ * counterfactuals, charts with only an approximate or relative time. This module
+ * makes the chart's grounding first-class so the rest of the system can act on
+ * it -- route generation (ephemeris vs the compiler's symbolic synthesis), frame
+ * interpretation honestly, and degrade gracefully when no instant exists.
+ *
+ * It does not compute charts; it resolves a {@link TemporalAnchor} /
+ * {@link SpatialAnchor} to a usable instant / place (or reports that none can be
+ * derived, and why). Pure and deterministic.
+ */
+const JD_UNIX_EPOCH = 2440587.5; // JD of 1970-01-01T00:00:00Z
+/** ISO-8601 timestamp -> UT Julian Day, or null when unparseable. */
+export function isoToJd(iso) {
+    const ms = Date.parse(iso);
+    return Number.isNaN(ms) ? null : JD_UNIX_EPOCH + ms / 86400000;
+}
+const UNIT_DAYS = {
+    y: 365.2425, mo: 30.436875, w: 7, d: 1, h: 1 / 24, m: 1 / 1440, s: 1 / 86400,
+};
+/**
+ * Parse a duration offset into days. Accepts a compact single unit
+ * (`"3d"`, `"-2h"`, `"1.5y"`, `"6mo"`, `"90m"`) or an ISO-8601 duration
+ * (`"P1Y2M10DT2H30M"`). Calendar units use mean lengths (year 365.2425 d,
+ * month 30.436875 d). Returns `NaN` when unparseable.
+ */
+export function parseOffset(offset) {
+    const s = offset.trim();
+    if (/^[+-]?P/i.test(s)) {
+        const m = s.match(/^([+-]?)P(?:(\d+(?:\.\d+)?)Y)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)W)?(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/i);
+        if (!m || s.replace(/^[+-]/, "") === "P")
+            return NaN;
+        const [, sign, y, mo, w, d, h, mi, sec] = m;
+        const n = (v) => (v ? parseFloat(v) : 0);
+        const days = n(y) * UNIT_DAYS.y + n(mo) * UNIT_DAYS.mo + n(w) * UNIT_DAYS.w
+            + n(d) + n(h) / 24 + n(mi) / 1440 + n(sec) / 86400;
+        return sign === "-" ? -days : days;
+    }
+    const m = s.match(/^([+-]?\d*\.?\d+)\s*(mo|[ywdhms])$/i);
+    if (!m)
+        return NaN;
+    return parseFloat(m[1]) * UNIT_DAYS[m[2].toLowerCase()];
+}
+/**
+ * Resolve a {@link TemporalAnchor} to a usable instant, using `registry` for
+ * relative references and narrative calendars. The result always reports its
+ * {@link Certainty}; `jd` is null exactly when no instant can be derived
+ * (`symbolic`, `none`, an unknown reference, or an unmappable calendar).
+ */
+export function resolveTime(anchor, registry = {}) {
+    switch (anchor.kind) {
+        case "instant": {
+            const jd = isoToJd(anchor.utc);
+            return jd === null
+                ? { jd: null, certainty: "none", note: `unparseable utc ${anchor.utc}` }
+                : { jd, certainty: "exact" };
+        }
+        case "range": {
+            const e = isoToJd(anchor.earliest);
+            const l = isoToJd(anchor.latest);
+            if (e === null || l === null) {
+                return { jd: null, certainty: "none", note: "unparseable range bound" };
+            }
+            const [lo, hi] = e <= l ? [e, l] : [l, e];
+            return {
+                jd: (lo + hi) / 2, certainty: "representative", earliest: lo, latest: hi,
+                note: "midpoint of the range",
+            };
+        }
+        case "relative": {
+            const base = registry.instants?.[anchor.anchorId];
+            if (base === undefined) {
+                return { jd: null, certainty: "none", note: `unknown anchor ${anchor.anchorId}` };
+            }
+            if (anchor.relation === "during") {
+                return { jd: base, certainty: "representative", note: `during ${anchor.anchorId}` };
+            }
+            if (anchor.offset === undefined) {
+                return {
+                    jd: base, certainty: "approximate",
+                    note: `${anchor.relation} ${anchor.anchorId} with no offset; using the reference instant`,
+                };
+            }
+            const off = parseOffset(anchor.offset);
+            if (Number.isNaN(off)) {
+                return { jd: null, certainty: "none", note: `unparseable offset ${anchor.offset}` };
+            }
+            const jd = anchor.relation === "before" ? base - off : base + off;
+            return { jd, certainty: "approximate", note: `${anchor.offset} ${anchor.relation} ${anchor.anchorId}` };
+        }
+        case "narrative": {
+            const resolver = anchor.calendar ? registry.calendars?.[anchor.calendar] : undefined;
+            if (!resolver) {
+                return {
+                    jd: null, certainty: "none",
+                    note: `no resolver for calendar ${anchor.calendar ?? "(unspecified)"}`
+                        + (anchor.sequence !== undefined ? `; sequence ${anchor.sequence}` : ""),
+                };
+            }
+            const jd = resolver(anchor.value);
+            return jd === null
+                ? { jd: null, certainty: "none", note: `calendar ${anchor.calendar} could not map ${anchor.value}` }
+                : { jd, certainty: "approximate", note: `${anchor.calendar}: ${anchor.value}` };
+        }
+        case "symbolic":
+            return { jd: null, certainty: "none", note: anchor.rationale };
+        case "none":
+            return { jd: null, certainty: "none", note: anchor.reason };
+    }
+}
+/**
+ * Resolve a {@link SpatialAnchor} to coordinates, using `registry` for relative
+ * references and the gazetteer for named places. `place` is null when no
+ * coordinates can be derived (`fictional`, `none`, an unknown reference).
+ */
+export function resolvePlace(anchor, registry = {}) {
+    switch (anchor.kind) {
+        case "geo":
+            return {
+                place: { lat: anchor.lat, lonEast: anchor.lonEast, altM: anchor.altM },
+                certainty: "exact",
+            };
+        case "named": {
+            const place = registry.gazetteer?.(anchor.placeId) ?? null;
+            return place
+                ? { place, certainty: "approximate", note: `gazetteer: ${anchor.placeId}` }
+                : { place: null, certainty: "none", note: `unknown place ${anchor.placeId}` };
+        }
+        case "region":
+            return {
+                place: { lat: anchor.lat, lonEast: anchor.lonEast }, certainty: "representative",
+                radiusKm: anchor.radiusKm, note: `centre of a ${anchor.radiusKm} km region`,
+            };
+        case "relative": {
+            const place = registry.places?.[anchor.anchorId] ?? null;
+            return place
+                ? { place, certainty: "approximate", note: `${anchor.relation} ${anchor.anchorId}` }
+                : { place: null, certainty: "none", note: `unknown place anchor ${anchor.anchorId}` };
+        }
+        case "fictional":
+            return { place: null, certainty: "none", note: anchor.value };
+        case "none":
+            return { place: null, certainty: "none", note: anchor.reason };
+    }
+}
+/** Realms whose charts come from a time + place (the ephemeris path). The rest
+ *  (`archetypal`, `conceptual`, `mythic`) are better generated from constraints
+ *  via the compiler, since they have no instant to compute from. */
+export const TIME_ANCHORED_REALMS = new Set([
+    "observed", "reported", "planned", "forecast", "counterfactual",
+]);
+/** Whether a realm is normally grounded in an instant (ephemeris) rather than
+ *  synthesized from symbolic constraints. */
+export function isTimeAnchored(realm) {
+    return TIME_ANCHORED_REALMS.has(realm);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caelus",
-  "version": "0.17.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",